Blog

Guida all'uso

Gestione delle risposte di Kimi K3 in pratica: JSON completo, interruzioni dello streaming e limiti dei tentativi

Nov 18, 2026
Immagine di copertina geometrica astratta su fondo verde scuro profondo, con due gruppi di nastri intrecciati che formano una griglia aperta, impreziosita da sobri accenti color ottone.
In questa pagina

Prima di tutto, distingui i due percorsi di risposta

Con la stessa interfaccia Kimi K3, ciò che ricevi può essere di due tipi completamente diversi: una risposta JSON completa, oppure una sequenza di blocchi di dati in streaming che arrivano in ordine. La prima è una consegna di documento «domanda-risposta», la seconda è una sequenza incrementale «genera e invia man mano». Molti bug nella gestione delle risposte non nascono da un parsing scritto male, ma dal non aver chiarito fin dall'inizio su quale dei due percorsi ci si trova.

Entrambi i percorsi condividono lo stesso protocollo di richiesta (openai_chat_completions, versione del contratto 2); le differenze si concentrano nel modo di consumo:

  • Non streaming: una volta restituita la richiesta, ottieni un corpo di risposta completo; testo, contenuto di ragionamento e usage sono tutti lì, basta leggerlo una volta.
  • Streaming: la risposta viene attivata in modalità opzionale, il server continua a inviare chunk e termina lo stream con il marcatore SSE [DONE]. A metà strada potresti ricevere decine o centinaia di blocchi, oppure la connessione potrebbe interrompersi; [DONE] indica solo la fine dello stream, non che il contenuto sia completo.

