Adicionar documentos a uma coleção
Nesta página
Atualizado em 2 de novembro de 2026. Esta lição reflete a versão
xai-sdk1.21.0 e a documentação da xAI: as chamadasawaitexigem o cliente assíncronoAsyncClient, o estado de indexação compara-se com a constantecollections_pb2.DOCUMENT_STATUS_PROCESSED(não uma cadeia de caracteres) e a ingestão em lote utilizaupload_document, que combina ambas as etapas numa única chamada. Fontes: Coleções via API · xai-sdk-python.
Por que razão a adição ocorre em duas etapas
Poderia esperar largar um PDF diretamente numa coleção, como arrasta um ficheiro para uma pasta. Não é assim que a API da xAI funciona: o documento passa primeiro pela API de Ficheiros, que o armazena e atribui um file_id, e depois pela API de Gestão, que associa esse identificador à coleção. Duas chamadas, duas chaves, duas etapas.
Esta separação tem uma consequência direta e útil: o ficheiro existe apenas uma vez no lado do armazenamento, mas pode ser associado a tantas coleções quantas forem necessárias. O mesmo relatório técnico pode alimentar a base de dados da equipa de produto e a da equipa de suporte sem ser carregado duas vezes, sem consumir quota duas vezes e sem risco de divergência entre duas cópias.
Etapa 1: Carregar o ficheiro
Nada de novo aqui, este é o endpoint que domina desde a primeira lição:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Recupere o file_id da resposta: é a chave para a próxima etapa.
Etapa 2: Associar à coleção
A adição assume a forma de um POST para um URL que combina os dois identificadores, o ID da coleção e o ID do ficheiro, e não requer corpo de pedido:
curl -X POST https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Assim que esta chamada é aceite, a xAI inicia a indexação do conteúdo. O documento passa então por vários estados de processamento antes de ficar realmente disponível para pesquisa.
Aguarde a conclusão da indexação
Esta é uma armadilha comum no primeiro pipeline: o pedido de adição devolve sucesso, segue-se imediatamente com uma pesquisa e a coleção responde que não encontra nada. O documento existe, mas ainda não está indexado. O estado a aguardar é DOCUMENT_STATUS_PROCESSED, e o SDK permite sondá-lo corretamente:
import asyncio
import os
from xai_sdk import AsyncClient
from xai_sdk.proto import collections_pb2
client = AsyncClient(
api_key=os.getenv("XAI_API_KEY"),
management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
)
async def wait_for_indexing(file_id, collection_id):
doc = await client.collections.get_document(file_id, collection_id)
while doc.status != collections_pb2.DOCUMENT_STATUS_PROCESSED:
if doc.status == collections_pb2.DOCUMENT_STATUS_FAILED:
raise RuntimeError(f"Indexing failed: {doc.error_message}")
await asyncio.sleep(3)
doc = await client.collections.get_document(file_id, collection_id)
print("Document indexed and ready for search")
asyncio.run(wait_for_indexing("file_abc123", "col_xyz789"))
O atraso depende diretamente do tamanho: um PDF de algumas páginas é indexado em poucos segundos, enquanto um documento de 100 MB pode levar vários minutos. Para ingestão noturna, este ciclo com uma pausa de três segundos é suficiente; numa interface onde o utilizador carrega um ficheiro e aguarda, forneça feedback visual em vez de um ecrã congelado.
Remover um documento sem o perder
Desassociar um ficheiro de uma coleção é uma operação distinta de o eliminar:
curl -X DELETE \
https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
O ficheiro desaparece do índice desta coleção, mas permanece disponível através da API de Ficheiros e pode ser associado noutro local. É exatamente isto que deve fazer quando uma ficha de produto se torna obsoleta para o suporte, mantendo contudo o seu valor de arquivo: remove-a da base de dados operacional sem destruir o documento.
Povoar uma coleção em lote
Ao inicializar uma base de dados a partir de uma pasta inteira, escreva o ciclo uma vez; servir-lhe-á bem durante muito tempo:
import asyncio
import os
from pathlib import Path
from xai_sdk import AsyncClient
client = AsyncClient(
api_key=os.getenv("XAI_API_KEY"),
management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
)
files = [
"docs/guide-installation.pdf",
"docs/reference-api.pdf",
"docs/faq.md",
"docs/changelog.txt",
]
async def populate(collection_id):
for file_path in map(Path, files):
# Etapas 1 e 2 numa única chamada: carregar via API de Ficheiros e depois associar
await client.collections.upload_document(
collection_id=collection_id,
name=file_path.name,
data=file_path.read_bytes(),
)
print(f"Added: {file_path}")
asyncio.run(populate("col_xyz789"))
Note a mistura de formatos na lista — PDF, Markdown e texto simples coexistem sem problemas na mesma coleção, o que o poupa de padronizar as suas fontes antes da ingestão.
Duas chaves, dois âmbitos
Este processo utiliza dois identificadores de acesso que não deve confundir: a chave de API padrão (XAI_API_KEY) para o carregamento da etapa 1 e a chave de Gestão (XAI_MANAGEMENT_API_KEY) para a associação da etapa 2. O SDK recebe ambas na criação do cliente e upload_document utiliza-as uma após a outra. Verifique se esta última possui a permissão AddFileToCollection: sem ela, o seu carregamento será bem-sucedido, a sua adição falhará com um erro 403 e acumulará ficheiros corretamente armazenados, mas ausentes de qualquer coleção.
Pontos-chave
- A adição a uma coleção ocorre em duas etapas: carregar e depois adicionar
- Um ficheiro pode pertencer a várias coleções simultaneamente
- O documento deve atingir o estado
DOCUMENT_STATUS_PROCESSEDantes de ser pesquisável - Remover um documento de uma coleção não elimina o ficheiro subjacente
- São necessárias duas chaves de API distintas: padrão para o carregamento, Gestão para a coleção