Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

xAI Python SDK: Operācijas asinhronā režīmā

Nodarbība 16 no 16 Atjaunota 2026. gada 2. novembris Programmētājs
Šajā lapā
  1. Automatizē savus RAG darbplūsmas Python valodā
  2. Instalēšana un konfigurēšana
  3. Darbības ar kolekcijām
  4. Dokumenta pievienošana un gaidīšana līdz indeksēšanai
  5. Meklēšana, izmantojot SDK
  6. Pilns end-to-end konveijers
  7. Galvenās atziņas
  8. Pārbaudi savas zināšanas

Atjaunināts 2026. gada 2. novembrī. Pamatojoties uz xai-sdk 1.21.0 kodu un oficiālo xAI piemēru: izsaukumiem ar await ir nepieciešams asinhronais klients AsyncClient (kamēr Client ir sinhronais), atgrieztie objekti satur laukus collection_id, collections, matches un chunk_content, indeksēšanas statusu salīdzina ar collections_pb2.DOCUMENT_STATUS_PROCESSED, un upload_document augšupielādē un pievieno failu vienā izsaukumā (iepriekšējais piemērs to darīja divreiz, izmantojot neeksistējošu metodi). Avoti: Collections via the API · Collections Search · xai-sdk-python.

Automatizē savus RAG darbplūsmas Python valodā

Viss, ko šī kursa laikā esi izsaukis, izmantojot curl, ir pieejams arī Python valodā: dokumentu augšupielāde, kolekciju pārvaldība, meklēšana un ģenerēšana. xAI SDK piedāvā divus klientus — vienu sinhrono (Client) un vienu asinhrono (AsyncClient) ar identiskām metodēm. Otrā ir pareizā izvēle RAG darbplūsmai, kas lielāko daļu laika pavada gaidīšanā — līdz beidzas augšupielāde, dokuments tiek indeksēts vai meklēšana atgriež rezultātus. Asinhrons kods apstrādā šīs gaidīšanas paralēli, nevis secīgi.

Instalēšana un konfigurēšana

pip install xai-sdk

Klientam ir nepieciešamas divas atslēgas: standarta API atslēga meklēšanai un ģenerēšanai, kā arī pārvaldības API atslēga kolekcijām.

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

Pēc noklusējuma katrs pieprasījums gaida 27 minūtes pirms noilguma, kas ir pietiekami liela PDF faila augšupielādei. Parametrs timeout (sekundēs) ļauj šo limitu sašaurināt interaktīvām lietotnēm.

Darbības ar kolekcijām

Trīs izsaukumi aptver visu dzīves ciklu. Izveide atgriež ID, ko izmantosi visur citur:

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

Saraksta iegūšana galvenokārt noder, lai atgūtu ID, ko neesi saglabājis, vai lai pārbaudītu konta stāvokli, ko izmanto vairāki projekti:

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

Dzēšana ir neatgriezeniska un noņem gan dokumentus, gan to indeksus:

await client.collections.delete(collection_id)

Dokumenta pievienošana un gaidīšana līdz indeksēšanai

Viens vienīgs izsaukums upload_document augšupielādē failu, izmantojot Files API, un pievieno to kolekcijai:

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

Ja fails jau eksistē Files API, add_existing_document(collection_id, file_id) to pievieno, neatkārtoti augšupielādējot.

Dokumenta pievienošana nepadarī to uzreiz pieejamu vaicājumiem. Indeksēšana prasa mainīgu laiku atkarībā no faila lieluma, un meklēšana, kas uzsākta pārāk agri, vienkārši atgriezīs mazāk rezultātu, nekā gaidīts — kļūda, ko ir īpaši sāpīgi diagnosticēt, jo tā neizraisa nekādu izņēmumu. Tāpēc ir nepieciešams šis gaidīšanas cikls, kas periodiski pārbauda statusu, līdz tas ir 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)

