Un modello di ragionamento pensa prima di rispondere, e sulla maggior parte delle API compatibili con OpenAI entrambe le cose escono da un unico budget: max_tokens. Se lo imposti come faresti per un modello senza ragionamento, qualche centinaio di token per una risposta breve, alcune risposte tornano vuote con finish_reason: "length". La soluzione rapida è in perché un modello di ragionamento restituisce una risposta vuota. Questo articolo è il metodo per arrivare a un budget affidabile: misurare, dimensionare dai percentili, rispettare la finestra di contesto e gestire le risposte che vengono comunque troncate.
Per quanto costa il ragionamento e come ridurlo, vedi token di ragionamento: perché paghi più output di quanto ne vedi.
Perché il budget finisce prima della risposta?
Il modello genera in ordine: prima il ragionamento, poi la risposta visibile. Ogni token di entrambi conta in max_tokens. La documentazione di BroadNet lo dice per DeepSeek V4.1 Flash, GLM 5.3 e Qwen3.8 27B: «the reasoning counts toward max_tokens» (traduzione: il ragionamento conta in max_tokens), e con un limite piccolo «the answer comes back empty» (traduzione: la risposta torna vuota). Il riferimento Chat Completions di OpenAI definisce max_completion_tokens allo stesso modo, come limite superiore «including visible output tokens and reasoning tokens» (traduzione: che include i token di output visibili e i token di ragionamento).
Quindi la domanda giusta non è «quanto è lunga la mia risposta?». È «quanto sono lunghi ragionamento e risposta insieme, su questo compito, con questo effort?». E varia più di quanto si pensi. La guida di OpenAI dice che i suoi modelli possono generare «anywhere from a few hundred to tens of thousands of reasoning tokens» (traduzione: da qualche centinaio a decine di migliaia di token di ragionamento), a seconda del problema.
Un max_tokens più alto costa di più?
No. È il motivo più comune per cui i budget vengono impostati troppo stretti. max_tokens è un tetto. Paghi i token effettivamente generati. Una risposta che richiede 1.800 token costa uguale con un tetto di 4.000 o di 40.000.
Ecco cosa costa invece un tetto stretto:
| Tetto rispetto al fabbisogno | Cosa paghi | Cosa ottieni |
|---|---|---|
| Tetto sopra il fabbisogno | I token generati | La risposta |
| Tetto sotto il fabbisogno | L’intero tetto, tutto in ragionamento | Niente di utilizzabile, più un retry |
Un esempio. Supponi che un quarto delle tue chiamate richieda più di 1.000 token. Con max_tokens=1000, ciascuna di quelle chiamate fattura 1.000 token di output di ragionamento, non restituisce nulla e viene ripetuta. In media sono 250 token di output sprecati per chiamata, su tutte le chiamate, prima ancora dei retry, più la latenza di una seconda richiesta. Con il tetto a 4.000 non si spreca nulla. Su Qwen3.8 27B l’output costa $2.17 per 1M di token, quindi a grandi volumi lo spreco si fa sentire.
Il vero rischio di un tetto alto è una risposta fuori controllo: un modello che va in loop o pensa troppo e genera molto più del necessario. Un tetto fisso lo limita. Scegli il tetto dai dati, come segue.
Come si misura quanto serve a un compito?
Esegui prompt reali per un solo tipo di compito con un tetto generoso, e registra i token di completamento e la quota di ragionamento. Quando il modello lo riporta, usage.completion_tokens_details.reasoning_tokens dà la parte di ragionamento; la documentazione di BroadNet elenca quel campo.
import os
from openai import OpenAI
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
MODEL = "broadnet/qwen3.8-27b"
def measure(prompts, ceiling=16_000, **kw):
"""Run real prompts with a generous ceiling and return per-call token counts."""
rows = []
for p in prompts:
r = client.chat.completions.create(model=MODEL, max_tokens=ceiling,
messages=[{"role": "user", "content": p}], **kw)
u, d = r.usage, r.usage.completion_tokens_details
reasoning = (d.reasoning_tokens or 0) if d else 0
rows.append({"reasoning": reasoning, "answer": u.completion_tokens - reasoning,
"finish": r.choices[0].finish_reason})
return rows
def pct(values, q):
values = sorted(values)
return values[min(len(values) - 1, int(q * len(values)))]
def recommend(rows, margin=1.2):
total = [r["reasoning"] + r["answer"] for r in rows]
return {"p50": pct(total, 0.5), "p95": pct(total, 0.95), "max": max(total),
"max_tokens": int(pct(total, 0.95) * margin),
"cut_off": sum(r["finish"] == "length" for r in rows)}
# print(recommend(measure(my_prompts))) # default effort
# print(recommend(measure(my_prompts, reasoning_effort="low")))
Regole per ottenere un numero affidabile:
- Un tipo di compito per esecuzione. Classificazione, estrazione, code review e pianificazione hanno distribuzioni molto diverse. Un unico
max_tokensglobale o spreca soldi in retry o lascia passare risposte fuori controllo. - 50 o più prompt reali. Il 95° percentile di dieci campioni è semplicemente il più grande.
- Eseguilo per ogni effort che usi.
reasoning_effort="low"cambia la distribuzione. BroadNet documentalow; testa gli altri valori prima di farci affidamento. - Se
cut_offnon è zero, alza il tetto e ripeti. Un campione troncato nasconde la sua lunghezza reale. - Ripeti quando cambiano modello o prompt. Una nuova versione del modello può pensare di più o di meno.
Poi imposta max_tokens per ogni compito partendo da recommend(). Il 95° percentile più il 20% lascia la maggior parte delle chiamate ben sotto il tetto e manda solo i rari casi lunghi al percorso di retry descritto sotto. Lo strumento gratuito per il budget dei token di ragionamento fa questi conti nel browser una volta che hai i tuoi numeri.
Come limita il budget la finestra di contesto?
La finestra di contesto contiene il prompt e la risposta insieme. Il feed dei prezzi di BroadNet definisce context_length come «the most tokens one request can hold, prompt and answer together» (traduzione: il massimo di token che una richiesta può contenere, prompt e risposta insieme). Quindi:
max_tokens ≤ lunghezza del contesto − token del prompt
| Modello | Contesto | Spazio per max_tokens con un prompt da 200.000 token |
|---|---|---|
| GLM 5.3 | 1.048.576 | 848.576 |
| DeepSeek V4.1 Flash | 1.048.576 | 848.576 |
| Qwen3.8 27B | 262.144 | 62.144 |
Conta nel lavoro a contesto lungo. Un agente la cui cronologia è cresciuta fino a 250.000 token su Qwen3.8 27B ha solo circa 12.000 token liberi per ragionamento e risposta. I compiti a contesto lungo tendono anche a richiedere più ragionamento, quindi controlla lo spazio rimasto al momento della chiamata, non una volta sola all’avvio. Finestra di contesto e il calcolatore della finestra di contesto spiegano come far stare tutto.
Cosa fare quando una risposta viene comunque troncata?
Controlla finish_reason a ogni chiamata. Se è length, la risposta manca o è incompleta, anche quando content contiene un po’ di testo. Non analizzarla come se fosse completa; un oggetto JSON troncato è una causa frequente di errori a valle (output strutturato).
Ripeti con un budget raddoppiato, entro lo spazio consentito dal contesto, fino a un tetto fisso:
import json, urllib.request
FEED = json.load(urllib.request.urlopen("https://inference.broadnet.ai/pricing.json"))
CONTEXT = {m["id"]: m.get("context_length") for m in FEED["models"]}
def ask(model, messages, budget=4_000, hard_cap=32_000, **kw):
"""Retry a cut-off reply with a doubled budget, never past the cap or the context window."""
while True:
r = client.chat.completions.create(model=model, messages=messages,
max_tokens=budget, **kw)
if r.choices[0].finish_reason != "length":
return r
room = CONTEXT[model] - r.usage.prompt_tokens # context holds prompt + answer
nxt = min(budget * 2, hard_cap, room)
if nxt <= budget:
raise RuntimeError(f"still cut off at max_tokens={budget}")
print(f"cut off at {budget}, retrying with {nxt}")
budget = nxt
Due alternative al raddoppio, a seconda del compito:
- Ripeti con
reasoning_effort="low"e lo stesso budget. Sui compiti semplici il modello spesso pensa troppo, e meno effort risolve senza alzare il tetto. - Dividi il compito. Se una risposta continua a sbattere contro un tetto alto, di solito la richiesta chiede troppo in una volta sola.
Registra ogni troncamento con il tipo di compito. Un tasso in aumento significa che sono cambiati il prompt, il modello o i dati in ingresso, e il budget va rimisurato. I retry sono nuove inferenze e si pagano di nuovo, quindi limita i tentativi, come in agenti a lunga esecuzione: timeout e retry.
Cosa cambia con lo streaming?
Con stream=True, il ragionamento avviene prima del primo token visibile, quindi all’inizio un modello di ragionamento può sembrare bloccato. In un’interfaccia di chat, mostra uno stato «sta pensando» finché non arriva il contenuto, e dimensiona i timeout del client sul tempo di ragionamento, non solo sulla risposta.
Alcuni server trasmettono in streaming anche il testo del ragionamento, in un campo separato. Il nome non è standard: l’API di DeepSeek usa reasoning_content, e vLLM ha rinominato il campo da reasoning_content a reasoning, avvertendo che il vecchio codice client potrebbe leggere in silenzio un campo vuoto (testo originale: «could silently read an empty» field). La documentazione di BroadNet non documenta un campo con il testo del ragionamento, quindi non costruire funzionalità su di esso senza controllare la risposta grezza del tuo modello. Se lo leggi, fallo in modo difensivo:
for chunk in stream:
if chunk.choices:
delta = chunk.choices[0].delta
thinking = getattr(delta, "reasoning", None) or getattr(delta, "reasoning_content", None)
# log or display `thinking` only if your provider actually sends it
if delta.content:
print(delta.content, end="")
elif chunk.usage: # last chunk, with include_usage
print("\nreasoning tokens:", getattr(chunk.usage.completion_tokens_details, "reasoning_tokens", None))
L’usage nell’ultimo chunk richiede stream_options={"include_usage": True}, che BroadNet documenta. Altro sugli stream nella guida allo streaming e in SSE spiegato.
Che nome di parametro inviare?
| API | Parametro | Include il ragionamento |
|---|---|---|
| OpenAI Chat Completions | max_completion_tokens (max_tokens deprecato) |
Sì |
| OpenAI Responses | max_output_tokens |
Sì |
| BroadNet Inference (Chat Completions) | max_tokens, come documentato |
Sì |
| Server vLLM | max_tokens, più thinking_token_budget facoltativo |
Sì |
Quando sposti codice tra provider, invia il nome che il provider documenta e verifica con una chiamata di prova che il limite abbia effetto. Un limite ignorato in silenzio sembra a posto finché non arriva una risposta fuori controllo. La checklist di migrazione copre gli altri parametri che cambiano.
Dove si colloca BroadNet Inference
I tre modelli di ragionamento di BroadNet riportano i token di ragionamento in usage quando il modello li fornisce, quindi la misurazione sopra funziona così com’è. DeepSeek V4.1 Flash e GLM 5.3 danno più spazio, con 1.048.576 token di contesto. Qwen3.8 27B ne ha 262.144. Se per un compito non ti serve il ragionamento, Gemma 4 VL 26B non è indicato come modello di ragionamento ed evita del tutto la questione del budget. Con un piano flat DeepSeek V4.1 Flash, i token di ragionamento non hanno costo per token, ma le risposte troncate costano comunque tempo, quindi vale lo stesso metodo. BroadNet non documenta un tetto separato per il ragionamento; se te ne serve uno, usa un provider o un server self-hosted che lo offra.
