Configurer les modèles dans Hermes Agent

Introduction

Configurer les modèles dans Hermes Agent est une décision d'exploitation, pas un réglage cosmétique : fenêtre de contexte, tool calling, latence, coût au million de tokens et disponibilité du fournisseur déterminent ce qu'un cron, un profil ou un agent va réellement pouvoir faire. Ce tutoriel est utile dès que vous voulez ajouter ou changer un fournisseur, brancher un endpoint local ou une chaîne de fallback, et tester la configuration avant un usage réel. Il est à éviter si vous n'avez pas installé Hermes (restez sur le guide d'installation) ou si vous voulez comparer des modèles hors Hermes. Une mauvaise configuration se paie en sessions qui s'arrêtent, en retries qui font grimper la facture, ou en outils qui échouent.

Résumé rapide

Étape	Commande ou fichier	Ce que vous apprenez
Identifier la couche	~/.hermes/config.yaml vs ~/.hermes/.env	où vit un modèle, où vit un secret
Choisir un fournisseur	hermes model (CLI) ou /model (session)	picker interactif, OAuth ou clé API
Valider la configuration	hermes doctor + une requête courte	signal de réussite et échec contrôlé
Endpoint local	bloc providers.<id> dans config.yaml	base_url, context_length, transport
Fallback explicite	hermes fallback ou fallback_providers:	chaîne ordonnée, modèles comparables
Isoler par profil	hermes --profile X --model Y	profil prod, profil expérimental, budget séparé

Comprendre les trois couches de configuration

Hermes sépare strictement les réglages non sensibles (modèle actif, terminal, compression, fallbacks, aliases), les secrets (clés API, tokens OAuth) et les identités longues (mémoire, skills, cron). ~/.hermes/config.yaml contient les réglages inspectables et modifiables sans risque : model.provider, model.default, model_aliases, fallback_providers, blocs auxiliary.*, blocs providers.*. Les secrets vivent dans ~/.hermes/.env. La règle de routage automatique de hermes config set est nette : tout nom en UPPER_SNAKE est traité comme variable d'environnement et écrit dans .env ; tout nom en dotted path va dans config.yaml. Une saisie ambiguë est refusée avec un message « did-you-mean ».

La précedence est verrouillée : (1) arguments CLI, (2) ~/.hermes/config.yaml, (3) ~/.hermes/.env, (4) défauts codés en dur. Un test ponctuel ne modifie donc jamais votre profil principal, et un cron démarré avec un modèle dédié n'écrasera pas votre modèle de chat. Pour le dire autrement : un changement de modèle dans une session déjà ouverte ne s'applique pas aux autres sessions ; il faut utiliser /model dans la session concernée pour basculer à chaud.

Choisir, configurer, tester et isoler un fournisseur

Le critère n'est pas « le meilleur modèle du moment », c'est « le modèle qui tient la charge prévue, au coût prévu, sur la fenêtre prévue ». Pour Hermes, quatre dimensions comptent : fenêtre de contexte (64 000 tokens est un plancher, visez 128 000+ pour les sessions longues), tool calling (testez sur vos cas réels, pas sur la pub du fournisseur), coût total (input vs output, retries après 429, prompt cache invalidé quand on change de modèle en pleine session — la relecture au tarif plein peut largement dépasser la différence de prix unitaire), et résidence des données (endpoint local ou fournisseur avec zone géographique explicite pour les charges sensibles).

Chemin court. hermes setup --portal active un OAuth chez Nous Portal, un fournisseur et les quatre outils du Tool Gateway (recherche web, image, TTS, navigateur) en une commande. Si Hermes est déjà installé, hermes model ouvre le picker interactif et écrit le résultat dans config.yaml sans redémarrage pour les nouvelles sessions.

Chemin clé API. hermes config set OPENROUTER_API_KEY sk-or-votre-clé (jamais dans le repo). Puis hermes model → « OpenRouter ». Pour un fournisseur direct (Anthropic, Google, xAI), la variable diffère (ANTHROPIC_API_KEY, GOOGLE_API_KEY, XAI_API_KEY).

Validation. Trois contrôles en cascade : hermes config get model.provider, hermes config get model.default, puis hermes doctor. Signal de réussite : hermes doctor se termine sans erreur et hermes -p "réponds OK" renvoie une réponse courte du modèle attendu. Scénario d'échec à tester : coupez la clé dans un terminal éphémère et relancez hermes doctor — vous devez voir une erreur d'authentification claire, pas un crash silencieux.

