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

O SDK Python da xAI: Operações Assíncronas

Aula 16 de 16 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Automatize os Seus Fluxos de Trabalho RAG em Python
  2. Instalação e Configuração
  3. Operações de Coleção
  4. Adicionar um Documento e Aguardar a Indexação
  5. Pesquisa a partir do SDK
  6. Um Pipeline Completo de Ponta a Ponta
  7. Pontos-chave
  8. Teste os Seus Conhecimentos

Atualizado em 2 de novembro de 2026. Com base no código xai-sdk 1.21.0 e no exemplo oficial da xAI: as chamadas await exigem o cliente assíncrono AsyncClient (o Client é síncrono), os objetos devolvidos expõem collection_id, collections, matches e chunk_content, o estado da indexação compara-se com collections_pb2.DOCUMENT_STATUS_PROCESSED, e upload_document carrega 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); await exige esta última
  • Ambas as chaves (API e Gestão) configuram-se no cliente
  • upload_document carrega e anexa numa única chamada; monitore a indexação via get_document ou wait_for_indexing=True
  • asyncio.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.