Configuration multi-modèle

Présentation des schémas courants d’utilisation de plusieurs fournisseurs de modèles : routage par agent, routage par indication, niveaux de coût, priorité au local avec solution de secours hébergée, basculement vers un fournisseur sans diffusion en continu, gestion des limites de débit et reprise de la diffusion en continu.

Les références pour le système de fournisseur se trouvent dans :

• Fournisseurs de modèles → Vue d’ensemble : ce que sont les fournisseurs, structure de la configuration
• Fournisseurs de modèles → Routage : répartition des agents, routage par indication et basculement de fournisseur
• Fournisseurs de modèles → Catalogue : la structure de configuration de chaque fournisseur

Quand utiliser une configuration multimodèle

La configuration multi-modèles est utile pour :

1. Hiérarchisation des coûts : le modèle économique gère les canaux à fort volume ; le modèle de raisonnement gère les requêtes complexes
2. Routage des capacités : modèle doté de capacités de vision pour les canaux contenant des images, modèle de raisonnement pour les workflows de recherche
3. Développement local d’abord : Ollama local pour le développement, point de terminaison hébergé pour la production
4. Isolation par équipe : différentes équipes utilisent différents agents avec différents model_providers et identifiants
5. Gestion des limites de débit sans streaming : basculer vers un autre profil de fournisseur configuré après une erreur 429 réessayable

Idée centrale : répartition par agent

Chaque entrée [agents.<alias>] part d’une entrée [providers.models.<type>.<alias>]. Ce profil de fournisseur peut déclarer des modèles alternatifs avec fallback_models et d’autres profils de fournisseur avec fallback. Consultez Routage pour connaître le schéma complet.

Pour exécuter plusieurs modèles, exécutez plusieurs agents, chacun étant lié à un fournisseur de modèle. Chaque canal est lié à un seul agent à la fois. Pour déplacer un canal vers un autre agent, modifiez la liste channels de l’agent qui doit le prendre en charge ; Config::validate() vérifie que les références sont résolues au démarrage.

Fiabilité inter-fournisseurs

Pour les appels non-streaming, ZeroClaw peut parcourir un graphe de secours ordonné entre les profils de fournisseurs. Chaque profil de secours conserve son propre endpoint, ses identifiants, son modèle, ses en-têtes, ses surcharges de capacités et ses déclarations de secours imbriquées. L’environnement d’exécution réessaie ou passe au profil suivant selon la classification de l’erreur et l’état de temporisation du profil.

OpenRouter reste un fournisseur de premier ordre et peut effectuer la sélection du fournisseur derrière un point de terminaison unique. Il s’agit d’une couche de routage externe facultative, et non d’une exigence pour le mécanisme de secours natif de ZeroClaw.

Réessai et solution de repli sans streaming

Pour les erreurs transitoires telles qu’une défaillance réseau, 503 ou un dépassement de délai, un appel non diffusé effectue de nouvelles tentatives avec une temporisation exponentielle plafonnée, configurable globalement sous reliability (valeurs par défaut : 2 tentatives, temporisation initiale de 500 ms). Une fois les tentatives d’une entrée épuisées, l’enveloppe fiable passe aux fallback_models du profil et aux profils de secours.

Limite de récupération du flux

Un appel en streaming sélectionne la première entrée éligible qui n’est pas en période de refroidissement et qui prend en charge les capacités de streaming requises. Il ne passe pas à une autre entrée une fois ce flux démarré. Si le flux échoue avant que la sortie visible n’atteigne un consommateur immuable, l’environnement d’exécution réessaie l’appel complet via le chemin sans streaming, qui peut parcourir le graphe de repli. Dès qu’une sortie visible existe, l’environnement d’exécution conserve la réponse partielle et ne rejoue pas la requête ni ne change de fournisseur. Voir Cycle de vie du routage des fournisseurs pour consulter le contrat complet.

Limitation de la rotation des clés API

Ne vous appuyez pas sur reliability.api_keys pour le basculement des identifiants. En cas de limitation de débit permettant une nouvelle tentative, le wrapper fiable sélectionne et journalise une autre clé, mais le trait ModelProvider ne peut pas l’appliquer au fournisseur déjà construit. La nouvelle tentative utilise toujours l’identifiant d’origine. L’issue n° 9190 suit cette limitation.

