Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Python SDK xAI: operacije asinhrone

Lekcija 16 od 16 Posodobljeno 2. november 2026 Razvijalec
Na tej strani
  1. Avtomatiziraj svoja delovna toka RAG v Pythonu
  2. Namestitev in konfiguracija
  3. Operacije z zbirkami
  4. Dodaj dokument in počakaj na indeksiranje
  5. Iskanje prek SDK-ja
  6. Celoten end-to-end cevovod
  7. Ključne ugotovitve
  8. Preveri svoje znanje

Posodobljeno 2. novembra 2026. Na podlagi kode xai-sdk 1.21.0 in uradnega primera xAI: klici await zahtevajo asinhroni odjemalec AsyncClient (odjemalec Client je sinhron), vrnjeni objekti izpostavljajo collection_id, collections, matches in chunk_content, stanje indeksiranja se primerja z collections_pb2.DOCUMENT_STATUS_PROCESSED, funkcija upload_document pa naloži in pripne datoteko v enem samem klicu (prejšnji primer jo je naložil dvakrat, enkrat z uporabo neobstoječe metode). Viri: Zbirke prek API-ja · Iskanje po zbirkah · xai-sdk-python.

Avtomatiziraj svoja delovna toka RAG v Pythonu

Vse, kar si v tem tečaju klical prek curla, obstaja tudi v Pythonu: nalaganje dokumentov, upravljanje zbirk, iskanje in generiranje. SDK xAI ponuja dva odjemalca, enega sinhrono (Client) in enega asinhrono (AsyncClient), z identičnimi metodami. Slednji je prava izbira za delovni tok RAG, ki večino časa čaka – na zaključek nalaganja, indeksiranje dokumenta ali vrnitev rezultatov iskanja. Asinhrona koda te čase obravnava vzporedno in ne zaporedno.

Namestitev in konfiguracija

pip install xai-sdk

Odjemalec zahteva dva ključa: standardni ključ API za iskanje in generiranje ter ključ Management API za zbirke.

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

Vsaka zahteva ima privzeto časovno omejitev 27 minut pred potekom, kar zadostuje za nalaganje velikega PDF-ja. Parameter timeout v sekundah ti omogoča, da to omejitev zaoštriš za interaktivno aplikacijo.

Operacije z zbirkami

Trije klici pokrijejo celoten življenjski cikel. Ustvarjanje vrne ID, ki ga boš ponovno uporabil povsod drugje:

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

Seznam je koristen predvsem za obnovitev ID-ja, ki ga nisi trajno shranil, ali za preverjanje stanja računa, ki ga deliš med več projekti:

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

Brisanje je nepovratno in odstrani dokumente ter njihova kazala:

await client.collections.delete(collection_id)

Dodaj dokument in počakaj na indeksiranje

En sam klic, upload_document, naloži datoteko prek API-ja Files in jo pripne zbirki:

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

Če datoteka že obstaja v API-ju Files, jo add_existing_document(collection_id, file_id) pripne brez ponovnega nalaganja.

Dodajanje dokumenta ga ne naredi takoj poizvedljivega. Indeksiranje traja različno dolgo, odvisno od velikosti datoteke, iskanje, zagnano prezgodaj, pa preprosto vrne manj rezultatov, kot je pričakovano – napaka, ki jo je še posebej boleče diagnosticirati, saj ne sproži nobene napake. Zato ta zanka čakanja, ki preverja stanje, dokler ne doseže 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)

Stanje je vrednost naštevanja, ne niz: primerjava z besedilom "DOCUMENT_STATUS_PROCESSED" nikoli ne bi bila resnična in zanka bi tekla v neskončnost. Za preprost primer upload_document(..., wait_for_indexing=True) to čakanje opravi namesto tebe.

Iskanje prek SDK-ja

Iskanje vrne enake ocenjene razdelke kot končna točka HTTP, in sicer na seznamu 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("---")

Celoten end-to-end cevovod

Prejšnji bloki se združijo v skripto, ki ustvari zbirko, naloži dokumente, počaka na indeksiranje, išče in nato generira odgovor z uporabo orodja 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. Ustvari zbirko
    collection = await client.collections.create(name="project-documentation")
    collection_id = collection.collection_id

    # 2. Dodaj dokumente vzporedno
    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. Počakaj, da se vsi dokumenti indeksirajo
    await asyncio.gather(*[
        wait_for_indexing(client, fid, collection_id) for fid in file_ids
    ])

    # 4. Iskanje
    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. Generiraj odgovor na podlagi zbirke
    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())

Oba klica asyncio.gather() opravita vse delo. Prvi sproži tri nalaganja hkrati namesto čakanja na zaključek vsakega posebej; drugi hkrati spremlja tri opravila indeksiranja: skupni čas se približa času najdaljšega dokumenta in ne vsoti vseh. Ker čakanje ne blokira zanke dogodkov, se ta koda neposredno prilega tudi aplikaciji FastAPI ali aiohttp, ki med indeksiranjem dokumentov še naprej obravnava druge zahteve.

Ključne ugotovitve

  • Python SDK xAI obstaja v sinhroni (Client) in asinhroni (AsyncClient) različici; await zahteva slednjega
  • Ob ključa (API in Management) se konfigurirata v odjemalcu
  • upload_document naloži in pripne v enem klicu; indeksiranje spremljaj prek get_document ali wait_for_indexing=True
  • asyncio.gather() ti omogoča vzporedno nalaganje in čakanje na indeksiranje
  • Generiranje izkorišča zbirko z orodjem collections_search, vključno z odgovorom in citati

Preveri svoje znanje

Datoteke, zbirke, iskanje: RAG, ki ga upravlja xAI.

1. Kaj omogoča API Files?

Odgovor: Nalaganje in upravljanje datotek (seznam, ogled, brisanje) v podprtih formatih – surov material za zbirke in poizvedbe z dokumenti.

2. Kaj je zbirka?

Odgovor: Nabor dokumentov, ki jih strežniško upravlja xAI, z metapodatki in dovoljenji – pripravljen indeks, ki ga poizveduješ brez gradnje lastnega vektorskega cevovoda.

3. Kateri načini iskanja so na voljo?

Odgovor: Ključne besede (točni izrazi), semantično (pomen) in hibridno (oboje) – izbira sledi naravi vprašanj, pri čemer hibridno pokriva večino primerov.

4. Kako se RAG integrira z generiranjem?

Odgovor: Prek orodja za iskanje po zbirkah: collections_search v SDK-ju xAI, file_search z ID-ji zbirk v API-ju Responses. Model med generiranjem poizveduje po tvojih dokumentih in navaja vire – vzorec RAG brez infrastrukture za vzdrževanje.

5. Na katere točke moraš biti pozoren pri proizvodnji?

Odgovor: Zaupnost naloženih podatkov (dovoljenja, življenjski cikel), ustreznost za optimizacijo (metapodatki, razdeljevanje) – in asinhroni SDK za obdelavo velikih količin.

Upravljan RAG: ti prineseš dokumente in vprašanja, xAI poskrbi za indeks – obdrži nadzor nad zaupnostjo in ustreznostjo.