Tempo limite, parâmetros proibidos e configuração
Nesta página
Atualizado em 3 de novembro de 2026. Com base nas melhores práticas da xAI e no guia Reasoning: o tempo de espera recomendado é de pelo menos 900 segundos (3.600 nos exemplos), e não “mínimo de 3.600 segundos”; a lista de modelos de raciocínio inclui o grok-4.6 e o grok-4.7; o grok-4.7 transmite um resumo do seu raciocínio; as justificações para os parâmetros proibidos, ausentes na documentação, foram removidas. Fontes: Melhores práticas · Reasoning.
Configure corretamente os seus pedidos de raciocínio
Os modelos de raciocínio têm restrições específicas que os modelos clássicos não possuem. Ignorar estas restrições pode causar erros silenciosos, tempos limite inesperados ou respostas truncadas. Esta lição abrange os parâmetros de configuração essenciais.
Tempo limite: pelo menos 900 segundos
As melhores práticas da xAI exigem pelo menos 900 segundos por pedido, e 1.800 segundos ou mais para avaliações longas; os exemplos do guia Reasoning definem mesmo o atraso para 3.600 segundos (1 hora). Estes números podem parecer elevados, mas refletem a realidade: um raciocínio profundo sobre um problema complexo pode levar vários minutos. A xAI recomenda também preferir a transmissão em fluxo (streaming), que mantém a ligação ativa durante gerações longas.
Por que razão um tempo limite tão longo?
Quando um modelo de raciocínio processa um problema difícil (demonstração matemática, análise de código complexa, raciocínio em várias etapas), potencialmente gera milhares de tokens de raciocínio interno antes de formular a sua resposta. Este processo é linear e não pode ser paralelizado.
Configuração do tempo limite
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)
)
Em JavaScript com o SDK da 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
});
Tempo limite do servidor web
Se a sua aplicação estiver atrás de um proxy reverso (nginx, Apache), configure também o tempo limite do lado do servidor:
# nginx
location /api/ {
proxy_read_timeout 3600s;
proxy_connect_timeout 10s;
proxy_send_timeout 3600s;
}
Parâmetros proibidos em modelos de raciocínio
Três parâmetros comummente utilizados com modelos clássicos não podem ser enviados para os modelos de raciocínio da xAI: segundo o guia Reasoning, um pedido que os contenha devolve um erro. A documentação não indica a razão para estas proibições; memorize a regra.
presencePenalty
// ERROR on reasoning models
{
"model": "grok-4.20-0309-reasoning",
"presence_penalty": 0.5, // Forbidden!
"messages": [...]
}
O presencePenalty penaliza os tokens que já apareceram na resposta para incentivar a diversidade.
frequencyPenalty
// ERROR on reasoning models
{
"model": "grok-4.20-0309-reasoning",
"frequency_penalty": 0.3, // Forbidden!
"messages": [...]
}
O frequencyPenalty penaliza os tokens proporcionalmente à sua frequência de aparição.
stop
// ERROR on reasoning models
{
"model": "grok-4.20-0309-reasoning",
"stop": ["\n\n"], // Forbidden!
"messages": [...]
}
O parâmetro stop interrompe a geração quando aparece uma sequência específica. Para limitar o comprimento da resposta, utilize max_completion_tokens em alternativa, que limita apenas a resposta visível, e uma instrução de formato no prompt.
Gestão de erros relacionados com parâmetros
Ao migrar código existente para um modelo de raciocínio, limpe os parâmetros não suportados:
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
Transmissão em fluxo (streaming) com modelos de raciocínio
A transmissão em fluxo funciona com modelos de raciocínio, mas o comportamento depende da geração: no grok-3-mini (geração anterior), o reasoning_content aparecia claramente no fluxo, antes dos tokens de resposta. No grok-4.20-0309-reasoning, o raciocínio permanece interno e não é transmitido: apenas a resposta final chega ao fluxo. Exceção notável: na API de Respostas, o grok-4.7 transmite um resumo do seu raciocínio, em eventos response.reasoning_summary_text.delta que pode exibir antes da resposta.
Exemplo histórico com o 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="")
Pontos-chave
- Permita pelo menos 900 segundos por pedido (3.600 nos exemplos do guia Reasoning) e prefira a transmissão em fluxo
- Três parâmetros são proibidos:
presencePenalty,frequencyPenaltyestop - Limpe os parâmetros ao migrar de modelos clássicos
- Utilize
max_completion_tokensem vez demax_tokens - A transmissão em fluxo funciona, mas o comportamento difere consoante o modelo