Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Cache x-grok-conv-id e Tempo Limite de Raciocínio

Aula 11 de 12 Atualizada a 30 de julho de 2026 Avancado
Nesta página
  1. Otimize Custos com Cache
  2. O Cabeçalho x-grok-conv-id
  3. Tempo Limite de 3600 Segundos para Raciocínio
  4. Nota sobre o grok-4.5 e o Raciocínio
  5. Verifique o Impacto do Cache
  6. Pontos-chave

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-id com 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.5 não devolve reasoning_content em texto simples
  • Monitore a taxa de acertos no cache em usage.prompt_tokens_details para validar a otimização