Cache x-grok-conv-id e Timeout per il Ragionamento
In questa pagina
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-idcon 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.5non restituiscereasoning_contentin testo semplice- Monitora il tasso di successo della cache in
usage.prompt_tokens_detailsper validare l’ottimizzazione