Endpoint local. Pour Ollama, vLLM, llama.cpp, LM Studio ou un proxy LiteLLM, le bloc canonique est providers.<id> dans config.yaml :

providers:
  my-ollama:
    api: http://localhost:11434/v1
    transport: openai_chat
    models:
      llama3.3:
        context_length: 128000

Le transport est presque toujours openai_chat ; passez en anthropic_messages uniquement si le proxy parle le protocole Anthropic natif. La clé est lue via key_env. Test progressif : chat court, sortie JSON, appel d'outil simple, session longue de 50 tours. N'empilez jamais de la configuration sur une base non validée. Pour la gouvernance des données, voyez LLM open source vs API fermée.

Fallback explicite. Le piège est qu'un modèle 8B local derrière Claude Opus donne une expérience dégradée sans message clair. Le fallback doit être explicite, testé et comparable en capacité. La commande hermes fallback réutilise le picker de hermes model ; les changements persistent sous fallback_providers: (voir l'exemple YAML dans la section Exemple concret). Trois règles : pas de fallback via variable d'environnement (« config.yaml ou rien ») ; ne masquez pas une erreur permanente ; chaîne courte (2 à 4 entrées) et comparable. Pour la continuité au niveau de l'agent, voyez Fallbacks pour agents IA.

Isolation par profil. Quand plusieurs charges coexistent, épinglez un modèle par profil pour tracer les coûts. Un profil est un répertoire ~/.hermes/profiles/<nom>/ indépendant. Pour démarrer : hermes --profile prod --model anthropic/claude-sonnet-4. Chaque profil voit ses ${VAR} résolues contre son propre .env. Séparez au minimum quatre charges : chat interactif (Sonnet / GPT-4.1), cron nocturne (GPT-4o-mini / Gemini Flash), agent délégué (budget séparé, plafond de concurrence), Bot Telegram (Sonnet pour l'UX réactive).

Diagnostic des erreurs fréquentes. Ne collez jamais une clé dans le chat, le repo, une capture ou un ticket ; si un secret fuit, révoquez-le immédiatement.

Code / symptôme	Cause probable	Contrôle rapide	Correction
401 Unauthorized	clé absente, mal copiée ou révoquée	hermes config get OPENROUTER_API_KEY	régénérer côté fournisseur, hermes config set
403 Forbidden	modèle non autorisé, région bloquée, scope manquant	dashboard du fournisseur	upgrader le plan ou changer de modèle
400 Bad Request sur context_length	prompt plus long que la fenêtre	réduire l'historique ou activer la compression	modèle à fenêtre plus large
429 Too Many Requests	quota de débit dépassé	vérifier la fenêtre de quota	ajouter un fallback, espacer, monter le tier
Outil appelé avec mauvais arguments	tool calling défaillant	essayer un autre modèle	ne pas utiliser ce modèle pour cette charge

Pour un diagnostic plus large, voyez Hermes Agent ne fonctionne pas : diagnostic.

Exemple concret

Contexte. Vous avez un profil prod qui sert un Bot Telegram d'assistance interne à une équipe de 12 personnes. Le modèle principal doit être fiable, le coût mensuel plafonné, et une coupure de 30 minutes du fournisseur principal doit rester transparente.

Mise en place du profil :

model:
  provider: openrouter
  default: anthropic/claude-sonnet-4
  switch_context_confirm_tokens: 100000

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4
  - provider: anthropic
    model: claude-sonnet-4-5
  - provider: nous
    model: nous-hermes-3

auxiliary:
  compression:
    provider: openrouter
    model: openai/gpt-4o-mini
  title_generation:
    provider: openrouter
    model: google/gemini-2.5-flash

Les clés sont écrites via hermes config set OPENROUTER_API_KEY ... et hermes config set ANTHROPIC_API_KEY ..., jamais à la main dans le repo.

Test du fallback. Dans une session de profil prod, pointez temporairement OPENROUTER_API_KEY sur une valeur invalide et envoyez une question simple. Vous devez observer : un message clair d'erreur 401 sur le premier fournisseur, une bascule automatique sur anthropic, une réponse en moins de 20 secondes. Vérifiez dans ~/.hermes/logs/errors.log quel fournisseur a répondu (secrets redactés automatiquement).

Checklist avant d'activer un cron sur ce profil : coût attendu par exécution vérifiable a posteriori dans le dashboard ; débit (RPM/TPM) avec marge par rapport au quota ; logs en place avec rotation et rétention ≥ 7 jours ; modèle effectif vérifié via hermes config get model.default dans le profil prod ; réponse livrée validée sur un cas réel et un cas d'échec contrôlé.

Bonnes pratiques

Un paramètre à la fois. Empiler fallback, changement de modèle et nouvelle clé rend tout diagnostic impossible en cas d'échec. Modifiez, testez, documentez, passez au suivant.

Session neuve pour valider. Une session déjà ouverte conserve le modèle avec lequel elle a démarré ; un changement dans config.yaml ne l'affecte pas. Ouvrez une nouvelle session ou utilisez /model à l'intérieur.

Surveiller le coût réel. Le piège d'une session longue est l'invalidation du prompt cache : changer de modèle en pleine conversation oblige le nouveau modèle à relire toute la conversation au tarif plein (input), sans le discount cache (75 à 90 %). Sur deux heures, cette relecture peut dépasser la différence de prix unitaire entre deux modèles. Si vous devez basculer, faites-le tôt.

Documenter. Un fichier MODELS.md à la racine du repo qui liste, par profil, quel modèle est utilisé et pourquoi évite les dérives (« on a mis Opus sur le cron de nuit sans s'en rendre compte »). Une ligne par surface.

Garder un repli simple. Si un petit workflow n'a pas besoin d'un modèle haut de gamme, ne le mettez pas sur un modèle haut de gamme. La complexité a un coût opérationnel que rien ne récupère quand la charge est faible.

Penser en surface, pas en modèle. « Le Bot Telegram utilise Sonnet via OpenRouter avec fallback Anthropic direct » décrit une surface ; « on utilise Sonnet » n'en est pas une. C'est cette description par surface qui permet de raisonner sur coûts, risques et SLAs.

Questions fréquentes

Comment changer le modèle dans une session déjà ouverte ?

Utilisez la commande slash /model dans la session (CLI, TUI ou gateway Telegram/Discord). Le changement prend effet immédiatement. hermes model hors session n'affecte que les nouvelles sessions. Au-delà d'un certain seuil de tokens en contexte, Hermes affiche un avertissement avant de basculer, parce que la relecture du cache invalidé peut coûter cher ; ajustez ce seuil via model.switch_context_confirm_tokens dans config.yaml.

Où mettre une clé API : config.yaml ou .env ?

Dans .env, toujours. La règle de routage de hermes config set est automatique : tout nom en UPPER_SNAKE va dans .env ; les chemins en dotted notation vont dans config.yaml. Si une clé apparaît dans config.yaml, retirez-la, révoquez-la et régénérez-la.

Peut-on utiliser un modèle local Ollama dans Hermes ?

Oui. Configurez un bloc providers.<id> dans config.yaml avec api: http://localhost:11434/v1, transport: openai_chat, et la liste des modèles. Pour de la production, vLLM ou SGLang offrent de meilleures garanties qu'Ollama sur un seul GPU. Pour un daemon loopback sans clé, omettez simplement key_env.

Que se passe-t-il si mon fournisseur principal tombe ?

Si vous avez configuré fallback_providers (via hermes fallback ou directement dans config.yaml), Hermes bascule automatiquement sur le suivant de la chaîne. La condition est que la chaîne soit comparable en capacité ; sinon, l'utilisateur verra une dégradation brutale de qualité sans message clair. Testez la chaîne au moins une fois en environnement jetable avant de faire confiance au fallback en production.

Comment garder mes clés secrètes sur plusieurs machines ?

Une clé par machine, dans ~/.hermes/.env, versionnée en local mais jamais dans Git. Pour les déploiements d'équipe, utilisez les secrets de votre plateforme (Vercel, GitHub Actions, Vault) et référencez-les via ${VAR} dans config.yaml. Les organisations peuvent aller plus loin avec le Managed Scope, qui permet à un administrateur de poser des valeurs que l'utilisateur standard ne peut pas écraser.

Articles liés

Le bon modèle est celui qui tient votre charge au bon coût, pas celui qui brille dans un classement. Gardez trois choses en tête : testez chaque fournisseur sur un cas réel avant de le mettre en production, isolez les charges par profil pour tracer les coûts, et documentez vos choix — un futur vous (ou un collègue) doit pouvoir comprendre pourquoi prod utilise Sonnet et pas Opus. Pour aller plus loin, voyez l'installation si vous partez de zéro, l'architecture générale du produit, le diagnostic en cas de panne, et la couche routeur OpenRouter pour absorber les variations de prix entre fournisseurs.

• Installer Hermes Agent pas à pas
• Hermes Agent : guide pour builders IA
• Hermes Agent ne fonctionne pas : diagnostic
• OpenRouter pour agents IA
• LiteLLM vs OpenRouter
• LLM open source vs API fermée pour agents