Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Cache x-grok-conv-id e Timeout per il Ragionamento

Lezione 11 di 12 Aggiornata il 30 luglio 2026 Avanzato
In questa pagina
  1. Ottimizza i costi con la cache
  2. L’intestazione x-grok-conv-id
  3. Timeout di 3600 secondi per il ragionamento
  4. Nota su grok-4.5 e il ragionamento
  5. Verifica l’impatto della cache
  6. Punti chiave

Ottimizza i costi con la cache

Ogni richiesta inviata alle API xAI viene fatturata al prezzo standard per token. Tuttavia, quando invii più richieste correlate (stessa conversazione, stesso argomento), parte del contesto si ripete. L’intestazione x-grok-conv-id consente a xAI di identificare queste richieste correlate e aumentare il tasso di successo della cache (cache hit rate), riducendo i tuoi costi.

L’intestazione x-grok-conv-id

Per abilitare la cache conversazionale, aggiungi un’intestazione personalizzata con un UUID v4 unico per conversazione:

import uuid

conversation_id = str(uuid.uuid4())

# Con l'SDK OpenAI
response = await client.chat.completions.create(
    model="grok-4.5",
    messages=[{"role": "user", "content": prompt}],
    extra_headers={
        "x-grok-conv-id": conversation_id
    }
)

Tutte le richieste che condividono lo stesso x-grok-conv-id beneficiano di un tasso di successo della cache migliorato. I token in cache sono fatturati a una tariffa ridotta rispetto ai token standard.

Regole di utilizzo

  • Genera un nuovo UUID per ogni conversazione o sessione logica
  • Riutilizza lo stesso UUID per tutte le richieste all’interno della stessa conversazione
  • Non riutilizzare un UUID tra conversazioni diverse (questo degrada la cache)
# Pattern per un chatbot
class ConversationManager:
    def __init__(self):
        self.conv_id = str(uuid.uuid4())
        self.messages = []

    async def send(self, user_message: str) -> str:
        self.messages.append({"role": "user", "content": user_message})

        response = await client.chat.completions.create(
            model="grok-4.5",
            messages=self.messages,
            extra_headers={"x-grok-conv-id": self.conv_id}
        )

        assistant_message = response.choices[0].message.content
        self.messages.append({"role": "assistant", "content": assistant_message})
        return assistant_message

Timeout di 3600 secondi per il ragionamento

I modelli di ragionamento (grok-4.20-0309-reasoning e simili) eseguono un ragionamento interno prima di rispondere. Questo processo può richiedere diversi minuti per problemi complessi. Il timeout predefinito per la maggior parte dei client HTTP (30-120 secondi) è insufficiente.

# Configurazione corretta per il ragionamento
from openai import AsyncOpenAI
import httpx

client = AsyncOpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(
        connect=10.0,     # connessione veloce
        read=3600.0,      # 1 ora per la lettura
        write=30.0,       # invio del prompt
        pool=10.0         # attesa della connessione
    )
)

read=3600.0 è il valore critico. Questo rappresenta il ritardo massimo tra l’inizio dell’elaborazione della richiesta da parte del server e la ricezione della risposta. Per un modello di ragionamento che elabora per 5 minuti, hai bisogno di questo margine.

Quando ridurre il timeout

Il timeout di 3600 secondi non è sempre necessario:

  • grok-4.5 (non-reasoning): un timeout di 120-300 secondi è solitamente sufficiente
  • Richieste semplici: anche con un modello di ragionamento, le domande brevi ricevono risposta in meno di un minuto
  • Ambiente di test: un timeout di 60 secondi ti permette di rilevare rapidamente i problemi
# Client per richieste veloci
fast_client = AsyncOpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(120.0)
)

# Client per ragionamenti complessi
reasoning_client = AsyncOpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(3600.0)
)

Utilizzare due client con timeout diversi è un pattern comune in produzione.

Nota su grok-4.5 e il ragionamento

Il modello grok-4.5 non restituisce il campo reasoning_content in testo semplice nella risposta. Il ragionamento interno viene eseguito ma rimane opaco. Se hai bisogno di preservare il processo di ragionamento, usa use_encrypted_content=True per mantenerlo tra le richieste senza poterlo leggere, oppure utilizza grok-4.20-0309-reasoning, che espone maggiormente il suo processo.

Verifica l’impatto della cache

Per misurare l’efficienza della cache, confronta il campo usage tra le richieste con e senza x-grok-conv-id:

response = await client.chat.completions.create(
    model="grok-4.5",
    messages=messages,
    extra_headers={"x-grok-conv-id": conv_id}
)

usage = response.usage
if hasattr(usage, 'prompt_tokens_details'):
    cached = usage.prompt_tokens_details.cached_tokens
    total = usage.prompt_tokens
    print(f"Cache hit: {cached}/{total} tokens ({cached/total*100:.0f}%)")

Un alto tasso di successo della cache significa che i tuoi token di contesto vengono riutilizzati invece di essere rielaborati, riducendo direttamente la tua fattura.

Punti chiave

  • x-grok-conv-id con un UUID v4 abilita la cache conversazionale per richieste correlate
  • I token in cache sono fatturati a una tariffa ridotta
  • Un timeout di 3600 secondi è necessario per i modelli di ragionamento
  • Usa client separati per richieste veloci e richieste di ragionamento
  • grok-4.5 non restituisce reasoning_content in testo semplice
  • Monitora il tasso di successo della cache in usage.prompt_tokens_details per validare l’ottimizzazione