Hermes Agent + llama.cpp : brancher un modèle local proprement

Hermes Agent est installé, la commande hermes répond, et tu as probablement déjà tapé deux ou trois messages avec un provider distant pour vérifier que tout tient debout. Bien. C’est le moment de lui brancher un vrai modèle local.

Ce tuto te donne le chemin le plus propre pour ça : un serveur llama.cpp, un modèle au format GGUF, un endpoint local compatible OpenAI, et Hermes qui pointe dessus. Pas de détour, pas de benchmark de modèles, pas de tunnel de flags avancés. Juste la chaîne qui marche, un premier test utile, et les erreurs qu’on voit revenir tout le temps.

Ce que tu auras à la fin
Un serveur llama-server qui tourne sur ta machine, un modèle GGUF chargé en mémoire, Hermes Agent configuré pour discuter avec cet endpoint local, et une première réponse qui vient vraiment de ta machine. À partir de là, tu es autonome.

Pour qui est ce tuto
Tu as déjà installé Hermes Agent en suivant le tuto précédent. Tu es à l’aise dans un terminal, tu sais ce qu’est une variable d’environnement, mais tu ne veux pas te taper une doc brute de 40 pages juste pour faire marcher la chaîne.

Ce qu’on branche exactement

Avant de taper une commande, pose-toi deux minutes sur la chaîne. C’est là que naissent la plupart des galères : on mélange des briques qu’on prend pour une seule.

Il y a quatre pièces, et chacune a un rôle distinct :

Le modèle : un fichier GGUF posé sur ton disque. C’est les poids. Seul, il ne fait rien.
Le runtime : llama.cpp, qui sait charger un GGUF, le faire tourner, et générer des tokens.
Le serveur : llama-server, fourni par llama.cpp, qui expose ce runtime derrière une API HTTP locale.
L’agent : Hermes Agent, qui n’a aucune idée de comment tourne ton modèle. Lui, il parle juste à un endpoint.

Quand tout est branché, la chaîne ressemble à ça :

GGUF → llama.cpp → llama-server → endpoint HTTP local → Hermes Agent

Le point important, c’est celui-ci : Hermes ne charge aucun modèle. Il consomme un endpoint. Depuis son point de vue, un modèle local ressemble à un provider distant avec une URL différente.

C’est pour ça que le branchement est propre : tu fais tourner ton modèle local d’un côté, et Hermes lui parle de l’autre comme à n’importe quelle API compatible OpenAI.

Garde cette séparation en tête tout le long. Elle explique presque tous les bugs que tu vas rencontrer.

Ce qu’il faut avant de commencer

Rapide inventaire avant de lancer quoi que ce soit.

Hermes Agent déjà installé via le chemin officiel.
llama.cpp installé ou compilé sur la machine.
Le binaire llama-server disponible dans ton terminal.
Un modèle GGUF déjà téléchargé ou prêt à l’être.
Un dossier propre pour ranger tes modèles.

Pas besoin d’une machine absurde pour valider la chaîne. Tu veux juste un modèle qui tourne de façon confortable.

Pour un premier test, le bon réflexe, c’est un modèle instruct raisonnable, en GGUF, dans une taille qui ne fait pas souffrir ta machine. Le but n’est pas d’impressionner Twitter. Le but, c’est de brancher proprement Hermes sur du local et de voir la boucle fonctionner.

Pourquoi llama.cpp est le chemin le plus propre

Tu pourrais brancher Hermes sur d’autres runtimes locaux. Mais llama.cpp reste le chemin le plus simple à expliquer et l’un des plus solides à utiliser.

Pourquoi :

le format GGUF est devenu une base très répandue
llama-server expose une API compatible OpenAI
la chaîne reste courte et lisible
il y a peu de plomberie inutile entre le modèle et l’agent

Concrètement, tu prends un GGUF, tu le lances avec llama-server, tu récupères un endpoint local du type http://127.0.0.1:8080/v1, et Hermes sait déjà parler à ça.

Moins il y a de briques entre toi et le modèle, moins il y a de trucs qui cassent.

Préparer le modèle local

Range ton GGUF dans un dossier dédié. Quelque chose comme ~/models/ suffit largement.

Quelques rappels simples :

un GGUF est un fichier de poids quantisés prêt à être consommé par llama.cpp
la quantisation joue directement sur le poids, la vitesse et le confort de ta machine
tous les modèles ne sont pas de bons choix pour débuter

Pour commencer, vise un modèle raisonnable, et pas trop lourd. Le bon critère n’est pas “le plus gros possible”. Le bon critère, c’est “ça répond vite, proprement, et je peux tester sans me battre contre la RAM ou la VRAM”.

Tu pourras changer de modèle après. Là, ce qu’on veut, c’est une chaîne propre.

Lancer le serveur llama.cpp

On passe au concret.

Ouvre un terminal, place-toi dans le bon contexte, et lance llama-server avec ton modèle :

llama-server -m /chemin/vers/ton-modele.gguf --port 8080

C’est la base. Tu charges le GGUF, tu ouvres un serveur local sur le port 8080, et tu exposes l’API.

Si tu as une machine avec GPU compatible et une build qui sait l’utiliser, tu peux demander explicitement un offload GPU complet :

llama-server -m /chemin/vers/ton-modele.gguf --port 8080 --n-gpu-layers all

Lis la sortie du terminal. Ne la laisse pas défiler en mode zombie. Tu dois voir le modèle se charger, puis le serveur écouter.

Le signal qu’on cherche, c’est simple : llama-server tourne, reste vivant, et écoute bien localement.

Laisse ce terminal ouvert.

Vérifier que le serveur répond vraiment

