BroadRouter
Loslegen

Tool Calling mit offenen Modellen: Schemas, parallele Aufrufe, Retries

Vom Team von BroadNet Inference · 4 Min. Lesezeit · Veröffentlicht · Aktualisiert

Offene Modelle auf OpenAI-kompatiblen APIs nutzen dasselbe Format mit tools und tool_calls wie OpenAI. Halten Sie Schemas klein und flach, parsen Sie Argumente als JSON-Strings, validieren Sie sie, bevor etwas ausgeführt wird, und geben Sie Fehler als Tool-Ergebnis an das Modell zurück, damit es neu versuchen kann. Begrenzen Sie die Schritte. Bei BroadNet ist Tool-Unterstützung für GLM 5.3 und Qwen3.8 27B gelistet.

Tool Calling macht aus einem Modell einen Agenten. Mit offenen Modellen auf einer OpenAI-kompatiblen API ist das Anfrageformat dasselbe, das Sie auch bei OpenAI verwenden würden. Unterschiedlich ist, wie oft etwas schiefgeht und was der Server tut, um es zu verhindern. Dieser Beitrag behandelt das Format, wie Sie Schemas schreiben, mit denen offene Modelle gut zurechtkommen, parallele Aufrufe, die fünf Fehler, die Ihnen tatsächlich begegnen, und eine Python-Schleife, die sie übersteht.

Wie funktioniert Tool Calling auf einer OpenAI-kompatiblen API?

  1. Sie senden messages plus eine tools-Liste. Jedes Tool hat einen Namen, eine Beschreibung und ein JSON Schema für seine Argumente.
  2. Das Modell antwortet mit finish_reason: "tool_calls" und einer tool_calls-Liste. Jeder Eintrag hat eine id, einen Funktionsnamen und arguments als JSON-String.
  3. Ihr Code führt jeden Aufruf aus und hängt pro Aufruf eine Nachricht mit role: "tool" und der passenden tool_call_id an.
  4. Sie rufen die API erneut auf. Das Modell antwortet oder fordert weitere Tools an.

Das Modell führt nie etwas aus. Ihr Code entscheidet, was ausgeführt wird.

Wie sollten Sie Tool-Schemas schreiben?

Offene Modelle halten sich zuverlässiger an einfache Schemas. Diese Regeln stammen aus dem Leitfaden von OpenAI und aus dem, was erfahrungsgemäß bricht:

  • Benennen Sie Tools nach der Aktion, etwa read_file oder search_code, und sagen Sie in der Beschreibung, wann jedes zu nutzen ist.
  • Halten Sie die Liste kurz. Der Leitfaden von OpenAI nennt weniger als 20 Funktionen zu Beginn eines Zugs als weiche Empfehlung. Jedes Schema wird außerdem bei jedem Aufruf mitgesendet; siehe das Token-Budget von Agenten.
  • Bevorzugen Sie flache Argumente. Strings, Zahlen, Booleans und Enums. Vermeiden Sie tiefe Verschachtelung und freie Objekte.
  • Nutzen Sie Enums für feste Auswahlwerte, damit das Modell keinen Wert erfinden kann. Der JSON-Schema-Generator macht aus einem Beispielobjekt mit Argumenten ein flaches Schema, das Sie in parameters einfügen können.
  • Markieren Sie Pflichtfelder. Der Strict Mode von OpenAI verlangt additionalProperties: false und jedes Feld in required, mit null als zusätzlichem Typ für optionale Felder. Ob ein Anbieter strict durchsetzt, ist unterschiedlich, validieren Sie also trotzdem.

Was ist mit parallelen Tool Calls?

Ein Modell kann in einem Zug mehrere Einträge in tool_calls zurückgeben, zum Beispiel drei Dateizugriffe. Führen Sie unabhängige Aufrufe parallel aus und geben Sie ein Ergebnis pro tool_call_id zurück, in beliebiger Reihenfolge. Haben Ihre Tools Seiteneffekte, die voneinander abhängen, setzen Sie parallel_tool_calls: false; laut dem Leitfaden von OpenAI beschränkt das das Modell auf keinen oder einen Aufruf pro Zug. Testen Sie, ob Ihr Anbieter das beachtet.

Warum scheitern Tool Calls?

Fehler Was Sie sehen Lösung
Fehlerhafte Argumente json.loads wirft eine Ausnahme Parse-Fehler als Tool-Ergebnis zurückgeben; Retry
Schema-Abweichung Fehlendes Feld, falscher Typ, erfundener Enum-Wert Validieren; Validierungsfehler zurückgeben
Unbekanntes Tool Ein Name, den Sie nie definiert haben „unknown tool, available: …“ zurückgeben
Kein Aufruf, obwohl nötig Stattdessen eine Textantwort tool_choice: "required" oder eine benannte Funktion
Abgeschnittener Aufruf finish_reason: "length" max_tokens erhöhen; Reasoning teilt sich das Limit