Solo dopo aver confermato questo punto il resto della discussione ha senso. Se nella tua catena applicativa coesistono entrambi i tipi di chiamata (ad esempio un'elaborazione batch in background e una conversazione frontend che condividono lo stesso wrapper), è consigliabile marcare esplicitamente il percorso nel client, invece di distinguerli con un giudizio implicito come «c'è o non c'è una callback»: quest'ultimo approccio nasconde mine di fallimento della deserializzazione in fase di refactoring.

Una semplice regola decisionale: usa lo streaming quando devi mostrare il testo all'utente carattere per carattere o quando l'output può essere molto lungo; usa il non streaming quando devi ottenere un risultato strutturato in un'unica soluzione, da salvare poi nel database o rielaborare. Il codice di parsing dei due percorsi dovrebbe essere scritto separatamente; in comune restano solo la costruzione della richiesta e la mappatura degli errori.

Lo stesso ingresso di richiesta si divide in due percorsi di consumo: uno restituisce la risposta in un blocco unico, l'altro la restituisce a frammenti successivi.

Analizzare il JSON completo: testo, contenuto di ragionamento e campi strutturati

La risposta non streaming segue il formato del corpo di risposta di OpenAI Chat Completions, ma c'è un punto facile da trascurare: testo e contenuto di ragionamento sono due campi diversi.

Il testo si trova nella posizione standard del contenuto del messaggio, mentre il processo di ragionamento di Kimi K3 viene consegnato tramite il campo reasoning_content. Questo significa che il tuo livello di parsing deve fare almeno tre cose:

  • estrarre dalla posizione del contenuto del messaggio la risposta finale destinata all'utente;
  • verificare se esiste reasoning_content e, in caso affermativo, decidere se registrarlo nei log, mostrarlo all'utente o scartarlo;
  • salvare separatamente usage per la fatturazione e il calcolo delle quote.

Mostrare reasoning_content come testo è un incidente frequente: è pensato per scenari di debug e spiegabilità, e inserirlo direttamente nei testi di prodotto o nelle risposte all'assistenza clienti produce tono e contenuti inappropriati. L'approccio corretto è assegnargli un percorso di consumo dedicato, ad esempio un log di debug o un ingresso opzionale come «visualizza il processo di ragionamento».

Come usare l'output strutturato

Il contratto supporta il parametro response_format e la capacità di output strutturato jsonObject. Puoi chiedere al modello di restituire un oggetto JSON, eliminando così uno strato fragile di estrazione con espressioni regolari. Ma vanno chiariti due presupposti: la capacità jsonObject non equivale al supporto della modalità JSON Schema; inoltre l'output strutturato non è una garanzia di «successo certo».

Tenta di analizzare il JSON solo dopo che la risposta si è completata normalmente e il contenuto è integro. Anche dopo l'analisi, devi gestire tre tipi di fallimento:

  • Fallimento del parsing: il contenuto restituito non è JSON valido, oppure mancano campi o i tipi non corrispondono. In questo caso non dovresti passare la stringa originale direttamente al livello applicativo superiore, ma entrare in un ramo di degrado.
  • Fallimento della validazione dello schema: la sintassi JSON è valida ma non rispetta la struttura dichiarata. jsonObject non garantisce vincoli a livello di JSON Schema; il livello applicativo deve comunque validare autonomamente campi, tipi e campi obbligatori.
  • Troncamento: quando la lunghezza dell'output raggiunge il limite di token di output di questo modello (131072), finish_reason può essere length e il JSON può terminare a metà. Non puoi considerare length come un successo JSON completo. Un parser JSON difettoso restituirà un errore, ma il caso più pericoloso è quando «riesce a malapena ad analizzare» e tu continui a eseguire la logica applicativa con mezzo oggetto.

Si consiglia di aggiungere dopo il parsing un controllo di integrità dei campi applicativi e delle evidenze, invece di affidarti solo alla validità sintattica del JSON. La finestra di contesto è 1000000; negli scenari con documenti lunghi l'input non è il collo di bottiglia, ma il troncamento dell'output resta un limite reale.

La busta della risposta viene scomposta in strati: testo, contenuto di ragionamento e usage formano ciascuno un ramo che fluisce verso il proprio consumatore.

Lettura in streaming: [DONE], finish_reason e usage

In modalità streaming il server invia i chunk in ordine e il marcatore di terminazione di rete SSE è [DONE]. Detta così sembra banale, ma viene spesso fraintesa: [DONE] indica solo che questo stream è terminato, non che la generazione abbia avuto successo né che il contenuto sia completo.

Per determinare lo stato terminale devi guardare choices[].finish_reason in ciascun chunk. Attualmente il frontend riconosce lo stato terminale quando finish_reason non è vuoto; anche se hai ricevuto [DONE], la mancanza di finish_reason deve comunque essere considerata un'interruzione. Un frame error all'interno dello stream indica invece il fallimento di questa richiesta.

Lo stream può terminare in diversi stati:

  1. Completamento normale: finish_reason è uno stato terminale di successo, seguito da [DONE]; il contenuto accumulato può essere considerato un risultato completo;
  2. Troncamento per lunghezza: finish_reason=length, l'output è stato troncato per il limite di lunghezza, il contenuto può essere incompleto e non può essere considerato un successo JSON completo;
  3. Altri motivi non di successo: ad esempio il filtro dei contenuti, da gestire separatamente e non da considerare completamento normale;
  4. Interruzione a metà: chiusura della connessione, timeout o ricezione di un frame error all'interno dello stream; in questo caso hai solo parte del contenuto e devi marcarlo come fallito o incompleto.

L'ultimo caso è il più facile da implementare come «prendo quello che arriva». Per una visualizzazione in chat può essere accettabile (l'utente vede mezza frase e può reinviare), ma per il salvataggio nel database, la fatturazione o l'attivazione di azioni downstream si tratta di dati errati. Usa «se è stato ricevuto uno stato terminale di successo finish_reason» come criterio di completezza, non limitarti a controllare [DONE].

L'usage viene aggregato dopo la fine dello stream

In modalità streaming, usage può comparire in un frame choices:[] dopo finish_reason. Il client deve leggere l'intero stream e poi aggregare l'usage; non si può garantire che [DONE] stesso porti l'usage.

Questo comporta due vincoli di codifica diretti:

  • Non eseguire fatturazione o calcolo delle quote già al primo chunk. In quel momento non sai quanto sarà lungo l'output finale e non hai il campo usage.
  • Non accumulare l'usage nei blocchi intermedi e non trattare [DONE] come contenitore dell'usage. Nei blocchi intermedi non ci sono dati usage affidabili; qualsiasi «stima» si discosterà dal valore finale.

L'ordine corretto è: durante lo streaming ti occupi solo di accumulare testo e stato; dopo aver letto lo stream, aggreghi l'usage dal frame choices:[] ed esegui la liquidazione. Se lo stream si interrompe a metà e hai già mostrato contenuto all'utente, lo stato dell'usage di questa chiamata è sconosciuto: hai bisogno di uno stato «incompleto», non di un valore predefinito 0 o di un valore stimato.

Inoltre, distingui i metadati interni dai campi di rete: response.stream.terminal=done e response.usage.delivery=final_chunk sono etichette di metadati interne alla piattaforma, non campi di rete SSE né stringhe di terminazione da confrontare nel client. Il client deve affidarsi solo a [DONE], finish_reason, ai frame error e al campo usage stesso.

