Timeout, parametri interziși și configurare
Pe această pagină
Actualizat la 3 noiembrie 2026. Pe baza celor mai bune practici xAI și a ghidului Reasoning: timpul de așteptare recomandat este de cel puțin 900 de secunde (3.600 în exemple), nu „minimum 3.600 de secunde“; lista modelelor de raționament include grok-4.6 și grok-4.7; grok-4.7 transmite în flux un rezumat al raționamentului său; justificările pentru parametrii interziși, absente din documentație, au fost eliminate. Surse: Cele mai bune practici · Reasoning.
Configurați corect cererile de raționament
Modelele de raționament au constrângeri specifice pe care modelele clasice nu le au. Ignorarea acestor constrângeri poate provoca erori silențioase, timeout-uri neașteptate sau răspunsuri trunchiate. Această lecție acoperă parametrii esențiali de configurare.
Timeout: cel puțin 900 de secunde
Cele mai bune practici xAI impun cel puțin 900 de secunde per cerere, iar 1.800 de secunde sau mai mult pentru evaluări lungi; exemplele din ghidul Reasoning setează chiar întârzierea la 3.600 de secunde (1 oră). Aceste cifre pot părea mari, dar reflectă realitatea: un raționament profund asupra unei probleme complexe poate dura câteva minute. xAI recomandă, de asemenea, preferarea streaming-ului, care menține conexiunea activă în timpul generărilor lungi.
De ce un timeout atât de lung?
Când un model de raționament procesează o problemă dificilă (demonstrație matematică, analiză complexă de cod, raționament în mai mulți pași), acesta generează potențial mii de jetoane (tokens) interne de raționament înainte de a formula răspunsul. Acest proces este liniar și nu poate fi paralelizat.
Configurarea timeout-ului
import httpx
from openai import OpenAI
# Configuration with high timeout
client = OpenAI(
api_key="your-api-key",
base_url="https://api.x.ai/v1",
timeout=httpx.Timeout(3600.0, connect=10.0)
)
În JavaScript cu SDK-ul OpenAI:
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: 'your-api-key',
baseURL: 'https://api.x.ai/v1',
timeout: 3600 * 1000 // 3600 seconds in milliseconds
});
Timeout al serverului web
Dacă aplicația dumneavoastră se află în spatele unui proxy invers (nginx, Apache), configurați și timeout-ul la nivel de server:
# nginx
location /api/ {
proxy_read_timeout 3600s;
proxy_connect_timeout 10s;
proxy_send_timeout 3600s;
}
Parametri interziși la modelele de raționament
Trei parametri utilizați frecvent cu modelele clasice nu pot fi trimiși către modelele de raționament xAI: conform ghidului Reasoning, o cerere care îi conține returnează o eroare. Documentația nu oferă motivul acestor interdicții; rețineți regula.
presencePenalty
// ERROR on reasoning models
{
"model": "grok-4.20-0309-reasoning",
"presence_penalty": 0.5, // Forbidden!
"messages": [...]
}
presencePenalty penalizează jetoanele care au apărut deja în răspuns pentru a încuraja diversitatea.
frequencyPenalty
// ERROR on reasoning models
{
"model": "grok-4.20-0309-reasoning",
"frequency_penalty": 0.3, // Forbidden!
"messages": [...]
}
frequencyPenalty penalizează jetoanele proporțional cu frecvența lor de apariție.
stop
// ERROR on reasoning models
{
"model": "grok-4.20-0309-reasoning",
"stop": ["\n\n"], // Forbidden!
"messages": [...]
}
Parametrul stop oprește generarea atunci când apare o secvență specifică. Pentru a limita lungimea răspunsului, utilizați în schimb max_completion_tokens, care limitează doar răspunsul vizibil, și o instrucțiune de format în prompt.
Gestionarea erorilor legate de parametri
Când migrați codul existent către un model de raționament, curățați parametrii neacceptați:
def prepare_params(model, base_params):
"""Cleans parameters for reasoning models."""
reasoning_models = [
# current range
"grok-4.7", "grok-4.6", "grok-4.5", "grok-4.20-0309-reasoning",
# historical identifiers, still present in existing code
"grok-3-mini", "grok-4-fast-reasoning",
]
params = {**base_params, "model": model}
if model in reasoning_models:
# Remove forbidden parameters
for forbidden in ["presence_penalty", "frequency_penalty", "stop"]:
params.pop(forbidden, None)
# Replace max_tokens with max_completion_tokens
if "max_tokens" in params:
params["max_completion_tokens"] = params.pop("max_tokens")
return params
Streaming cu modelele de raționament
Streaming-ul funcționează cu modelele de raționament, dar comportamentul depinde de generație: la grok-3-mini (generația anterioară), reasoning_content apărea în clar în flux, înainte de jetoanele de răspuns. La grok-4.20-0309-reasoning, raționamentul rămâne intern și nu este transmis în flux: doar răspunsul final ajunge în flux. Excepție notabilă: la API-ul Responses, grok-4.7 transmite în flux un rezumat al raționamentului său, în evenimentele response.reasoning_summary_text.delta pe care le puteți afișa înainte de răspuns.
Exemplu istoric cu 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="")
Puncte cheie
- Alocați cel puțin 900 de secunde per cerere (3.600 în exemplele din ghidul Reasoning) și preferați streaming-ul
- Trei parametri sunt interziși:
presencePenalty,frequencyPenaltyșistop - Curățați parametrii la migrarea de la modelele clasice
- Utilizați
max_completion_tokensîn loc demax_tokens - Streaming-ul funcționează, dar comportamentul diferă în funcție de model