Die ersten beiden sind zu erwarten, nicht selten. Die Tool-Calling-Doku von vLLM sagt, dass im Modus auto, sofern kein Tool strict: true setzt (oder der Server eine Mindest-Strenge erzwingt) und der Parser des Modells Constraints unterstützt, gilt: „vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.“ (Übersetzung: „vLLM extrahiert Tool Calls aus Rohtext, daher können Argumente gelegentlich fehlerhaft sein oder das Parameter-Schema der Funktion verletzen.“) Eine benannte Funktion nutzt das Structured-Outputs-Backend von vLLM. Ihr Anbieter kann Modelle anders bereitstellen, behandeln Sie die Validierung also als Pflicht.

Die letzte Zeile erwischt alle, die Reasoning-Modelle nutzen. GLM 5.3 und Qwen3.8 27B denken nach, bevor sie antworten, und das Thinking zählt zu max_tokens. Warum Antworten leer oder abgeschnitten zurückkommen erklärt, wie viel Platz Sie lassen sollten.

Eine Tool-Schleife mit Validierung und Retry

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")

Drei Designentscheidungen sind hier wichtig:

  1. Fehler gehen als Tool-Ergebnis an das Modell zurück. Das Modell sieht, was falsch war, und behebt es meist im nächsten Zug. Eine Ausnahme zu werfen verschenkt diese Chance.
  2. Die Schleife ist begrenzt. max_steps stoppt ein Modell, das ohne Fortschritt immer weiter Tools aufruft.
  3. Transport-Retries sind getrennt. max_retries am Client behandelt 429 und 5xx. Falsche Argumente werden in der Schleife behandelt. Vermischen Sie beides nicht; siehe Fehler und Retries.

Für Tools mit Seiteneffekten, etwa dem Versand einer E-Mail, ergänzen Sie einen Idempotenzschlüssel, damit ein wiederholter Schritt nicht doppelt handelt. Lang laufende Agenten behandelt das.

Welche BroadNet-Modelle unterstützen Tool Calling?

Modell Tools gelistet Kontext Hinweise
GLM 5.3 Ja 1.048.576 Auch strukturierte Ausgabe
Qwen3.8 27B Ja 262.144 Auch Bildeingabe
DeepSeek V4.1 Flash Nicht gelistet 1.048.576 Bildeingabe; Tools vor dem Einsatz testen
Gemma 4 VL 26B Nicht gelistet 32.768 Nicht für Tool-Schleifen

Für die Wahl zwischen den beiden Modellen mit Tool-Unterstützung siehe GLM 5.3 vs. Qwen3.8 27B. Muss die endgültige Antwort einer Form entsprechen, ohne dass eine Funktion laufen muss, ist strukturierte Ausgabe einfacher als ein Tool.

Wo BroadNet Inference ins Bild passt

BroadNet Inference stellt GLM 5.3 und Qwen3.8 27B mit gelistetem Tool Calling über das Standardformat für Chat Completions bereit, sodass die Schleife oben unverändert mit dem OpenAI Python SDK läuft. Die Preise pro Token stehen auf der Preisseite. BroadNet hostet keine serverseitigen Tools wie Websuche oder Codeausführung, und die Doku listet kein Tool Calling für DeepSeek V4.1 Flash, das Modell der unbegrenzten Pläne. Für einen Agenten mit vielen Tool-Aufrufen nutzen Sie GLM 5.3 oder Qwen3.8 27B pro Token. Wenn Sie trotzdem die Flatrate wollen, prüfen Sie mit einer Meteor-Stunde für $1, ob DeepSeek V4.1 Flash Ihre Tools zuverlässig aufruft, bevor Sie einen Monat kaufen.

Häufige Fragen

Unterstützen offene Modelle Function Calling?

Viele ja, aber das hängt vom Modell ab und davon, wie der Anbieter es bereitstellt. Bei BroadNet Inference listet die Doku Tool Calling für GLM 5.3 und Qwen3.8 27B, nicht aber für DeepSeek V4.1 Flash oder Gemma 4 VL 26B.

Warum sind die Argumente meiner Tool Calls ungültiges JSON?

Solange der Server das Dekodieren nicht einschränkt, werden Argumente als Text erzeugt und danach geparst. Laut vLLM-Doku können aus Rohtext extrahierte Argumente gelegentlich fehlerhaft sein. Fangen Sie den Parse-Fehler ab und senden Sie ihn als Tool-Ergebnis zurück, damit das Modell sich korrigieren kann.

Wie schalte ich parallele Tool Calls ab?

Setzen Sie im OpenAI-Format parallel_tool_calls auf false. Dann ruft das Modell pro Zug höchstens ein Tool auf. Prüfen Sie, ob Ihr Anbieter das Feld beachtet.

Warum antwortet das Modell mit Text, statt ein Tool aufzurufen?

Mit tool_choice auto entscheidet das Modell selbst. Setzen Sie tool_choice auf required oder auf eine bestimmte Funktion, wenn ein Aufruf Pflicht ist. Prüfen Sie außerdem, ob die Tool-Beschreibung sagt, wann es zu nutzen ist.

Warum wird mein Tool Call abgeschnitten?

Reasoning-Modelle rechnen das Thinking auf max_tokens an. Ein kleines Limit kann die Antwort mitten in den Argumenten beenden. Prüfen Sie finish_reason und erhöhen Sie max_tokens.

Als Markdown lesenChatGPT fragenClaude fragenPerplexity fragen