DeepSeek V4 Pro (0813): Thinking Passback e matrice a 3 API

Questo articolo illustra le note d'uso e le trappole da evitare per deepseek-v4-pro-0813. Su AIHubMix il modello è disponibile tramite le API Chat Completions, Responses e Messages compatibili con Claude. Vedi anche: documentazione ufficiale delle API di DeepSeek.

Le conclusioni "Verificate" e le risposte di esempio di ogni sezione provengono da chiamate effettive eseguite il 2026-08-13 tramite le API di AIHubMix (Chat Completions / Responses / Messages); le specifiche non contrassegnate come "Verificate" provengono dalla documentazione ufficiale di DeepSeek.

1. Posizionamento del modello e specifiche in sintesi

V4 Pro è il livello di fascia alta della generazione V4 di DeepSeek (il più leggero deepseek-v4-flash ne è il fratello). La linea di rilascio risale a DeepSeek-V4 Preview del 2026-04-24, e 0813 è l'etichetta di VERSIONE DEL MODELLO assegnata da DeepSeek alla build attuale. Oltre alle specifiche grezze, quattro aspetti lo distinguono:

• Un modello di frontiera sparso: 1.6T parametri totali / 49B attivati (un'architettura MoE, o mixture-of-experts: a ogni passaggio di inferenza si attiva solo un sottoinsieme di reti esperte; i parametri totali determinano la capacità di conoscenza, quelli attivati determinano il costo di calcolo per chiamata). La model card elenca l'attenzione ibrida CSA+HCA, mHC e l'ottimizzatore Muon.
• Pesi aperti con licenza MIT: deepseek-ai/DeepSeek-V4-Pro è pubblicato su HuggingFace con licenza MIT (una delle licenze open source più permissive: sono consentiti sia l'uso commerciale sia la ridistribuzione closed-source) e può essere ospitato autonomamente. La licenza MIT è insolita per un modello di questa dimensione. Le note sull'hosting autonomo nella model card suggeriscono inoltre una finestra di contesto di ≥384K token quando si esegue in Think Max (il livello di thinking più alto): si tratta di una linea guida di deployment per l'hosting autonomo, non di una specifica dell'API ospitata.
• Supporto multi-protocollo di prima parte, non traduzione di terze parti: DeepSeek stesso offre un'API OpenAI Chat, un endpoint compatibile con Anthropic (/anthropic, che mappa claude-opus* su questo modello) e la Responses API (DeepSeek descrive un supporto nativo del formato, con adattamenti per Codex). Offre inoltre il completamento FIM (fill-in-the-middle) come funzionalità Beta su un endpoint separato, che non fa parte delle tre API di AIHubMix.
• Un divario di circa 120× tra prezzo con cache hit e cache miss: il meccanismo di prezzo pubblicato da DeepSeek è cache hit $0.003625/M contro cache miss $0.435/M (output $0.87/M), e il caching è automatico, senza alcun parametro da impostare. Per i carichi di lavoro che riutilizzano prefissi lunghi (system prompt, documenti lunghi), questo divario domina la fattura. Il prezzo di vendita effettivo è quello mostrato nella pagina del modello.

Verificato: superare max_tokens viene rifiutato dalla validazione invece di essere troncato in silenzio. Inviando max_tokens=9999999 si ottiene HTTP 400, e il corpo dell'errore indica il campo e riporta il limite massimo 393216.

# max_tokens=9999999 -> HTTP 400
"...max_tokens... 393216"

❗ Le immagini non generano errore, ma vengono eliminate: la dicitura ufficiale per la Responses API è "Image and file inputs are not supported (input_image parts do not cause an error, but are replaced with a placeholder text)": una parte input_image non fa fallire la richiesta, ma viene sostituita con testo segnaposto. In Chat Completions il campo content del messaggio utente accetta solo una stringa, e in Messages i blocchi type="image" sono contrassegnati come Not Supported. Quando si costruisce un routing multimodale, non considerare mai "nessun errore" come prova che il modello abbia effettivamente visto l'immagine.

2. Come si disattiva il thinking? Tre API, tre forme di campo

V4 Pro usa il thinking per impostazione predefinita: non inviare alcun parametro e la risposta conterrà i contenuti di thinking. La disattivazione usa una forma di campo diversa su ciascuna delle tre API.

Chat Completions

Usa l'oggetto thinking di primo livello.

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_API_KEY>",
)

completion = client.chat.completions.create(
    model="deepseek-v4-pro-0813",
    messages=[{"role": "user", "content": "What is 2 + 2?"}],
    extra_body={"thinking": {"type": "disabled"}},
)

# Thinking on  (default): message.reasoning_content present, reasoning_tokens = 43
# Thinking off (disabled): reasoning_content absent, reasoning_tokens absent

Verificato: con thinking.type="disabled" scompaiono insieme message.reasoning_content e usage.completion_tokens_details.reasoning_tokens, il che conferma che l'interruttore ha avuto effetto.

Responses

Su Responses non esiste un interruttore separato; disattivare il thinking significa impostare il livello su none.

response = client.responses.create(
    model="deepseek-v4-pro-0813",
    input="What is 2 + 2?",
    reasoning={"effort": "none"},
)

# effort="none": usage.output_tokens_details.reasoning_tokens = 0
#                output[0] is the message item directly (no reasoning item)
# effort unset : output always starts with a reasoning item

Verificato: reasoning.effort="none" differisce in modo osservabile dal livello predefinito (i token di thinking scendono a zero e l'elemento di output reasoning scompare), il che conferma che ha avuto effetto.

Messages

Stesso nome e stessa forma di Chat Completions: l'oggetto thinking di primo livello.

from anthropic import Anthropic

client = Anthropic(
    api_key="<AIHUBMIX_API_KEY>",
    base_url="https://aihubmix.com",
)

response = client.messages.create(
    model="deepseek-v4-pro-0813",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What is 2 + 2?"}],
    extra_body={"thinking": {"type": "disabled"}},
)

# Thinking on  (default): content = [thinking block, text block]
# Thinking off (disabled): content = [text block]

Verificato: una volta disattivato, il blocco thinking scompare del tutto e resta solo il blocco text.

Sui livelli di thinking: low e max hanno entrambi restituito 200 su Chat Completions nei test (high è il predefinito e si applica quando il campo viene omesso), ma i conteggi dei token di thinking non mostrano una differenza monotona tra i livelli per la stessa domanda (domanda facile: low=43 / max=27; domanda difficile: low=114 / max=92), e nella risposta non viene restituito nulla — i livelli vengono accettati, ma dalla risposta non è osservabile alcun segnale distintivo. Su Responses, solo il livello none (thinking disattivato) può essere confermato dal lato della risposta.

3. Perché una conversazione multi-turno restituisce improvvisamente 400? La cronologia di thinking va restituita in forma letterale

Questa è la trappola più comune con questo modello: in modalità thinking, una conversazione multi-turno deve restituire il contenuto di thinking del turno precedente in forma letterale, altrimenti la richiesta viene rifiutata. Non si tratta di una degradazione o di una qualità inferiore, ma di un HTTP 400 vero e proprio.

Le tre API trasportano lo stesso contenuto di thinking con nomi di campo diversi:

Verificato (condizioni di attivazione): questa validazione scatta in modo costante nelle richieste multi-turno che contengono tools (il modello emette una chiamata a tool, poi il risultato del tool viene inviato indietro). Nelle richieste multi-turno semplici senza tool, in cui il modello risponde direttamente, la validazione non è scattata in questo ciclo di test e la richiesta ha restituito 200. In altre parole, l'orchestrazione dei tool (carichi di lavoro agent / function-calling) è il punto in cui è più probabile incappare nel problema, quindi trattate il contenuto di thinking come parte dello stato della conversazione che salvate e riproducete.

Chat Completions

# Multi-turn: pass the previous assistant message back verbatim, including reasoning_content
messages = [
    {"role": "user", "content": "What is 1 + 1? Remember the result."},
    {
        "role": "assistant",
        "content": "2",
        "reasoning_content": "<reasoning_content from the previous response>",
    },
    {"role": "user", "content": "Add 1 to the result."},
]

# Dropping reasoning_content -> HTTP 400 invalid_request_error

Verificato: un messaggio storico dell'assistente privo di reasoning_content restituisce 400; reinserendolo, la stessa identica richiesta restituisce 200 e prosegue correttamente.

Responses

# Multi-turn: input = previous input + response.output (reasoning item included) + new message
input = previous_input + response.output + [
    {"role": "user", "content": "Add 1 to the result."}
]

# Filtering out the type="reasoning" item -> HTTP 400

Verificato: basta reinserire response.output così com'è. Filtrare gli elementi di output con type == "message" durante la costruzione della cronologia elimina l'elemento reasoning e provoca il 400: è il modo più comune di caderci.

Messages

# Multi-turn: pass response.content back verbatim as the assistant message
messages = [
    {"role": "user", "content": "What's the weather in Paris?"},
    {"role": "assistant", "content": response.content},   # thinking + tool_use blocks
    {"role": "user", "content": [tool_result_block]},
]

# Stripping the thinking block -> HTTP 400

Verificato: rimuovere il blocco thinking dall'array dei contenuti restituisce 400 (con error.type impostato a invalid_request_error).

4. Chiamata di tool

Ogni API dichiara i tool nella propria forma di protocollo; le forme non sono intercambiabili.

Chat Completions

Forma annidata (un oggetto function che racchiude name / parameters). Un tool_choice con funzione nominata forza la chiamata.

completion = client.chat.completions.create(
    model="deepseek-v4-pro-0813",
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get weather for a city",
            "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        },
    }],
    tool_choice={"type": "function", "function": {"name": "get_weather"}},
)