Utilisez des profils de fournisseur distincts avec leurs propres identifiants, ou un service de routage externe, lorsque le basculement au niveau des identifiants est requis.

Développement local avec alternative hébergée

Exécutez un agent local-Ollama et un agent de fournisseur hébergé côte à côte ; routez chaque canal vers celui que vous souhaitez qu’il utilise.

L’agent dev s’exécute depuis la CLI (aucune liaison de canal requise, zeroclaw agent -a dev suffit). Lorsque Ollama est hors service, l’agent dev échoue rapidement et fait remonter l’erreur. Les canaux de prod ne sont pas affectés.

Profil local-small sans repli textuel

Les petits modèles locaux ont généralement besoin d’un profil d’exécution, et non d’un mode spécifique au fournisseur. Gardez le fournisseur Ollama concentré sur les détails de connexion, puis utilisez [runtime_profiles.<alias>] pour affiner le comportement de la boucle prompt/outil. ZeroClaw expose un préréglage d’exécution local_small intégré pour les chemins de code qui installent directement les préréglages d’exécution. Si vous modifiez la configuration manuellement, utilisez ce bloc équivalent :

[providers.models.ollama.local]
uri   = "http://localhost:11434"
model = "qwen2.5-coder:7b"

[agents.local]
model_provider  = "ollama.local"
risk_profile    = "supervised"
runtime_profile = "local_small"

[risk_profiles.supervised]
level                            = "supervised"
workspace_only                   = true
require_approval_for_medium_risk = true
block_high_risk_commands         = true

[runtime_profiles.local_small]
agentic                 = true
compact_context          = true
strict_tool_parsing      = true
max_tool_iterations      = 4
max_actions_per_hour     = 10
max_cost_per_day_cents   = 100
shell_timeout_secs       = 30
max_delegation_depth     = 1
delegation_timeout_secs  = 60
agentic_timeout_secs     = 120
max_history_messages     = 20
max_context_tokens       = 8000
parallel_tools           = false
max_system_prompt_chars  = 4000
max_tool_result_chars    = 4000
keep_tool_context_turns  = 1
memory_recall_limit      = 3

Ce profil compose des primitives existantes :

• compact_context maintient un contexte de démarrage réduit.
• strict_tool_parsing traite le texte de repli ressemblant à du XML/JSON comme du texte de l’assistant, sauf si le fournisseur renvoie des appels d’outils natifs.
• max_tool_iterations, max_context_tokens, max_system_prompt_chars et max_tool_result_chars limitent les boucles incontrôlées et les contextes de prompt/outil trop volumineux.
• max_actions_per_hour, max_cost_per_day_cents, et les champs timeout/delegation maintiennent les exécutions locales sur la même forme de budget que le préréglage intégré.
• parallel_tools = false et keep_tool_context_turns = 1 maintiennent les exécutions locales séquentielles et limitent le contexte d’outils retenu.

Avec Ollama, il s’agit d’un profil sans repli textuel : les outils autorisés restent configurés dans risk_profile, mais le balisage d’outils au format texte provenant du modèle n’est pas exécuté. Utilisez-le pour les agents locaux privilégiant le chat, ou pour les fournisseurs qui renvoient des appels d’outils natifs/structurés. Si un modèle local doit utiliser la syntaxe d’outils de repli textuel de ZeroClaw, définissez strict_tool_parsing = false et conservez les autres limites des petits modèles.

Hiérarchisation des coûts : modèle puissant si nécessaire, modèle rapide sinon

Exécutez deux agents et routez les canaux vers le niveau approprié. L’outil delegate permet à un agent d’en solliciter un autre en cours de conversation. La délégation est conditionnée : le profil de risque de l’appelant doit définir delegation_policy mode = "allow", et la cible doit être accessible depuis l’appelant (un pair du même profil, ou une entrée explicite dans la liste delegates de l’appelant). Les agents frontline et heavy ci-dessous s’exécutent sur le même profil de risque trusted, de sorte qu’ils s’atteignent mutuellement en tant que pairs du même profil ; ils diffèrent par le modèle et le profil d’exécution (budget d’itérations), non par la surface de confiance.

