Fournisseurs

verbatra livre cinq fournisseurs derrière une seule interface : Anthropic, OpenAI, Gemini et openai-compatible (un serveur compatible OpenAI, local ou auto-hébergé) sont des grands modèles de langage, et DeepL est un service de traduction automatique. Tu en sélectionnes un dans le bloc provider de ta configuration, par id. Chaque identifiant de modèle sur cette page est un exemple, pas une recommandation : les catalogues de modèles changent, donc vérifie la liste actuelle de ton fournisseur.

Lequel choisir ?

Tout fournisseur fonctionne avec tout format et toute commande ; le choix porte sur le coût, la qualité, la confidentialité, et la façon d'obtenir une clé.

• Petit projet ou projet perso, tu le veux gratuit ? Utilise Gemini. Il a une vraie offre d'API gratuite, donc tu peux traduire une appli entière à coût zéro. Récupère une clé sur Google AI Studio et définis GEMINI_API_KEY. L'offre gratuite est limitée en débit (voir la note plus bas), ce qui ne compte que sur une grosse première exécution.
• La meilleure qualité de traduction pour une appli en production ? Utilise Anthropic ou OpenAI. Les deux sont des LLM payants et lisent ANTHROPIC_API_KEY ou OPENAI_API_KEY.
• Gros volume, piloté par glossaire, ou pas de LLM dans la boucle ? Utilise DeepL. C'est une API de traduction automatique dédiée avec une offre gratuite et une payante, et elle prend en charge un glossaire natif par id. Elle ne traduit pas les chaînes portant des placeholders (voir la note plus bas) ; pour celles-là, utilise un fournisseur LLM.
• Hors ligne, sans coût, ou tes chaînes ne doivent jamais quitter ton réseau ? Utilise openai-compatible. Il pointe verbatra vers un serveur d'inférence local ou auto-hébergé (LM Studio, Ollama, vLLM) au lieu d'une API hébergée. Pas de compte, pas de clé d'API, et aucune sortie réseau au-delà de ta machine ou de ton LAN.

Pas sûr ? Commence sur l'offre gratuite de Gemini, puis change de fournisseur plus tard en modifiant un seul id dans ta configuration. Rien d'autre ne change.

Les clés viennent de l'environnement

verbatra ne lit jamais une clé d'API depuis la configuration. Chaque fournisseur hébergé lit exactement une variable d'environnement :

Définis la variable dans .env (que verbatra init ajoute au .gitignore) ou exporte-la dans ton shell ou le coffre de secrets de ta CI. Quand la variable est absente ou vide, le fournisseur échoue avec une erreur structurée MISSING_API_KEY dont le message nomme la variable mais n'inclut jamais une valeur de clé. Ne commite jamais une vraie clé.

openai-compatible est différent : la plupart des serveurs locaux n'ont besoin d'aucune clé, donc il n'est pas dans ce tableau. Voir sa propre section plus bas pour le fonctionnement de sa résolution de clé.

Anthropic

provider: {
  id: "anthropic",
  options: {
    model: "claude-sonnet-4-6", // example model id
    maxTokens: 4096,
  },
}

Lit ANTHROPIC_API_KEY. model et maxTokens sont tous deux requis. maxTokens plafonne les tokens qu'une seule réponse peut produire ; c'est l'option de limite de tokens de sortie de ce fournisseur (les autres l'appellent maxOutputTokens).

OpenAI

provider: {
  id: "openai",
  options: {
    model: "gpt-5.4-mini", // example model id
    maxOutputTokens: 4096,
  },
}

Lit OPENAI_API_KEY. model et maxOutputTokens sont tous deux requis.

Gemini

provider: {
  id: "gemini",
  options: {
    model: "gemini-2.5-flash", // example model id
    maxOutputTokens: 4096,
  },
}

Lit GEMINI_API_KEY. model et maxOutputTokens sont tous deux requis.

DeepL

provider: {
  id: "deepl",
  options: {},
}

Lit DEEPL_API_KEY. DeepL est une API de traduction automatique, pas un LLM : il n'a pas de champ model et pas de limite de tokens de sortie. La seule option est un glossaryId optionnel nommant un glossaire que tu as déjà créé dans DeepL :

provider: {
  id: "deepl",
  options: {
    glossaryId: "<your-glossary-id>",
  },
}

DeepL se dégrade en douceur au lieu d'échouer quand il ne peut pas honorer un réglage, et rapporte chaque dégradation comme un avis sur l'exécution :

