Indice della Documentazione
Recupera l'indice completo della documentazione su: https://docs.aihubmix.com/llms.txt
Utilizza questo file per scoprire tutte le pagine disponibili prima di esplorare ulteriormente.

Guida di Kimi K3 di luglio 2026: max reasoning_effort, storia del pensiero, caricamento dinamico degli strumenti, output strutturato, caching automatico, prefisso parziale e input visivi.

Questo articolo tratta i nuovi parametri e le note d'uso per Kimi K3. Su AIHubMix, K3 è disponibile tramite le API di Chat Completions, Risposte e Messaggi compatibili con Claude. Vedi anche: documentazione ufficiale della piattaforma Moonshot.

Le conclusioni e le risposte campione "Verificate" in ciascuna sezione provengono da chiamate effettive effettuate il 2026-07-17 tramite le API di AIHubMix (Chat Completions / Risposte / Messaggi).

1. Specifiche del Modello a Colpo d'Occhio

Verificato: entrambi i limiti di stop sono validati e superare uno dei due restituisce 400; l'API dei Messaggi applica la stessa validazione a stop_sequences.

❗ Quando viene colpita una sequenza di stop, l'API dei Messaggi non segue la semantica di Anthropic: nei test, stop_reason è "end_turn" (anziché "stop_sequence"), stop_sequence è null, e il testo visibile prima della parola di stop può essere vuoto. I client che si basano su questi due campi per rilevare la troncatura dovrebbero prenderne nota.

# stop con 6 voci / una voce di 33 byte -> HTTP 400
"Richiesta non valida: array di stop troppo lungo. Ci si aspettava un array con lunghezza massima 5, ma è stato ricevuto un array con lunghezza 6"
"Richiesta non valida: la sequenza di stop non deve essere più lunga di 32, ma è stata ricevuta 33"

2. Modalità di Pensiero: reasoning_effort Supporta Solo max

Il pensiero di K3 è attivato per impostazione predefinita e reasoning_effort supporta solo un singolo livello: "max".

Le conversazioni multi-turno devono restituire la storia del pensiero parola per parola: secondo la documentazione ufficiale di Moonshot, K3 è addestrato con il pensiero preservato, quindi nelle conversazioni multi-turno il messaggio precedente dell'assistente deve essere restituito completo e non modificato (incluso il contenuto del pensiero). La mancanza di storia del pensiero porta a una qualità di output instabile. Se utilizzi un framework di gestione delle sessioni o un layer proxy, conferma che il contenuto del pensiero venga restituito senza tagli.

Il contenuto del pensiero viene restituito nel campo `reasoning_content` della risposta; nelle conversazioni multi-turno, restituisci il messaggio precedente dell'assistente (incluso `reasoning_content`) parola per parola.

```text theme={null}
from openai import OpenAI

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

completion = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="max",
    messages=[
        {"role": "user", "content": "Una lumaca è sul fondo di un pozzo di 10 metri. Ogni giorno sale di 3 metri, ma ogni notte scivola indietro di 2 metri. Quanti giorni ci vogliono per raggiungere la cima?"}
    ],
)

print(completion.choices[0].message.reasoning_content)
print(completion.choices[0].message.content)
```

```text theme={null}
# Multi-turn: restituisci il messaggio precedente dell'assistente parola per parola
messages = [
    {"role": "user", "content": "Qual è la capitale della Francia?"},
    {"role": "assistant", "content": "Parigi.", "reasoning_content": "<reasoning_content dalla risposta precedente>"},
    {"role": "user", "content": "E la sua popolazione?"},
]
```

> **Verificato**: la risposta restituisce `reasoning_content`; dopo aver restituito il messaggio precedente dell'assistente (incluso `reasoning_content`) parola per parola, i turni successivi rispondono normalmente.

Il contenuto del pensiero viene restituito come un elemento di output `reasoning`; nelle conversazioni multi-turno, aggiungi gli elementi di output del turno precedente (`reasoning` + `message`) di nuovo in `input` parola per parola.

