Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

xAI Python SDK: operacijos asinchroniniu režimu

Paskaita 16 iš 16 Atnaujinta 2026 m. lapkričio 2 d. Kūrėjas
Šiame puslapyje
  1. Automatizuokite savo RAG darbo eigas Python kalba
  2. Diegimas ir konfigūravimas
  3. Kolekcijų operacijos
  4. Dokumento pridėjimas ir laukimas, kol bus baigtas indeksavimas
  5. Paieška naudojant SDK
  6. Pilna端到端 (end-to-end) darbo eiga
  7. Svarbiausi punktai
  8. Patikrinkite savo žinias

Atnaujinta 2026 m. lapkričio 2 d. Remiantis xai-sdk 1.21.0 kodu ir oficialiu xAI pavyzdžiu: await kvietimams reikia asinchroninio kliento AsyncClient (Client yra sinchroninis), grąžinami objektai pateikia collection_id, collections, matches ir chunk_content, indeksavimo būsena lyginama su collections_pb2.DOCUMENT_STATUS_PROCESSED, o upload_document įkelia ir prideda failą vienu kvietimu (ankstesnis pavyzdys jį įkeldavo du kartus, naudodamas neegzistuojantį metodą). Šaltiniai: Kolekcijos per API · Kolekcijų paieška · xai-sdk-python.

Automatizuokite savo RAG darbo eigas Python kalba

Viskas, ką šiame kurse kvietėte naudodami curl, egzistuoja ir Python kalboje: dokumentų įkėlimas, kolekcijų valdymas, paieška, generavimas. xAI SDK siūlo du klientus: vieną sinchroninį (Client) ir vieną asinchroninį (AsyncClient) su identiškais metodais. Pastarasis yra tinkamas pasirinkimas RAG darbo eigai, kuri didžiąją laiko dalį praleidžia laukdama – kol baigsis įkėlimas, kol dokumentas bus indeksuotas, kol grįš paieškos rezultatai. Asinchroninis kodas šiuos laukimo procesus apdoroja lygiagrečiai, o ne nuosekliai.

Diegimas ir konfigūravimas

pip install xai-sdk

Klientui reikia dviejų raktų: standartinio API rakto paieškai ir generavimui bei valdymo API rakto kolekcijoms.

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

Kiekvienas užklausas pagal nutylėjimą turi 27 minuų laiko limitą prieš pasibaigiant, kas pakanka dideliam PDF failui įkelti. Parametras timeout (sekundėmis) leidžia sugriežtinti šį limitą interaktyvioms programoms.

Kolekcijų operacijos

Trys kvietimai apima visą gyvavimo ciklą. Kūrimas grąžina ID, kurį naudosite visuose kituose veiksmuose:

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

Sąrašo gavimas daugiausia padeda atkurti ID, kurio neišsaugojote, arba patikrinti paskyros, bendrai naudojamos keliuose projektuose, būseną:

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

Ištrynimas yra negrįžtamas ir pašalina dokumentus bei jų indeksus:

await client.collections.delete(collection_id)

Dokumento pridėjimas ir laukimas, kol bus baigtas indeksavimas

Vienas kvietimas, upload_document, įkelia failą per „Files API“ ir prideda jį prie kolekcijos:

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

Jei failas „Files API“ jau egzistuoja, add_existing_document(collection_id, file_id) jį prideda neįkeldamas iš naujo.

Pridėjus dokumentą, jis nėra iškart paruoštas užklausoms. Indeksavimas trunka įvairiai, priklausomai nuo failo dydžio, o per anksti paleista paieška tiesiog grąžina mažiau rezultatų nei tikėtasi – tai klaida, kurią ypač sunku diagnozuoti, nes ji neišmeta jokios klaidos. Todėl reikalingas šis laukimo ciklas, kuris tikrina būseną, kol pasiekiamas 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)

Būsena yra enumeracijos reikšmė, o ne tekstas: lyginant ją su tekstu "DOCUMENT_STATUS_PROCESSED", sąlyga niekada nebus tenkinama ir ciklas vyks amžinai. Paprastu atveju upload_document(..., wait_for_indexing=True) šį laukimą atlieka už jus.

