Lähe põhisisu juurde
Eesti— Vali keel
Menüü

xAI Python SDK: Asünkroonsed toimingud

Õppetund 16 / 16 Värskendatud 2. november 2026 Arendajatele
Sellel lehel
  1. Automatiseeri oma RAG töövooge Pythonis
  2. Paigaldamine ja seadistamine
  3. Kollektsioonide toimingud
  4. Dokumendi lisamine ja indekseerimise ootamine
  5. Otsing SDK-st
  6. Täielik otsast-otsani torustik
  7. Peamised punktid
  8. Testi oma teadmisi

Uuendatud 2. novembril 2026. Põhineb xai-sdk versioonil 1.21.0 ja ametlikul xAI näitel: await väljakutsed nõuavad asünkroonset klienti AsyncClient (klient Client on sünkroonne), tagastatud objektid paljastavad collection_id, collections, matches ja chunk_content, indekseerimisolekut võrreldakse väärtusega collections_pb2.DOCUMENT_STATUS_PROCESSED ning upload_document laadib faili üles ja seob selle kollektsiooniga ühe kõnega (eelmine näide laadis selle kaks korda üles, kasutades olematut meetodit). Allikad: Kollektsioonid API kaudu · Kollektsioonide otsing · xai-sdk-python.

Automatiseeri oma RAG töövooge Pythonis

Kõik, mida oled selle kursuse vältel curl-i kaudu kutsunud, on olemas ka Pythonis: dokumentide üleslaadimine, kollektsioonide haldamine, otsing ja genereerimine. xAI SDK pakub kahte klienti: üht sünkroonset (Client) ja teist asünkroonset (AsyncClient), millel on identsed meetodid. Viimane on RAG töövoogude jaoks õige valik, kuna need veedavad suurema osa ajast oodates – faili üleslaadimise lõppemist, dokumendi indekseerimist või otsingu tulemuste naasmist. Asünkroonne kood käsitleb neid ooteid paralleelselt, mitte järjestikku.

Paigaldamine ja seadistamine

pip install xai-sdk

Klient nõuab kahte võtit: standardne API võti otsingu ja genereerimise jaoks ning haldus-API võti kollektsioonide jaoks.

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

Iga päringu vaikimisi aegumine on 27 minutit, mis katab suure PDF-faili üleslaadimise. Parameeter timeout (sekundites) võimaldab seda piirangut interaktiivse rakenduse jaoks kitsendada.

Kollektsioonide toimingud

Kolm kõnet katavad kogu elutsükli. Loome käik tagastab ID, mida kasutad kõikjal mujal:

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

Loetlemine aitab peamiselt taastada ID-d, mida sa ei salvestanud, või kontrollida konto olekut, mida jagatakse mitme projekti vahel:

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

Kustutamine on pöördumatu ja eemaldab nii dokumendid kui ka nende indeksid:

await client.collections.delete(collection_id)

Dokumendi lisamine ja indekseerimise ootamine

Üksainus kõne, upload_document, laadib faili Files API kaudu üles ja seob selle kollektsiooniga:

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

Kui fail on Files API-s juba olemas, seob add_existing_document(collection_id, file_id) selle uuesti üles laadimata.

Dokumendi lisamine ei tee seda kohe päritavaks. Indekseerimine võtab sõltuvalt faili suurusest erineva aja ja liiga vara käivitatud otsing tagastab lihtsalt vähem tulemusi, kui oodatud – viga, mida on eriti valus diagnoosida, kuna see ei tekita veateadet. Seetõttu see ootetsükkel, mis küsitleb olekut kuni DOCUMENT_STATUS_PROCESSED saavutamiseni:

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)

Olek on loendiväärtus, mitte sõne: selle võrdlemine tekstiga "DOCUMENT_STATUS_PROCESSED" ei oleks kunagi tõene ja tsükkel jookseks igavesti. Lihtsa juhu korral käsitleb seda ootamist sinu eest upload_document(..., wait_for_indexing=True).

Otsing SDK-st

Otsing tagastab samad hinnatud tükid kui HTTP lõpp-punkt, loendis 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("---")

Täielik otsast-otsani torustik

Eelmised plokid moodustavad skripti, mis loob kollektsiooni, laadib dokumendid üles, ootab indekseerimist, teeb otsingu ja genereerib seejärel vastuse, kasutades tööriista 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. Loo kollektsioon
    collection = await client.collections.create(name="project-documentation")
    collection_id = collection.collection_id

    # 2. Lisa dokumendid paralleelselt
    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. Oota, kuni kõik dokumendid on indekseeritud
    await asyncio.gather(*[
        wait_for_indexing(client, fid, collection_id) for fid in file_ids
    ])

    # 4. Otsing
    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. Genereeri vastus põhinevalt kollektsioonil
    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())

Kaks asyncio.gather() kõnet teevad kogu töö. Esimene käivitab kolm üleslaadimist koos, selle asemel et oodata igaühe lõppemist; teine jälgib kolme indekseerimistööd samaaegselt: koguaeg läheneb pikima dokumendi ajale, mitte kõigi summale. Ja kuna ootamine ei blokeeri sündmuste tsüklit, sobib sama kood otse FastAPI või aiohttp rakendusse, mis jätkab teiste päringute teenindamist samal ajal, kui su dokumendid indekseeruvad.

Peamised punktid

  • xAI Python SDK on olemas sünkroonses (Client) ja asünkroonses (AsyncClient) versioonis; await nõuab viimast
  • Mõlemad võtmed (API ja haldus) seadistatakse kliendis
  • upload_document laadib üles ja seob ühe kõnega; jälgi indekseerimist get_document või wait_for_indexing=True kaudu
  • asyncio.gather() võimaldab üles laadida ja indekseerimist oodata paralleelselt
  • Genereerimine kasutab kollektsiooni tööriistaga collections_search, kaasates vastuse ja tsitaadid

Testi oma teadmisi

Failid, kollektsioonid, otsing: xAI hallatav RAG.

1. Mida võimaldab Files API teha?

Vastus: Laadida üles ja hallata faile (loetleda, vaadata, kustutada) toetatud vormingutes – toores materjal kollektsioonide ja päringute jaoks dokumentidega.

2. Mis on kollektsioon?

Vastus: xAI poolt serveripoolselt hallatav dokumentide kogum koos metaandmete ja õigustega – valmis kasutamiseks indeks, mida pärid ilma oma vektoritorustikku ehitamata.

3. Millised otsingurežiimid on saadaval?

Vastus: Märksõna (täpsed terminid), semantiline (tähendus) ja hübriid (mõlemad) – valik sõltub küsimuste olemusest, kusjuures hübriid katab enamiku juhtumeid.

4. Kuidas integreerub RAG genereerimisega?

Vastus: Kollektsiooni otsingu tööriista kaudu: collections_search xAI SDK-s, file_search koos kollektsiooni ID-dega Responses API-s. Mudel pärib su dokumente genereerimise ajal ja tsiteerib allikaid – RAG muster ilma taristut hooldamata.

5. Millised punktid nõuavad tootmises tähelepanu?

Vastus: Üleslaaditud andmete konfidentsiaalsus (õigused, elutsükkel), asjakohasuse optimeerimine (metaandmed, tükeldamine) – ja asünkroonne SDK suure mahuga töötlemiseks.

Hallatud RAG: sina tood dokumendid ja küsimused, xAI haldab indeksit – hoia kontrolli konfidentsiaalsuse ja asjakohasuse üle.