# Observed: finish_reason "tool_calls", tool_calls[0].function.arguments = {"city": "Paris"}

❗ Verificato: tool_choice: "required" non può essere usato con il thinking attivo: restituisce 400 Thinking mode does not support this tool_choice; disattivando il thinking (thinking.type="disabled") la stessa identica richiesta restituisce 200. Quando serve la semantica "deve chiamare un tool", usate invece un tool_choice con funzione nominata (come sopra, che funziona con il thinking attivo), oppure disattivate prima il thinking e poi usate required.

Responses

Forma piatta (type / name / parameters allo stesso livello).

response = client.responses.create(
    model="deepseek-v4-pro-0813",
    input="What's the weather in Paris?",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Get weather for a city",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
)

# Observed output items: ["reasoning", "function_call"]; arguments = {"city": "Paris"}

Verificato: copiare la forma annidata di Chat Completions (function: {...}) in Responses restituisce 400: usate la forma piatta. tool_choice: "required" è soggetto alla stessa restrizione della modalità thinking che vale per Chat.

Messages

Forma nativa di Anthropic (input_schema), con tool_choice: {"type": "any"} per forzare una chiamata.

response = client.messages.create(
    model="deepseek-v4-pro-0813",
    max_tokens=1024,
    tools=[{
        "name": "get_weather",
        "description": "Get weather for a city",
        "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice={"type": "any"},
    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
)

# Observed: content contains a tool_use block, name = get_weather, input = {"city": "Paris"}

❗ La chiamata parallela di tool non può essere disattivata, per scelta progettuale di DeepSeek: la pagina ufficiale di compatibilità Anthropic indica, nella riga tool_choice, che disable_parallel_tool_use is ignored, e la pagina Responses riporta allo stesso modo parallel_tool_calls | Ignored (parallel tool calling is always enabled). I test confermano il comportamento: chiedere informazioni su due città contemporaneamente con disable_parallel_tool_use: true restituisce comunque due blocchi tool_use. Se servono esecuzioni seriali, prendete la prima chiamata oppure accodatele voi lato client.

Numero di tool e costo del contesto: inviare 200 definizioni di funzione in una singola richiesta ha comunque restituito 200 con una risposta normale e non ha attivato alcuna validazione del numero (osservato su questo percorso; numeri più alti non sono stati testati). Tuttavia, prompt_tokens per quella richiesta ha raggiunto 6.105 — le definizioni dei tool entrano nel contesto per intero e vengono fatturate. Quando hai molti tool, riduci l'insieme dei tool per scenario invece di dichiararli tutti incondizionatamente.

5. Output strutturato

Chat Completions

response_format supporta la modalità JSON.

completion = client.chat.completions.create(
    model="deepseek-v4-pro-0813",
    messages=[{"role": "user", "content": "Return {\"a\": 1} as JSON."}],
    response_format={"type": "json_object"},
)

# Observed response content: {"a":1}

Verificato: l'output è un JSON valido.

Responses

Dichiara uno JSON Schema tramite text.format, con supporto della modalità strict.

response = client.responses.create(
    model="deepseek-v4-pro-0813",
    input="Return the number 1 under key a.",
    text={
        "format": {
            "type": "json_schema",
            "name": "extract",
            "strict": True,
            "schema": {"type": "object", "properties": {"a": {"type": "integer"}}, "required": ["a"]},
        }
    },
)

# Observed output text: {"a":1}

Verificato: l'output è conforme in modo rigoroso allo schema fornito.

Messages

Il protocollo Messages (Anthropic) non ha un equivalente di response_format / text.format. La soluzione alternativa più comune consiste nel trasportare lo schema in un tool — dichiara un tool il cui input_schema sia lo schema di destinazione, imposta tool_choice: {"type": "any"} e leggi il risultato strutturato dal campo input del blocco tool_use. Questo ciclo di test non ha verificato specificamente questo schema; quando servono garanzie rigorose sullo schema, preferisci Chat Completions o Responses.

6. Come si attiva la cache del contesto? Non si attiva, è automatica

La cache del contesto (i prefissi identici vengono riutilizzati e la parte in cache viene fatturata a una tariffa inferiore) è attiva per impostazione predefinita e non richiede parametri. Una seconda richiesta con lo stesso prefisso lungo segnala il riscontro in usage, con un nome di campo che varia a seconda dell'API. Per i dettagli sulla cache e i prezzi attuali, consulta la pagina del modello; per la strategia di cache tra modelli e le tecniche per il tasso di riscontro, consulta le pratiche di prompt caching.

Chat Completions

# usage of the second call with an identical long prefix
"prompt_tokens_details": {"cached_tokens": 640}   # first call: 0

Verificato: due chiamate consecutive con lo stesso prefisso lungo sullo stesso canale hanno portato cached_tokens da 0 a 640.

Responses

# usage of the second call with identical long instructions
"input_tokens_details": {"cached_tokens": 896}    # first call: 0

Messages

# usage of a call whose long system prefix was already warmed
"cache_read_input_tokens": 896

Verificato: il prefisso sopra è stato predisposto da una richiesta Responses con contenuto identico, e la prima chiamata Messages ha subito registrato un riscontro di 896 — coerente con una cache basata sul prefisso del contenuto e condivisa tra le superfici dei protocolli.

7. logprobs: Chat restituisce due canali

logprobs (probabilità logaritmiche — il dettaglio di confidenza per ogni token candidato del modello) viene restituito in forme diverse nelle due API, e il codice di parsing deve gestirle separatamente.

Chat Completions

completion = client.chat.completions.create(
    model="deepseek-v4-pro-0813",
    messages=[{"role": "user", "content": "Say hi."}],
    logprobs=True,
    top_logprobs=2,
)

# Observed: choices[0].logprobs contains TWO arrays
#   logprobs.content[]            -> tokens of the final answer
#   logprobs.reasoning_content[]  -> tokens of the thinking text

❗ Verificato: Chat restituisce probabilità logaritmiche sia per content sia per reasoning_content. Il codice che legge solo logprobs.content, secondo la struttura di risposta standard di OpenAI, non genera errori ma ignora silenziosamente il canale del ragionamento; se il tuo codice presume un unico array sotto logprobs, aggiungi prima un controllo della struttura.

Responses

response = client.responses.create(
    model="deepseek-v4-pro-0813",
    input="Say hi.",
    top_logprobs=3,
)

# Observed: logprobs only on the final message item
#   output[-1].content[0].logprobs[] with logprob + top_logprobs details

Verificato: Responses allega i logprobs solo all'elemento di testo finale — nessuna struttura a doppio canale come quella vista su Chat.

Messages

Il protocollo Messages (Anthropic) non ha un campo equivalente. Per il dettaglio delle probabilità a livello di token, usa Chat Completions o Responses.

8. Quali API possono cercare sul web?

La ricerca web qui è uno strumento lato server (il recupero viene eseguito sul server; il client non invia mai la richiesta direttamente) e, nei test, viene effettivamente eseguita sia con le API Responses sia con quelle Messages.

Responses

response = client.responses.create(
    model="deepseek-v4-pro-0813",
    input="What is the latest stable version of Python?",
    tools=[{"type": "web_search"}],
)

# Observed output item sequence:
# ["reasoning", "web_search_call", "reasoning", "message"]

Verificato: nella sequenza di output compare un elemento web_search_call, il che significa che il server ha effettivamente eseguito un recupero.

Messages

response = client.messages.create(
    model="deepseek-v4-pro-0813",
    max_tokens=1024,
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    messages=[{"role": "user", "content": "What is the latest stable version of Python?"}],
)

# Observed content block sequence:
# ["thinking", "server_tool_use", "web_search_tool_result", "thinking", "text"]
# usage.server_tool_use.web_search_requests = 1

Verificato: usage.server_tool_use.web_search_requests vale 1 — la richiesta di recupero è avvenuta davvero ed è stata conteggiata.

Chat Completions

La ricerca web non può essere attivata su Chat. Il riferimento ufficiale dell'API Chat di DeepSeek non contiene alcun campo per lo strumento di ricerca nello schema della richiesta (questa assenza è stata accertata scorrendo l'elenco dei campi uno per uno; DeepSeek non ha fatto alcuna dichiarazione esplicita che neghi il supporto). L'API con una dichiarazione ufficiale esplicita di supporto alla ricerca lato server è Responses (web_search), e la pagina ufficiale di compatibilità con Messages elenca anche i blocchi di contenuto legati alla ricerca.

# Three control groups, same question requiring live information, all HTTP 200:
# A no search field       -> "cannot retrieve", annotations = null
# B web_search_options    -> "cannot retrieve", annotations = null, usage identical to A
# C enable_search         -> "cannot retrieve", annotations = null, usage identical to A

Verificato: inviare web_search_options o enable_search non genera errori, ma non recupera nulla — la risposta non contiene annotations (l'elenco delle citazioni allegato a una risposta quando viene eseguita la ricerca web) e l'uso coincide campo per campo con il gruppo di controllo. Per l'accesso al web, usa le API Responses o Messages.

9. Note sull'uso: scelte di progettazione di DeepSeek e deviazioni sul nostro percorso

Tutto ciò che segue restituisce HTTP 200 pur comportandosi in modo controintuitivo. Le cause sono diverse, e diverso è anche ciò che bisogna fare al riguardo, quindi sono elencate separatamente: il primo gruppo riguarda il modo in cui DeepSeek ha progettato il modello, e cambiare provider non lo modificherà; il secondo gruppo riguarda il comportamento attuale sul percorso di AIHubMix, su cui stiamo lavorando.

9.1 Per progettazione di DeepSeek

9.2 Comportamento attuale sul percorso di AIHubMix

9.3 Non definito da DeepSeek, quindi nessun giudizio in un senso o nell'altro

Inviare per reasoning_effort un valore fuori dall'enum (ad es. bogus_xyz) restituisce 200 con una risposta normale, nessun errore e nessun effetto osservabile. Il fatto è sufficientemente chiaro: questo percorso attualmente non valida l'enum di reasoning_effort. Non è chiaro invece se dovrebbe farlo: DeepSeek pubblica l'enum valido ma non dichiara mai se un livello non valido debba essere rifiutato, quindi non esiste un riferimento con cui confrontarsi; per questo non è né un comportamento ufficiale né un difetto del nostro percorso. L'approccio sicuro lato client consiste nel validare tu stesso il livello, senza contare sul fatto che l'API lo intercetti.

10. Matrice di supporto Capacità × API

Le celle seguenti indicano la grafia del parametro / campo per ciascuna API. Salvo dove è indicata come formulazione esplicita di DeepSeek, ogni conclusione deriva da chiamate effettive eseguite il 2026-08-13 sulle API di produzione di AIHubMix.

Legenda: ✅ verificato come funzionante · 🟡 accettato ma non confermabile come effettivo · ❗ richiede attenzione (vedi le note sopra) · ➖ nessun concetto equivalente in questa API

FAQ

Quali API supporta deepseek-v4-pro-0813 su AIHubMix?
Chat Completions (/v1/chat/completions), Responses (/v1/responses) e l'API Messages compatibile con Claude (/v1/messages).

Perché una conversazione multi-turno restituisce all'improvviso 400?
La causa più comune è la cronologia del ragionamento non restituita. In modalità thinking, il contenuto di ragionamento del turno precedente deve essere ripetuto esattamente com'è: reasoning_content sul messaggio dell'assistente per Chat, l'elemento di output type="reasoning" per Responses e il blocco di contenuto thinking per Messages. Il problema si manifesta soprattutto nelle conversazioni multi-turno con strumenti: molti framework filtrano gli elementi di output con type == "message" durante la ricostruzione della cronologia, eliminando così l'elemento di ragionamento.

Il thinking può essere disattivato?
Sì. Invia thinking: {"type": "disabled"} su Chat o Messages, e reasoning: {"effort": "none"} su Responses. Una volta disattivato, scompaiono sia il contenuto di thinking sia i token di thinking.

I tre livelli di reasoning_effort sono diversi?
low / high / max sono tutti accettati (il valore predefinito è high; medium e xhigh vengono mappati su high per compatibilità). Nei test, il numero di token di thinking per la stessa domanda non mostra una differenza monotona tra i livelli e nulla viene restituito, quindi la differenza non può essere confermata dal lato del chiamante. Solo il livello none su Responses (thinking disattivato) produce una differenza chiaramente osservabile.

Perché tool_choice: "required" restituisce 400?
Questo valore non è accettato con il thinking attivo (il corpo dell'errore recita Thinking mode does not support this tool_choice). Usa un tool_choice con nome di funzione ({"type": "function", "function": {"name": "..."}}) per forzare una chiamata specifica con il thinking attivo, oppure disattiva prima il thinking e poi usa required.

Come si attiva la cache del contesto?
Non serve attivarla: è automatica. Inserisci all'inizio della richiesta i contenuti stabili e invariati (prompt di sistema, frammenti di conoscenza, definizioni degli strumenti) e il numero di hit viene riportato in usage: prompt_tokens_details.cached_tokens su Chat, input_tokens_details.cached_tokens su Responses e cache_read_input_tokens su Messages.

Per prezzi e stato in tempo reale, consulta la pagina del modello deepseek-v4-pro-0813; per altri modelli, visita la galleria dei modelli.

Guide pratiche correlate: guida pratica a Kimi K3 (nuovi parametri e una matrice di supporto a tre API) e modifiche alla cache dei prompt e alla fatturazione di GPT-5.6.