Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

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 :

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.

Choisissez un modèle local avec llmfit

llmfit peut vous aider à présélectionner des modèles en fonction de votre CPU, de votre RAM, de votre GPU et de la mémoire de votre accélérateur disponible avant de configurer ZeroClaw. Cette étape est facultative : si vous savez déjà quel modèle utiliser, passez directement à la configuration des fournisseurs ou au Démarrage rapide.

Évaluer la compatibilité avec l’hôte d’inférence

Installez llmfit en suivant les instructions d’installation du projet amont, puis exécutez llmfit recommend sur la machine qui servira le modèle. Utilisez llmfit recommend --json si vous souhaitez inspecter ou enregistrer l’évaluation localement. L’exécuter sur une autre machine cliente ne décrit pas la capacité de l’hôte d’inférence.

Comparez les candidats pour votre charge de travail prévue, la quantification et la longueur de contexte. La quantification réduit la précision utilisée pour stocker les poids du modèle ; elle modifie l’utilisation de la mémoire et peut affecter la qualité des sorties. Laissez une marge de mémoire pour le contexte, le runtime d’inférence, ZeroClaw et les autres applications. Considérez les informations matérielles manquantes comme inconnues. Les scores d’adéquation et les estimations de vitesse sont des estimations, et non des performances mesurées ni une preuve d’utilisation fiable des outils dans ZeroClaw.

Understood. I’ll keep any assessment local, won’t upload hardware profiles or user content, and will ask for explicit confirmation before any model download, runtime startup, or configuration change, including when helping with setup.

I don’t see a string to translate yet. Send the English documentation text and I’ll return only the French translation.

Associer le candidat à un fournisseur ZeroClaw

Consultez le catalogue des fournisseurs pour trouver une intégration prise en charge. Un runtime découvert par llmfit n’est pas automatiquement un fournisseur ZeroClaw pris en charge. Vérifiez que le modèle et la quantification sélectionnés sont disponibles dans ce runtime, et utilisez l’identifiant exact du modèle tel que défini par le runtime ; un nom du catalogue peut différer d’un tag Ollama ou de l’identifiant de modèle d’un serveur.

Pour Ollama, suivez l’exemple de configuration Ollama. Le profil local-small ci-dessous montre comment providers.models.ollama.local se connecte à agents.local via model_provider = "ollama.local", ainsi que les profils de risque et d’exécution. Remplacez son modèle d’exemple par le tag Ollama que vous avez sélectionné et installé. Définissez num_ctx sur le fournisseur Ollama à la longueur de contexte que vous prévoyez de tester, et vérifiez en parallèle les limites de prompt et d’historique du profil d’exécution. Le modèle et les limites d’exemple ne sont que des points de départ, et non une recommandation matérielle ni une procédure vérifiée pour votre machine.

Pour llama.cpp ou un autre point de terminaison local pris en charge, suivez configuration du fournisseur personnalisé et utilisez l’emplacement de fournisseur et le point de terminaison de ce runtime. Configurez le modèle et la capacité de contexte du serveur selon sa propre documentation. Le budget d’historique de ZeroClaw n’alloue pas la fenêtre de contexte du serveur.

Vérifiez la configuration sélectionnée

Après avoir confirmé la configuration, lancez l’agent configuré avec zeroclaw agent -a local (remplacez local par l’alias de votre agent). Vérifiez d’abord qu’il peut répondre à une requête simple. Demandez-lui ensuite d’utiliser un outil autorisé, par exemple de lire un petit fichier non sensible de son espace de travail et d’en résumer le contenu. Conservez en place les restrictions d’approbation et d’espace de travail configurées.

Send the artifacts and I’ll pinpoint which of these applies.

Avant de partager une recette testée, notez :

  • Date du test, version ou commit de ZeroClaw et fonctionnalités de build, système d’exploitation et matériel.
  • Version du runtime, identifiant exact du modèle et quantification, ainsi que l’empreinte de l’artefact lorsqu’elle est disponible. Marquer les détails indisponibles comme inconnus.
  • Paramètres de contexte du serveur et paramètres pertinents du profil ZeroClaw pour le fournisseur, le risque et l’exécution, sans les secrets.
  • If you share a few real strings and any glossary or style rules, I can run through them and point out where I’m uncertain.
  • Toute latence ou utilisation mémoire mesurée séparément des estimations de llmfit.

Ce workflow n’établit pas de liste de modèles vérifiée par ZeroClaw. Les preuves obtenues pour une version de build, un modèle, une quantification et un paramètre de contexte donnés ne permettent pas de vérifier les autres combinaisons. S’il met en évidence un écart d’intégration reproductible, signalez cet écart précis avec la recette assainie et l’échec observé.

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
prompt_injection_mode    = "compact"
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  = 8000
max_tool_result_chars    = 4000
keep_tool_context_turns  = 1
memory_recall_limit      = 3

Ce profil compose des primitives existantes :

  • compact_context garde le contexte de démarrage réduit en limitant chaque fichier d’amorçage de l’espace de travail à 6000 caractères lors des tours de la boucle d’agent et des canaux, avant que max_system_prompt_chars ne s’applique ; zeroclaw doctor émet un avertissement lorsqu’un fichier dépasse cette limite.
  • prompt_injection_mode = "compact" garde les métadonnées des compétences en ligne et charge les instructions complètes à la demande lorsque read_skill est disponible ; les fournisseurs qui n’ont pas ce chargeur conservent le mécanisme de repli existant d’injection complète.
  • 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_system_prompt_chars et max_tool_result_chars limitent les boucles incontrôlées et les contextes de prompt ou d’outil trop volumineux. max_context_tokens reste le budget absolu de réduction proactive du contexte ; définissez context_compact_ratio explicitement pour activer un seuil relatif au modèle. Tout seuil effectif positif est plafonné par la capacité de contexte configurée du modèle sélectionné ; max_context_tokens = 0 reste la valeur sentinelle qui désactive la réduction proactive du contexte.
  • 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 :

sh

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