Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Migrazione graduale alle API Responses

Lezione 12 di 12 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Perché e quando migrare
  2. Passo 1: Identifica le funzionalità che utilizzi
  3. Passo 2: Migra le chiamate di base
  4. Passo 3: Migra le conversazioni multi-turno
  5. Passo 4: Sfrutta le nuove funzionalità
  6. Strategia di migrazione consigliata
  7. Punti chiave
  8. Metti alla prova le tue conoscenze

Aggiornato il 3 novembre 2026: La mappatura dei parametri indicava precedentemente che max_tokens manteneva il suo nome nelle API Responses; la tabella di xAI lo cambia in max_output_tokens e anche i contatori di utilizzo cambiano nome. Fonte: Confronto con Chat Completions.

Perché e quando migrare

L’endpoint Chat Completions è contrassegnato come legacy. Continuerà a funzionare, ma non riceverà nuove funzionalità. Se la tua applicazione necessita di strumenti lato server (ricerca web, esecuzione di codice), archiviazione delle conversazioni o ragionamento crittografato, la migrazione alle API Responses diventa necessaria.

La buona notizia: questa migrazione può avvenire gradualmente. Non devi riscrivere tutto in una volta sola.

Passo 1: Identifica le funzionalità che utilizzi

Prima di migrare, fai il punto su ciò che la tua applicazione utilizza con Chat Completions:

# Audit del tuo codice esistente
# Cerca questi pattern:

# 1. Chiamate di base (testo semplice)
client.chat.completions.create(model=..., messages=...)

# 2. Streaming
client.chat.completions.create(..., stream=True)

# 3. Chiamata di funzioni
client.chat.completions.create(..., tools=[...])

# 4. Visione (immagini)
# messaggi con content come array [text, image_url]

# 5. Parametri di generazione
# temperature, max_tokens, top_p, stop, seed

Le chiamate di base e lo streaming sono le più semplici da migrare. La chiamata di funzioni richiede un adattamento del formato. La visione funziona in modo simile.

Passo 2: Migra le chiamate di base

La migrazione di una chiamata semplice segue questo schema:

# PRIMA — Chat Completions
response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)
texte = response.choices[0].message.content

# DOPO — API Responses
response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    instructions="You are a helpful assistant.",
    input="Hello!"
)
texte = response.output_text

Mappatura dei campi

Le modifiche principali sono:

  • messages con ruolo system → instructions (parametro dedicato)
  • messages con ruolo user → input (stringa semplice)
  • response.choices[0].message.content → response.output_text
  • max_tokens → max_output_tokens, secondo la tabella di mappatura di xAI; temperature mantiene il suo nome
  • response.usage.prompt_tokens e completion_tokens → input_tokens e output_tokens (dettagli: input_tokens_details.cached_tokens, output_tokens_details.reasoning_tokens)

Passo 3: Migra le conversazioni multi-turno

È qui che le API Responses semplificano le cose. Invece di ricostruire la cronologia a ogni richiesta, le colleghi tramite ID:

# PRIMA — Chat Completions (gestisci tu la cronologia)
historique = [
    {"role": "system", "content": "You are a helpful assistant."}
]

def envoyer_message(texte: str) -> str:
    historique.append({"role": "user", "content": texte})
    response = client.chat.completions.create(
        model="grok-4.20-0309-reasoning",
        messages=historique
    )
    reponse = response.choices[0].message.content
    historique.append({"role": "assistant", "content": reponse})
    return reponse

# DOPO — API Responses (il server gestisce la cronologia)
dernier_id = None

def envoyer_message(texte: str) -> str:
    response = client.responses.create(
        model="grok-4.20-0309-reasoning",
        instructions="You are a helpful assistant.",
        input=texte,
        previous_response_id=dernier_id
    )
    dernier_id = response.id
    return response.output_text

Il codice è più semplice e non devi più gestire manualmente l’array dei messaggi.

Passo 4: Sfrutta le nuove funzionalità

