BroadRouter
Commencer

Appel d’outils et modèles ouverts : schémas, parallélisme, relances

Par l’équipe BroadNet Inference · 4 min de lecture · Publié · Mis à jour

Les modèles ouverts servis par des API compatibles OpenAI utilisent le même format tools et tool_calls qu’OpenAI. Gardez des schémas petits et plats, parsez les arguments comme des chaînes JSON, validez-les avant d’exécuter quoi que ce soit et renvoyez les erreurs au modèle comme résultats d’outil pour qu’il réessaie. Plafonnez le nombre d’étapes. Chez BroadNet, GLM 5.3 et Qwen3.8 27B indiquent la prise en charge des outils.

L’appel d’outils est ce qui transforme un modèle en agent. Avec des modèles ouverts sur une API compatible OpenAI, le format de requête est celui que vous utiliseriez avec OpenAI. Ce qui change, c’est la fréquence des ratés et ce que fait le serveur pour les éviter. Cet article couvre le format, la façon d’écrire des schémas que les modèles ouverts gèrent bien, les appels parallèles, les cinq échecs que vous rencontrerez vraiment et une boucle Python qui y résiste.

Comment fonctionne l’appel d’outils sur une API compatible OpenAI ?

  1. Vous envoyez messages et une liste tools. Chaque outil a un nom, une description et un JSON Schema pour ses arguments.
  2. Le modèle répond avec finish_reason: "tool_calls" et une liste tool_calls. Chaque entrée comporte un id, un nom de fonction et des arguments sous forme de chaîne JSON.
  3. Votre code exécute chaque appel et ajoute un message role: "tool" par appel, avec le tool_call_id correspondant.
  4. Vous rappelez l’API. Le modèle répond ou demande d’autres outils.

Le modèle n’exécute jamais rien. C’est votre code qui décide de ce qui s’exécute.

Comment écrire des schémas d’outils ?

Les modèles ouverts suivent plus fiablement des schémas simples. Ces règles viennent du guide d’OpenAI et de ce qui casse en pratique :

  • Nommez les outils par action, comme read_file ou search_code, et dites dans la description quand utiliser chacun.
  • Gardez la liste courte. Le guide d’OpenAI présente le seuil de moins de 20 fonctions au début d’un tour comme une suggestion souple. Chaque schéma est en outre envoyé à chaque appel ; voir le budget de tokens d’un agent.
  • Préférez des arguments plats. Chaînes, nombres, booléens et enums. Évitez l’imbrication profonde et les objets libres.
  • Utilisez des enums pour les choix fixes, afin que le modèle ne puisse pas inventer de valeur. Le générateur de JSON Schema transforme un objet d’arguments d’exemple en schéma plat à coller dans parameters.
  • Marquez les champs obligatoires. Le mode strict d’OpenAI exige additionalProperties: false et tous les champs dans required, avec null comme type pour les champs facultatifs. L’application de strict varie selon les fournisseurs : validez de toute façon.

Et les appels d’outils parallèles ?

Un modèle peut renvoyer plusieurs entrées dans tool_calls en un seul tour, par exemple trois lectures de fichiers. Exécutez les appels indépendants en parallèle et renvoyez un résultat par tool_call_id, dans n’importe quel ordre. Si vos outils ont des effets de bord qui dépendent les uns des autres, réglez parallel_tool_calls: false ; selon le guide d’OpenAI, cela limite le modèle à zéro ou un appel par tour. Vérifiez que votre fournisseur le respecte.

Pourquoi les appels d’outils échouent-ils ?

Échec Ce que vous voyez Correctif
Arguments mal formés json.loads lève une exception Renvoyer l’erreur de parsing comme résultat d’outil ; relancer
Non-conformité au schéma Champ manquant, mauvais type, enum inventé Valider ; renvoyer l’erreur de validation
Outil inconnu Un nom que vous n’avez jamais défini Renvoyer « unknown tool, available: … »
Pas d’appel alors qu’il en faut un Une réponse en texte à la place tool_choice: "required" ou une fonction nommée
Appel coupé finish_reason: "length" Augmenter max_tokens ; le raisonnement le partage

Les deux premiers sont attendus, pas rares. La documentation de vLLM sur l’appel d’outils indique qu’en mode auto, sauf si un outil définit strict: true (ou si le serveur impose un niveau minimal de rigueur) et que le parseur du modèle prend en charge les contraintes, « vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema. » (traduction : « vLLM extrait les appels d’outils du texte brut, si bien que les arguments peuvent parfois être mal formés ou enfreindre le schéma de paramètres de la fonction. ») Une fonction nommée passe par le backend de structured outputs de vLLM. Votre fournisseur peut servir les modèles autrement : considérez la validation comme obligatoire.

La dernière ligne piège ceux qui utilisent des modèles de raisonnement. GLM 5.3 et Qwen3.8 27B réfléchissent avant de répondre, et la réflexion compte dans max_tokens. Pourquoi les réponses reviennent vides ou coupées explique quelle marge laisser.

Une boucle d’outils qui valide et relance

import json, os
from openai import OpenAI
from jsonschema import validate, ValidationError

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
MODEL = "broadnet/glm-5.3"

TOOLS = [{"type": "function", "function": {
    "name": "get_order_status",
    "description": "Look up one order by its ID. Use when the user asks where an order is.",
    "parameters": {"type": "object",
                   "properties": {"order_id": {"type": "string"}},
                   "required": ["order_id"], "additionalProperties": False}}}]
