API VergeOS compatible OpenAI

Documentation de l’endpoint API VergeOS compatible OpenAI, permettant aux applications d’interagir avec des LLM hébergés localement en utilisant le format standard de l’API OpenAI avec Python, JavaScript et cURL.

Vue d’ensemble

VergeOS fournit un point de terminaison d’API compatible OpenAI qui permet aux applications d’interagir avec des grands modèles de langage (LLM) hébergés localement en utilisant le format standard de l’API OpenAI. Cela vous permet d’utiliser des outils et des bibliothèques familiers tout en exécutant les modèles entièrement dans votre environnement VergeOS.

L’API achemine automatiquement les requêtes vers vos assistants configurés et leurs modèles sous-jacents, fournissant une interface unifiée pour les interactions IA.

Prérequis

Avant d’utiliser l’API compatible OpenAI, assurez-vous que les composants suivants sont en cours d’exécution :

1. AI-Helper Worker: Ce worker traite les requêtes de l’API et doit être en cours d’exécution. Il démarre automatiquement lorsque le service IA est activé.
2. Au moins un assistant avec un modèle en ligne: Un assistant doit être configuré et son modèle sous-jacent doit être à l’état « En ligne ».

Pour vérifier ces prérequis :

1. Accédez à IA → Voir les workers pour confirmer que le worker AI-Helper est en cours d’exécution
2. Accédez à IA → Assistants pour confirmer qu’au moins un assistant affiche l’état « En ligne »

Points de terminaison de l’API

L’API compatible OpenAI est disponible à l’adresse :

https://<your-vergeos-url>/v1

Points de terminaison pris en charge

Point de terminaison	Description
/v1/models	Liste les modèles disponibles (renvoie les assistants configurés)
/v1/chat/completions	Générer des complétions de conversation

Authentification

Les requêtes de l’API nécessitent une authentification à l’aide d’un jeton Bearer :

Authorization: Bearer <your-api-key>

Création d’une clé API

1. Accédez à Système → Utilisateurs
2. Sélectionnez l’utilisateur qui sera propriétaire de la clé API (ou créez un nouvel utilisateur)
3. Cliquez sur Nouvelle clé API dans le menu de gauche
4. Configurez les paramètres de la clé :

   • Nom: Un nom descriptif pour la clé (par ex., my-app-key)
   • Description (facultatif) : Détails supplémentaires sur l’objectif de la clé
   • Type d’expiration: Choisissez « Définir une date » ou « Jamais »
   • Expire: Si vous utilisez Définir une date, sélectionnez la date/l’heure d’expiration
5. Enregistrez la clé et copiez le jeton généré

Sécurité

La clé API n’est affichée qu’une seule fois lors de sa création. Conservez-la en lieu sûr, car elle ne pourra pas être récupérée ultérieurement.

Les clés API héritent des autorisations de l’utilisateur associé. Pour une utilisation en production, envisagez de créer un utilisateur API dédié avec les autorisations appropriées.

Utilisation de base

Exemple Python

from openai import OpenAI

client = OpenAI(
    base_url="https://your-vergeos-instance.com/v1",
    api_key="your-api-key"
)

response = client.chat.completions.create(
    model="qwen3-coder-14B",  # Utilisez le nom de l’assistant
    messages=[
        {"role": "user", "content": "Écrivez une fonction hello world en Python"}
    ],
    max_tokens=1024,
    temperature=0.7
)

print(response.choices[0].message.content)

Exemple cURL

curl https://your-vergeos-instance.com/v1/chat/completions \\
  -H "Authorization: Bearer your-api-key" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "qwen3-coder-14B",
    "messages": [{"role": "user", "content": "Bonjour !"}],
    "max_tokens": 100
  }'

Lister les modèles disponibles

curl https://your-vergeos-instance.com/v1/models \\
  -H "Authorization: Bearer your-api-key"

Noms des modèles

Dans les requêtes API, utilisez le nom de l’assistant (par ex., qwen3-coder-14B) comme le paramètre model et non le nom du modèle sous-jacent (par ex., Qwen3-14B-Q6_K).

Format de réponse

Les réponses suivent le format standard OpenAI avec des informations temporelles supplémentaires :

{
  "id": "unique-completion-id",
  "object": "chat.completion",
  "created": 1768822431,
  "model": "assistant-name",
  "system_fingerprint": "assistant-name",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Contenu de la réponse ici"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 100,
    "total_tokens": 132
  },
  "timings": {
    "prompt_n": 12,
    "prompt_ms": 365.388,
    "prompt_per_token_ms": 30.449,
    "prompt_per_second": 32.84,
    "predicted_n": 100,
    "predicted_ms": 1620.788,
    "predicted_per_token_ms": 16.21,
    "predicted_per_second": 61.70
  }
}