Una volta migrato, puoi sfruttare le funzionalità esclusive delle API Responses:

Ricerca web integrata

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What are the latest developments in generative AI?",
    tools=[{"type": "web_search"}]
)
# La risposta include citazioni con URL di origine

Archiviazione delle risposte

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Analyze this document...",
    store=True  # Mantiene per 30 giorni
)

# Recupera successivamente
stored = client.responses.retrieve(response.id)

Ragionamento crittografato

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Solve this complex problem...",
    include=["reasoning.encrypted_content"]
)
# Il ragionamento crittografato può essere riutilizzato nelle richieste successive

Strategia di migrazione consigliata

Invece di migrare tutto in una volta, procedi per passi:

  1. Identifica le chiamate Chat Completions nel tuo codice
  2. Classificale per complessità (base → streaming → chiamata di funzioni)
  3. Migra prima i nuovi endpoint o le nuove funzionalità (greenfield)
  4. Poi migra le chiamate esistenti più semplici
  5. Mantieni Chat Completions per le integrazioni di terze parti che lo richiedono (LangChain, ecc.)

Coesistenza temporanea

È perfettamente accettabile eseguire entrambi gli endpoint fianco a fianco durante la transizione:

# Wrapper che astrae l'endpoint utilizzato
class GrokClient:
    def __init__(self, use_responses: bool = False):
        self.use_responses = use_responses
        self.client = OpenAI(
            api_key=os.getenv("XAI_API_KEY"),
            base_url="https://api.x.ai/v1"
        )

    def generate(self, system: str, user_message: str) -> str:
        if self.use_responses:
            response = self.client.responses.create(
                model="grok-4.20-0309-reasoning",
                instructions=system,
                input=user_message
            )
            return response.output_text
        else:
            response = self.client.chat.completions.create(
                model="grok-4.20-0309-reasoning",
                messages=[
                    {"role": "system", "content": system},
                    {"role": "user", "content": user_message}
                ]
            )
            return response.choices[0].message.content

Questo approccio ti permette di passare gradualmente, testando ogni migrazione singolarmente.

Punti chiave

  • La migrazione può essere graduale: non serve riscrivere tutto in una volta
  • Cambiamenti principali: messages → input/instructions, choices[0].message.content → output_text
  • Le conversazioni multi-turno passano da un array di messaggi a un semplice previous_response_id
  • Le API Responses danno accesso a funzionalità esclusive (web_search, archiviazione, ragionamento crittografato)
  • Esegui entrambi gli endpoint fianco a fianco durante la transizione e migra per ordine di complessità

Metti alla prova le tue conoscenze

L’API legacy compresa e la migrazione preparata.

1. Cosa significa lo status legacy e stateless di Chat Completions?

Risposta: L’endpoint rimane supportato ma non evolve più: essendo stateless, richiede il rinvio dell’intera cronologia a ogni chiamata; le API Responses sono la strada moderna.

2. Quali ruoli strutturano i messaggi?

Risposta: system (e developer), user, assistant: il framework, le richieste, le risposte; l’intera cronologia ricomincia a ogni richiesta.

3. Come si utilizza il codice OpenAI esistente con Grok?

Risposta: Cambiando base_url in https://api.x.ai/v1 e la chiave API; la compatibilità del formato gestisce il resto, inclusi OpenAI SDK e Vercel AI SDK.

4. Cosa leggi nella risposta e nell'utilizzo?

Risposta: choices contiene le risposte con finish_reason; usage dettaglia i token, inclusi reasoning_tokens per i modelli di ragionamento: la base per il tracciamento dei costi.

5. Come migrare correttamente alle API Responses?

Risposta: Gradualmente: nuovi sviluppi in Responses, endpoint esistenti convertiti uno per uno con nuovo test dei prompt; il confronto tra i due formati guida la conversione.

Comprendi il legacy, costruisci per il moderno: il piano di migrazione graduale del corso è la tua roadmap, senza grandi sconvolgimenti.