API compatible OpenAI

vLLM, LM Studio, un proxy interne : tout serveur qui parle le protocole OpenAI et que la liste ci-dessus ne nomme pas.

Connectez tout serveur qui parle le protocole de complétion de chat d’OpenAI sans être l’un des fournisseurs nommés : vLLM, LM Studio, un proxy ou une passerelle interne. La connexion est réglée une fois pour toute l’organisation par un administrateur ; les membres l’emploient ensuite depuis l’éditeur de workflow sans jamais voir la clé.

Contrairement aux fournisseurs nommés, Mankomail ne sait rien à l’avance de ce serveur : vous donnez son adresse, et les workflows nomment le modèle à appeler.

En bref

• Identifiant : openai_compatible
• Famille : Fournisseur d’IA
• Configurée par : Un administrateur, pour toute l’organisation
• Authentification : Clé d’API du fournisseur
• Type de credential : llm_provider

Avant de commencer

• L’URL de base du serveur, préfixe de version compris (par exemple https://llm.exemple.interne/v1). Elle doit être joignable depuis le serveur Mankomail, qui fait les appels.
• Une clé d’API acceptée par ce serveur. Ce type de connexion exige une clé : si votre serveur ne vérifie pas les clés, saisissez une valeur quelconque non vide.
• L’identifiant exact du modèle servi par le serveur.
• Un compte administrateur sur Mankomail, et une instance dotée d’une clé de chiffrement (ENCRYPTION_KEY).

Pour Ollama, préférez la connexion dédiée Ollama : elle ne demande pas de clé et sait lister les modèles du serveur.

Qui la configure

Les connexions d’IA appartiennent à l’organisation, pas à un membre. Seul un administrateur peut les créer, les modifier, les tester ou les supprimer, depuis la page Connexions. Un membre voit la section Intelligence artificielle avec la mention « Les fournisseurs d’IA sont configurés une fois pour toute l’organisation, par un administrateur. » Il ne voit jamais de clé : dans l’éditeur de workflow, il choisit seulement une connexion par son libellé, et un modèle.

La clé est chiffrée avant d’être enregistrée et n’est plus jamais réaffichée : l’écran n’en montre que les quatre derniers caractères (« Clé enregistrée (se termine par …) »). Enregistrer une clé exige la clé de chiffrement de l’instance (ENCRYPTION_KEY, voir Variables d’environnement) ; sans elle, l’enregistrement échoue avec llm.encryption_disabled.

Ajouter la connexion

1. Ouvrez Connexions dans la navigation principale.
2. Dans la section Intelligence artificielle, repérez la ligne API compatible OpenAI et cliquez sur Configurer. (Vous pouvez aussi cliquer sur Ajouter dans cette section et choisir API compatible OpenAI dans le catalogue.)
3. Libellé : pré-rempli avec le nom du fournisseur. Donnez-lui le nom du serveur, par exemple « vLLM interne ».
4. Clé d’API : collez la clé. Elle est obligatoire pour une nouvelle connexion et n’est jamais réaffichée.
5. URL du serveur : obligatoire (« L’adresse de l’API compatible, jusqu’au préfixe de version inclus. »). Mankomail appelle <URL>/chat/completions.
6. Modèles activés : la carte indique « Aucun catalogue connu pour ce fournisseur : tout modèle saisi sera accepté. » Il n’y a rien à cocher.
7. Cliquez sur Enregistrer.

Quand vous modifiez une connexion enregistrée, laissez le champ Clé d’API vide pour conserver la clé.

Modèles

Cette connexion n’a pas de catalogue de modèles et ne sait pas lister les modèles du serveur : il n’y a pas de bouton Voir les modèles disponibles. En conséquence :

• aucun modèle n’est activé, donc tout identifiant de modèle est accepté ;
• il n’y a pas non plus de modèle recommandé : chaque nœud IA doit nommer son modèle via un nœud fournisseur (voir plus bas). Un nœud qui s’en remet aux défauts de l’instance échoue avec llm.no_default_model ;
• Tester a besoin d’un modèle avec lequel tester et n’en trouve pas : il échoue avec llm.no_default_model. Vérifiez la connexion en lançant un essai avec un nœud fournisseur qui nomme le modèle.

Les développeurs peuvent poser une liste d’autorisation par l’API (enabledModels sur PUT /api/v1/admin/llm/connections/{id}, voir API). Le premier modèle activé sert alors de défaut et de modèle de test.

Quel fournisseur et quel modèle un nœud IA utilise

Les nœuds IA (par exemple Catégoriser, Extraire, Rédiger (IA), Résumer et Instruction libre (IA)) appellent chacun le modèle avec un usage : classer, extraire, rédiger ou usage général. L’analyse de boîte a son propre usage. Pour chaque appel, le fournisseur et le modèle se résolvent dans cet ordre — la première règle applicable l’emporte :

1. Un nœud fournisseur câblé sur le port model du nœud — par exemple un nœud API compatible OpenAI. Ses champs Connexion et Modèle s’appliquent ; un Modèle vide signifie « le modèle recommandé pour cet usage chez ce fournisseur ».
2. Le choix de l’administrateur pour cet usage, dans le panneau Quelle IA pour quel usage de la page Connexions.
3. Le défaut de l’instance — la première ligne de ce panneau, « Par défaut (tous les usages non réglés) ». Elle peut nommer un fournisseur seul (« … · modèle recommandé ») ou un fournisseur et un modèle.
4. Le premier fournisseur configuré, par date de configuration (sans préférence de marque), avec le modèle recommandé pour l’usage.

Un choix devenu inutilisable (clé retirée, modèle décoché) est ignoré au profit de la règle suivante, et le panneau affiche « Choix inapplicable » à côté. Sous chaque ligne, « Utilise : fournisseur · modèle » montre ce que le prochain appel obtiendra réellement. Quand rien ne peut servir un usage, la ligne affiche « Aucun » et les nœuds échouent avec llm.no_provider_configured ou llm.no_default_model.

Faute de catalogue, le panneau Quelle IA pour quel usage ne peut proposer aucun modèle de cette connexion pour un usage. Employez-la en câblant un nœud fournisseur qui nomme le modèle.

Plusieurs clés pour un même fournisseur

Une organisation peut détenir plusieurs connexions API compatible OpenAI — par exemple deux serveurs. Chaque connexion a son Libellé, sa clé, son URL de serveur et sa liste de modèles activés.

• Pour en ajouter une, ouvrez la carte du fournisseur et cliquez sur Ajouter une connexion. Le libellé est obligatoire et doit être unique (sinon : « Ce libellé est déjà utilisé par une autre connexion. »).
• La première connexion d’un fournisseur devient automatiquement sa connexion Par défaut. À partir de deux, la carte les liste ; cliquez sur Mettre par défaut sur une autre pour déplacer le défaut.
• La connexion par défaut est celle qu’emploie tout ce qui n’en nomme aucune : les défauts par usage, le défaut de l’instance, l’analyse de boîte, et tout nœud fournisseur dont le champ Connexion reste sur « Par défaut (…) ».
• Pour imposer une clé précise à un nœud, choisissez-la dans le champ Connexion du nœud fournisseur API compatible OpenAI.

Pour supprimer une connexion, sélectionnez-la, cliquez sur Supprimer, puis sur Confirmer la suppression. Deux refus protègent les workflows en service :

• si des workflows publiés référencent la connexion, la carte affiche « Des workflows publiés utilisent cette connexion ; confirmez pour la supprimer quand même. » et les nomme. Confirmer une nouvelle fois la supprime, et ces nœuds échoueront alors avec llm.connection_not_found jusqu’à ce que vous choisissiez une autre connexion ;
• la connexion par défaut ne se supprime pas tant que le fournisseur en a d’autres (llm.connection_is_default) : mettez-en d’abord une autre par défaut. Supprimer la dernière connexion retire le fournisseur de l’instance.

Utiliser API compatible OpenAI dans un workflow

Pour qu’un nœud IA travaille avec API compatible OpenAI quels que soient les défauts de l’instance, câblez-lui un nœud fournisseur :

1. Ajoutez le nœud API compatible OpenAI sur le canevas (fiche du nœud).
2. Tirez un lien de ce nœud vers le port model du nœud IA.
3. Dans Connexion, gardez « Par défaut (…) » pour employer la connexion par défaut du fournisseur, ou choisissez une autre connexion par son libellé.
4. Dans Modèle, laissez le champ vide pour employer le modèle recommandé pour l’usage du nœud, ou saisissez un identifiant de modèle. L’éditeur propose les modèles activés sur la connexion choisie et prévient quand l’identifiant n’y est pas activé (« Ce modèle n’est pas activé sur la connexion choisie : l’exécution le refusera. »).
5. Température est facultative ; laissez-la vide pour garder le réglage du fournisseur.

Le nœud fournisseur n’est pas une étape : il ne s’exécute jamais seul, ne porte aucune clé, et indique seulement au nœud IA câblé quel fournisseur, quelle connexion et quel modèle employer. Un même nœud fournisseur peut alimenter plusieurs nœuds IA.

Si la connexion choisie a été supprimée, l’exécution échoue avec llm.connection_not_found — elle ne se rabat jamais sur une autre clé. Si la connexion appartient à un autre fournisseur, l’exécution échoue avec llm.connection_provider_mismatch.

Pour ce fournisseur, le champ Modèle est en pratique obligatoire : saisissez l’identifiant exact servi par votre serveur.

Sortie structurée

Quand un nœud attend une réponse structurée, Mankomail envoie le schéma JSON attendu sous forme de format de réponse json_schema non strict. Beaucoup de serveurs compatibles le prennent en charge ; si le vôtre ne le fait pas, la requête peut être refusée (llm.provider_rejected) ou la réponse ne pas correspondre. Mankomail tente une réparation sur une réponse illisible ; au-delà, l’étape échoue avec llm.invalid_json.

Pendant un essai

Un essai appelle le vrai modèle : vous voyez la catégorie, l’extraction ou le brouillon que le modèle produit réellement. Seules les actions irréversibles (envoi, déplacement, requêtes HTTP) sont simulées. Un appel d’essai coûte autant qu’en production et apparaît dans Usage et coûts de l’IA.

La sortie n’est fabriquée que si l’instance n’a aucun fournisseur utilisable — aucune connexion d’IA, ou un nœud fournisseur câblé vers un fournisseur non configuré. L’éditeur affiche alors « IA sautée : aucune clé sur cette instance », et l’effet de l’étape indique qu’aucun modèle n’aurait été appelé faute de fournisseur d’IA configuré. Quand un modèle peut être résolu, l’effet nomme le modèle que l’exécution emploierait réellement. La sortie fabriquée est la plus petite valeur conforme à la forme attendue : la première catégorie à vrai, les champs texte à simulated.

Les refus de politique ne sont pas masqués pendant un essai : un modèle non activé (llm.model_not_allowed), une connexion supprimée (llm.connection_not_found), un quota épuisé ou une panne du fournisseur font échouer l’essai exactement comme en production.

Coûts et données

Les appels sont comptés dans Usage et coûts de l’IA (appels et tokens, par jour, fournisseur, modèle et origine). La colonne de coût reste vide pour les modèles dont le tarif ne figure pas dans le catalogue intégré : un tarif inconnu s’affiche comme inconnu, jamais comme zéro.

Le contenu des e-mails traités par un nœud IA est envoyé au serveur que vous avez configuré ; la suite dépend de ce serveur.

Erreurs fréquentes

Les erreurs sont signalées par un code stable, que l’interface traduit. Sur la page Connexions, la raison d’un Tester ou d’une liste de modèles en échec s’affiche dans la carte du fournisseur, et les autres refus (enregistrement, suppression) dans un bandeau en haut de la section ; pendant une exécution, le code figure dans l’erreur de l’étape. Voir aussi Gestion des erreurs et rejeu et la référence des codes d’erreur.

Code	Cause	Que faire
llm.invalid_api_key	Le fournisseur a refusé la clé (HTTP 401 ou 403) : révoquée, mal copiée ou sans accès.	Créez une nouvelle clé chez le fournisseur, collez-la dans la carte, Enregistrer, puis Tester. L’exécution n’est pas retentée.
llm.rate_limited	Le fournisseur a répondu 429, 502, 503, 504 ou 529 (quota, crédits ou surcharge), ou la limite propre à l’instance (LLM_MAX_REQUESTS_PER_MINUTE, 60 appels par minute et par fournisseur par défaut) est atteinte.	Rien à faire pour un pic passager : l’étape est différée puis reprise sans consommer de tentative. Si cela dure, vérifiez votre quota ou vos crédits chez le fournisseur.
llm.timeout	Le fournisseur n’a pas répondu dans le délai LLM_REQUEST_TIMEOUT_MS (120 secondes par défaut).	Retenté automatiquement. Pour de longues rédactions sur un serveur lent, relevez le délai.
llm.provider_unavailable	Erreur réseau, ou autre réponse 5xx du fournisseur.	Retenté automatiquement avec un délai croissant. Vérifiez l’état du fournisseur si cela dure.
llm.provider_rejected	Le fournisseur a refusé la requête elle-même (HTTP 400, 404 ou 422) : identifiant de modèle inconnu, entrée trop longue, schéma refusé.	Vérifiez l’identifiant du modèle dans le nœud fournisseur ou les modèles activés. L’exécution n’est pas retentée.
llm.model_not_allowed	Le modèle nommé par le nœud n’est pas activé sur la connexion employée.	Cochez le modèle dans la carte, ou nommez un modèle activé dans le nœud fournisseur.
llm.no_default_model	Aucun modèle ne peut être choisi pour cet usage : pas de modèle recommandé chez ce fournisseur et aucun modèle activé. Également renvoyé par Tester quand il n’y a aucun modèle avec lequel tester.	Activez au moins un modèle sur la connexion, ou nommez le modèle dans le nœud fournisseur.
llm.no_provider_configured	Aucune connexion d’IA n’existe sur l’instance.	Un administrateur ajoute une connexion sur la page Connexions.
llm.provider_not_configured	Un nœud fournisseur est câblé vers un fournisseur sans connexion, ou le premier enregistrement est parti sans clé.	Configurez le fournisseur, ou câblez un nœud fournisseur d’un fournisseur configuré.
llm.connection_not_found	La connexion choisie dans le nœud fournisseur a été supprimée.	Choisissez une autre connexion dans le champ Connexion du nœud, puis republiez.
llm.connection_provider_mismatch	La connexion choisie dans le nœud appartient à un autre fournisseur que le nœud.	Choisissez une connexion du bon fournisseur, ou remplacez le nœud fournisseur.
llm.invalid_json	Le modèle a rendu un JSON inexploitable pour une sortie structurée, même après une réparation automatique.	Relancez, ou employez un modèle plus capable pour ce nœud.
llm.output_truncated	La réponse structurée a été coupée par le plafond de tokens de sortie.	Demandez moins, ou relevez LLM_DEFAULT_MAX_OUTPUT_TOKENS (4 096 par défaut).
llm.empty_output	Un modèle à raisonnement a consacré tout son budget au raisonnement et n’a rien écrit.	Relancez, ou employez un autre modèle pour ce nœud.
llm.content_refused	Le modèle a refusé de répondre à ce contenu.	Revoyez la consigne ou l’entrée. L’exécution n’est pas retentée.
llm.connection_in_use	Suppression refusée : des workflows publiés utilisent la connexion (leurs noms sont listés).	Changez d’abord leur connexion, ou confirmez la suppression une seconde fois.
llm.connection_is_default	Suppression refusée : c’est la connexion par défaut du fournisseur et d’autres existent.	Cliquez sur Mettre par défaut sur une autre connexion, puis supprimez celle-ci.
llm.connection_label_taken	Une autre connexion utilise déjà ce libellé.	Choisissez un autre libellé.
llm.encryption_disabled	L’instance n’a pas de ENCRYPTION_KEY : elle ne peut stocker aucun secret.	Définissez la variable et redémarrez l’instance.
llm.invalid_base_url	L’URL du serveur est absente ou mal formée, ou une URL a été envoyée pour un fournisseur dont l’adresse est fixe.	Saisissez l’URL complète, préfixe de version compris.

Nœuds qui utilisent cette connexion

• API compatible OpenAI — llm.openai_compatible