Connecter des fournisseurs tiers et auto-hébergés

Libre WebUI 0.16.0 ajoute un espace Connexions aux fournisseurs dédié dans Paramètres > Plugins. Utilisez-le pour activer un fournisseur intégré, diriger un plugin compatible vers une autre API, examiner le catalogue de modèles effectif ou connecter une passerelle auto-hébergée sur un réseau de confiance.

Libre WebUI prend actuellement en charge les formats de communication de fournisseurs suivants :

• OpenAI Chat Completions ;
• OpenAI Responses ;
• Anthropic Messages ; et
• le contenu et les appels de fonctions Google Gemini.

Les définitions Anthropic et Gemini intégrées utilisent des adaptateurs dédiés, sélectionnés selon l’identité de leur fournisseur. Un fournisseur nouvellement importé utilise la sémantique d’OpenAI Chat Completions ou d’OpenAI Responses ; le diriger vers une API compatible avec Anthropic ou Gemini ne sélectionne pas ces adaptateurs intégrés. Un fournisseur dont les requêtes, la diffusion en continu, les appels d’outils ou les réponses ont une autre forme exige un adaptateur dans le backend. Le JSON du plugin décrit le routage et la configuration ; il ne traduit pas un protocole sans rapport.

Ouvrir les connexions aux fournisseurs

1. Connectez-vous et ouvrez Paramètres > Plugins.
2. Recherchez le fournisseur dans la liste du volet gauche.
3. Sélectionnez-le pour examiner son état d’activation et son catalogue de modèles effectif.
4. Activez le fournisseur pour votre compte.
5. Sélectionnez Configurer uniquement si vous devez enregistrer un identifiant ou remplacer un réglage de connexion.

La configuration du fournisseur est fermée par défaut. Les réglages de connexion apparaissent d’abord pour les administrateurs, tandis que les commandes d’échantillonnage, telles que la température et les limites de jetons, restent dans la section Paramètres avancés, réduite séparément. Les valeurs héritées par défaut sont présentées comme indications, et non comme remplacements de compte préremplis.

Les définitions de plugins constituent une configuration partagée de l’instance ; seuls les administrateurs peuvent donc les importer, installer, mettre à jour ou supprimer. Chaque utilisateur authentifié contrôle son propre état d’activation, ses identifiants et ses réglages de génération autorisés.

Ajouter rapidement une connexion

Paramètres > Connexions offre un parcours plus court pour le cas courant : un point de terminaison compatible avec OpenAI et une clé d’API. Les administrateurs voient une fiche consacrée à l’environnement Ollama local, avec son état et sa version, une liste des connexions existantes compatibles avec OpenAI et un petit formulaire pour en ajouter une.

L’ajout d’une connexion exige un nom affiché, l’URL complète des complétions de chat et, facultativement, une clé d’API. Libre WebUI dérive l’identifiant de connexion du nom, installe la définition du fournisseur, enregistre la clé côté serveur, active la connexion et demande au point de terminaison les modèles qu’il fournit. Les modèles découverts remplacent le catalogue provisoire et apparaissent dans le sélecteur de modèles du chat.

Chaque ligne indique le point de terminaison, le nombre de modèles, la présence éventuelle d’une clé enregistrée, un bouton d’activation, une commande d’actualisation des modèles et une commande de suppression. Tout réglage plus avancé — modes de l’API Responses, remplacement de l’URL de base, catalogues par capacité, politique des paramètres de génération — reste dans l’espace plus complet Paramètres > Plugins décrit ci-dessus.

Codex (connexion ChatGPT)

Le fournisseur intégré Codex (ChatGPT) ne nécessite aucune clé d’API. Lorsque le serveur dispose d’une connexion Codex CLI (codex login exécuté sous l’utilisateur du système d’exploitation du serveur), le fournisseur apparaît aux administrateurs et propose la famille documentée de modèles Codex via la session ChatGPT. Les jetons d’accès sont lus dans le fichier auth.json propre à la CLI, actualisés au moyen du même client OAuth que celui employé par la CLI, puis réécrits pour que celle-ci continue de fonctionner ; leurs valeurs n’apparaissent jamais dans les journaux.

Comme les requêtes sont émises par le backend, jamais depuis le conteneur d’une tâche, ces modèles peuvent aussi alimenter Work avec sa boucle d’outils isolée habituelle. Le fournisseur est réservé aux administrateurs, car chaque appel utilise l’abonnement ChatGPT du propriétaire du serveur. Masquez-le entièrement avec CODEX_OAUTH_MODELS_ENABLED=false ou utilisez une autre connexion avec CODEX_HOME.