Avant même de lancer Hermes, vérifie que ton endpoint local est réellement en ligne.

Dans un deuxième terminal, fais :

curl http://127.0.0.1:8080/v1/models

Si tu récupères du JSON, c’est bon signe. Le serveur est joignable, l’API répond, et tu peux passer à la suite.

Si tu reçois une erreur de connexion, ne touche pas encore à Hermes. Le problème est plus bas dans la chaîne :

serveur non lancé
mauvais port
modèle mal chargé
binaire mal appelé

Tant que curl ne répond pas proprement, Hermes ne peut rien faire de bon.

Brancher Hermes Agent sur l’endpoint local

Côté Hermes, le chemin le plus propre pour un premier branchement, c’est la commande interactive.

Lance :

hermes model

Dans le sélecteur, choisis Custom endpoint.

Hermes va te demander les informations utiles. Selon la version, il peut sonder l’endpoint pour détecter le modèle ; sinon, renseigne celui exposé par /v1/models.

base URL : http://127.0.0.1:8080/v1
api key : vide si ton endpoint local n’en exige pas, ou une valeur explicite comme local-key si tu veux garder une convention claire
model : celui détecté par Hermes, ou celui renvoyé par /v1/models si le flow te le demande
context length : si Hermes te la demande, indique la fenêtre de contexte réellement exposée par ton endpoint, pas une valeur au hasard

Le point important ici, c’est l’URL. Ce n’est pas :

http://127.0.0.1:8080
ni http://127.0.0.1:8080/v1/chat/completions

C’est bien :

http://127.0.0.1:8080/v1

Une fois que c’est fait, Hermes persiste la configuration dans son dossier utilisateur.

Tu peux vérifier ce qu’il a enregistré avec :

hermes config show

Tu veux voir ton endpoint local ressortir clairement dans la config. Si ce n’est pas le cas, refais la sélection proprement au lieu de bricoler dans tous les sens.

Faire le premier test utile

Maintenant, on valide la boucle complète.

Lance une session :

hermes chat

Et demande quelque chose de simple mais réel. Pas juste “salut”. Par exemple :

explique-moi en trois phrases ce qu’est un scheduler
résume-moi la différence entre RAM et VRAM
donne-moi une explication simple du rôle d’un endpoint local

Ce que tu veux observer :

Hermes répond bien dans son terminal
le terminal de llama-server s’active au même moment
la réponse vient bien de ton modèle local

C’est ça le vrai test. Pas juste “la commande se lance”, mais “la chaîne complète fonctionne de bout en bout”.

Si tu veux pousser le contrôle un cran plus loin, regarde aussi l’activité machine pendant la requête avec tes outils habituels. Pas pour benchmarker. Juste pour confirmer que c’est bien ta machine qui travaille.

Les erreurs les plus fréquentes

C’est ici qu’on récupère l’essentiel des blocages.

Le serveur n’est pas réellement lancé

Tu pensais l’avoir lancé, mais tu as fermé le terminal, ou il est tombé au chargement du modèle.

Symptôme :

Hermes échoue immédiatement
curl http://127.0.0.1:8080/v1/models ne répond pas

Commence toujours par là.

Mauvais port

Tu as lancé llama-server sur un port, puis configuré Hermes sur un autre.

Erreur bête, très fréquente.

Mauvais endpoint

Tu as mis :

http://127.0.0.1:8080
ou http://127.0.0.1:8080/v1/chat/completions

au lieu de :

http://127.0.0.1:8080/v1

Ça suffit à casser tout le branchement.

Hermes parle encore à un provider distant

Tu pensais être passé en local, mais la config pointe encore ailleurs.

Symptôme classique :

Hermes répond
mais rien ne bouge côté llama-server

Là, il faut relire la config, pas accuser le modèle.

Modèle trop lourd

Tu as choisi un modèle trop gros pour ta machine.

Résultat :

chargement laborieux
réponse très lente
impression de bug alors que c’est juste un mauvais choix de départ

Redescends d’un cran. Tu valides la chaîne d’abord. Tu joueras au bras de fer matériel après.

Confusion entre modèle chargé et modèle accessible

Le serveur a bien chargé un modèle, mais Hermes ne pointe pas correctement dessus, ou tu as laissé une config incohérente.

Dans le doute :

vérifie /v1/models
vérifie hermes config show
relance un test simple

Lenteur prise pour un bug

Première requête, modèle fraîchement chargé, machine moyenne : ça peut prendre un peu de temps.

Ne redémarre pas tout au bout de trois secondes. Regarde les logs avant de paniquer.

Ce que tu ne dois pas faire

Quelques mauvaises idées classiques :

lancer un modèle énorme juste pour faire le malin
mélanger plusieurs endpoints dès le premier soir
changer cinq paramètres d’un coup
empiler modèle local + tools + config avancée dans la même session
benchmarker avant même d’avoir validé la chaîne

Le bon ordre est simple :

serveur local
endpoint qui répond
Hermes branché dessus
premier test utile
seulement après, le reste

La suite logique

Tu as maintenant un modèle local branché proprement à Hermes Agent. C’est une vraie base de travail.

La suite logique de la série, c’est le tuto sur la configuration de Hermes Agent :

comprendre ce que hermes model a réellement écrit
lire la config sans la subir
savoir quoi toucher, et quoi laisser tranquille
préparer proprement l’ajout des tools ensuite

D’ici là, le meilleur réflexe, c’est d’utiliser ton install telle quelle :

pose quelques vraies questions
regarde les logs
change éventuellement de modèle une fois
confirme que ta chaîne reste propre

Le plus important à ce stade, ce n’est pas d’empiler.
C’est de sentir que la base tient vraiment.