xAI Python SDK: Asünkroonsed toimingud
Sellel lehel
Uuendatud 2. novembril 2026. Põhineb
xai-sdkversioonil 1.21.0 ja ametlikul xAI näitel:awaitväljakutsed nõuavad asünkroonset klientiAsyncClient(klientClienton sünkroonne), tagastatud objektid paljastavadcollection_id,collections,matchesjachunk_content, indekseerimisolekut võrreldakse väärtusegacollections_pb2.DOCUMENT_STATUS_PROCESSEDningupload_documentlaadib faili üles ja seob selle kollektsiooniga ühe kõnega (eelmine näide laadis selle kaks korda üles, kasutades olematut meetodit). Allikad: Kollektsioonid API kaudu · Kollektsioonide otsing · xai-sdk-python.
Automatiseeri oma RAG töövooge Pythonis
Kõik, mida oled selle kursuse vältel curl-i kaudu kutsunud, on olemas ka Pythonis: dokumentide üleslaadimine, kollektsioonide haldamine, otsing ja genereerimine. xAI SDK pakub kahte klienti: üht sünkroonset (Client) ja teist asünkroonset (AsyncClient), millel on identsed meetodid. Viimane on RAG töövoogude jaoks õige valik, kuna need veedavad suurema osa ajast oodates – faili üleslaadimise lõppemist, dokumendi indekseerimist või otsingu tulemuste naasmist. Asünkroonne kood käsitleb neid ooteid paralleelselt, mitte järjestikku.
Paigaldamine ja seadistamine
pip install xai-sdk
Klient nõuab kahte võtit: standardne API võti otsingu ja genereerimise jaoks ning haldus-API võti kollektsioonide jaoks.
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"),
)
Iga päringu vaikimisi aegumine on 27 minutit, mis katab suure PDF-faili üleslaadimise. Parameeter timeout (sekundites) võimaldab seda piirangut interaktiivse rakenduse jaoks kitsendada.
Kollektsioonide toimingud
Kolm kõnet katavad kogu elutsükli. Loome käik tagastab ID, mida kasutad kõikjal mujal:
collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Collection created: {collection_id}")
Loetlemine aitab peamiselt taastada ID-d, mida sa ei salvestanud, või kontrollida konto olekut, mida jagatakse mitme projekti vahel:
response = await client.collections.list()
for col in response.collections:
print(f"{col.collection_id} — {col.collection_name} ({col.documents_count} documents)")
Kustutamine on pöördumatu ja eemaldab nii dokumendid kui ka nende indeksid:
await client.collections.delete(collection_id)
Dokumendi lisamine ja indekseerimise ootamine
Üksainus kõne, upload_document, laadib faili Files API kaudu üles ja seob selle kollektsiooniga:
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
Kui fail on Files API-s juba olemas, seob add_existing_document(collection_id, file_id) selle uuesti üles laadimata.
Dokumendi lisamine ei tee seda kohe päritavaks. Indekseerimine võtab sõltuvalt faili suurusest erineva aja ja liiga vara käivitatud otsing tagastab lihtsalt vähem tulemusi, kui oodatud – viga, mida on eriti valus diagnoosida, kuna see ei tekita veateadet. Seetõttu see ootetsükkel, mis küsitleb olekut kuni DOCUMENT_STATUS_PROCESSED saavutamiseni:
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)
Olek on loendiväärtus, mitte sõne: selle võrdlemine tekstiga "DOCUMENT_STATUS_PROCESSED" ei oleks kunagi tõene ja tsükkel jookseks igavesti. Lihtsa juhu korral käsitleb seda ootamist sinu eest upload_document(..., wait_for_indexing=True).
Otsing SDK-st
Otsing tagastab samad hinnatud tükid kui HTTP lõpp-punkt, loendis 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("---")
Täielik otsast-otsani torustik
Eelmised plokid moodustavad skripti, mis loob kollektsiooni, laadib dokumendid üles, ootab indekseerimist, teeb otsingu ja genereerib seejärel vastuse, kasutades tööriista 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. Loo kollektsioon
collection = await client.collections.create(name="project-documentation")
collection_id = collection.collection_id
# 2. Lisa dokumendid paralleelselt
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. Oota, kuni kõik dokumendid on indekseeritud
await asyncio.gather(*[
wait_for_indexing(client, fid, collection_id) for fid in file_ids
])
# 4. Otsing
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. Genereeri vastus põhinevalt kollektsioonil
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())
Kaks asyncio.gather() kõnet teevad kogu töö. Esimene käivitab kolm üleslaadimist koos, selle asemel et oodata igaühe lõppemist; teine jälgib kolme indekseerimistööd samaaegselt: koguaeg läheneb pikima dokumendi ajale, mitte kõigi summale. Ja kuna ootamine ei blokeeri sündmuste tsüklit, sobib sama kood otse FastAPI või aiohttp rakendusse, mis jätkab teiste päringute teenindamist samal ajal, kui su dokumendid indekseeruvad.
Peamised punktid
- xAI Python SDK on olemas sünkroonses (
Client) ja asünkroonses (AsyncClient) versioonis;awaitnõuab viimast - Mõlemad võtmed (API ja haldus) seadistatakse kliendis
upload_documentlaadib üles ja seob ühe kõnega; jälgi indekseerimistget_documentvõiwait_for_indexing=Truekauduasyncio.gather()võimaldab üles laadida ja indekseerimist oodata paralleelselt- Genereerimine kasutab kollektsiooni tööriistaga
collections_search, kaasates vastuse ja tsitaadid
Testi oma teadmisi
Failid, kollektsioonid, otsing: xAI hallatav RAG.
1. Mida võimaldab Files API teha?
Vastus: Laadida üles ja hallata faile (loetleda, vaadata, kustutada) toetatud vormingutes – toores materjal kollektsioonide ja päringute jaoks dokumentidega.
2. Mis on kollektsioon?
Vastus: xAI poolt serveripoolselt hallatav dokumentide kogum koos metaandmete ja õigustega – valmis kasutamiseks indeks, mida pärid ilma oma vektoritorustikku ehitamata.
3. Millised otsingurežiimid on saadaval?
Vastus: Märksõna (täpsed terminid), semantiline (tähendus) ja hübriid (mõlemad) – valik sõltub küsimuste olemusest, kusjuures hübriid katab enamiku juhtumeid.
4. Kuidas integreerub RAG genereerimisega?
Vastus: Kollektsiooni otsingu tööriista kaudu: collections_search xAI SDK-s, file_search koos kollektsiooni ID-dega Responses API-s. Mudel pärib su dokumente genereerimise ajal ja tsiteerib allikaid – RAG muster ilma taristut hooldamata.
5. Millised punktid nõuavad tootmises tähelepanu?
Vastus: Üleslaaditud andmete konfidentsiaalsus (õigused, elutsükkel), asjakohasuse optimeerimine (metaandmed, tükeldamine) – ja asünkroonne SDK suure mahuga töötlemiseks.
Hallatud RAG: sina tood dokumendid ja küsimused, xAI haldab indeksit – hoia kontrolli konfidentsiaalsuse ja asjakohasuse üle.