```text theme={null}
from openai import OpenAI

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

response = client.responses.create(
    model="kimi-k3",
    input="Rispondi in una parola: capitale della Francia",
)

# Tipi di elementi di output osservati: ["reasoning", "message"]; testo: "Parigi"
# Multi-turn: input = [primo messaggio dell'utente] + output della risposta + [prossimo messaggio dell'utente]
# Risposta osservata al secondo turno con elementi di output restituiti: "Berlino"
```

Il contenuto del pensiero viene restituito come blocchi di contenuto `thinking` nativi; nelle conversazioni multi-turno, restituisci i blocchi di contenuto precedenti dell'assistente (inclusi i blocchi di pensiero) parola per parola.

```text theme={null}
from anthropic import Anthropic

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

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Rispondi in una parola: capitale della Francia"}
    ],
)

# Tipi di blocchi di risposta osservati: ["thinking", "text"]; testo: "Parigi"
# Multi-turn: restituisci response.content parola per parola come messaggio dell'assistente
```

3. I Parametri di Campionamento Sono Fissi

I parametri di campionamento di K3 sono fissi dal fornitore: temperature 1.0, top_p 0.95, n 1, e presence_penalty / frequency_penalty 0. La raccomandazione ufficiale è di omettere questi parametri dalle richieste.

Nota: i valori di campionamento fissi fanno parte delle specifiche ufficiali e non possono essere verificati dai segnali di risposta; segui la raccomandazione ufficiale e ometti questi parametri.

4. Chiamata agli Strumenti e Caricamento Dinamico degli Strumenti