Le timings le champ fournit des métriques de performance non disponibles dans l’API OpenAI standard.

Configuration des assistants

Les assistants définissent la manière dont l’API interagit avec les modèles sous-jacents. L’assistant Nom est utilisé comme le paramètre model paramètre dans les requêtes API.

Pour des instructions détaillées sur la création et la configuration des assistants, consultez le Guide de configuration IA.

Paramètres clés pour l’utilisation de l’API

• Nom: Cela devient le paramètre model paramètre dans les appels API
• Désactiver la réflexion: Activez cette option pour que les modèles disposant de capacités de réflexion renvoient du contenu via l’API
• Invite système: Appliqué automatiquement à chaque requête API

Workers

Le système IA utilise deux types de workers :

• AI-Helper Worker: Traite les requêtes API et les achemine vers les modèles. Démarre automatiquement et est requis pour que l’API fonctionne.
• Workers de modèles: Gèrent l’inférence pour chaque modèle en cours d’exécution. Créés automatiquement lorsqu’un modèle démarre.

Consultez l’état des workers à IA → Voir les workers.

Conversations multi-tours

L’API prend en charge les conversations multi-tours en incluant l’historique des messages :

response = client.chat.completions.create(
    model="qwen3-coder-14B",
    messages=[
        {"role": "user", "content": "Qu’est-ce que Python ?"},
        {"role": "assistant", "content": "Python est un langage de programmation..."},
        {"role": "user", "content": "Montrez-moi un exemple simple"}
    ]
)

Lorsque Historique de discussion est activé sur l’assistant, le système peut également conserver le contexte entre des appels API distincts au sein d’une session.

Travailler avec des modèles à réflexion

Certains modèles (comme Qwen3) disposent de capacités de « réflexion » qui leur permettent de raisonner en interne sur les problèmes avant de répondre.

Si vous utilisez un tel modèle via l’API et recevez des réponses vides, le modèle peut produire des jetons de réflexion filtrés de la réponse. Pour obtenir le contenu réel de la réponse :

1. Accédez à IA → Assistants
2. Cliquez sur votre assistant
3. Cliquez sur Modifier l’assistant
4. Activez le Désactiver la réflexion interrupteur
5. Cliquez sur Soumettre

Cela supprime le processus de réflexion et ne renvoie que la réponse finale.

Exemples d’intégration

Intégration dans l’IDE

De nombreux IDE prennent en charge des points de terminaison personnalisés compatibles OpenAI. Configurez votre IDE avec :

• URL de base de l’API: https://your-vergeos-instance.com/v1
• Clé API: Votre clé API VergeOS
• Modèle: Le nom de votre assistant (par ex., qwen3-coder-14B)

Intégration de l’application

Utilisez n’importe quelle bibliothèque cliente OpenAI :

Python

from openai import OpenAI
client = OpenAI(base_url="https://your-vergeos-instance.com/v1", api_key="your-key")

JavaScript

import OpenAI from 'openai';
const client = new OpenAI({
  baseURL: 'https://your-vergeos-instance.com/v1',
  apiKey: 'your-key'
});

cURL

curl https://your-vergeos-instance.com/v1/chat/completions \\
  -H "Authorization: Bearer your-key" \\
  -H "Content-Type: application/json" \\
  -d '{"model": "assistant-name", "messages": [...]}'

Dépannage

Erreur : connexion requise

{"err":"Connexion requise"}

Cause: Clé API manquante ou invalide.

Solution: Incluez une clé API valide dans l’en-tête Authorization.

Contenu de réponse vide

Cause: Le modèle utilise des jetons de réflexion qui sont filtrés de la sortie.

Solution: Activez « Désactiver la réflexion » dans les paramètres de l’assistant.

Modèle introuvable

Cause: Le nom du modèle spécifié ne correspond à aucun assistant.

Solution:

• Utilisez le nom exact de l’assistant (sensible à la casse)
• Vérifiez que l’assistant existe dans IA → Assistants
• Assurez-vous que le modèle de l’assistant est en ligne

Connexion refusée

Cause: Le worker AI-Helper n’est pas en cours d’exécution.

Solution:

• Vérifiez IA → Voir les workers pour vérifier l’état du worker AI-Helper
• Redémarrez le service IA si nécessaire

Réponses lentes

Cause: Le modèle est en cours de chargement ou fortement sollicité.

Solution:

• Vérifiez l’utilisation des ressources du worker à IA → Voir les workers
• Envisagez d’allouer davantage de cœurs CPU ou de RAM au modèle
• Utilisez un modèle plus petit pour obtenir des réponses plus rapides

---

Compatibilité de version: Cette fonctionnalité est disponible dans VergeOS 26.0 et versions ultérieures.