xAI Python SDK: Asinkrone operacije
Na ovoj stranici
Ažurirano 2. studenoga 2026. Na temelju koda
xai-sdk1.21.0 i službenog xAI primjera: pozivi sawaitzahtijevaju asinkroni klijentAsyncClient(dok jeClientsinkron), vraćeni objekti izlažucollection_id,collections,matchesichunk_content, status indeksiranja uspoređuje se scollections_pb2.DOCUMENT_STATUS_PROCESSED, aupload_documentučitava i pridružuje datoteku u jednom pozivu (prethodni je primjer to radio dvaput, koristeći nepostojeću metodu). Izvori: Kolekcije putem API-ja · Pretraživanje kolekcija · xai-sdk-python.
Automatiziraj svoje RAG tijekove rada u Pythonu
Sve što si do sada u ovom tečaju pozivao putem curla postoji i u Pythonu: učitavanje dokumenata, upravljanje kolekcijama, pretraživanje i generiranje. xAI SDK nudi dva klijenta, jedan sinkroni (Client) i jedan asinkroni (AsyncClient), s identičnim metodama. Potonji je ispravan izbor za RAG tijek rada, koji većinu vremena provodi čekajući—dok se učitavanje ne završi, dokument ne indeksira ili pretraga ne vrati rezultate. Asinkroni kod obrađuje ta čekanja paralelno, a ne sekvencijalno.
Instalacija i konfiguracija
pip install xai-sdk
Klijent zahtijeva dva ključa: standardni API ključ za pretraživanje i generiranje te Management API ključ za kolekcije.
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"),
)
Svaki zahtjev prema zadanim postavkama ima vremensko ograničenje (timeout) od 27 minuta prije isteka, što pokriva učitavanje velikih PDF datoteka. Parametar timeout, izražen u sekundama, omogućuje ti da pooštriš ovo ograničenje za interaktivne aplikacije.
Operacije s kolekcijama
Tri poziva pokrivaju cijeli životni ciklus. Stvaranje vraća ID koji ćeš ponovno koristiti svugdje drugdje:
collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Collection created: {collection_id}")
Ispis popisa pomaže uglavnom u oporavku ID-a koji nisi trajno pohranio ili u provjeri stanja računa koji se dijeli između više projekata:
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 i uklanja dokumente te njihove indekse:
await client.collections.delete(collection_id)
Dodavanje dokumenta i čekanje indeksiranja
Jedan jedini poziv, upload_document, učitava datoteku putem Files API-ja i pridružuje je kolekciji:
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
Ako datoteka već postoji u Files API-ju, add_existing_document(collection_id, file_id) pridružuje je bez ponovnog učitavanja.
Dodavanje dokumenta ne čini ga odmah dostupnim za upite. Indeksiranje traje promjenjivo vrijeme ovisno o veličini datoteke, a pretraga pokrenuta prerano jednostavno vraća manje rezultata nego što se očekivalo—greška koju je posebno bolno dijagnosticirati jer ne izaziva nikakvu pogrešku. Zato postoji ova petlja čekanja koja ispituje status dok se ne postigne 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)
Status je vrijednost enumeracije, a ne niz znakova: usporedba s tekstom "DOCUMENT_STATUS_PROCESSED" nikada ne bi bila istinita i petlja bi se vrtjela u beskonačnost. Za jednostavne slučajeve, upload_document(..., wait_for_indexing=True) obavlja ovo čekanje umjesto tebe.
Pretraživanje putem SDK-a
Pretraživanje vraća iste ocijenjene isječke kao i HTTP krajnja točka, u popisu 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("---")
Cjeloviti end-to-end pipeline
Prethodni blokovi sastavljaju se u skriptu koja stvara kolekciju, učitava dokumente, čeka indeksiranje, pretražuje, a zatim generira odgovor koristeći alat 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. Stvori kolekciju
collection = await client.collections.create(name="project-documentation")
collection_id = collection.collection_id
# 2. Dodaj dokumente paralelno
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. Pričekaj da se svi dokumenti indeksiraju
await asyncio.gather(*[
wait_for_indexing(client, fid, collection_id) for fid in file_ids
])
# 4. Pretraži
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 temelju kolekcije
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())
Dva poziva asyncio.gather() obavljaju sav posao. Prvi pokreće tri učitavanja zajedno umjesto da čeka završetak svakog pojedinačno; drugi istovremeno nadzire tri zadatka indeksiranja: ukupno vrijeme približava se vremenu potrebnom za najduži dokument, a ne zbroju svih. Budući da čekanje ne blokira petlju događaja (event loop), isti se kod može izravno uklopiti u FastAPI ili aiohttp aplikaciju, koja nastavlja obrađivati druge zahtjeve dok se tvoji dokumenti indeksiraju.
Ključne točke
- xAI Python SDK postoji u sinkronoj (
Client) i asinkronoj (AsyncClient) verziji;awaitzahtijeva potonju - Oba ključa (API i Management) konfiguriraju se u klijentu
upload_documentučitava i pridružuje u jednom pozivu; prati indeksiranje putemget_documentiliwait_for_indexing=Trueasyncio.gather()omogućuje paralelno učitavanje i čekanje indeksiranja- Generiranje koristi kolekciju s alatom
collections_search, uključujući odgovor i citate
Provjeri svoje znanje
Datoteke, kolekcije, pretraživanje: RAG kojim upravlja xAI.
1. Što ti omogućuje Files API?
Odgovor: Učitavanje i upravljanje datotekama (popis, pregled, brisanje) u podržanim formatima—sirovi materijal za kolekcije i upite s dokumentima.
2. Što je kolekcija?
Odgovor: Skup dokumenata kojima server-side upravlja xAI, s metapodacima i dopuštenjima—indeks spreman za uporabu koji možeš upitivati bez izgradnje vlastitog vektorskog pipelinea.
3. Koji su načini pretraživanja dostupni?
Odgovor: Ključne riječi (točni izrazi), semantičko (značenje) i hibridno (oboje)—izbor ovisi o prirodi pitanja, pri čemu hibridno pokriva većinu slučajeva.
4. Kako se RAG integrira s generiranjem?
Odgovor: Putem alata za pretraživanje kolekcije: collections_search u xAI SDK-u ili file_search s ID-jevima kolekcija u Responses API-ju. Model upituje tvoje dokumente tijekom generiranja i citira izvore—RAG uzorak bez infrastrukture koju moraš održavati.
5. Na koje točke treba obratiti pozornost u proizvodnji?
Odgovor: Povjerljivost učitanih podataka (dopuštenja, životni ciklus), relevantnost za optimizaciju (metapodaci, chunking)—te asinkroni SDK za obradu velikih volumena.
Upravljani RAG: ti donosiš dokumente i pitanja, xAI se brine o indeksu—zadrži kontrolu nad povjerljivošću i relevantnošću.