Statuss ir enumerācijas vērtība, nevis virkne: salīdzinājums ar tekstu "DOCUMENT_STATUS_PROCESSED" nekad nebūs patiess, un cikls darbotos mūžīgi. Vienkāršos gadījumos upload_document(..., wait_for_indexing=True) paveic šo gaidīšanu tavā vietā.

Meklēšana, izmantojot SDK

Meklēšana atgriež tos pašus novērtētos fragmentus kā HTTP galapunkts, sarakstā 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("---")

Pilns end-to-end konveijers

Iepriekšējie bloki veido skriptu, kas izveido kolekciju, augšupielādē dokumentus, gaida līdz to indeksēšanai, veic meklēšanu un pēc tam ģenerē atbildi, izmantojot rīku 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. Izveido kolekciju
    collection = await client.collections.create(name="project-documentation")
    collection_id = collection.collection_id

    # 2. Pievieno dokumentus paralēli
    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. Gaida, līdz visi dokumenti ir indeksēti
    await asyncio.gather(*[
        wait_for_indexing(client, fid, collection_id) for fid in file_ids
    ])

    # 4. Meklēšana
    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. Ģenerē atbildi, pamatojoties uz kolekciju
    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())

Abi asyncio.gather() izsaukumi paveic visu darbu. Pirmais uzsāk trīs augšupielādes vienlaicīgi, negaidot katras pabeigšanu; otrais vienlaikus uzrauga trīs indeksēšanas uzdevumus: kopējais laiks tuvojas ilgākā dokumenta apstrādes laikam, nevis visu laiku summai. Un tā kā gaidīšana nebloķē notikumu cilpu, šis pats kods tieši iekļaujas FastAPI vai aiohttp lietotnē, kas turpina apkalpot citus pieprasījumus, kamēr tavi dokumenti tiek indeksēti.

Galvenās atziņas

  • xAI Python SDK pastāv sinhronā (Client) un asinhronā (AsyncClient) versijā; await prasa pēdējo
  • Abas atslēgas (API un pārvaldības) tiek konfigurētas klientā
  • upload_document augšupielādē un pievieno vienā izsaukumā; indeksēšanu uzrauga ar get_document vai wait_for_indexing=True
  • asyncio.gather() ļauj augšupielādēt un gaidīt indeksēšanu paralēli
  • Ģenerēšana izmanto kolekciju ar rīku collections_search, nodrošinot gan atbildi, gan atsauces

Pārbaudi savas zināšanas

Faili, kolekcijas, meklēšana: RAG, ko pārvalda xAI.

1. Ko ļauj darīt Files API?

Atbilde: Augšupielādēt un pārvaldīt failus (saraksts, skatīšana, dzēšana) atbalstītajos formātos — tie ir izejmateriāli kolekcijām un vaicājumiem ar dokumentiem.

2. Kas ir kolekcija?

Atbilde: Dokumentu kopa, ko servera pusē pārvalda xAI, ar metadatiem un atļaujām — gatavs lietošanai indekss, ko vaicā, neveidojot savu vektoru konveijeru.

3. Kuri meklēšanas režīmi ir pieejami?

Atbilde: Atslēgvārdu (precīzi termini), semantiskā (nozīme) un hibrīda (abi) — izvēle ir atkarīga no jautājumu rakstura, un hibrīda režīms aptver lielāko daļu gadījumu.

4. Kā RAG integrējas ar ģenerēšanu?

Atbilde: Izmantojot kolekciju meklēšanas rīku: collections_search xAI SDK vai file_search ar kolekciju ID atbilžu API. Modelis vaicā tavus dokumentus ģenerēšanas laikā un norāda avotus — RAG modelis bez uzturamas infrastruktūras.

5. Kam jāpievērš uzmanība ražošanas vidē?

Atbilde: Augšupielādēto datu konfidencialitāte (atļaujas, dzīves cikls), atbilstības optimizēšana (metadati, sadalīšana fragmentos) — un asinhronais SDK liela apjoma apstrādei.

Pārvaldīts RAG: tu nodrošini dokumentus un jautājumus, xAI rūpējas par indeksu — saglabā kontroli pār konfidencialitāti un atbilstību.