Cache x-grok-conv-id e Tempo Limite de Raciocínio
Nesta página
Otimize Custos com Cache
Cada pedido enviado à API da xAI é faturado ao preço padrão por token. No entanto, quando envia vários pedidos relacionados (mesma conversa, mesmo tópico), parte do contexto repete-se. O cabeçalho x-grok-conv-id permite à xAI identificar estes pedidos relacionados e aumentar a taxa de acertos no cache, reduzindo os seus custos.
O Cabeçalho x-grok-conv-id
Para ativar o cache conversacional, adicione um cabeçalho personalizado com um UUID v4 único por conversa:
import uuid
conversation_id = str(uuid.uuid4())
# Com o SDK da OpenAI
response = await client.chat.completions.create(
model="grok-4.5",
messages=[{"role": "user", "content": prompt}],
extra_headers={
"x-grok-conv-id": conversation_id
}
)
Todos os pedidos que partilham o mesmo x-grok-conv-id beneficiam de uma taxa de acertos no cache melhorada. Os tokens em cache são faturados a uma taxa reduzida em comparação com os tokens padrão.
Regras de Utilização
- Gere um novo UUID para cada conversa ou sessão lógica
- Reutilize o mesmo UUID para todos os pedidos dentro da mesma conversa
- Não reutilize um UUID em conversas diferentes (isto degrada o cache)
# Padrão para um 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
Tempo Limite de 3600 Segundos para Raciocínio
Os modelos de raciocínio (grok-4.20-0309-reasoning e semelhantes) realizam um raciocínio interno antes de responder. Este raciocínio pode demorar vários minutos para problemas complexos. O tempo limite padrão da maioria dos clientes HTTP (30-120 segundos) é insuficiente.
# Configuração correta para raciocínio
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, # ligação rápida
read=3600.0, # 1 hora para leitura
write=30.0, # envio do prompt
pool=10.0 # espera da ligação
)
)
read=3600.0 é o valor crítico. Este é o atraso máximo entre o momento em que o servidor começa a processar o seu pedido e o momento em que recebe a resposta. Para um modelo de raciocínio que raciocina durante 5 minutos, precisa desta margem.
Quando Reduzir o Tempo Limite
O tempo limite de 3600 segundos nem sempre é necessário:
- grok-4.5 (não raciocínio): um tempo limite de 120-300 segundos é geralmente suficiente
- Pedidos simples: mesmo com um modelo de raciocínio, perguntas curtas respondem em menos de um minuto
- Ambiente de teste: um tempo limite de 60 segundos permite detetar problemas rapidamente
# Cliente para pedidos rápidos
fast_client = AsyncOpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1",
timeout=httpx.Timeout(120.0)
)
# Cliente para raciocínio complexo
reasoning_client = AsyncOpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1",
timeout=httpx.Timeout(3600.0)
)
Utilizar dois clientes com tempos limite diferentes é um padrão comum em produção.
Nota sobre o grok-4.5 e o Raciocínio
O modelo grok-4.5 não devolve o campo reasoning_content em texto simples na resposta. O raciocínio interno é realizado, mas permanece opaco. Se precisar de ver o processo de raciocínio, utilize use_encrypted_content=True para o preservar entre pedidos sem poder lê-lo, ou grok-4.20-0309-reasoning, que expõe mais do seu processo.
Verifique o Impacto do Cache
Para medir a eficiência do cache, compare o campo usage entre pedidos com e sem 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}%)")
Uma elevada taxa de acertos no cache significa que os seus tokens de contexto são reutilizados em vez de serem reprocessados, o que reduz diretamente a sua fatura.
Pontos-chave
x-grok-conv-idcom um UUID v4 ativa o cache conversacional para pedidos relacionados- Os tokens em cache são faturados a uma taxa reduzida
- Um tempo limite de 3600 segundos é necessário para modelos de raciocínio
- Utilize clientes separados para pedidos rápidos e pedidos de raciocínio
grok-4.5não devolvereasoning_contentem texto simples- Monitore a taxa de acertos no cache em
usage.prompt_tokens_detailspara validar a otimização