Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Stato legacy e principio stateless

Lezione 1 di 12 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. L’endpoint Chat Completions nell’ecosistema xAI
  2. Un endpoint stateless: invia tutto a ogni richiesta
  3. Punti chiave

Aggiornato il 3 novembre 2026 sulla base delle best practice di xAI: xAI classifica ora le Chat Completions come deprecate e raccomanda l’API Responses per i modelli di ragionamento Grok. Motivo concreto: le Chat Completions non dispongono di un campo per il ragionamento cifrato del modello, quindi ogni conversazione multi-turno o chiamata di strumento perde il ragionamento dei turni precedenti. Le nuove funzionalità arrivano inoltre prima sull’API Responses. Fonti: Best practice di xAI · Chat Completions (legacy).

L’endpoint Chat Completions nell’ecosistema xAI

L’API di xAI offre due endpoint principali per interagire con i modelli Grok: l’API Responses (endpoint primario) e l’endpoint Chat Completions. Quest’ultimo è contrassegnato come legacy: rimane pienamente funzionale, ma le nuove funzionalità sono ora prioritarie per l’API Responses.

Perché interessarsene allora? Perché le Chat Completions restano l’endpoint più adottato nell’ecosistema. Tutti gli SDK OpenAI esistenti, framework come LangChain o LlamaIndex e migliaia di tutorial utilizzano questo formato. Se stai migrando da un altro provider o lavori con strumenti di terze parti, questo è probabilmente il primo endpoint che utilizzerai.

Legacy
Stato ufficiale
Stateless
Nessuno stato sul server
OpenAI
Formato compatibile
3600s
Timeout raccomandato

Un endpoint stateless: invia tutto a ogni richiesta

Il principio fondamentale delle Chat Completions è che sono stateless: il server non conserva alcuno storico della conversazione. A ogni chiamata, devi includere l’intero storico dei messaggi precedenti nella tua richiesta.

Nello specifico, ciò significa che per una conversazione con 10 scambi, la tua undicesima richiesta deve contenere i 10 messaggi precedenti (utente + assistente) più il nuovo messaggio. È la tua applicazione a gestire questo storico.

{
  "model": "grok-4.20-0309-reasoning",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hello! How can I help you?"},
    {"role": "user", "content": "Explain deep learning to me."}
  ]
}

In questo esempio, i primi tre messaggi rappresentano lo storico della conversazione. Solo l’ultimo è il nuovo messaggio dell’utente. Il modello ha bisogno di tutto questo contesto per produrre una risposta coerente.

Implicazioni pratiche

Questo approccio stateless comporta diverse implicazioni:

  • Controllo totale: decidi esattamente quali messaggi inviare al modello. Puoi filtrare, riassumere o modificare lo storico prima di ogni chiamata.
  • Costo proporzionale: ogni richiesta viene fatturata per tutti i token inviati, incluso lo storico. Più lunga è la conversazione, più costa ogni scambio.
  • Nessuna persistenza sul server: nessun dato viene memorizzato lato xAI tra le richieste. Questo è un vantaggio per la privacy, ma ti richiede di gestire tu stesso la persistenza.

Confronto con l’API Responses

L’API Responses, invece, è stateful: mantiene lo storico lato server tramite previous_response_id. Non hai bisogno di reinviare i messaggi precedenti: basta un semplice identificatore. Le risposte possono essere memorizzate fino a 30 giorni con store: true.

La scelta tra i due dipende dal tuo caso d’uso. Se lavori con un SDK OpenAI esistente o stai migrando da un altro provider, le Chat Completions sono il punto di partenza logico. Per un nuovo progetto, si raccomanda l’API Responses.

Punti chiave

  • Le Chat Completions sono contrassegnate come legacy, ma rimangono pienamente funzionali e compatibili con l’ecosistema OpenAI
  • L’endpoint è stateless: devi reinviare l’intero storico a ogni richiesta
  • Il costo di ogni richiesta include tutti i token dello storico
  • L’API Responses offre un’alternativa stateful con persistenza lato server
  • Per i modelli di ragionamento, si raccomanda un timeout di 3600 secondi