Paieška naudojant SDK

Paieška grąžina tuos pačius įvertintus fragmentus kaip ir HTTP galinis taškas, sąraše 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("---")

Pilna端到端 (end-to-end) darbo eiga

Ankstesni blokai sujungiami į scenarijų, kuris sukuria kolekciją, įkelia dokumentus, laukia, kol bus baigtas indeksavimas, atlieka paiešką ir tada generuoja atsakymą naudodamas įrankį 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. Sukurti kolekciją
    collection = await client.collections.create(name="project-documentation")
    collection_id = collection.collection_id

    # 2. Pridėti dokumentus lygiagrečiai
    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. Laukti, kol visi dokumentai bus indeksuoti
    await asyncio.gather(*[
        wait_for_indexing(client, fid, collection_id) for fid in file_ids
    ])

    # 4. Paieška
    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. Generuoti atsakymą pagal kolekciją
    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())

Du asyncio.gather() kvietimai atlieka visą darbą. Pirmasis paleidžia tris įkėlimus vienu metu, nelaukdamas, kol kiekvienas baigsis; antrasis vienu metu stebi tris indeksavimo užduotis: bendras laikas artėja prie ilgiausiai trunkančio dokumento laiko, o ne visų laikų sumos. Kadangi laukimas neužblokuoja įvykių ciklo, tas pats kodas tiesiogiai tinka „FastAPI“ arba „aiohttp“ programoms, kurios toliau aptarnauja kitas užklausas, kol jūsų dokumentai indeksuojami.

Svarbiausi punktai

  • xAI Python SDK egzistuoja sinchronine (Client) ir asinchronine (AsyncClient) versijomis; await reikalauja pastarosios
  • Abu raktai (API ir valdymo) konfigūruojami kliente
  • upload_document įkelia ir prideda vienu kvietimu; stebėkite indeksavimą naudodami get_document arba wait_for_indexing=True
  • asyncio.gather() leidžia įkelti ir laukti indeksavimo lygiagrečiai
  • Generavimas naudoja kolekciją su įrankiu collections_search, pateikdamas atsakymą ir citatas

Patikrinkite savo žinias

Failai, kolekcijos, paieška: RAG, valdomas xAI.

1. Ką leidžia daryti „Files API“?

Atsakymas: Įkelti ir valdyti failus (sąrašas, peržiūra, ištrynimas) palaikomais formatais – tai žaliava kolekcijoms ir užklausoms su dokumentais.

2. Kas yra kolekcija?

Atsakymas: Dokumentų rinkinys, serverio lygmeniu valdomas xAI, su metaduomenimis ir leidimais – tai paruoštas naudoti indeksas, kurį galite užklausti nekurdami savo vektorinės paieškos infrastruktūros.

3. Kokios paieškos rūšys yra galimos?

Atsakymas: Raktažodžių (tikslūs terminai), semantinė (prasmė) ir hibridinė (abu būdai) – pasirinkimas priklauso nuo klausimų pobūdžio, o hibridinė tinka daugeliu atvejų.

4. Kaip RAG integruojamas su generavimu?

Atsakymas: Per kolekcijos paieškos įrankį: collections_search xAI SDK arba file_search su kolekcijų ID „Responses API“. Modelis generavimo metu užklauna jūsų dokumentus ir cituoja šaltinius – tai RAG šablonas be poreikio prižiūrėti infrastruktūrą.

5. Į kokius punktus reikia atkreipti dėmesį gamybinėje aplinkoje?

Atsakymas: Įkeliamų duomenų konfidencialumas (leidimai, gyvavimo ciklas), aktualumo optimizavimas (metaduomenys, skaidymas į dalis) ir asinchroninis SDK didelės apimties duomenų apdorojimui.

Valdomas RAG: jūs pateikiate dokumentus ir klausimus, xAI tvarko indeksą – išlaikykite konfidencialumo ir aktualumo kontrolę.