AsyncOpenAI com httpx.Timeout
Nesta página
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
AsyncOpenAIfunciona com a API da xAI através debase_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,RateLimitErroreAPIConnectionErrorcobrem os principais casos de erro - Esta escolha é ideal para reutilizar código existente ou integrar ferramentas de terceiros compatíveis com a OpenAI