• Une carte de termes glossary configurée n'est pas appliquée (DeepL n'utilise qu'un id de glossaire pré-créé), rapporté comme GLOSSARY_IGNORED.
• tone se mappe sur la formalité de DeepL : formal devient plus formel, informal devient moins formel, neutral ou un ton absent est omis. Sur une clé de l'offre gratuite, la formalité n'est pas prise en charge, donc un ton non par défaut se dégrade vers le défaut, rapporté comme FORMALITY_DOWNGRADED.

openai-compatible

Pointe verbatra vers un serveur qui parle l'API Chat Completions d'OpenAI : LM Studio, Ollama, vLLM et similaires fonctionnent tous. L'id nomme le protocole réseau, pas l'endroit où le serveur tourne, donc une API hébergée qui parle le même protocole rentre ici aussi.

provider: {
  id: "openai-compatible",
  options: {
    baseUrl: "http://192.168.178.74:1234/v1",
    model: "qwen2.5-14b-instruct", // example: whatever your server exposes
    maxOutputTokens: 1024,
  },
}

baseUrl, model et maxOutputTokens sont requis. Contrairement à tout autre fournisseur, baseUrl vit dans la configuration plutôt que dans l'environnement : c'est une adresse réseau que tu connais déjà (une IP LAN ou localhost), pas un secret. Elle doit être une URL absolue valide avec le schéma http ou https ; tout le reste, y compris un schéma manquant, fait échouer la validation de la configuration immédiatement.

baseUrl doit inclure le segment de chemin d'API de ton serveur, typiquement /v1 : LM Studio, Ollama et vLLM servent tous leurs routes compatibles OpenAI sous /v1. Un baseUrl sans lui reste une URL syntaxiquement valide, donc il passe la validation de configuration et échoue à la place au moment de la requête en atteignant le mauvais chemin.

Une API hébergée qui parle le même protocole fonctionne de la même façon. L'API de chat completions de Mistral en est un exemple :

provider: {
  id: "openai-compatible",
  options: {
    baseUrl: "https://api.mistral.ai/v1",
    model: "mistral-large-latest", // example: check Mistral's current model list
    maxOutputTokens: 4096,
    apiKeyEnvVar: "MISTRAL_API_KEY",
  },
}

apiKeyEnvVar nomme la variable d'environnement contenant ta clé pour ce serveur. C'est le même fournisseur openai-compatible pointé vers un autre point d'accès, pas un fournisseur Mistral dédié.

Les clés sont optionnelles

La plupart des serveurs d'inférence locaux n'ont besoin d'aucune clé d'API, donc openai-compatible résout sa clé en trois niveaux, dans l'ordre :

1. apiKeyEnvVar, un champ de configuration optionnel nommant une variable d'environnement où lire une vraie clé. Si tu définis ce champ et que la variable nommée est absente ou vide, verbatra échoue avec MISSING_API_KEY au lieu de retomber en silence, puisque tu as explicitement dit qu'une clé est requise.
2. OPENAI_COMPATIBLE_API_KEY, une variable d'environnement de convention, lue quand apiKeyEnvVar n'est pas défini. Si elle est définie et non vide, verbatra l'utilise ; sinon, verbatra continue sans erreur.
3. Le placeholder "local", envoyé quand aucun des deux niveaux ci-dessus ne résout quoi que ce soit. C'est une chaîne fixe, non secrète, pas une vraie clé, et c'est exactement ce qui fait qu'un serveur local sans clé fonctionne sans aucune configuration.

apiKeyEnvVar ne peut jamais nommer ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY ou DEEPL_API_KEY : la validation de configuration rejette ça d'emblée, donc une configuration ne peut pas pointer ce fournisseur vers la clé d'un fournisseur hébergé par son nom. Le client ne lit jamais non plus OPENAI_API_KEY lui-même et passe toujours une valeur de clé explicite au SDK sous-jacent, donc une clé hébergée ne peut jamais atteindre un baseUrl personnalisé.

Choisir un modèle local

Préfère un modèle ajusté par instructions, sans raisonnement et avec une bonne couverture multilingue. verbatra demande un unique objet JSON strict et le valide, donc tu veux un modèle qui suit de façon fiable les consignes de format. qwen2.5-14b-instruct est un choix par défaut raisonnable ; prends le plus grand modèle de ce type que ton matériel exécute bien.

Un mauvais modèle local échoue bruyamment, pas en silence : verbatra valide chaque réponse du fournisseur contre un schéma canonique ainsi que l'intégrité des placeholders et ICU, donc un modèle qui émet de la prose de raisonnement ou du JSON tronqué est rejeté avec une erreur INVALID_RESPONSE ou OUTPUT_TRUNCATED au lieu d'écrire une traduction corrompue.

