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

AsyncOpenAI com httpx.Timeout

Aula 2 de 12 Atualizada a 30 de julho de 2026 Avancado
Nesta página
  1. A Alternativa ao SDK da OpenAI
  2. Configurar o AsyncOpenAI para a xAI
  3. Compreender o httpx.Timeout
  4. Enviar Pedidos
  5. Tratamento de Erros com httpx
  6. Quando Escolher o AsyncOpenAI em vez do SDK da xAI
  7. Pontos-chave

A Alternativa ao SDK da OpenAI

O SDK nativo da xAI não é a sua única opção para trabalhar de forma assíncrona com a API do Grok. O SDK da OpenAI, amplamente adotado no ecossistema Python, funciona com a API da xAI graças à compatibilidade de formatos. Esta abordagem permite-lhe reutilizar código existente da OpenAI e aproveitar o ecossistema de ferramentas circundante.

Configurar o AsyncOpenAI para a xAI

A inicialização requer três parâmetros: a sua chave de API, o URL base da xAI e um tempo limite ajustado para modelos de 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(3600.0)
)

O detalhe crucial aqui é httpx.Timeout(3600.0). O SDK da OpenAI utiliza o httpx como seu cliente HTTP subjacente e o tempo limite predefinido é de 10 minutos. Para os modelos de raciocínio do Grok, precisa de aumentar este valor para 3600 segundos (uma hora) para evitar desconexões prematuras.

Compreender o httpx.Timeout

A classe httpx.Timeout aceita vários parâmetros que controlam diferentes fases da ligação:

# Tempo limite uniforme: 3600s para tudo
timeout = httpx.Timeout(3600.0)

# Tempo limite granular
timeout = httpx.Timeout(
    connect=10.0,    # tempo limite da ligação inicial
    read=3600.0,     # tempo limite de leitura da resposta
    write=30.0,      # tempo limite de envio do pedido
    pool=10.0        # tempo de espera por uma ligação livre
)

Em produção, pode afinar estes valores. A ligação inicial deve falhar rapidamente se o servidor estiver inacessível (10 segundos são suficientes), enquanto o tempo limite de leitura precisa de ser paciente o suficiente para aguardar o raciocínio do modelo.

Enviar Pedidos

A sintaxe segue o formato padrão do SDK da OpenAI, utilizando await:

import asyncio

async def query_grok(prompt: str) -> str:
    response = await client.chat.completions.create(
        model="grok-4.20-0309-reasoning",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

result = asyncio.run(query_grok("What are the advantages of Rust over C++?"))

Verá a mesma estrutura da API da OpenAI: um array messages com funções e conteúdo. A resposta segue o mesmo esquema, acessível através de response.choices[0].message.content.

Tratamento de Erros com httpx

O SDK da OpenAI com httpx fornece exceções específicas que deve capturar:

from openai import APITimeoutError, APIConnectionError, RateLimitError

async def safe_query(prompt: str) -> str | None:
    try:
        response = await client.chat.completions.create(
            model="grok-4.20-0309-reasoning",
            messages=[{"role": "user", "content": prompt}]
        )
        return response.choices[0].message.content
    except APITimeoutError:
        print("Tempo limite excedido—o pedido demorou demasiado tempo")
        return None
    except RateLimitError:
        print("Limite de taxa atingido—reduza a frequência dos pedidos")
        return None
    except APIConnectionError:
        print("Não foi possível ligar ao servidor da xAI")
        return None

As três exceções mais comuns são APITimeoutError (o modelo não respondeu dentro do tempo atribuído), RateLimitError (excedeu os limites de RPM/TPM) e APIConnectionError (problema de rede).

Quando Escolher o AsyncOpenAI em vez do SDK da xAI

O SDK da OpenAI é preferível se já tiver uma base de código da OpenAI, utilizar ferramentas de terceiros compatíveis com a OpenAI (LangChain, LiteLLM) ou quiser alternar entre fornecedores sem modificar o seu código. O SDK nativo da xAI, no entanto, oferece um acesso mais direto a funcionalidades específicas do Grok, como ferramentas integradas.

Pontos-chave

  • O AsyncOpenAI funciona com a API da xAI através de base_url="https://api.x.ai/v1"
  • O httpx.Timeout(3600.0) é obrigatório para modelos de raciocínio
  • O formato de pedido e resposta é idêntico à API padrão da OpenAI
  • As exceções APITimeoutError, RateLimitError e APIConnectionError cobrem os principais casos de erro
  • Esta escolha é ideal para reutilizar código existente ou integrar ferramentas de terceiros compatíveis com a OpenAI