Un altro dettaglio pratico: per accumulare il testo usa l'aggiunta a una lista e poi un join, invece della concatenazione ripetuta di stringhe; con output lunghi la differenza di prestazioni è evidente.

La linea temporale superiore raggiunge un blocco terminale color ottone con un finish_reason di successo; quella inferiore si interrompe a metà e non raggiunge lo stato terminale di successo, quindi non si può presumere di aver ottenuto un risultato completo.

Perché un tentativo POST non è un'idempotenza gratuita

Molte logiche di retry sono scritte così: la richiesta genera un'eccezione di timeout, la catturi, aspetti un po' e reinvii. Questo articolo discute solo la semantica delle operazioni POST generativo come il completamento di conversazione: un simile retry può causare doppi addebiti e effetti collaterali duplicati e non va trattato come idempotenza gratuita.

Il motivo è semplice: il timeout è un giudizio del client, non una promessa del server. Quando il tuo timer scatta, la richiesta può essere già arrivata completa al server, può aver già iniziato l'inferenza, o addirittura può essere già completata e fatturata, con la sola risposta persa sulla via del ritorno. Il client non può distinguere queste due situazioni basandosi solo sul tipo di eccezione:

  • la richiesta non è arrivata al server: il retry non produce una seconda esecuzione;
  • la richiesta è stata accettata e ha prodotto effetti: il retry è una seconda chiamata.

Gli «effetti» del completamento di conversazione includono di solito il consumo di token e la fatturazione, oltre alle azioni che attivi sul lato applicativo in base alla risposta (scrittura su database, invio di moduli, invio di messaggi). Ripetere una POST di esito incerto equivale a compiere questi effetti collaterali due volte. Non è un rischio teorico: jitter di rete, timeout del gateway e reset della connessione da parte di dispositivi intermedi creano stabilmente questo tipo di stati ambigui.

Il problema peggiore è che una risposta 5xx completa, un timeout, una disconnessione o un fallimento del parsing JSON non possono dimostrare che la richiesta non sia stata generata, non sia stata addebitata o non abbia avuto effetti collaterali. L'errore che vedi indica solo che questa volta il client non ha ottenuto un risultato utilizzabile.

Quindi il presupposto corretto per un retry non è «c'è stato un errore», ma «questa richiesta non è stata eseguita con certezza». Prima di scrivere qualsiasi codice di retry, rispondi a questa domanda; se non ci riesci, non rinviare automaticamente.

Delimitare i limiti dei tentativi: in quali casi si può rinviare

Realizzare il retry come una tabella a livelli è più affidabile che scrivere un unico for retry in range(3). Di seguito la strategia di gestione suddivisa per tipo di errore.

Esecuzione certamente non avvenuta: si può riprovare

  • Fallimento dell'apertura della connessione (fallimento DNS, connessione rifiutata): la richiesta chiaramente non ha raggiunto il server, si tratta di invio certamente non avvenuto e il retry non produce una seconda esecuzione.
  • Risposta di rate limiting (ad esempio 429): esegui il retry con backoff solo se la documentazione dell'interfaccia o la semantica della risposta garantiscono esplicitamente il rifiuto prima dell'esecuzione; non dedurre da un 429 o da un altro codice di stato che la richiesta non sia stata eseguita o non sia stata fatturata. Il backoff deve includere jitter casuale per evitare retry sincronizzati tra più client.
  • Meccanismo di deduplicazione esplicitamente fornito dall'interfaccia e realmente utilizzato dal server: puoi riprovare secondo la sua semantica solo quando la documentazione dell'interfaccia lo specifica chiaramente e il server lo usa effettivamente per deduplicare. Gli identificatori di richiesta generati dal client servono solo al tracciamento; non puoi presumere che un determinato header o campo abbia effetto idempotente.

