BroadRouter
Inizia

Tool calling con modelli aperti: schemi, chiamate parallele, retry

A cura del team di BroadNet Inference · 4 min di lettura · Pubblicato · Aggiornato

I modelli aperti sulle API compatibili con OpenAI usano lo stesso formato tools e tool_calls di OpenAI. Tieni gli schemi piccoli e piatti, tratta gli argomenti come stringhe JSON, validali prima di eseguire qualsiasi cosa e restituisci gli errori al modello come risultati dei tool, così può riprovare. Limita i passaggi. Su BroadNet, GLM 5.3 e Qwen3.8 27B dichiarano il supporto ai tool.

Il tool calling è ciò che trasforma un modello in un agente. Con i modelli aperti su un’API compatibile con OpenAI, il formato della richiesta è lo stesso che useresti con OpenAI. Cambiano la frequenza con cui le cose vanno storte e ciò che il server fa per evitarlo. Questo articolo copre il formato, come scrivere schemi che i modelli aperti gestiscono bene, le chiamate parallele, i cinque fallimenti che vedrai davvero e un ciclo Python che li supera.

Come funziona il tool calling su un’API compatibile con OpenAI?

  1. Invii messages più una lista tools. Ogni tool ha un nome, una descrizione e uno JSON Schema per i suoi argomenti.
  2. Il modello risponde con finish_reason: "tool_calls" e una lista tool_calls. Ogni voce ha un id, un nome di funzione e arguments come stringa JSON.
  3. Il tuo codice esegue ogni chiamata e aggiunge un messaggio role: "tool" per chiamata, con il tool_call_id corrispondente.
  4. Chiami di nuovo l’API. Il modello risponde o chiede altri tool.

Il modello non esegue mai nulla. È il tuo codice a decidere cosa eseguire.

Come scrivere gli schemi dei tool?

I modelli aperti seguono in modo più affidabile gli schemi semplici. Queste regole vengono dalla guida di OpenAI e da ciò che tende a rompersi:

  • Dai ai tool nomi d’azione, come read_file o search_code, e scrivi nella descrizione quando usare ciascuno.
  • Tieni la lista corta. La guida di OpenAI presenta le meno di 20 funzioni all’inizio di un turno come un suggerimento, non una regola rigida. Ogni schema viene anche inviato a ogni chiamata; vedi il budget di token di un agente.
  • Preferisci argomenti piatti. Stringhe, numeri, booleani ed enum. Evita annidamenti profondi e oggetti a forma libera.
  • Usa gli enum per le scelte fisse, così il modello non può inventare un valore. Il generatore di JSON schema trasforma un oggetto di argomenti di esempio in uno schema piatto da incollare in parameters.
  • Segna i campi obbligatori. La modalità strict di OpenAI richiede additionalProperties: false e ogni campo in required, con null come tipo per quelli facoltativi. Non tutti i provider impongono strict, quindi valida comunque.

E le chiamate parallele ai tool?

Un modello può restituire più voci in tool_calls nello stesso turno, per esempio tre letture di file. Esegui in parallelo le chiamate indipendenti e restituisci un risultato per ogni tool_call_id, in qualsiasi ordine. Se i tuoi tool hanno effetti collaterali che dipendono l’uno dall’altro, imposta parallel_tool_calls: false; la guida di OpenAI dice che così il modello è limitato a zero o una chiamata per turno. Verifica che il tuo provider lo rispetti.

Perché le chiamate ai tool falliscono?

Fallimento Cosa vedi Soluzione
Argomenti malformati json.loads solleva un’eccezione Restituisci l’errore di parsing come risultato del tool; riprova
Schema non rispettato Campo mancante, tipo sbagliato, enum inventato Valida; restituisci l’errore di validazione
Tool sconosciuto Un nome che non hai mai definito Restituisci “unknown tool, available: …”
Nessuna chiamata quando serve Una risposta testuale tool_choice: "required" o una funzione specifica
Chiamata tagliata finish_reason: "length" Alza max_tokens; il ragionamento lo condivide

