Comment donner des outils à un modèle dont le template lit xml_tools (SmolLM3)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

# Comment donner des outils à un modèle dont le template lit `xml_tools` (SmolLM3)

Ce guide montre comment faire appeler les outils de mm par un modèle comme SmolLM3. Sa fiche dit qu'il sait appeler des outils, mais à travers mm il n'en appelle jamais : il décrit la commande au lieu de la lancer. Il suppose que vous avez déjà un fichier d'agent pour ce modèle (écrit par `mm init`, par exemple).

## Pourquoi ça ne marche pas par défaut

mm envoie ses outils dans le champ `tools` de l'API OpenAI, et llama-server (derrière llmman, Ollama, DMR…) les transmet au chat template du modèle sous ce nom. Le template de SmolLM3 ne lit jamais `tools` : il lit `xml_tools` (l'argument de `apply_chat_template(xml_tools=…)` dans l'exemple de sa fiche). Le modèle ne voit donc aucun outil. Quand on lui donne `xml_tools`, il répond par l'appel sous forme de texte — `<tool_call>{"name": "bash", "arguments": {"command": "ls"}}</tool_call>` — que le serveur ne transforme pas en appel d'outil.

## Étapes

1. Dans le fichier de l'agent, ajoutez :

   ```yaml
   toolFormat: xml_tools
   ```

   mm envoie alors les outils dans `chat_template_kwargs.xml_tools`, réécrit les appels précédents dans l'historique sous forme de texte `<tool_call>` (le template n'affiche un message que par son texte), et transforme les blocs `<tool_call>` de la réponse en appels d'outils — en streaming ou non. Ils n'apparaissent pas dans le texte de la réponse.

2. Coupez le raisonnement — le template de SmolLM3 l'active par défaut :

   ```yaml
   sampling:
     chat_template_kwargs:
       enable_thinking: false
   ```

   Avec le raisonnement activé, SmolLM3-3B répète son appel après la réponse de l'outil au lieu de répondre (mesuré : 3 essais sur 3 ; sans raisonnement, 6 sur 6 ont répondu).

3. Lancez `mm` et demandez quelque chose qu'un outil sait faire : `List the files of this directory.` Une ligne `🛠️  bash: ls`, la sortie de la commande en dessous et le compteur `⚙ 1 command(s)` montrent que l'appel a eu lieu.

## Variantes

- **Un nouvel agent.** Pour la famille `smollm3`, `mm init` fait les deux étapes : il écrit `toolFormat: xml_tools` quand l'usage a des outils, et `enable_thinking: false` quel que soit l'usage, avec une note en fin de fichier.
- **Un usage sans outils** (`translator`, `json`) : rien à faire, `toolFormat` ne change rien sans outils.
- **Voir ce qui passe sur le réseau.** Avec `trace: {enabled: true}`, les fichiers de requête montrent `chat_template_kwargs.xml_tools` et aucun `tools` ; les fichiers de réponse montrent le texte `<tool_call>` brut du serveur, avant que mm ne le lise. Voir [Comment voir le JSON envoyé au modèle](inspect-model-traffic.md).
- **Un appel cassé.** Un `<tool_call>` dont le JSON est coupé (par `max_tokens`) ou mal formé est rendu au modèle avec une note, comme pour tout modèle, du moment que le nom de l'outil se lit ; sinon il reste dans le texte de la réponse.

## Limites

- Les tâches en plusieurs étapes restent fragiles avec SmolLM3-3B : pendant les essais, il a parfois pris la sortie d'un outil pour une phrase de l'utilisateur (le template affiche la réponse d'un outil comme un message de l'utilisateur). Entourer cette sortie de balises `<tool_response>` n'a rien changé de mesurable.
- Le `common/chat.cpp` de llama.cpp ne traitait pas SmolLM3 à part au moment où ce guide a été écrit (13 novembre 2026), et le llama-server de llmman n'analysait pas ces appels : d'où le travail fait du côté de mm.

## Voir aussi

- La clé : [Référence de la configuration](../reference/configuration.md) (`toolFormat`)
- Couper le raisonnement sur d'autres serveurs : [Comment couper le raisonnement d'un modèle](turn-reasoning-off.md)
- D'où viennent les chiffres de `smollm3` : [Explication de `mm init`](../explanation/mm-init.md)