Ir al contenido principal
Español— Elegir un idioma
Menú

El SDK de Python de xAI: Operaciones asíncronas

Lección 16 de 16 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Automatiza tus flujos de trabajo RAG en Python
  2. Instalación y configuración
  3. Operaciones con colecciones
  4. Añadir un documento y esperar a la indexación
  5. Búsqueda desde el SDK
  6. Un canal completo de extremo a extremo
  7. Puntos clave
  8. Pon a prueba tus conocimientos

Actualizado el 2 de noviembre de 2026. Basado en el código de xai-sdk 1.21.0 y el ejemplo oficial de xAI: las llamadas await requieren el cliente asíncrono AsyncClient (el Client es síncrono), los objetos devueltos exponen collection_id, collections, matches y chunk_content, el estado de indexación se compara con collections_pb2.DOCUMENT_STATUS_PROCESSED, y upload_document sube y adjunta el archivo en una única llamada (el ejemplo anterior lo subía dos veces, usando un método inexistente). Fuentes: Colecciones a través de la API · Búsqueda en colecciones · xai-sdk-python.

Automatiza tus flujos de trabajo RAG en Python

Todo lo que has invocado mediante curl a lo largo de este curso existe en Python: carga de documentos, gestión de colecciones, búsqueda y generación. El SDK de xAI ofrece dos clientes, uno síncrono (Client) y otro asíncrono (AsyncClient), con métodos idénticos. Este último es la elección correcta para un flujo de trabajo RAG, que pasa la mayor parte del tiempo esperando: a que termine una carga, a que se indexe un documento o a que la búsqueda devuelva resultados. El código asíncrono gestiona estas esperas en paralelo en lugar de en secuencia.

Instalación y configuración

pip install xai-sdk

El cliente requiere dos claves: la clave de API estándar para búsqueda y generación, y la clave de API de gestión para las colecciones.

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 petición tiene por defecto un tiempo de espera de 27 minutos antes de caducar, lo cual cubre la carga de un PDF grande. El parámetro timeout, en segundos, te permite ajustar este límite para una aplicación interactiva.

Operaciones con colecciones

Tres llamadas cubren todo el ciclo de vida. La creación devuelve el ID que reutilizarás en todas las demás operaciones:

collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Colección creada: {collection_id}")

Listar las colecciones sirve principalmente para recuperar un ID que no persististe o para comprobar el estado de una cuenta compartida entre varios proyectos:

response = await client.collections.list()
for col in response.collections:
    print(f"{col.collection_id} — {col.collection_name} ({col.documents_count} documentos)")

La eliminación es irreversible y borra los documentos junto con sus índices:

await client.collections.delete(collection_id)

Añadir un documento y esperar a la indexación

Una única llamada, upload_document, sube el archivo a través de la API de Files y lo adjunta a la colección:

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

Si el archivo ya existe en la API de Files, add_existing_document(collection_id, file_id) lo adjunta sin volver a subirlo.

Añadir un documento no lo hace consultable de inmediato. La indexación tarda un tiempo variable según el tamaño del archivo, y una búsqueda lanzada demasiado pronto simplemente devolverá menos resultados de los esperados: un error particularmente doloroso de diagnosticar, ya que no genera ninguna excepción. De ahí este bucle de espera, que sondea el estado hasta alcanzar 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("Documento listo")
            return
        if doc.status == collections_pb2.DOCUMENT_STATUS_FAILED:
            raise RuntimeError(f"Indexación fallida: {doc.error_message}")
        await asyncio.sleep(3)

El estado es un valor de enumeración, no una cadena: compararlo con el texto "DOCUMENT_STATUS_PROCESSED" nunca sería verdadero y el bucle se ejecutaría indefinidamente. Para un caso sencillo, upload_document(..., wait_for_indexing=True) gestiona esta espera por ti.

Búsqueda desde el SDK

La búsqueda devuelve los mismos fragmentos puntuados que el extremo HTTP, en la lista matches:

results = await client.collections.search(
    query="Procedimiento de validación de pedidos",
    collection_ids=[collection_id],
)

for m in results.matches:
    print(f"Puntuación: {m.score:.2f}")
    print(f"Contenido: {m.chunk_content[:200]}")
    print("---")

Un canal completo de extremo a extremo

Los bloques anteriores se ensamblan en un script que crea la colección, sube documentos, espera a la indexación, realiza una búsqueda y luego genera una respuesta utilizando la herramienta 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. Crear la colección
    collection = await client.collections.create(name="project-documentation")
    collection_id = collection.collection_id

    # 2. Añadir documentos en 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. Esperar a que todos los documentos se indexen
    await asyncio.gather(*[
        wait_for_indexing(client, fid, collection_id) for fid in file_ids
    ])

    # 4. Búsqueda
    results = await client.collections.search(
        query="¿Cómo desplegar en producción?",
        collection_ids=[collection_id],
    )
    for m in results.matches:
        print(f"[{m.score:.2f}] {m.chunk_content[:150]}")

    # 5. Generar una respuesta basada en la colección
    chat = client.chat.create(
        model="grok-4.7",
        tools=[collections_search(collection_ids=[collection_id])],
    )
    chat.append(user("Explica el procedimiento de despliegue y cita tus fuentes."))
    response = await chat.sample()
    print(response.content)
    print(response.citations)


asyncio.run(rag_pipeline())

Las dos llamadas a asyncio.gather() hacen todo el trabajo. La primera lanza las tres cargas juntas en lugar de esperar a que cada una termine; la segunda monitoriza los tres trabajos de indexación simultáneamente: el tiempo total se aproxima al del documento más largo, en lugar de la suma de todos. Y dado que la espera no bloquea el bucle de eventos, el mismo código encaja directamente en una aplicación FastAPI o aiohttp, que sigue atendiendo otras peticiones mientras tus documentos se indexan.

Puntos clave

  • El SDK de Python de xAI existe en versiones síncrona (Client) y asíncrona (AsyncClient); await requiere esta última.
  • Ambas claves (API y de gestión) se configuran en el cliente.
  • upload_document sube y adjunta en una sola llamada; monitoriza la indexación mediante get_document o wait_for_indexing=True.
  • asyncio.gather() te permite subir y esperar la indexación en paralelo.
  • La generación aprovecha la colección con la herramienta collections_search, incluyendo respuesta y citas.

Pon a prueba tus conocimientos

Archivos, colecciones, búsqueda: RAG gestionado por xAI.

1. ¿Qué te permite hacer la API de Files?

Respuesta: Subir y gestionar archivos (listar, ver, eliminar) en formatos compatibles: la materia prima para colecciones y consultas con documentos.

2. ¿Qué es una colección?

Respuesta: Un conjunto de documentos gestionados en el servidor por xAI, con metadatos y permisos: el índice listo para usar que consultas sin necesidad de construir tu propia canalización vectorial.

3. ¿Qué modos de búsqueda están disponibles?

Respuesta: Palabras clave (términos exactos), semántico (significado) e híbrido (ambos); la elección depende de la naturaleza de las preguntas, cubriendo el modo híbrido la mayoría de los casos.

4. ¿Cómo se integra RAG con la generación?

Respuesta: A través de la herramienta de búsqueda en colecciones: collections_search en el SDK de xAI, file_search con IDs de colección en la API de Responses. El modelo consulta tus documentos durante la generación y cita sus fuentes: el patrón RAG sin infraestructura que mantener.

5. ¿Qué puntos requieren atención para producción?

Respuesta: Confidencialidad de los datos subidos (permisos, ciclo de vida), relevancia a optimizar (metadatos, fragmentación) y el SDK asíncrono para el procesamiento de alto volumen.

RAG gestionado: tú aportas los documentos y las preguntas, xAI se encarga del índice; mantén el control de la confidencialidad y la relevancia.