> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/automate-protect-and-extend/fr/ia-privee/open-ai-router.md).

# API VergeOS compatible OpenAI

## 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é

{% hint style="warning" %}
**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.
{% endhint %}

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

```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

```bash
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

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

{% hint style="info" %}
**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`).
{% endhint %}

## Format de réponse

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

```json
{
  "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](/automate-protect-and-extend/fr/ia-privee/configuration.md#ai-assistant-management).

{% hint style="success" %}
**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
  {% endhint %}

## 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 :

```python
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 :

{% tabs %}
{% tab title="Python" %}

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

{% endtab %}

{% tab title="JavaScript" %}

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

{% endtab %}

{% tab title="cURL" %}

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

{% endtab %}
{% endtabs %}

## Dépannage

### Erreur : connexion requise

```json
{"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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/automate-protect-and-extend/fr/ia-privee/open-ai-router.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.