Choisir un fournisseur intégré ou importé

Libre WebUI comprend des définitions pour OpenAI, Anthropic, Gemini, Groq, Mistral, OpenRouter, Kimi Code de Moonshot AI, Hugging Face, GitHub Models, MLX LM local et d’autres services de modèles ou de médias. Commencez par une entrée intégrée lorsque son protocole et son contrat d’authentification correspondent au service souhaité.

Pour un autre service compatible, un administrateur peut importer une définition JSON de plugin. Cet exemple minimal décrit une passerelle compatible avec OpenAI :

{
  "id": "private-ai-gateway",
  "name": "Private AI Gateway",
  "type": "completion",
  "endpoint": "http://ai-gateway:8080/v1/chat/completions",
  "api_mode": "chat_completions",
  "auth": {
    "header": "Authorization",
    "prefix": "Bearer ",
    "key_env": "PRIVATE_AI_GATEWAY_API_KEY"
  },
  "model_map": ["gateway-chat"]
}

Importez le fichier depuis Paramètres > Plugins, activez-le et enregistrez la clé d’API pour le compte qui utilisera la connexion. Ajoutez des variables de connexion à la définition lorsque les administrateurs doivent pouvoir modifier l’URL de base, le chemin, la découverte ou les champs de point de terminaison propres aux capacités. Le fichier intégré plugins/openai.json fournit un exemple complet.

Pour une passerelle intentionnellement dépourvue d’authentification sur un réseau de confiance, définissez auth.header et auth.key_env comme chaînes vides, et omettez auth.prefix. Libre WebUI n’exige ni n’envoie alors de clé d’API pour ce plugin.

Choisir Chat Completions ou Responses

Les plugins de complétion compatibles avec OpenAI peuvent utiliser l’un ou l’autre mode d’API :

Mode de l’API	Chemin de requête par défaut	Champ de requête typique
chat_completions	/chat/completions	messages
responses	/responses	input

Le fournisseur OpenAI intégré expose le Mode de l’API dans sa configuration. Libre WebUI transpose les sorties Responses terminées et diffusées en continu vers Chat et Work, notamment un état de rejeu limité pour le raisonnement et les appels d’outils.

Changer de mode modifie le chemin d’opération par défaut. Cela ne change pas le protocole utilisé par le serveur en amont : ne sélectionnez Responses que lorsque ce serveur met en œuvre des formes de requêtes et d’événements Responses compatibles.

Configurer une URL de base ou un point de terminaison complet

Libre WebUI résout la route de complétion dans l’ordre suivant :

1. Un remplacement de endpoint complet et différent de la valeur par défaut.
2. base_url accompagné d’un api_path facultatif.
3. Le point de terminaison déclaré dans la définition du plugin.

Utilisez URL de base pour la racine de l’API :

https://gateway.example/v1

Sans chemin personnalisé, le mode Chat Completions envoie les requêtes à :

https://gateway.example/v1/chat/completions

Le mode Responses les envoie plutôt à :

https://gateway.example/v1/responses

Utilisez Chemin de l’API lorsque le fournisseur expose une opération compatible à un autre chemin relatif à cette racine. N’utilisez Ancien point de terminaison complet que si vous devez fournir l’URL complète de l’opération ; un véritable point de terminaison complet prend le pas sur l’URL de base et le chemin de l’API.

Les suffixes de points de terminaison connus /chat/completions, /completions et /responses déterminent aussi la sémantique de la requête. Un chemin d’opération personnalisé non reconnu conserve le mode d’API explicitement sélectionné.

Après avoir modifié une route ou une clé d’API, enregistrez de nouveau le fournisseur avant de tester Chat. Lorsque le plugin déclare une authentification, une route de connexion personnalisée exige un identifiant enregistré par le même compte. Un plugin intentionnellement dépourvu d’authentification peut laisser les deux champs d’authentification vides. Libre WebUI n’envoie pas une clé d’environnement gérée par l’opérateur vers une destination définie par l’utilisateur ; le repli vers l’environnement est réservé à la route intégrée de confiance.

Découvrir ou maintenir les identifiants de modèles

Sélectionnez un fournisseur de chat actif et utilisez Actualiser les modèles pour lancer la découverte. Libre WebUI recharge à la fois le catalogue du fournisseur sélectionné et la liste des modèles de Chat.

