Python SDK od xAI: Asynchrónne operácie
Na tejto strane
Aktualizované 2. novembra 2026. Na základe kódu
xai-sdk1.21.0 a oficiálneho príkladu xAI: volania sawaitvyžadujú asynchrónneho klientaAsyncClient(klientClientje synchrónny), vrátené objekty poskytujú atribútycollection_id,collections,matchesachunk_content, stav indexovania sa porovnáva scollections_pb2.DOCUMENT_STATUS_PROCESSEDa funkciaupload_documentnahrá a pripojí súbor v jednom volaní (predchádzajúci príklad ho nahrával dvakrát, raz pomocou neexistujúcej metódy). Zdroje: Collections via the API · Collections Search · xai-sdk-python.
Automatizuj svoje pracovné postupy RAG v Pythone
Všetko, čo si v tomto kurze volal cez curl, existuje aj v Pythone: nahrávanie dokumentov, správa kolekcií, vyhľadávanie aj generovanie. SDK od xAI ponúka dvoch klientov – jedného synchrónneho (Client) a jedného asynchrónneho (AsyncClient) – s identickými metódami. Pre pracovný postup RAG je tou správnou voľbou práve asynchrónny klient, pretože väčšinu času stráca čakáním – na dokončenie nahrávania, na zindexovanie dokumentu alebo na návrat výsledkov vyhľadávania. Asynchrónny kód rieši tieto čakania paralelne, nie postupne za sebou.
Inštalácia a konfigurácia
pip install xai-sdk
Klient potrebuje dva kľúče: štandardný API kľúč pre vyhľadávanie a generovanie a kľúč Management API pre prácu s kolekciami.
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žiadavka má predvolený časový limit 27 minút pred vypršaním, čo stačí na nahratie veľkého PDF súboru. Parameter timeout v sekundách ti umožňuje tento limit sprísniť pre interaktívne aplikácie.
Operácie s kolekciami
Tri volania pokrývajú celý životný cyklus. Vytvorenie vráti ID, ktoré budeš používať všade inde:
collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Collection created: {collection_id}")
Výpis zoznamu sa hodí hlavne na získanie ID, ktoré si neuložil, alebo na kontrolu stavu účtu zdieľaného medzi viacerými projektmi:
response = await client.collections.list()
for col in response.collections:
print(f"{col.collection_id} — {col.collection_name} ({col.documents_count} documents)")
Vymazanie je nezvratné a odstráni dokumenty aj ich indexy:
await client.collections.delete(collection_id)
Pridanie dokumentu a čakanie na indexovanie
Jedno jediné volanie, upload_document, nahrá súbor cez Files API a pripojí ho ku kolekcii:
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
Ak súbor už v Files API existuje, funkcia add_existing_document(collection_id, file_id) ho pripojí bez opätovného nahrávania.
Pridanie dokumentu ešte neznamená, že je okamžite dostupný na dotazy. Indexovanie trvá rôzne dlho v závislosti od veľkosti súboru a vyhľadávanie spustené príliš skoro jednoducho vráti menej výsledkov, než sa očakáva – čo je chyba, ktorú sa obzvlášť ťažko diagnostikuje, pretože nevyvolá žiadnu výnimku. Preto tu máme tento čakací cyklus, ktorý zisťuje stav, kým nedosiahne 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 enumerácie, nie reťazec: porovnanie s textom "DOCUMENT_STATUS_PROCESSED" by nikdy nebolo pravdivé a cyklus by bežal donekonečna. Pre jednoduché prípady sa o toto čakanie postará už samotné volanie upload_document(..., wait_for_indexing=True).
Vyhľadávanie cez SDK
Vyhľadávanie vráti rovnaké ohodnotené časti (chunks) ako HTTP endpoint, a to v zozname 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
Predchádzajúce bloky sa spájajú do skriptu, ktorý vytvorí kolekciu, nahra dokumenty, počká na ich zindexovanie, vyhľadá a následne vygeneruje odpoveď pomocou nástroja 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. Vytvorenie kolekcie
collection = await client.collections.create(name="project-documentation")
collection_id = collection.collection_id
# 2. Pridanie dokumentov paralelne
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. Čakanie na zindexovanie všetkých dokumentov
await asyncio.gather(*[
wait_for_indexing(client, fid, collection_id) for fid in file_ids
])
# 4. Vyhľadávanie
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. Generovanie odpovede na základe kolekcie
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())
Dve volania asyncio.gather() odvedú všetku prácu. Prvé spustí tri nahrávania naraz namiesto čakania na dokončenie každého zvlášť; druhé monitoruje tri úlohy indexovania súčasne: celkový čas sa tak priblíži času potrebnému pre najdlhší dokument, namiesto súčtu všetkých. A keďže čakanie neblokuje event loop, tento kód zapadne priamo aj do aplikácie postavenej na FastAPI alebo aiohttp, ktorá môže počas indexovania tvoich dokumentov pokračovať v obsluhe ďalších požiadaviek.
Kľúčové poznatky
- Python SDK od xAI existuje v synchrónnej (
Client) aj asynchrónnej (AsyncClient) verzii;awaitsi vyžaduje tú druhú - Oba kľúče (API aj Management) sa konfigurujú pri inicializácii klienta
upload_documentnahrá a pripojí súbor v jednom volaní; stav indexovania monitoruj cezget_documentalebo použiwait_for_indexing=Trueasyncio.gather()ti umožní nahrávať a čakať na indexovanie paralelne- Generovanie využíva kolekciu prostredníctvom nástroja
collections_search, vrátane odpovede a citácií
Otestuj si svoje vedomosti
Súbory, kolekcie, vyhľadávanie: RAG spravované systémom xAI.
1. Čo ti umožňuje Files API?
Odpoveď: Nahrávať a spravovať súbory (zoznam, zobrazenie, vymazanie) v podporovaných formátoch – sú to surové materiály pre kolekcie a dotazy s dokumentmi.
2. Čo je to kolekcia?
Odpoveď: Množina dokumentov spravovaných na strane servera systémom xAI, vrátane metadát a oprávnení – ide o pripravený index, ktorý môžeš používať bez toho, aby si si budoval vlastný vektorový pipeline.
3. Aké režimy vyhľadávania sú dostupné?
Odpoveď: Kľúčové slová (presné výrazy), sémantické (význam) a hybridné (obe) – výber závisí od povahy otázok, pričom hybridný režim pokrýva väčšinu prípadov.
4. Ako sa RAG integruje s generovaním?
Odpoveď: Prostredníctvom nástroja na vyhľadávanie v kolekcii: collections_search v SDK od xAI alebo file_search s ID kolekcií v Responses API. Model počas generovania vyhľadáva v tvojich dokumentoch a cituje zdroje – ide o vzor RAG bez nutnosti udržiavať vlastnú infraštruktúru.
5. Na čo si dať pozor pri nasadení do produkcie?
Odpoveď: Dôvernosť nahraných dát (oprávnenia, životný cyklus), relevantnosť na optimalizáciu (metadáta, chunking) – a použitie asynchrónneho SDK pre spracovanie veľkých objemov.
Spravovaný RAG: ty prinášaš dokumenty a otázky, xAI sa postará o index – zachovaj si kontrolu nad dôvernosťou a relevantnosťou.