BroadRouter

Impostare max_tokens per i modelli di ragionamento: un metodo

A cura del team di BroadNet Inference · 6 min di lettura · Pubblicato

Su un modello di ragionamento, max_tokens limita insieme ragionamento e risposta, quindi un limite stretto può chiudere la risposta prima di qualsiasi testo visibile. Misura i token di completamento totali per tipo di compito, imposta max_tokens a circa il 95° percentile più il 20%, tieni prompt più max_tokens dentro la finestra di contesto e ripeti le risposte troncate con un budget raddoppiato, fino a un tetto fisso.

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:

  1. Un tipo di compito per esecuzione. Classificazione, estrazione, code review e pianificazione hanno distribuzioni molto diverse. Un unico max_tokens globale o spreca soldi in retry o lascia passare risposte fuori controllo.
  2. 50 o più prompt reali. Il 95° percentile di dieci campioni è semplicemente il più grande.
  3. Eseguilo per ogni effort che usi. reasoning_effort="low" cambia la distribuzione. BroadNet documenta low; testa gli altri valori prima di farci affidamento.
  4. Se cut_off non è zero, alza il tetto e ripeti. Un campione troncato nasconde la sua lunghezza reale.
  5. 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.

Domande frequenti

Perché il mio modello di ragionamento restituisce una risposta vuota?

Il modello ha speso l’intero budget di max_tokens nel ragionamento nascosto prima di scrivere la risposta. In quel caso finish_reason è "length". Alza max_tokens, abbassa reasoning_effort, o entrambe le cose. Da questo articolo trovi il link a una guida breve con la soluzione rapida.

Che max_tokens devo impostare per un modello di ragionamento?

Prima misura. Esegui 50 o più prompt reali con un tetto generoso, prendi il 95° percentile di completion_tokens per quel compito e aggiungi circa il 20%. La documentazione di BroadNet indica 1.000 token o più come minimo; OpenAI suggerisce di riservarne 25.000 quando inizi con i suoi modelli.

Un max_tokens più alto costa di più?

Non di per sé. Paghi i token che il modello genera, non il tetto. Un tetto più alto costa di più solo quando una risposta altrimenti sarebbe stata troncata, e in quel caso la risposta troncata ti sarebbe costata comunque un retry.

max_completion_tokens è la stessa cosa di max_tokens?

Su OpenAI, max_completion_tokens sostituisce il deprecato max_tokens e include esplicitamente i token di ragionamento. Molti provider compatibili con OpenAI documentano invece max_tokens. La documentazione di BroadNet usa max_tokens e dice che il ragionamento conta al suo interno.

Posso limitare il ragionamento separatamente dalla risposta?

Solo se il server lo supporta. vLLM ha un parametro thinking_token_budget, e alcuni provider ne hanno uno proprio. BroadNet documenta reasoning_effort impostato a low, non un tetto separato per il ragionamento, quindi dimensiona i due insieme.

Leggi in MarkdownChiedi a ChatGPTChiedi a ClaudeChiedi a Perplexity