La découverte s’exécute aussi automatiquement : le catalogue d’un fournisseur actif est de nouveau découvert s’il est absent ou plus ancien que PLUGIN_MODEL_DISCOVERY_TTL_MS. Les modèles affichés suivent ainsi le fournisseur, plutôt que de rester figés au moment de son activation. Actualiser les modèles force une vérification immédiate et en indique le résultat :

Résultat	Signification
Catalogue mis à jour	Le fournisseur a répondu et sa liste de modèles diffère de celle enregistrée
Catalogue déjà à jour	Le fournisseur a répondu avec la même liste
Clé d’API requise	Aucune clé utilisable : aucune requête n’a été effectuée et l’ancien catalogue reste affiché
Impossible de charger le catalogue	Le fournisseur était inaccessible ou n’a rien renvoyé d’utilisable

Une clé définie uniquement dans l’environnement n’est pas utilisée pour un fournisseur qui exécute une définition installée plutôt que la définition intégrée ; le message le précise lorsque ce cas s’applique. Les modèles de parole, d’image et d’embedding trouvés dans le catalogue d’un fournisseur sont répertoriés ici avec leurs étiquettes de capacité, mais exclus du sélecteur de modèles de chat.

Pour une route compatible avec OpenAI, la découverte choisit l’URL de la liste des modèles comme suit :

• une route se terminant par /models est utilisée telle quelle ;
• un suffixe d’opération connu, comme /chat/completions, /completions, /responses, /embeddings ou /messages, est remplacé par /models ; et
• dans les autres cas, /models est ajouté à la route.

Par exemple, ces deux routes de complétion produisent la même URL de découverte :

https://gateway.example/v1/chat/completions
https://gateway.example/v1/responses

-> https://gateway.example/v1/models

Lorsque cette dérivation ne produit pas l’URL complète correcte, exposez models_endpoint dans le tableau variables du plugin :

{
  "name": "models_endpoint",
  "type": "string",
  "label": "Models Endpoint",
  "default": "https://gateway.example/v1/models"
}

La valeur héritée par défaut ou enregistrée par l’administrateur prend le pas sur l’adresse dérivée. Une propriété models_endpoint de premier niveau dans le manifeste n’est pas lue. La découverte attend une réponse compatible avec OpenAI, contenant des objets de modèles dans un tableau data :

{
  "data": [{ "id": "gateway-chat" }, { "id": "gateway-code" }]
}

Les identifiants découverts sont stockés par utilisateur et ne réécrivent pas le fichier partagé du plugin. Si le fournisseur ne met pas en œuvre une découverte compatible, conservez les identifiants de modèles de repli dans model_map du JSON du plugin. Le catalogue de Connexions aux fournisseurs est en lecture seule ; les étiquettes de capacité indiquent quelle route du plugin répertorie un modèle et ne constituent pas des contrôles d’état.

Les identifiants de modèles ne sont pas uniques à l’échelle globale. Chat enregistre l’identifiant brut du modèle avec l’identité exacte de son fournisseur Ollama ou plugin ; un modèle Ollama et plusieurs plugins peuvent donc exposer le même nom sans risque. Si le fournisseur enregistré devient indisponible, Libre WebUI signale que la sélection n’est plus disponible au lieu d’acheminer silencieusement la requête vers un autre fournisseur.

Configurer séparément la génération d’images

Le fournisseur OpenAI intégré expose la génération d’images via https://api.openai.com/v1/images/generations et utilise actuellement gpt-image-2 par défaut dans les nouvelles configurations. Les anciens identifiants GPT Image restent dans son catalogue de repli pour les déploiements existants compatibles.

Les routes de chat et d’image sont volontairement isolées. Une URL de base de Chat personnalisée ne reçoit pas automatiquement les requêtes d’image. Laissez image_endpoint vide pour utiliser le point de terminaison d’image déclaré par le plugin, ou définissez-le sur l’URL complète de l’opération d’API Image compatible si votre fournisseur en propose une.

Les choix d’images sont qualifiés par fournisseur, comme ceux de Chat. Si deux plugins actifs exposent le même identifiant de modèle d’image, Libre WebUI envoie la requête uniquement au fournisseur sélectionné dans le volet d’image.

Connecter une passerelle HTTP en toute sécurité

