O SDK Python da xAI: Operações Assíncronas
Nesta página
Atualizado em 2 de novembro de 2026. Com base no código
xai-sdk1.21.0 e no exemplo oficial da xAI: as chamadasawaitexigem o cliente assíncronoAsyncClient(oClienté síncrono), os objetos devolvidos expõemcollection_id,collections,matchesechunk_content, o estado da indexação compara-se comcollections_pb2.DOCUMENT_STATUS_PROCESSED, eupload_documentcarrega e anexa o ficheiro numa única chamada (o exemplo anterior carregava-o duas vezes, usando um método inexistente). Fontes: Collections via the API · Collections Search · xai-sdk-python.
Automatize os Seus Fluxos de Trabalho RAG em Python
Tudo o que invocou via curl ao longo deste curso existe em Python: carregamento de documentos, gestão de coleções, pesquisa e geração. O SDK da xAI oferece dois clientes, um síncrono (Client) e outro assíncrono (AsyncClient), com métodos idênticos. Este último é a escolha certa para um fluxo de trabalho RAG, que passa a maior parte do tempo à espera — que um carregamento termine, que um documento seja indexado, que uma pesquisa devolva resultados. O código assíncrono gere estas esperas em paralelo, e não em sequência.
Instalação e Configuração
pip install xai-sdk
O cliente requer duas chaves: a chave de API padrão para pesquisa e geração, e a chave da API de Gestão para coleções.
import os
from xai_sdk import AsyncClient
client = AsyncClient(
api_key=os.getenv("XAI_API_KEY"),
management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
)
Cada pedido tem um tempo limite predefinido de 27 minutos antes de expirar, o que cobre o carregamento de um PDF de grandes dimensões. O parâmetro timeout, em segundos, permite-lhe apertar este limite para uma aplicação interativa.
Operações de Coleção
Três chamadas cobrem todo o ciclo de vida. A criação devolve o ID que reutilizará em todo o lado:
collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Collection created: {collection_id}")
A listagem serve principalmente para recuperar um ID que não persistiu, ou para verificar o estado de uma conta partilhada entre vários projetos:
response = await client.collections.list()
for col in response.collections:
print(f"{col.collection_id} — {col.collection_name} ({col.documents_count} documents)")
A eliminação é irreversível e remove os documentos e os seus índices:
await client.collections.delete(collection_id)
Adicionar um Documento e Aguardar a Indexação
Uma única chamada, upload_document, carrega o ficheiro via API de Ficheiros e anexa-o à coleção:
from pathlib import Path
async def add_document(client, collection_id, file_path):
path = Path(file_path)
document = await client.collections.upload_document(
collection_id=collection_id,
name=path.name,
data=path.read_bytes(),
)
return document.file_metadata.file_id
Se o ficheiro já existir na API de Ficheiros, add_existing_document(collection_id, file_id) anexa-o sem o voltar a carregar.
Adicionar um documento não o torna imediatamente consultável. A indexação demora um tempo variável consoante o tamanho do ficheiro, e uma pesquisa lançada demasiado cedo devolve simplesmente menos resultados do que o esperado — um erro particularmente doloroso de diagnosticar, já que não gera nenhuma exceção. Daí este ciclo de espera, que consulta o estado até obter DOCUMENT_STATUS_PROCESSED:
import asyncio
from xai_sdk.proto import collections_pb2
async def wait_for_indexing(client, file_id, collection_id):
while True:
doc = await client.collections.get_document(file_id, collection_id)
if doc.status == collections_pb2.DOCUMENT_STATUS_PROCESSED:
print("Document ready")
return
if doc.status == collections_pb2.DOCUMENT_STATUS_FAILED:
raise RuntimeError(f"Indexing failed: {doc.error_message}")
await asyncio.sleep(3)
O estado é um valor de enumeração, não uma cadeia de caracteres: compará-lo com o texto "DOCUMENT_STATUS_PROCESSED" nunca seria verdadeiro, e o ciclo executaria para sempre. Para um caso simples, upload_document(..., wait_for_indexing=True) gere esta espera por si.
Pesquisa a partir do SDK
A pesquisa devolve os mesmos fragmentos pontuados que o endpoint HTTP, na lista matches:
results = await client.collections.search(
query="Order validation procedure",
collection_ids=[collection_id],
)
for m in results.matches:
print(f"Score: {m.score:.2f}")
print(f"Content: {m.chunk_content[:200]}")
print("---")
Um Pipeline Completo de Ponta a Ponta
Os blocos anteriores juntam-se num script que cria a coleção, carrega documentos, aguarda a indexação, pesquisa e, depois, gera uma resposta usando a ferramenta collections_search:
import asyncio
import os
from xai_sdk import AsyncClient
from xai_sdk.chat import user
from xai_sdk.tools import collections_search
async def rag_pipeline():
client = AsyncClient(
api_key=os.getenv("XAI_API_KEY"),
management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
)
# 1. Criar a coleção
collection = await client.collections.create(name="project-documentation")
collection_id = collection.collection_id
# 2. Adicionar documentos em paralelo
files = [
"docs/architecture.pdf",
"docs/api-reference.pdf",
"docs/deployment-guide.md",
]
file_ids = await asyncio.gather(*[
add_document(client, collection_id, f) for f in files
])
# 3. Aguardar que todos os documentos sejam indexados
await asyncio.gather(*[
wait_for_indexing(client, fid, collection_id) for fid in file_ids
])
# 4. Pesquisar
results = await client.collections.search(
query="How to deploy to production?",
collection_ids=[collection_id],
)
for m in results.matches:
print(f"[{m.score:.2f}] {m.chunk_content[:150]}")
# 5. Gerar uma resposta com base na coleção
chat = client.chat.create(
model="grok-4.7",
tools=[collections_search(collection_ids=[collection_id])],
)
chat.append(user("Explain the deployment procedure and cite your sources."))
response = await chat.sample()
print(response.content)
print(response.citations)
asyncio.run(rag_pipeline())
As duas chamadas asyncio.gather() fazem todo o trabalho. A primeira lança os três carregamentos em conjunto, em vez de esperar que cada um termine; a segunda monitoriza os três trabalhos de indexação simultaneamente: o tempo total aproxima-se do do documento mais demorado, e não da soma de todos. E como a espera não bloqueia o ciclo de eventos, o mesmo código encaixa diretamente numa aplicação FastAPI ou aiohttp, que continua a servir outros pedidos enquanto os seus documentos são indexados.
Pontos-chave
- O SDK Python da xAI existe nas versões síncrona (
Client) e assíncrona (AsyncClient);awaitexige esta última - Ambas as chaves (API e Gestão) configuram-se no cliente
upload_documentcarrega e anexa numa única chamada; monitore a indexação viaget_documentouwait_for_indexing=Trueasyncio.gather()permite carregar e aguardar a indexação em paralelo- A geração aproveita a coleção com a ferramenta
collections_search, completa com resposta e citações
Teste os Seus Conhecimentos
Ficheiros, coleções, pesquisa: RAG gerido pela xAI.
1. O que permite fazer a API de Ficheiros?
Resposta: Carregar e gerir ficheiros (listar, visualizar, eliminar) em formatos suportados — a matéria-prima para coleções e consultas com documentos.
2. O que é uma coleção?
Resposta: Um conjunto de documentos gerido no lado do servidor pela xAI, com metadados e permissões — o índice pronto a usar que consulta sem precisar de construir o seu próprio pipeline vetorial.
3. Quais os modos de pesquisa disponíveis?
Resposta: Por palavras-chave (termos exatos), semântica (significado) e híbrida (ambos) — a escolha segue a natureza das perguntas, cobrindo a híbrida a maioria dos casos.
4. Como é que o RAG se integra na geração?
Resposta: Através da ferramenta de pesquisa de coleção: collections_search no SDK da xAI, file_search com IDs de coleção na API de Respostas. O modelo consulta os seus documentos durante a geração e cita as suas fontes — o padrão RAG sem infraestrutura para manter.
5. Que pontos exigem atenção para produção?
Resposta: Confidencialidade dos dados carregados (permissões, ciclo de vida), relevância a otimizar (metadados, fragmentação) — e o SDK assíncrono para processamento de alto volume.
RAG gerido: você traz os documentos e as perguntas, a xAI trata do índice — mantenha o controlo da confidencialidade e da relevância.