L’agent de première ligne traite chaque message entrant sur Haiku. Lorsqu’il a besoin d’un raisonnement plus approfondi, il appelle l’outil delegate avec agent = "heavy" ; comme les deux agents partagent le profil de risque trusted et que ce profil autorise la délégation, l’agent plus lourd prend en charge la sous-tâche sur Opus.

Gestion des erreurs en mode non streaming

Pour les appels sans streaming, les échecs réessayables incluent :

1. Timeout : le fournisseur n’a pas répondu dans le délai d’expiration configuré
2. Erreur de connexion : échec du réseau ou du DNS
3. Limitation de débit (429) : place temporairement le profil du fournisseur en période de refroidissement en mémoire et passe à l’entrée suivante lorsqu’une autre entrée existe
4. Service indisponible (503) : problème temporaire du service

Les nouvelles tentatives ne sont PAS déclenchées par :

1. Requête invalide (400) : entrée mal formée ; réessayer ne servira à rien
2. Échec d’authentification permanent : format de clé API non valide
3. Erreurs de sortie du modèle : le modèle a répondu mais a renvoyé une charge utile d’erreur

Lorsque toutes les entrées matérialisées sont épuisées ou en période de refroidissement, l’échec est propagé au canal appelant avec les échecs de tentative collectés.

Débogage

Les journaux persistants ("rolling" est la valeur par défaut) capturent les comportements de nouvelle tentative, de temporisation et de repli. Interrogez ensuite les traces :

zeroclaw doctor traces --contains réessayer
zeroclaw doctor traces --contains "429"
zeroclaw doctor traces --contains "model_provider"

Bonnes pratiques

1. Un agent par intention de routage. Si deux canaux nécessitent des comportements de modèle différents, nommez deux agents.
2. Attribuez explicitement la propriété aux profils de secours. Conservez chaque point de terminaison, identifiant d’authentification, modèle et remplacement de capacité dans le profil qui le fournit.
3. Traitez OpenRouter comme une couche de routage facultative. Utilisez-le lorsque la sélection du fournisseur côté serveur est utile ; utilisez les profils de secours de ZeroClaw lorsque l’environnement d’exécution doit gérer l’ordre.
4. Ne vous appuyez pas sur reliability.api_keys. Utilisez des profils construits séparément jusqu’à la résolution de l’issue #9190.
5. Testez chaque agent en isolation. zeroclaw agent -a <alias> exécute un agent sans la tuyauterie de canaux qui gêne.
6. Documentez l’intention de l’agent. Ajoutez des lignes # comment expliquant quels canaux chaque agent dessert et pourquoi.
7. Injectez les secrets via env, pas en inline. ZEROCLAW_providers__models__<type>__<alias>__api_key=... définit api_key au démarrage ; voir Variables d’environnement.
8. Séparez les agents dev et prod. Chaque environnement dispose de sa propre entrée [agents.<alias>] liée à ses propres canaux.

Résolution des informations d’identification

Chaque entrée de fournisseur résout les informations d’identification dans cet ordre :

1. api_key en ligne sur l’entrée du fournisseur.
2. Magasin de secrets dans ~/.zeroclaw/secrets.
3. Surcharge d’environnement générique : ZEROCLAW_providers__models__<type>__<alias>__api_key=... au démarrage. Si votre shell exporte déjà ANTHROPIC_API_KEY, OPENROUTER_API_KEY ou un nom par défaut de fournisseur similaire, reliez-le à cette variable miroir du schéma avant le démarrage, sauf si la famille de fournisseurs documente explicitement une passerelle d’environnement d’exécution native. Consultez Variables d’environnement pour la grammaire complète et des exemples de passerelles.

Les identifiants ne sont pas partagés entre les profils de fournisseurs ; définissez-les pour chaque profil. Une surcharge au niveau de la route model_routes[].api_key a une priorité supérieure lors de la construction de sa cible routée. Les cibles des routes sont dédoublonnées par model_provider ; ainsi, le premier identifiant de route correspondant peut construire le fournisseur partagé par plusieurs indications. Préférez les identifiants propres au profil lorsque les routes partagent une cible.

Documentation Connexe

• Fournisseurs de modèles → Aperçu
• Fournisseurs de modèles → Routage
• Variables d’environnement