Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Timeout, parametri vietati e configurazione

Lezione 11 di 12 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Configura correttamente le tue richieste di ragionamento
  2. Timeout: almeno 900 secondi
  3. Parametri vietati sui modelli di ragionamento
  4. Gestione degli errori legati ai parametri
  5. Streaming con i modelli di ragionamento
  6. Punti chiave

Aggiornato il 3 novembre 2026. Sulla base delle best practice di xAI e della guida Reasoning: il tempo di attesa raccomandato è di almeno 900 secondi (3.600 negli esempi), non “minimo 3.600 secondi”; l’elenco dei modelli di ragionamento include grok-4.6 e grok-4.7; grok-4.7 trasmette in streaming un riepilogo del suo ragionamento; sono state rimosse le giustificazioni per i parametri vietati, assenti dalla documentazione. Fonti: Best practices · Reasoning.

Configura correttamente le tue richieste di ragionamento

I modelli di ragionamento hanno vincoli specifici che i modelli classici non possiedono. Ignorare questi vincoli può causare errori silenziosi, timeout imprevisti o risposte troncate. Questa lezione copre i parametri di configurazione essenziali.

Timeout: almeno 900 secondi

Le best practice di xAI richiedono almeno 900 secondi per richiesta, e 1.800 secondi o più per valutazioni lunghe; gli esempi della guida Reasoning impostano addirittura il ritardo a 3.600 secondi (1 ora). Questi numeri possono sembrare elevati, ma riflettono la realtà: un ragionamento profondo su un problema complesso può richiedere diversi minuti. xAI raccomanda inoltre di preferire lo streaming, che mantiene la connessione attiva durante generazioni lunghe.

Perché un timeout così lungo?

Quando un modello di ragionamento elabora un problema difficile (dimostrazione matematica, analisi di codice complessa, ragionamento multi-step), genera potenzialmente migliaia di token di ragionamento interno prima di formulare la sua risposta. Questo processo è lineare e non può essere parallelizzato.

Configurazione del timeout

import httpx
from openai import OpenAI

# Configurazione con timeout elevato
client = OpenAI(
    api_key="your-api-key",
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(3600.0, connect=10.0)
)

In JavaScript con l’SDK OpenAI:

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'your-api-key',
  baseURL: 'https://api.x.ai/v1',
  timeout: 3600 * 1000  // 3600 secondi in millisecondi
});

Timeout del server web

Se la tua applicazione si trova dietro un reverse proxy (nginx, Apache), configura anche il timeout lato server:

# nginx
location /api/ {
    proxy_read_timeout 3600s;
    proxy_connect_timeout 10s;
    proxy_send_timeout 3600s;
}

Parametri vietati sui modelli di ragionamento

Tre parametri comunemente usati con i modelli classici non possono essere inviati ai modelli di ragionamento di xAI: secondo la guida Reasoning, una richiesta che li contiene restituisce un errore. La documentazione non fornisce il motivo di questi divieti; ricorda semplicemente la regola.

presencePenalty

// ERRORE sui modelli di ragionamento
{
  "model": "grok-4.20-0309-reasoning",
  "presence_penalty": 0.5,  // Vietato!
  "messages": [...]
}

presencePenalty penalizza i token già apparsi nella risposta per incoraggiare la diversità.

frequencyPenalty

// ERRORE sui modelli di ragionamento
{
  "model": "grok-4.20-0309-reasoning",
  "frequency_penalty": 0.3,  // Vietato!
  "messages": [...]
}

frequencyPenalty penalizza i token proporzionalmente alla loro frequenza di apparizione.

stop

// ERRORE sui modelli di ragionamento
{
  "model": "grok-4.20-0309-reasoning",
  "stop": ["\n\n"],  // Vietato!
  "messages": [...]
}

Il parametro stop interrompe la generazione quando appare una sequenza specifica. Per delimitare la lunghezza della risposta, usa invece max_completion_tokens, che limita solo la risposta visibile, e un’istruzione di formato nel prompt.

Gestione degli errori legati ai parametri

Quando migri codice esistente verso un modello di ragionamento, pulisci i parametri non supportati:

def prepare_params(model, base_params):
    """Pulisce i parametri per i modelli di ragionamento."""
    reasoning_models = [
        # gamma attuale
        "grok-4.7", "grok-4.6", "grok-4.5", "grok-4.20-0309-reasoning",
        # identificatori storici, ancora presenti nel codice esistente
        "grok-3-mini", "grok-4-fast-reasoning",
    ]

    params = {**base_params, "model": model}

    if model in reasoning_models:
        # Rimuovi i parametri vietati
        for forbidden in ["presence_penalty", "frequency_penalty", "stop"]:
            params.pop(forbidden, None)

        # Sostituisci max_tokens con max_completion_tokens
        if "max_tokens" in params:
            params["max_completion_tokens"] = params.pop("max_tokens")

    return params

Streaming con i modelli di ragionamento

Lo streaming funziona con i modelli di ragionamento, ma il comportamento dipende dalla generazione: su grok-3-mini (generazione precedente), reasoning_content appariva in chiaro nello stream, prima dei token di risposta. Su grok-4.20-0309-reasoning, il ragionamento rimane interno e non viene trasmesso in streaming: solo la risposta finale arriva nello stream. Eccezione notevole: sulle API Responses, grok-4.7 trasmette in streaming un riepilogo del suo ragionamento, negli eventi response.reasoning_summary_text.delta che puoi visualizzare prima della risposta.

Esempio storico con grok-3-mini:

stream = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
    reasoning_effort="high",
    stream=True
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if hasattr(delta, 'reasoning_content') and delta.reasoning_content:
        print(f"[Reasoning] {delta.reasoning_content}", end="")
    elif delta.content:
        print(f"[Response] {delta.content}", end="")

Punti chiave

  • Consenti almeno 900 secondi per richiesta (3.600 negli esempi della guida Reasoning) e preferisci lo streaming
  • Tre parametri sono vietati: presencePenalty, frequencyPenalty e stop
  • Pulisci i parametri quando migri dai modelli classici
  • Usa max_completion_tokens invece di max_tokens
  • Lo streaming funziona ma il comportamento varia a seconda del modello