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

xAI SDK AsyncClient

Aula 1 de 12 Atualizada a 2 de novembro de 2026 Avancado
Nesta página
  1. Por que mudar para o modo assíncrono
  2. Inicializar o AsyncClient
  3. Enviar um pedido assíncrono
  4. Diferença em relação ao cliente síncrono
  5. Pontos-chave

Por que mudar para o modo assíncrono

Quando consulta a API da xAI de forma síncrona, cada chamada bloqueia a execução do seu programa até à chegada da resposta. Para um modelo de raciocínio como o grok-4.5, um único pedido pode demorar várias dezenas de segundos. Se precisar de processar 100 pedidos, o tempo total de espera torna-se proibitivo.

O modo assíncrono resolve este problema. Em vez de esperar por cada resposta, o seu programa lança o pedido e continua a execução. Recupera o resultado mais tarde, quando este estiver disponível. Esta abordagem permite-lhe processar múltiplos pedidos em paralelo e utilizar totalmente a sua largura de banda para a API.

3600s
Tempo limite recomendado
5x
Throughput paralelo
-50%
Alternativa à Batch API
RPM
Limite de taxa a respeitar

Inicializar o AsyncClient

O SDK da xAI fornece a classe AsyncClient, dedicada a chamadas assíncronas. A inicialização é semelhante à do cliente síncrono, com um parâmetro timeout que deve configurar sempre:

import os
from xai_sdk import AsyncClient
from xai_sdk.chat import user

client = AsyncClient(
    api_key=os.getenv("XAI_API_KEY"),
    timeout=3600,
)

timeout=3600 equivale a uma hora. Este valor pode parecer elevado, mas é necessário para modelos de raciocínio que realizam um pensamento prolongado antes de responder. Um tempo limite demasiado curto provoca erros de queda de ligação em pedidos complexos.

Enviar um pedido assíncrono

Depois de inicializar o cliente, envia pedidos utilizando a sintaxe await do Python:

import asyncio

async def ask_grok(question: str) -> str:
    chat = client.chat.create(
        model="grok-4.20-0309-reasoning",
        max_tokens=500
    )
    chat.append(user(question))
    response = await chat.sample()
    return response.text

# Ponto de entrada
result = asyncio.run(ask_grok("Explain the algorithmic complexity of quicksort"))
print(result)

A função ask_grok utiliza async def, tornando-a uma corrotina. A chamada await chat.sample() suspende esta corrotina até à chegada da resposta, sem bloquear outras tarefas potenciais.

Diferença em relação ao cliente síncrono

O cliente síncrono bloqueia o thread atual durante toda a duração do pedido. O cliente assíncrono liberta o thread para executar outras corrotinas. Esta distinção é irrelevante se enviar apenas um pedido, mas torna-se crítica quando processa múltiplos pedidos em paralelo.

# Síncrono: cada chamada espera pela resposta
for question in questions:
    response = client.chat.completions.create(...)  # bloqueante
    process(response)

# Assíncrono: as chamadas correm em paralelo
async def main():
    tasks = [ask_grok(q) for q in questions]
    responses = await asyncio.gather(*tasks)  # paralelo
    for r in responses:
        process(r)

No exemplo síncrono, se cada pedido demorar 10 segundos e tiver 20, o tempo total é de 200 segundos. No modo assíncrono, com um semáforo de 5 (que descobrirá em lições posteriores), o tempo reduz-se para cerca de 40 segundos.

Pontos-chave

  • O AsyncClient do SDK da xAI permite-lhe enviar pedidos sem bloquear a execução
  • O parâmetro timeout=3600 é essencial para modelos de raciocínio
  • O xai-sdk requer Python 3.10 ou superior (versão 1.21.0 em 2 de novembro de 2026, segundo o PyPI)
  • O benefício real surge ao processar múltiplos pedidos em paralelo
  • asyncio.run() serve como ponto de entrada para executar uma corrotina a partir de código síncrono