Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Python SDK od xAI: Asynchrónne operácie

Lekcia 16 z 16 Aktualizované 2. novembra 2026 Vývojár
Na tejto strane
  1. Automatizuj svoje pracovné postupy RAG v Pythone
  2. Inštalácia a konfigurácia
  3. Operácie s kolekciami
  4. Pridanie dokumentu a čakanie na indexovanie
  5. Vyhľadávanie cez SDK
  6. Kompletný end-to-end pipeline
  7. Kľúčové poznatky
  8. Otestuj si svoje vedomosti

Aktualizované 2. novembra 2026. Na základe kódu xai-sdk 1.21.0 a oficiálneho príkladu xAI: volania s await vyžadujú asynchrónneho klienta AsyncClient (klient Client je synchrónny), vrátené objekty poskytujú atribúty collection_id, collections, matches a chunk_content, stav indexovania sa porovnáva s collections_pb2.DOCUMENT_STATUS_PROCESSED a funkcia upload_document nahrá 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; await si vyžaduje tú druhú
  • Oba kľúče (API aj Management) sa konfigurujú pri inicializácii klienta
  • upload_document nahrá a pripojí súbor v jednom volaní; stav indexovania monitoruj cez get_document alebo použi wait_for_indexing=True
  • asyncio.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.