Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Python SDK xAI: Asynchronní operace

Lekce 16 z 16 Aktualizováno 2. listopadu 2026 Vývojář
Na této stránce
  1. Automatizuj své pracovní postupy RAG v Pythonu
  2. Instalace a konfigurace
  3. Operace s kolekcemi
  4. Přidání dokumentu a čekání na indexaci
  5. Vyhledávání pomocí SDK
  6. Kompletní end-to-end pipeline
  7. Klíčové poznatky
  8. Ověř si své znalosti

Aktualizováno 2. listopadu 2026. Na základě kódu xai-sdk 1.21.0 a oficiálního příkladu xAI: volání await vyžadují asynchronního klienta AsyncClient (zatímco Client je synchronní), vrácené objekty exposingují collection_id, collections, matches a chunk_content, stav indexování se porovnává s collections_pb2.DOCUMENT_STATUS_PROCESSED a upload_document nahraje a připojí soubor v jediném volání (předchozí příklad jej nahrával dvakrát, jednou pomocí neexistující metody). Zdroje: Collections via the API · Collections Search · xai-sdk-python.

Automatizuj své pracovní postupy RAG v Pythonu

Všechno, co jsi v tomto kurzu volal přes curl, existuje i v Pythonu: nahrávání dokumentů, správa kolekcí, vyhledávání i generování. SDK xAI nabízí dva klienty: synchronního (Client) a asynchronního (AsyncClient), kteří mají totožné metody. Pro workflow RAG je tou správnou volbou ten druhý, protože většinu času strávíš čekáním – na dokončení nahrávání, na indexaci dokumentu nebo na návrat výsledků hledání. Asynchronní kód zpracovává tato čekání paralelně, nikoliv sekvenčně.

Instalace a konfigurace

pip install xai-sdk

Klient vyžaduje dva klíče: standardní API klíč pro vyhledávání a generování a klíč Management API pro správu kolekcí.

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"),
)

Každý požadavek má ve výchozím nastavení časový limit 27 minut před vypršením, což stačí na nahrání velkého PDF. Parametr timeout v sekundách ti umožňuje tento limit zpřísnit pro interaktivní aplikace.

Operace s kolekcemi

Tři volání pokrývají celý životní cyklus. Vytvoření vrátí ID, které budeš znovu používat všude jinde:

collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Collection created: {collection_id}")

Výpis pomáhá hlavně obnovit ID, které jsi neuložil, nebo zkontrolovat stav účtu sdíleného mezi více projekty:

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

Smazání je nevratné a odstraní dokumenty i jejich indexy:

await client.collections.delete(collection_id)

Přidání dokumentu a čekání na indexaci

Jediné volání, upload_document, nahraje soubor přes Files API a připojí jej ke kolekci:

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

Pokud soubor již v Files API existuje, add_existing_document(collection_id, file_id) jej připojí bez opětovného nahrávání.

Přidání dokumentu jej okamžitě neučiní dotazovatelným. Indexace trvá proměnlivou dobu v závislosti na velikosti souboru a vyhledávání spuštěné příliš brzy jednoduše vrátí méně výsledků, než se očekává – chyba, kterou je obzvlášť bolestivé diagnostikovat, protože nevyvolá žádnou výjimku. Proto tento čekací cyklus, který zjišťuje stav, dokud nedosáhne 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)

Stav je hodnota výčtu (enum), nikoliv řetězec: porovnání s textem "DOCUMENT_STATUS_PROCESSED" by nikdy nebylo pravdivé a smyčka by běžela navždy. Pro jednoduché případy se o toto čekání postará upload_document(..., wait_for_indexing=True).

Vyhledávání pomocí SDK

Vyhledávání vrací stejné ohodnocené úryvky jako HTTP endpoint, a to v seznamu 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("---")

Kompletní end-to-end pipeline

Předchozí bloky se skládají do skriptu, který vytvoří kolekci, nahraje dokumenty, počká na indexaci, provede vyhledávání a následně vygeneruje odpověď pomocí nástroje 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. Vytvoření kolekce
    collection = await client.collections.create(name="project-documentation")
    collection_id = collection.collection_id

    # 2. Paralelní přidání dokumentů
    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. Čekání na indexaci všech dokumentů
    await asyncio.gather(*[
        wait_for_indexing(client, fid, collection_id) for fid in file_ids
    ])

    # 4. Vyhledávání
    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. Generování odpovědi na základě kolekce
    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())

Obě volání asyncio.gather() odvedou veškerou práci. První spustí všechna tři nahrávání najednou místo čekání na dokončení každého zvlášť; druhé monitoruje všechny tři úlohy indexování současně: celkový čas se blíží času nejdelšího dokumentu, nikoliv součtu všech. A protože čekání neblokuje smyčku událostí, zapadá tento kód přímo do aplikace FastAPI nebo aiohttp, která může nadále obsluhovat další požadavky, zatímco se tvé dokumenty indexují.

Klíčové poznatky

  • Python SDK xAI existuje v synchronní (Client) a asynchronní (AsyncClient) verzi; await vyžaduje tu druhou.
  • Oba klíče (API i Management) se konfigurují v klientovi.
  • upload_document nahraje a připojí soubor v jednom volání; indexaci monitoruj přes get_document nebo použij wait_for_indexing=True.
  • asyncio.gather() ti umožní nahrávat a čekat na indexaci paralelně.
  • Generování využívá kolekci prostřednictvím nástroje collections_search, včetně odpovědi a citací.

Ověř si své znalosti

Soubory, kolekce, vyhledávání: RAG spravované xAI.

1. Co ti umožňuje Files API?

Odpověď: Nahrávat a spravovat soubory (vypisovat, zobrazovat, mazat) v podporovaných formátech – surovinu pro kolekce a dotazy s dokumenty.

2. Co je to kolekce?

Odpověď: Sada dokumentů spravovaná na straně serveru společností xAI, včetně metadat a oprávnění – index připravený k použití, který dotazuješ bez nutnosti budovat vlastní vektorové pipeline.

3. Které režimy vyhledávání jsou dostupné?

Odpověď: Klíčová slova (přesné výrazy), sémantické (význam) a hybridní (oboje) – volba závisí na povaze otázek, přičemž hybridní pokrývá většinu případů.

4. Jak se RAG integruje s generováním?

Odpověď: Prostřednictvím nástroje pro vyhledávání v kolekci: collections_search v SDK xAI nebo file_search s ID kolekcí v Responses API. Model během generování dotazuje tvé dokumenty a cituje zdroje – vzor RAG bez infrastruktury, kterou bys musel udržovat.

5. Na jaké body je třeba dbát při nasazení do produkce?

Odpověď: Důvěrnost nahraných dat (oprávnění, životní cyklus), relevance k optimalizaci (metadata, chunking) – a asynchronní SDK pro zpracování vysokého objemu dat.

Spravované RAG: ty přinášíš dokumenty a otázky, xAI se stará o index – udrž si kontrolu nad důvěrností a relevancí.