tools supporta fino a 128 strumenti; tool_choice supporta la forzatura e la disabilitazione delle chiamate agli strumenti. K3 supporta anche il caricamento dinamico degli strumenti: iniezione di nuovi strumenti a metà conversazione tramite il campo tools di un messaggio di sistema (una forma di messaggio specifica per l'API di Chat).

`tool_choice` supporta `auto` / `none` / `required`; `required` forza il modello a chiamare uno strumento. Caricamento dinamico degli strumenti: il messaggio di sistema che inietta lo strumento non porta `content`, gli strumenti iniettati hanno effetto per i turni successivi e il messaggio deve essere incluso di nuovo in ogni richiesta.

```text theme={null}
messages = [
    {"role": "system", "content": "Sei un assistente utile."},
    {"role": "user", "content": "Ciao."},
    {"role": "assistant", "content": "Ciao, come posso aiutarti?"},
    # Inietta un nuovo strumento a metà conversazione: solo campo tools, nessun contenuto
    {
        "role": "system",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_time",
                    "description": "Ottieni l'ora corrente",
                    "parameters": {"type": "object", "properties": {}},
                },
            }
        ],
    },
    {"role": "user", "content": "Che ore sono adesso?"},
]
```

```text theme={null}
# tool_choice="required" con prompt "Ciao" -> il modello è costretto a chiamare lo strumento
"finish_reason": "tool_calls",
"tool_calls": [{"function": {"name": "get_weather", "arguments": "{\"city\":\"New York\"}"}}]
```

> **Verificato**: `tool_choice: "required"` forza una chiamata a uno strumento anche per prompt non correlati; `"none"` sopprime le chiamate agli strumenti; gli strumenti iniettati a metà conversazione tramite un messaggio di sistema senza `content` possono essere chiamati normalmente.

Le definizioni degli strumenti utilizzano una struttura piatta (`name` a livello superiore); forzare una chiamata utilizza anch'esso `tool_choice: "required"`, e le chiamate vengono restituite come elementi di output `function_call`. Il supporto per il caricamento dinamico degli strumenti è in fase di sviluppo; per ora, dichiara tutti gli strumenti nel parametro `tools` di livello superiore.

```text theme={null}
response = client.responses.create(
    model="kimi-k3",
    input="Ciao",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Ottieni il meteo per una città",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice="required",
)

# Output osservato contiene: {"type": "function_call", "name": "get_weather", "arguments": "{\"city\":\"Londra\"}"}
```

Gli strumenti utilizzano il formato di Anthropic (`input_schema`); forza una chiamata con `tool_choice: {"type": "any"}` e disabilita le chiamate con `{"type": "none"}`. ❗ **L'endpoint ufficiale dei Messaggi di Kimi K3 (compatibile con Anthropic) non supporta il caricamento dinamico degli strumenti**: nei test, il messaggio di iniezione restituisce 200, ma lo strumento iniettato non ha effetto (il modello non può chiamarlo). Dichiara tutti gli strumenti nel parametro `tools` di livello superiore.

```text theme={null}
response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    tools=[{
        "name": "get_weather",
        "description": "Ottieni il meteo per una città",
        "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice={"type": "any"},
    messages=[{"role": "user", "content": "Ciao"}],
)

# Osservato: stop_reason "tool_use"; il contenuto contiene un blocco tool_use che chiama get_weather
```

5. Output Strutturato

Un output strutturato fa sì che il modello restituisca contenuti che si conformano rigorosamente a uno schema JSON dato.

`response_format` supporta `json_schema` con modalità `strict`.

```text theme={null}
completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Parigi è la capitale della Francia. Estrai il nome della città."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "extract",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    },
)

# Contenuto della risposta osservato: {"city":"Parigi"}
```

> **Verificato**: l'output è un JSON valido conforme allo schema.

Un output strutturato è dichiarato tramite `text.format`.

```text theme={null}
response = client.responses.create(
    model="kimi-k3",
    input="Parigi è la capitale della Francia. Estrai il nome della città.",
    text={
        "format": {
            "type": "json_schema",
            "name": "extract",
            "strict": True,
            "schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        }
    },
)

# Testo di output osservato: {"city":"Parigi"}
```

❗ **L'endpoint ufficiale dei Messaggi di Kimi K3 (compatibile con Anthropic) non supporta output strutturati**: i campi di output strutturati vengono silenziosamente ignorati — la richiesta restituisce HTTP 200 con testo libero, senza errore o avviso di fallback, e il parsing JSON a valle fallirà. Quando hai bisogno di output strutturato, utilizza le API di Chat Completions o Responses.

6. Il Caching del Contesto è Automatico

Il caching del contesto di K3 è abilitato automaticamente, senza parametri richiesti. Quando un prefisso lungo ripetuto colpisce la cache, l'importo colpito viene riportato nell'uso (il nome del campo varia a seconda dell'API). I prezzi della cache sono sulla pagina del modello.

```text theme={null} # uso della seconda chiamata con un prefisso lungo identico "prompt_tokens_details": {"cached_tokens": 1536} ```

> **Verificato**: la seconda richiesta con un prefisso lungo identico riporta il colpo in `usage.prompt_tokens_details.cached_tokens`.

```text theme={null} # uso della seconda chiamata Responses con istruzioni lunghe identiche "input_tokens_details": {"cached_tokens": 1536} ``` ```text theme={null} # uso della seconda chiamata Messages con un prompt di sistema lungo identico "cache_read_input_tokens": 1536 ```

7. Completamento del Prefisso partial

Il completamento del prefisso fa sì che il modello continui a generare da un dato prefisso, ben adatto al completamento del codice e all'output controllato dal formato.

Passa `"partial": true` nell'ultimo messaggio dell'assistente.

```text theme={null}
messages = [
    {"role": "user", "content": "Scrivi un haiku sul mare."},
    {"role": "assistant", "content": "Le onde si piegano nella schiuma,", "partial": True},
]

# Prefisso: "Le onde si piegano nella schiuma,"  ->  continuazione restituita dal modello
# il sale aleggia nell'aria—
# la luna tira la marea a casa.
```

> **Verificato**: la generazione continua dal prefisso dato senza ripeterlo.

Passa il prefisso come messaggio dell'assistente alla fine dell'array `input`; non è necessario alcun parametro `partial`.

```text theme={null}
response = client.responses.create(
    model="kimi-k3",
    input=[
        {"role": "user", "content": "Scrivi un haiku sul mare."},
        {"role": "assistant", "content": "Le onde si piegano nella schiuma,"},
    ],
)

# Continuazione osservata: "il sale aleggia nell'aria— / la luna tira la marea a casa."
```

La stessa capacità è raggiunta con il prefill nativo dell'assistente del protocollo, senza parametro `partial` — passa il prefisso come ultimo messaggio dell'assistente.

```text theme={null}
response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Scrivi un haiku sul mare."},
        {"role": "assistant", "content": "Le onde si piegano nella schiuma,"},
    ],
)

# Continuazione osservata: "il vento salato porta il grido del gabbiano— / la marea tira ..."
```

8. Input Visivo

Le immagini vengono passate come base64; il formato del blocco di contenuto varia a seconda dell'API.

```text theme={null} messages = [ { "role": "user", "content": [ {"type": "text", "text": "Qual è il colore dominante di questa immagine? Una parola."}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,"}}, ], } ]

# Contenuto della risposta osservato: "Rosso"  (input: un PNG rosso solido 64x64)
```

> **Verificato**: l'input immagine base64 funziona e il modello descrive correttamente l'immagine di test.

```text theme={null} input = [ { "role": "user", "content": [ {"type": "input_text", "text": "Qual è il colore dominante di questa immagine? Una parola."}, {"type": "input_image", "image_url": "data:image/png;base64,"}, ], } ]

# Testo di output osservato: "Rosso"
```

```text theme={null} messages = [ { "role": "user", "content": [ {"type": "text", "text": "Qual è il colore dominante di questa immagine? Una parola."}, {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": ""}}, ], } ]

# Testo di risposta osservato: "Rosso"
```

9. Riferimento Verificato: Latenza e Uso di un Compito Lungo in Una Singola Chiamata

Il pensiero di K3 è fissato al livello massimo, quindi le richieste singole per compiti complessi richiedono significativamente più tempo rispetto ai modelli tipici. Dati misurati da un compito di generazione di gioco HTML in un singolo file (un prompt con un'immagine di riferimento, generato in un colpo solo senza iterazione): la richiesta singola ha impiegato 2.541 secondi (circa 42 minuti), con 74.994 token di completamento, di cui 54.486 (73%) erano token di pensiero; l'output finale era di 1.275 righe di codice direttamente eseguibile, con finish_reason stop.

Raccomandazioni lato client:

• Imposta i timeout del client a minuti o più a lungo e preferisci lo streaming per compiti lunghi;
• Lascia ampio margine in max_completion_tokens — in questo caso il pensiero da solo ha consumato 54.486 token.

10. Capacità × Matrice di Supporto API

Ogni cella nella tabella sottostante è stata verificata il 2026-07-17 tramite chiamate effettive alle API di produzione di AIHubMix; ogni cella mostra la sintassi del parametro / campo per l'API corrispondente.

FAQ

Quali API supporta K3 su AIHubMix?
Chat Completions (/v1/chat/completions), Risposte (/v1/responses) e l'API Messaggi compatibile con Claude (/v1/messages).

È possibile disabilitare o ridurre il pensiero?
No. Il pensiero di K3 è attivato per impostazione predefinita e reasoning_effort supporta solo il singolo livello "max".

Perché il reasoning_content deve essere restituito nelle conversazioni multi-turno?
K3 è addestrato con il pensiero preservato; Moonshot richiede che il messaggio precedente dell'assistente venga restituito completo e non modificato. La mancanza di storia del pensiero porta a una qualità di output instabile.

Quali sono i limiti sul parametro stop?
Al massimo 5 sequenze di stop, ciascuna non più lunga di 32 byte; superare uno dei due limiti restituisce un errore 400.

L'API dei Messaggi supporta output strutturati?
❗ No. L'endpoint ufficiale dei Messaggi di Kimi K3 (compatibile con Anthropic) ignora silenziosamente i campi di output strutturati (restituendo 200 con testo libero e senza errore). Per output strutturati, utilizza response_format su Chat Completions o text.format su Risposte.

Perché le richieste singole di K3 richiedono così tanto tempo?
Il pensiero di K3 è fissato al livello massimo e i token di pensiero costituiscono una grande parte nei compiti complessi (73% dei token di completamento nel caso misurato). Imposta i timeout del client a minuti o più a lungo e utilizza lo streaming.

Per prezzi e stato in tempo reale, vedere la pagina del modello Kimi K3; per altri modelli, visita la galleria dei modelli.

Ultimo aggiornamento: 2026-07-17