Un assistant qui répond, c'est bien. Un assistant qui agit (créer un rappel, lire un fichier, télécharger une librairie) passe par des appels d'outils : le modèle ne répond plus en texte, il émet une demande structurée que le client exécute. C'est là que Gemma 4 12B, servi par vLLM sur le serveur d'inférence de Sover.tech (une RTX 5060 Ti 16 Go), me donnait du fil à retordre.
Deux symptômes, sur deux agents différents (Nod, l'assistant personnel open source de n8n, et opencode) :
- le modèle appelait le mauvais outil, avec des arguments inventés, que le client refusait ;
- des appels pourtant corrects sortaient en texte brut dans la réponse, au lieu d'être exécutés. Sur un bench de génération de code long, la tâche s'arrêtait net au premier fichier à écrire.
Le réflexe serait de conclure que le modèle est trop petit. Ce n'était pas le cas. Les deux symptômes venaient de deux défauts distincts dans la chaîne entre le modèle et le client, aucun dans le modèle lui-même. Après correction : 69 % puis 97 % d'appels valides sur une vraie requête d'agent, et plus aucun appel en texte brut, sans changer de modèle ni de carte, et sans rien perdre en vitesse. Cet article raconte comment je les ai trouvés, avec les mesures.
Il prolonge la série sur Gemma 4 12B en production : l'anatomie du fichier de poids, les dimensions d'un modèle et pourquoi l'inférence est memory-bound. Ce dernier servira à la fin.
Le trajet d'un appel d'outil
Pour comprendre où ça casse, il faut suivre un appel d'outil de bout en bout. Il traverse quatre étapes, et seule la troisième est le modèle.
1. le client décrit ses outils en JSON Schema (nom, paramètres, valeurs permises)
2. le gabarit convertit ces schémas dans le format de Gemma, à l'intérieur du prompt
3. le modèle génère un appel avec ses jetons spéciaux
4. le parser de vLLM reconnaît ces jetons et les reconvertit en tool_calls JSON
Le format de Gemma 4 ne ressemble pas à du JSON. Un appel ressemble à ceci, où <|tool_call>, <tool_call|> et <|"|> (le délimiteur de chaîne) sont chacun un seul jeton spécial du vocabulaire, et pas une suite de caractères :
<|tool_call>call:manage_personal_context{action:<|"|>schedule_create<|"|>,args:{kind:<|"|>once<|"|>}}<tool_call|>
Le raisonnement du modèle, quand il est activé, est encadré de la même façon : <|channel>thought au début, <channel|> à la fin. Garder ces deux formats en tête suffit pour suivre la suite.
La méthode : mesurer, pas deviner
J'ai écarté trois fausses pistes avant de trouver, et chacune avait l'air plausible. Le parser de vLLM, d'abord : des tickets publics décrivent exactement ce genre de fuite. Le décodage spéculatif (MTP), ensuite : un ticket le désigne pour des arguments perdus en flux. Le tokenizer, enfin : Google a publié un correctif de « glitch tokens » que la version quantifiée servie n'avait pas. Les trois ont été écartés par une mesure, pas par un raisonnement.
Trois outils ont fait tout le travail.
- Voir ce que le modèle reçoit vraiment. vLLM expose
/tokenizeet/detokenize: on rend le prompt exactement comme le serveur le rend, outils compris, et on le lit. - Rejouer des requêtes réelles. Une requête de test bien propre ne reproduisait rien. Il a fallu capturer les vraies requêtes des agents (un petit relais HTTP local entre opencode et vLLM, et la journalisation des corps de requête côté vLLM le temps d'un essai), puis les rejouer des dizaines de fois.
- Reproduire hors ligne, dans le conteneur. Le parser de vLLM est du Python : on peut l'instancier dans le pod, avec le vrai tokenizer, et lui donner une séquence de jetons morceau par morceau. Un défaut aléatoire en production devient alors déterministe.
Premier défaut : le gabarit qui jette les schémas
Le symptôme
Une demande simple à Nod, « crée trois rappels », produisait des appels à l'outil skills avec une action schedule_create. Nod les refusait : skills n'accepte que list, read, save et patch. L'action schedule_create existe bien, mais sur un autre outil, manage_personal_context.
Ce que le modèle recevait
Le rendu de l'outil par vLLM, lu avec /detokenize, a tout expliqué :
declaration:skills{...,parameters:{properties:{action:{type:<|"|><|"|>},...
Un type vide, et aucune des quatre valeurs permises. Le modèle connaissait le nom schedule_create par le prompt système de l'agent, mais rien ne lui disait à quel outil il appartenait. Il devinait.
La cause est dans le gabarit de conversation (le fichier Jinja qui construit le prompt) publié par Google avec le modèle. Il convertit les schémas JSON dans le format de Gemma, mais ne connaît que le sous-ensemble de l'API Gemini : type, enum (pour les chaînes), nullable, items et properties. Tout le reste disparaît sans avertissement. Or ce « reste » est partout :
| Forme de schéma | Qui l'émet | Rendu par le gabarit d'origine |
|---|---|---|
anyOf de const | Zod (Nod, opencode), pour chaque liste de valeurs permises | type vide, valeurs perdues |
anyOf: [X, {type: null}] | serveurs MCP en Python, pour chaque paramètre optionnel | type vide |
type: ["string", "null"] | divers générateurs | un type illisible |
Sur une vraie requête de Nod, 12 outils sur 32 étaient touchés, dont le paramètre action de presque tous ses outils internes. Tous les paramètres optionnels du serveur MCP Nextcloud l'étaient aussi.
Le correctif
Pas besoin de toucher aux poids. vLLM accepte un gabarit externe avec --chat-template. J'ai copié celui de Google et réécrit une seule macro, format_parameters, pour qu'elle traduise ces formes dans le vocabulaire que le modèle connaît :
- un
anyOfde constantes devient unenum; - une branche
nulldisparaît et la propriété devientnullable; - une vraie union garde sa première branche (le format de Gemma n'a pas d'union) ;
- un type en liste garde son premier type non nul.
Le même outil, rendu par le gabarit corrigé :
action:{enum:[<|"|>list<|"|>,<|"|>read<|"|>,<|"|>save<|"|>,<|"|>patch<|"|>],type:<|"|>STRING<|"|>}
Le gabarit est livré dans une ConfigMap Kustomize, montée dans le pod vLLM. Le suffixe de hash de la ConfigMap relance vLLM à chaque modification. Un test unitaire rend le gabarit dans le même bac à sable Jinja que transformers (ImmutableSandboxedEnvironment) et vérifie deux choses : les formes réelles relevées sur Nod sont bien rendues, et un schéma classique sort au caractère près comme avec le gabarit d'origine. Rien ne doit changer pour ce qui marchait déjà.
La mesure
Pour comparer les deux gabarits sans autre variable, j'ai rendu le prompt moi-même avec chacun (après avoir vérifié que mon rendu local était identique, jeton pour jeton, à celui de vLLM), puis envoyé le prompt brut au modèle. Conversation neuve de Nod, son vrai prompt système et ses 32 outils, 32 tirages par gabarit :
| Gabarit | Appels valides | Refusés par le client | Aucun appel |
|---|---|---|---|
| Google, d'origine | 22 (69 %) | 6 | 4 |
| Corrigé | 31 (97 %) | 0 | 1 |
Un piège à connaître : une conversation déjà remplie d'appels refusés ne se répare pas toute seule. Rejouée telle quelle, elle restait à 0 appel valide, quel que soit le gabarit, parce que le modèle recopie ses propres échecs. Un message qui nomme explicitement l'outil et l'action la faisait passer à 12 sur 12.
Second défaut : l'appel qui sort en texte
Le symptôme
Le premier défaut corrigé, le modèle choisissait le bon outil. Mais de temps en temps, l'appel arrivait au client sous cette forme, dans le texte de la réponse :
thought
<channel|><|tool_call>call:webfetch{url:<|"|>https://...three.min.js<|"|>}<tool_call|>
Le client n'y voit pas d'appel, donc il n'exécute rien et considère la tâche terminée. Sur mon bench de génération d'un système solaire en three.js, les runs s'arrêtaient en moins d'une minute, au premier fichier à écrire.
Une fausse piste instructive
Ma première hypothèse : le modèle écrit parfois ses balises en texte ordinaire (les caractères <, |, tool_call...) au lieu du jeton spécial. Dans ce cas, le parser a raison de ne rien reconnaître, il ne doit pas déclencher d'appel quand le modèle parle de son propre format. L'hypothèse était testable : en demandant à vLLM les numéros de jetons générés (return_token_ids), on voit si <|tool_call> est le jeton 48 ou une suite de morceaux de texte. Verdict : sur des dizaines de tirages, toutes les balises étaient de vrais jetons spéciaux. Le modèle n'y était pour rien.
Le mécanisme
Les numéros de jetons ont révélé autre chose. Avant certains appels, Gemma 4 rouvre un second bloc de raisonnement, vide, juste après avoir fermé le premier : 5 tirages sur 12 sur une vraie requête d'opencode. Et le décodage spéculatif (MTP) livre jusqu'à trois jetons par morceau de flux. Dans toutes les fuites capturées, la séquence était la même :
morceau n [ ".", <channel|>, <|channel> ] fin ET début de bloc
morceau n+1 [ "thought", "\n", <channel|> ] rien n'est émis
morceau n+2 [ <|channel> ] sort en TEXTE
... puis l'appel entier part en texte
Le déclencheur : la fin d'un bloc et le début du suivant dans le même morceau. En les séparant artificiellement dans la reproduction hors ligne, tout rentrait dans l'ordre.
Restait à savoir quel composant perdait le fil. Les tickets publics accusaient le parser gemma4 de vLLM. Pourtant, rejouée dans la classe Gemma4Parser, la séquence exacte passait sans erreur. La clé était dans la façon dont vLLM assemble ses parsers. Avec --reasoning-parser gemma4 --tool-call-parser gemma4, vLLM v0.34.0 n'utilise pas Gemma4Parser directement : il compose un DelegatingParser générique, qui fait travailler deux instances séparées, l'une pour le raisonnement, l'autre pour les outils. Une dernière variable faisait basculer la reproduction : enable_thinking: true, que le serveur ajoute par défaut à toutes les requêtes. Avec elle, le parser composé échouait sur la séquence réelle, exactement comme en production, au même morceau. Sans elle, il passait.
Deux corrections possibles
Couper le MTP. Un jeton par morceau, la fin et le début d'un bloc ne tombent plus jamais ensemble. Mesuré : 0 fuite sur 20, alors que 15 tirages sur 20 rouvraient bien un bloc. Mais le prix est lourd. Comme expliqué dans l'article sur le memory-bound, la génération est limitée par la bande passante mémoire : le MTP valide plusieurs jetons par lecture des poids, et c'est lui qui donne la vitesse. Sans lui, la carte tombait de 84 à 46 jetons par seconde, soit 45 % de moins.
Changer de parser. vLLM fournit aussi un parser générique, hf, unifié (une seule instance pour le raisonnement et les outils) et piloté par un response_template déclaré dans la configuration du tokenizer. Google en a ajouté un au tokenizer de Gemma 4 en juillet 2026. Il décrit exactement le format :
"thinking": { "open": "<|channel>thought\n", "close": "<channel|>" },
"tool_calls": { "open_pattern": "<\\|tool_call>call:(?P<name>\\w+)",
"close": "<tool_call|>",
"content_args": { "string_delims": [["<|\"|>", "<|\"|>"]], "unquoted_keys": true },
"repeats": true }
La version quantifiée NVFP4 de RedHat que je sers n'a pas ce response_template. Elle porte un tokenizer antérieur. Mais vLLM permet de prendre le tokenizer dans un autre dépôt que les poids, avec --tokenizer. Avant de le faire, j'ai comparé les deux fichiers : mêmes 262 144 jetons aux mêmes numéros, mêmes jetons spéciaux. La seule différence porte sur 239 règles de fusion BPE retirées par Google (les fameux glitch tokens, des fragments de code source comme HDROffsets), qui ne servent qu'au découpage du texte en entrée et jamais à la génération. Les deux tokenizers sont donc interchangeables pour ces poids.
La mesure
Même requête réelle d'opencode (40 000 jetons de prompt), en flux, 20 tirages par configuration :
| Configuration | Appels sortis en texte | Débit |
|---|---|---|
parsers gemma4, MTP | 2 / 20 | 84 jetons/s |
parsers gemma4, sans MTP | 0 / 20 | 46 jetons/s |
parsers hf, tokenizer Google, MTP | 0 / 20 | 84 jetons/s |
Avant de valider, j'ai vérifié que le nouveau parser ne cassait rien d'autre. Une boucle d'agent qui enchaîne les appels passe 10 fois sur 10. Trois appels collés dans une même réponse, découpés en morceaux de 1 à 3 jetons, sont tous décodés. Et aucun appel ne se retrouve rangé par erreur dans le raisonnement. Les tirages sans appel s'arrêtaient tous sur ma limite de longueur de test, en plein raisonnement.
La configuration finale
Les poids ne changent pas, le MTP reste actif. Trois options et un fichier suffisent :
args:
- RedHatAI/gemma-4-12B-it-NVFP4
- --speculative-config
- '{"model":"google/gemma-4-12B-it-assistant","num_speculative_tokens":2}'
- --enable-auto-tool-choice
- --tool-call-parser
- hf
- --reasoning-parser
- hf
- --default-chat-template-kwargs
- '{"enable_thinking": true}'
- --chat-template
- /etc/vllm/chat-template/chat_template.jinja
- --tokenizer
- google/gemma-4-12B-it
Chacune de ces lignes est épinglée par un test sur le rendu Kustomize : parsers hf, tokenizer de Google, MTP présent, gabarit monté depuis la ConfigMap. La prochaine mise à jour ne pourra pas les perdre en silence.
Ce que j'en retiens
- Le modèle n'était pas en cause. Les deux défauts étaient dans la plomberie : un gabarit qui perd de l'information, et un assemblage de parsers fragile dans un cas précis. Changer de modèle n'aurait rien corrigé, et un modèle plus gros aurait seulement masqué une partie du premier.
- Regarder ce que le modèle reçoit.
/tokenizepuis/detokenize, avec les outils, prennent deux minutes et auraient évité des heures d'hypothèses. C'est le premier réflexe à avoir sur un agent qui se trompe d'outil. - Les requêtes de test propres mentent. Aucune de mes requêtes synthétiques ne reproduisait le second défaut. Il a fallu des requêtes réelles, longues, rejouées en nombre.
- Une option de performance peut changer le comportement fonctionnel. Le MTP n'a rien de faux, mais il change la forme du flux, et c'est un parser fragile qui en a fait les frais. Le couper aurait été une rustine coûteuse : il fallait trouver le vrai fautif.
- Épingler la configuration par des tests. Ces deux corrections tiennent en quatre lignes d'arguments. Sans test, une montée de version de vLLM ou une copie d'overlay les ferait disparaître sans bruit.
Le défaut du DelegatingParser mérite d'être signalé en amont, avec la séquence de jetons qui le reproduit à coup sûr. En attendant, le parser hf et le response_template de Google font le travail, sans rien coûter en vitesse.