xAI Python SDK: Operācijas asinhronā režīmā
Šajā lapā
Atjaunināts 2026. gada 2. novembrī. Pamatojoties uz
xai-sdk1.21.0 kodu un oficiālo xAI piemēru: izsaukumiem arawaitir nepieciešams asinhronais klientsAsyncClient(kamērClientir sinhronais), atgrieztie objekti satur laukuscollection_id,collections,matchesunchunk_content, indeksēšanas statusu salīdzina arcollections_pb2.DOCUMENT_STATUS_PROCESSED, unupload_documentaugš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ā;awaitprasa pēdējo - Abas atslēgas (API un pārvaldības) tiek konfigurētas klientā
upload_documentaugšupielādē un pievieno vienā izsaukumā; indeksēšanu uzrauga arget_documentvaiwait_for_indexing=Trueasyncio.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.