Analyse tolérante pour les modèles locaux et plus petits

openai-compatible demande le même format de réponse strict et contraint par schéma que le fournisseur hébergé openai. La seule différence est au retour : les modèles locaux et plus petits ont plus tendance à envelopper une réponse par ailleurs correcte dans de la prose ou une clôture de code Markdown malgré la consigne contraire, donc openai-compatible extrait le premier objet JSON équilibré n'importe où dans la réponse avant l'analyse, là où le fournisseur hébergé ne le fait pas. Sa sortie passe quand même par exactement la même validation de schéma et les mêmes contrôles d'intégrité des placeholders et ICU que tout autre fournisseur : la sortie d'un modèle local est une entrée non fiable, et une réponse malformée ou aux placeholders discordants est rejetée de la même façon.

Ton et glossaire selon les fournisseurs

Les champs de configuration optionnels tone et glossary (voir Fichier de configuration) sont appliqués par fournisseur :

• Ton. Les fournisseurs LLM (Anthropic, OpenAI, Gemini et openai-compatible) reçoivent le ton avec la requête et ont pour instruction de le respecter. DeepL le mappe sur la formalité, avec la dégradation de l'offre gratuite décrite plus haut.
• Glossaire. Les fournisseurs LLM reçoivent la carte de termes et ont pour instruction de traiter ses termes comme contraignants. DeepL ignore une carte de termes (avec un avis GLOSSARY_IGNORED) et applique uniquement son glossaryId natif.

Comportement partagé par chaque fournisseur

Découpage en lots

Le travail d'une locale est découpé en sous-lots séquentiels d'au plus maxBatchSize entrées (50 par défaut ; voir Fichier de configuration), pour qu'une requête trop grosse ne puisse pas faire échouer toute la locale. Un sous-lot échoué est retenu et retenté automatiquement à l'exécution suivante pendant que les autres sous-lots avancent quand même. DeepL découpe en plus un sous-lot en autant de requêtes que ses propres plafonds par requête l'exigent, de façon transparente.

Nouvelles tentatives

Les échecs transitoires (une réponse de limite de débit ou une erreur serveur) sont retentés automatiquement avec un court backoff : les clients SDK d'OpenAI, d'Anthropic et de DeepL retentent par défaut, et verbatra ajoute une nouvelle tentative équivalente de son cru pour Gemini, dont le SDK ne le fait pas. Les nouvelles tentatives lissent des accrocs momentanés ; un échec durable remonte quand même comme une erreur structurée.

Erreurs structurées

Un échec de fournisseur ne remonte jamais comme une erreur SDK brute, qui pourrait porter des en-têtes de requête ou une clé. verbatra classe chaque échec selon son statut HTTP ou sa classe d'erreur SDK et lève une erreur structurée avec un code stable et un message fixe, sans secret :

Un échec n'affecte que son propre sous-lot : les clés échouées sont retenues et reprises à l'exécution suivante.

Limites de tokens de sortie

Les quatre fournisseurs LLM plafonnent le nombre de tokens qu'une seule réponse peut produire. Quand un modèle s'arrête parce qu'il a atteint ce plafond, verbatra lève OUTPUT_TRUNCATED au lieu d'un échec générique de réponse malformée, avec un message fixe :

The provider stopped because the output-token limit was reached. Reduce the batch size or raise the configured max output tokens.

Chacun des deux leviers le résout : baisse maxBatchSize dans ta configuration pour que chaque requête produise une réponse plus petite, ou augmente le plafond par réponse du fournisseur (maxTokens pour Anthropic, maxOutputTokens pour OpenAI, Gemini et openai-compatible). DeepL n'est pas concerné : il n'a pas de cas de troncature de tokens de sortie. verbatra se rétablit aussi de lui-même : quand un sous-lot est tronqué, il le redivise en moitiés et réessaie, en descendant jusqu'à une seule entrée, de sorte que les clés qui tiennent dans une requête plus petite sont quand même traduites et que seule une entrée isolée qui déborde encore est retenue pour la prochaine exécution.

Signalements de révision

Les traductions acceptées de chaque fournisseur passent par les mêmes contrôles post-traduction, et un résultat suspect (par exemple un résultat identique à sa source, ou qui a manqué un terme de glossaire) est signalé dans la file de révision plutôt que rejeté. Les codes de raison et la façon de traiter la file sont couverts dans Sûreté de la traduction et Réviser les traductions dans Studio.