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

Adicionar documentos a uma coleção

Aula 6 de 16 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Por que razão a adição ocorre em duas etapas
  2. Etapa 1: Carregar o ficheiro
  3. Etapa 2: Associar à coleção
  4. Aguarde a conclusão da indexação
  5. Remover um documento sem o perder
  6. Povoar uma coleção em lote
  7. Duas chaves, dois âmbitos
  8. Pontos-chave

Atualizado em 2 de novembro de 2026. Esta lição reflete a versão xai-sdk 1.21.0 e a documentação da xAI: as chamadas await exigem o cliente assíncrono AsyncClient, o estado de indexação compara-se com a constante collections_pb2.DOCUMENT_STATUS_PROCESSED (não uma cadeia de caracteres) e a ingestão em lote utiliza upload_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_PROCESSED antes 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