Risultato sconosciuto: gestione esplicita necessaria

  • Timeout: è la categoria più pericolosa. Il timeout non dimostra che la richiesta non sia stata eseguita; il reinvio può produrre una nuova generazione a pagamento. Gli identificatori di richiesta generati dal client possono essere usati solo per il tracciamento; solo se il server supporta esplicitamente e usa effettivamente un meccanismo di deduplicazione è possibile evitare inferenze e addebiti duplicati. La deduplicazione lato applicativo può al massimo evitare azioni downstream duplicate, non può impedire al modello di rigenerare e fatturare. Se non puoi confermare la semantica di deduplicazione del server, non rinviare automaticamente: segnala l'errore all'utente o passa a un processo di compensazione manuale/asincrono.
  • Risposta 5xx completa: anche se il corpo della risposta è completo e leggibile, non dimostra che non ci sia stata generazione, addebito o effetto collaterale. Puoi riprovare solo quando l'esecuzione è certamente non avvenuta oppure la documentazione dell'interfaccia specifica che il server deduplica realmente in base all'identificatore; altrimenti trattala come risultato sconosciuto.
  • Fallimento del parsing della risposta: include il fallimento del parsing JSON e il fallimento della validazione dello schema. La richiesta può essere già riuscita ed essere già stata fatturata; il fallimento del parsing non dimostra che non ci sia stata generazione. Un retry può causare doppi addebiti ed effetti collaterali duplicati; si consiglia di marcarlo esplicitamente come risultato sconosciuto e registrarlo, per poter verificare a posteriori l'usage.
  • Disconnessione a metà dello streaming o ricezione di un frame error all'interno dello stream: il contenuto già inviato non può essere concatenato con un nuovo risultato; il reinvio sarà considerato una generazione completamente nuova.

Non riprovare automaticamente

  • Errori nei parametri della richiesta (errori di parametri tra i 4xx): qualunque numero di retry dà lo stesso risultato, amplificando solo l'errore.
  • Rifiuti di moderazione dei contenuti: il reinvio non cambia la conclusione.
  • Qualsiasi situazione in cui non puoi determinare «se ha già avuto effetto» e non esiste una semantica di deduplicazione lato server.

Inserire i limiti nel codice

Due vincoli ingegneristici meritano di essere consolidati: imposta un limite massimo al numero di retry (di solito 1 o 2 sono sufficienti) e applicali solo a invii certamente non avvenuti o a casi in cui la documentazione dell'interfaccia garantisce esplicitamente il rifiuto prima dell'esecuzione; registra per ogni retry l'identificatore di richiesta, il tipo di errore e la durata, perché «quanti retry sono stati fatti» determina direttamente la tua fattura di utilizzo e il percorso di troubleshooting. Per i retry delle richieste in streaming presta ulteriore attenzione: reinviare dopo una disconnessione a metà connessione produce una generazione completamente nuova a pagamento e il contenuto già inviato non può essere concatenato con il nuovo risultato.

Se sei ancora in fase di scelta, puoi prima dare un'occhiata alla pagina del modello Kimi K3 per conoscere i dettagli del contratto e poi decidere la granularità della strategia di retry.

Checklist operativa

Raccogli le regole precedenti in una checklist da confrontare punto per punto in fase di revisione:

  • Il client distingue esplicitamente i due percorsi di consumo, streaming e non streaming, invece di basarsi su giudizi impliciti?
  • Nel parsing non streaming, testo e reasoning_content sono gestiti separatamente e reasoning_content non finisce direttamente nei testi visibili all'utente?
  • usage viene salvato separatamente ed è correlabile ai record applicativi?
  • L'output strutturato viene analizzato solo dopo che la risposta si è completata normalmente e il contenuto è integro, con fallback indipendenti per fallimento del parsing, fallimento della validazione dello schema, fallimento delle validazioni applicative e delle evidenze e finish_reason=length?
  • La lettura in streaming riconosce lo stato terminale tramite finish_reason non vuoto, invece di attendere solo [DONE]?
  • [DONE] viene trattato solo come marcatore di fine stream e la mancanza di finish_reason viene marcata come interruzione?
  • L'usage viene aggregato dal frame choices:[] dopo aver letto lo stream, senza presumere che [DONE] porti l'usage?
  • I frame error all'interno dello stream vengono riconosciuti come fallimento, non come fine normale?
  • Il retry è suddiviso per tipo di errore e si applica solo a invii certamente non avvenuti o a casi in cui la documentazione dell'interfaccia garantisce esplicitamente il rifiuto prima dell'esecuzione?
  • Timeout, disconnessioni, 5xx completi o fallimenti del parsing JSON vengono gestiti esplicitamente come «risultato sconosciuto», senza promettere che il retry sia sicuro?
  • Il numero di retry ha un limite massimo e ogni retry dispone di log utilizzabili per verificare l'usage?
  • Il reinvio dopo un'interruzione dello streaming viene considerato una nuova generazione, non una continuazione?

Non è necessario soddisfare l'intera checklist in una volta, ma ogni voce corrisponde a un problema che si verifica realmente in produzione. Affronta per prime le due voci sul criterio di stato terminale finish_reason e sui limiti dei retry: sono quelle con il beneficio più diretto.

Inizia a creare con artefatti IA persistenti

Ottieni la tua chiave API e chiama modelli di immagini, video e audio tramite un'unica API basata sui task.

Leggi la documentazione API