SCHEMAS = {t["function"]["name"]: t["function"]["parameters"] for t in TOOLS}
IMPL = {"get_order_status": lambda order_id: f"Order {order_id}: shipped"}

def run_call(call):
    name = call.function.name
    if name not in IMPL:
        return f"Error: unknown tool {name}. Available: {', '.join(IMPL)}"
    try:
        args = json.loads(call.function.arguments or "{}")
        validate(args, SCHEMAS[name])
    except (json.JSONDecodeError, ValidationError) as e:
        return f"Error: invalid arguments ({e}). Send the call again with valid JSON."
    return str(IMPL[name](**args))

def agent(messages, max_steps=8):
    for _ in range(max_steps):
        r = client.chat.completions.create(model=MODEL, messages=messages,
                                           tools=TOOLS, max_tokens=4000)
        msg = r.choices[0].message
        if r.choices[0].finish_reason == "length":
            raise RuntimeError("Output limit reached; raise max_tokens")
        messages.append(msg.model_dump(exclude_none=True))
        if not msg.tool_calls:
            return msg.content
        for call in msg.tool_calls:
            messages.append({"role": "tool", "tool_call_id": call.id,
                             "content": run_call(call)})
    raise RuntimeError("Step limit reached")

Trois choix de conception comptent ici :

  1. Les erreurs reviennent au modèle comme résultats d’outil. Le modèle voit ce qui n’allait pas et le corrige généralement au tour suivant. Lever une exception gâche cette occasion.
  2. La boucle est bornée. max_steps arrête un modèle qui enchaîne les appels d’outils sans progresser.
  3. Les relances réseau sont séparées. max_retries sur le client gère les 429 et les 5xx. Les mauvais arguments sont gérés dans la boucle. Ne mélangez pas les deux ; voir erreurs et relances.

Pour les outils à effets de bord, comme l’envoi d’un e-mail, ajoutez une clé d’idempotence pour qu’une étape relancée n’agisse pas deux fois. Les agents de longue durée traitent ce point.

Quels modèles BroadNet prennent en charge l’appel d’outils ?

Modèle Outils indiqués Contexte Remarques
GLM 5.3 Oui 1 048 576 Aussi sortie structurée
Qwen3.8 27B Oui 262 144 Aussi entrée image
DeepSeek V4.1 Flash Non indiqué 1 048 576 Entrée image ; testez les outils avant d’en dépendre
Gemma 4 VL 26B Non indiqué 32 768 Pas pour des boucles d’outils

Pour choisir entre les deux modèles qui gèrent les outils, voir GLM 5.3 vs Qwen3.8 27B. Quand la réponse finale doit respecter une forme sans qu’aucune fonction n’ait besoin de s’exécuter, la sortie structurée est plus simple qu’un outil.

La place de BroadNet Inference

BroadNet Inference sert GLM 5.3 et Qwen3.8 27B, pour lesquels l’appel d’outils est indiqué, via le format standard des chat completions : la boucle ci-dessus tourne sans modification avec le SDK Python d’OpenAI. Les prix au token figurent sur la page des prix. BroadNet n’héberge pas d’outils côté serveur comme la recherche web ou l’exécution de code, et sa documentation n’indique pas l’appel d’outils pour DeepSeek V4.1 Flash, le modèle des forfaits illimités. Pour un agent très dépendant des outils, utilisez GLM 5.3 ou Qwen3.8 27B au token. Si vous voulez quand même le forfait, vérifiez sur une heure Meteor à $1 que DeepSeek V4.1 Flash appelle vos outils de façon fiable avant d’acheter un mois.

Questions fréquentes

Les modèles ouverts prennent-ils en charge le function calling ?

Beaucoup, oui, mais cela dépend du modèle et de la façon dont le fournisseur le sert. Chez BroadNet Inference, la documentation indique l’appel d’outils pour GLM 5.3 et Qwen3.8 27B. Elle ne l’indique pas pour DeepSeek V4.1 Flash ni pour Gemma 4 VL 26B.

Pourquoi les arguments de mes appels d’outils sont-ils du JSON invalide ?

Tant que le serveur ne contraint pas le décodage, les arguments sont générés comme du texte puis parsés. La documentation de vLLM indique que des arguments extraits du texte brut peuvent parfois être mal formés. Interceptez l’erreur de parsing et renvoyez-la comme résultat d’outil pour que le modèle se corrige.

Comment désactiver les appels d’outils parallèles ?

Dans le format OpenAI, réglez parallel_tool_calls sur false. Le modèle est alors limité à zéro ou un appel d’outil par tour. Vérifiez que votre fournisseur respecte ce champ.

Pourquoi le modèle répond-il en texte au lieu d’appeler un outil ?

Avec tool_choice auto, c’est le modèle qui décide. Réglez tool_choice sur required, ou sur une fonction précise, quand un appel est obligatoire. Vérifiez aussi que la description de l’outil dit quand l’utiliser.

Pourquoi mon appel d’outil est-il coupé ?

Les modèles de raisonnement comptent la réflexion dans max_tokens. Une limite basse peut interrompre la réponse au milieu des arguments. Vérifiez finish_reason et augmentez max_tokens.

Lire en MarkdownDemander à ChatGPTDemander à ClaudeDemander à Perplexity