I primi due sono attesi, non rari. La documentazione di vLLM sul tool calling dice che in modalità auto, a meno che un tool non imposti strict: true (o il server imponga un livello minimo di rigore) e il parser del modello supporti i vincoli, «vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.» (traduzione: vLLM estrae le chiamate ai tool dal testo grezzo, quindi gli argomenti possono occasionalmente essere malformati o violare lo schema dei parametri della funzione). Una funzione specifica usa il backend structured-outputs di vLLM. Il tuo provider può servire i modelli in modo diverso, quindi considera la validazione obbligatoria.

L’ultima riga sorprende chi usa i modelli di ragionamento. GLM 5.3 e Qwen3.8 27B ragionano prima di rispondere, e il thinking conta in max_tokens. Perché le risposte tornano vuote o tagliate spiega quanto margine lasciare.

Un ciclo di tool che valida e riprova

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

Qui contano tre scelte di design:

  1. Gli errori tornano al modello come risultati dei tool. Il modello vede cosa non andava e di solito lo corregge al turno successivo. Sollevare un’eccezione butta via questa possibilità.
  2. Il ciclo è limitato. max_steps ferma un modello che continua a chiamare tool senza fare progressi.
  3. I retry di trasporto sono separati. max_retries sul client gestisce 429 e 5xx. Gli argomenti sbagliati si gestiscono nel ciclo. Non mescolare le due cose; vedi errori e retry.

Per i tool con effetti collaterali, come l’invio di un’email, aggiungi una chiave di idempotenza così un passaggio ripetuto non agisce due volte. Lo spiega agenti a lunga esecuzione.

Quali modelli BroadNet supportano il tool calling?

Modello Tool dichiarati Contesto Note
GLM 5.3 Sì 1.048.576 Anche output strutturato
Qwen3.8 27B Sì 262.144 Anche input di immagini
DeepSeek V4.1 Flash Non dichiarato 1.048.576 Input di immagini; prova i tool prima di farci affidamento
Gemma 4 VL 26B Non dichiarato 32.768 Non adatto ai cicli di tool

Per scegliere tra i due modelli con i tool, vedi GLM 5.3 vs Qwen3.8 27B. Quando la risposta finale deve avere una certa forma ma non serve eseguire nessuna funzione, l’output strutturato è più semplice di un tool.

Dove si inserisce BroadNet Inference

BroadNet Inference serve GLM 5.3 e Qwen3.8 27B con il tool calling dichiarato, tramite il formato standard chat completions, quindi il ciclo qui sopra gira senza modifiche con l’SDK Python di OpenAI. I prezzi per token sono nella pagina dei prezzi. Non offre tool lato server come la ricerca web o l’esecuzione di codice, e la sua documentazione non indica il tool calling per DeepSeek V4.1 Flash, il modello dei piani illimitati. Per un agente che usa molto i tool, usa GLM 5.3 o Qwen3.8 27B a token. Se vuoi comunque il piano flat, verifica con un’ora Meteor a $1 che DeepSeek V4.1 Flash chiami i tuoi tool in modo affidabile prima di comprare un mese.

Domande frequenti

I modelli aperti supportano il function calling?

Molti sì, ma il supporto dipende dal modello e da come il provider lo serve. Su BroadNet Inference la documentazione indica il tool calling per GLM 5.3 e Qwen3.8 27B. Non lo indica per DeepSeek V4.1 Flash né per Gemma 4 VL 26B.

Perché gli argomenti delle mie chiamate ai tool sono JSON non valido?

Se il server non vincola la decodifica, gli argomenti vengono generati come testo e parsati dopo. La documentazione di vLLM dice che gli argomenti estratti dal testo grezzo possono occasionalmente essere malformati. Intercetta l’errore di parsing e rimandalo come risultato del tool, così il modello può correggersi.

Come disattivo le chiamate parallele ai tool?

Nel formato OpenAI imposta parallel_tool_calls a false. Così il modello è limitato a zero o una chiamata per turno. Verifica che il tuo provider rispetti il campo.

Perché il modello risponde con del testo invece di chiamare un tool?

Con tool_choice auto decide il modello. Imposta tool_choice a required, o a una funzione specifica, quando la chiamata è obbligatoria. Controlla anche che la descrizione del tool dica quando usarlo.

Perché la mia chiamata al tool è tagliata?

I modelli di ragionamento contano il thinking in max_tokens. Un limite basso può chiudere la risposta a metà degli argomenti. Controlla finish_reason e alza max_tokens.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity