Python SDK xAI: Asynchronní operace
Na této stránce
Aktualizováno 2. listopadu 2026. Na základě kódu
xai-sdk1.21.0 a oficiálního příkladu xAI: voláníawaitvyžadují asynchronního klientaAsyncClient(zatímcoClientje synchronní), vrácené objekty exposingujícollection_id,collections,matchesachunk_content, stav indexování se porovnává scollections_pb2.DOCUMENT_STATUS_PROCESSEDaupload_documentnahraje 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;awaitvyžaduje tu druhou. - Oba klíče (API i Management) se konfigurují v klientovi.
upload_documentnahraje a připojí soubor v jednom volání; indexaci monitoruj přesget_documentnebo použijwait_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í.