Python SDK xAI: operacije asinhrone
Na tej strani
Posodobljeno 2. novembra 2026. Na podlagi kode
xai-sdk1.21.0 in uradnega primera xAI: kliciawaitzahtevajo asinhroni odjemalecAsyncClient(odjemalecClientje sinhron), vrnjeni objekti izpostavljajocollection_id,collections,matchesinchunk_content, stanje indeksiranja se primerja zcollections_pb2.DOCUMENT_STATUS_PROCESSED, funkcijaupload_documentpa 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;awaitzahteva slednjega - Ob ključa (API in Management) se konfigurirata v odjemalcu
upload_documentnaloži in pripne v enem klicu; indeksiranje spremljaj prekget_documentaliwait_for_indexing=Trueasyncio.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.