Añadir documentos a una colección
En esta página
Actualizado el 2 de noviembre de 2026. Esta lección refleja la versión
xai-sdk1.21.0 y la documentación de xAI: las llamadasawaitrequieren el cliente asíncronoAsyncClient, el estado de indexación se compara con la constantecollections_pb2.DOCUMENT_STATUS_PROCESSED(no una cadena de texto) y la ingesta masiva utilizaupload_document, que combina ambos pasos en una única llamada. Fuentes: Colecciones mediante la API · xai-sdk-python.
Por qué la adición ocurre en dos pasos
Podrías esperar soltar un PDF directamente en una colección, como si arrastraras un archivo a una carpeta. Sin embargo, la API de xAI no funciona así: el documento pasa primero por la API de Archivos (Files API), que lo almacena y le asigna un file_id, y luego por la API de Gestión (Management API), que vincula ese identificador a la colección. Dos llamadas, dos claves, dos pasos.
Esta separación tiene una consecuencia directa y útil: el archivo existe una sola vez en el almacenamiento, pero puede vincularse a tantas colecciones como sea necesario. El mismo informe técnico puede alimentar la base de datos del equipo de producto y la del equipo de soporte sin necesidad de subirlo dos veces, sin consumir cuota duplicada y sin riesgo de divergencia entre dos copias.
Paso 1: Subir el archivo
Nada nuevo aquí; este es el endpoint que dominas desde la primera lección:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Recupera el file_id de la respuesta: es la clave para el siguiente paso.
Paso 2: Adjuntar a la colección
La adición toma la forma de una petición POST a una URL que combina los dos identificadores, el ID de la colección y el ID del archivo, y no requiere cuerpo de solicitud:
curl -X POST https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Una vez aceptada esta llamada, xAI comienza a indexar el contenido. El documento pasa entonces por varios estados de procesamiento antes de estar realmente disponible para la búsqueda.
Espera a que finalice la indexación
Este es un error común en el primer pipeline: la solicitud de adición devuelve éxito, realizas inmediatamente una búsqueda y la colección responde que no encuentra nada. El documento existe, pero aún no está indexado. El estado que debes esperar es DOCUMENT_STATUS_PROCESSED, y el SDK te permite sondearlo correctamente:
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"Indexación fallida: {doc.error_message}")
await asyncio.sleep(3)
doc = await client.collections.get_document(file_id, collection_id)
print("Documento indexado y listo para búsqueda")
asyncio.run(wait_for_indexing("file_abc123", "col_xyz789"))
El retraso depende directamente del tamaño: un PDF de pocas páginas se indexa en unos segundos, mientras que un documento de 100 MB puede tardar varios minutos. Para ingestas nocturnas, este bucle con una pausa de tres segundos es suficiente; en una interfaz donde el usuario sube un archivo y espera, proporciona retroalimentación visual en lugar de una pantalla congelada.
Eliminar un documento sin perderlo
Desvincular un archivo de una colección es una operación distinta a borrarlo:
curl -X DELETE \
https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
El archivo desaparece del índice de esta colección, pero sigue disponible a través de la API de Archivos y puede vincularse en otro lugar. Esto es exactamente lo que debes hacer cuando una ficha de producto queda obsoleta para soporte pero conserva su valor de archivo: la retiras de la base de datos operativa sin destruir el documento.
Poblar una colección en masa
Al inicializar una base de datos desde una carpeta entera, escribe el bucle una vez; te servirá durante mucho tiempo:
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):
# Pasos 1 y 2 en una única llamada: subir vía Files API y luego adjuntar
await client.collections.upload_document(
collection_id=collection_id,
name=file_path.name,
data=file_path.read_bytes(),
)
print(f"Añadido: {file_path}")
asyncio.run(populate("col_xyz789"))
Observa la mezcla de formatos en la lista: PDF, Markdown y texto plano coexisten sin problemas en la misma colección, lo que te ahorra tener que estandarizar tus fuentes antes de la ingesta.
Dos claves, dos ámbitos
Este proceso utiliza dos identificadores de acceso que no debes confundir: la clave de API estándar (XAI_API_KEY) para la subida del paso 1, y la clave de Gestión (XAI_MANAGEMENT_API_KEY) para la adjunción del paso 2. El SDK recibe ambas al crear el cliente, y upload_document las utiliza una tras otra. Verifica que esta última tenga el permiso AddFileToCollection: sin él, tu subida tendrá éxito, pero tu adición fallará con un error 403, y acumularás archivos correctamente almacenados pero ausentes de cualquier colección.
Puntos clave
- La adición a una colección ocurre en dos pasos: subir y luego añadir
- Un archivo puede pertenecer a múltiples colecciones simultáneamente
- El documento debe alcanzar el estado
DOCUMENT_STATUS_PROCESSEDantes de ser buscable - Eliminar un documento de una colección no borra el archivo subyacente
- Se requieren dos claves de API distintas: estándar para la subida y de Gestión para la colección