Les points de terminaison des fournisseurs peuvent utiliser des URL HTTP ou HTTPS absolues. HTTP convient à une passerelle auto-hébergée sur un réseau local, un réseau Tailscale ou un réseau privé de conteneurs de confiance, mais transmet les clés d’API, les invites, les résultats d’outils et le contenu généré sans chiffrement du transport. Préférez HTTPS dès que la route franchit une frontière réseau ou que la passerelle prend en charge TLS.

Les requêtes proviennent du backend Libre WebUI, et non du navigateur. Choisissez une adresse accessible depuis ce backend :

Emplacement du backend	Exemple de racine du fournisseur
Processus natif, même machine	http://127.0.0.1:8081/v1
Service Docker Compose	http://ai-gateway:8080/v1
Du conteneur vers l’hôte pris en charge	http://host.docker.internal:8081/v1
Hôte du réseau local ou Tailscale de confiance	http://192.168.1.20:8081/v1

Dans un conteneur, localhost désigne le conteneur Libre WebUI lui-même. Il ne désigne pas un autre service Compose et ne permet pas automatiquement d’atteindre l’hôte.

Libre WebUI accepte uniquement des URL de fournisseur HTTP et HTTPS, valide la destination finale avant de sélectionner un identifiant et ne suit pas les redirections des requêtes adressées au fournisseur ou à la découverte. Configurez directement l’URL de l’opération finale.

Vérifier la passerelle avant de l’activer

Testez la découverte des modèles depuis la machine ou le conteneur qui exécute le backend Libre WebUI :

curl http://ai-gateway:8080/v1/models \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY'

Testez ensuite l’opération correspondant au mode d’API sélectionné.

Chat Completions :

curl http://ai-gateway:8080/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gateway-chat",
    "messages": [{"role": "user", "content": "Reply with: ready"}],
    "stream": false
  }'

Responses :

curl http://ai-gateway:8080/v1/responses \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gateway-chat",
    "input": "Reply with: ready",
    "store": false
  }'

Lorsque les deux appels fonctionnent, configurez la même route, le même mode, le même identifiant et le même identifiant de modèle dans Connexions aux fournisseurs. Activez le fournisseur, sélectionnez Actualiser les modèles, puis choisissez son modèle qualifié par fournisseur dans Chat. Work peut également l’utiliser si le modèle prend correctement en charge les appels d’outils.

Dépannage

Symptôme	Vérification
Les requêtes atteignent toujours le point de terminaison intégré	Supprimez un ancien remplacement du point de terminaison complet, puis enregistrez l’URL de base et le chemin d’API voulus.
Le fournisseur reçoit la mauvaise charge utile	Faites correspondre le mode d’API au protocole Chat Completions ou Responses en amont et vérifiez le suffixe final.
L’actualisation ne renvoie aucun identifiant	Testez /models, vérifiez la forme data[].id, exposez ou configurez la variable models_endpoint, ou maintenez model_map.
Un ancien modèle reste après la modification d’une route	Enregistrez la modification ; Libre WebUI efface le catalogue découvert obsolète de cet utilisateur avant l’actualisation.
La clé d’API est signalée comme absente	Enregistrez un identifiant propre à l’utilisateur pour la route personnalisée ; le repli vers l’environnement intégré ne suit pas les remplacements.
Un déploiement Docker ne peut pas atteindre localhost	Utilisez le nom de service Compose de la passerelle, un alias d’hôte pris en charge ou une adresse de réseau privé accessible.
Chat fonctionne, mais pas la génération d’images	Configurez séparément l’image_endpoint complet et sélectionnez un modèle exposé par cette capacité d’image.
Chat fonctionne, mais Work rejette le modèle	Vérifiez que le modèle prend en charge des appels d’outils compatibles ; une complétion de texte ordinaire ne suffit pas.
Le fournisseur renvoie une redirection	Configurez directement l’URL finale validée ; Libre WebUI ne suit délibérément pas les redirections des fournisseurs.

Pour connaître en détail le routage, les identifiants, l’état de rejeu et le comportement des autorisations, consultez Plugins. Pour les échecs propres au déploiement, consultez Dépannage.

Remerciements à la communauté

Ce guide et l’expérience Connexions aux fournisseurs de Libre WebUI 0.16.0 ont été façonnés par ZhengJin (@fangzhengjin), dont les commentaires détaillés sur les fournisseurs tiers et le concept d’expérience utilisateur assisté par l’IA dans #163 ont aidé à définir ce flux de travail.

Documentation connexe

• Plugins
• Travailler avec les modèles
• MLX LM sur Apple Silicon
• Work : espaces de travail isolés
• Dépannage