xAI Python SDK: operacijos asinchroniniu režimu
Šiame puslapyje
Atnaujinta 2026 m. lapkričio 2 d. Remiantis
xai-sdk1.21.0 kodu ir oficialiu xAI pavyzdžiu:awaitkvietimams reikia asinchroninio klientoAsyncClient(Clientyra sinchroninis), grąžinami objektai pateikiacollection_id,collections,matchesirchunk_content, indeksavimo būsena lyginama sucollections_pb2.DOCUMENT_STATUS_PROCESSED, oupload_documentįkelia ir prideda failą vienu kvietimu (ankstesnis pavyzdys jį įkeldavo du kartus, naudodamas neegzistuojantį metodą). Šaltiniai: Kolekcijos per API · Kolekcijų paieška · xai-sdk-python.
Automatizuokite savo RAG darbo eigas Python kalba
Viskas, ką šiame kurse kvietėte naudodami curl, egzistuoja ir Python kalboje: dokumentų įkėlimas, kolekcijų valdymas, paieška, generavimas. xAI SDK siūlo du klientus: vieną sinchroninį (Client) ir vieną asinchroninį (AsyncClient) su identiškais metodais. Pastarasis yra tinkamas pasirinkimas RAG darbo eigai, kuri didžiąją laiko dalį praleidžia laukdama – kol baigsis įkėlimas, kol dokumentas bus indeksuotas, kol grįš paieškos rezultatai. Asinchroninis kodas šiuos laukimo procesus apdoroja lygiagrečiai, o ne nuosekliai.
Diegimas ir konfigūravimas
pip install xai-sdk
Klientui reikia dviejų raktų: standartinio API rakto paieškai ir generavimui bei valdymo API rakto kolekcijoms.
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"),
)
Kiekvienas užklausas pagal nutylėjimą turi 27 minuų laiko limitą prieš pasibaigiant, kas pakanka dideliam PDF failui įkelti. Parametras timeout (sekundėmis) leidžia sugriežtinti šį limitą interaktyvioms programoms.
Kolekcijų operacijos
Trys kvietimai apima visą gyvavimo ciklą. Kūrimas grąžina ID, kurį naudosite visuose kituose veiksmuose:
collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Collection created: {collection_id}")
Sąrašo gavimas daugiausia padeda atkurti ID, kurio neišsaugojote, arba patikrinti paskyros, bendrai naudojamos keliuose projektuose, būseną:
response = await client.collections.list()
for col in response.collections:
print(f"{col.collection_id} — {col.collection_name} ({col.documents_count} documents)")
Ištrynimas yra negrįžtamas ir pašalina dokumentus bei jų indeksus:
await client.collections.delete(collection_id)
Dokumento pridėjimas ir laukimas, kol bus baigtas indeksavimas
Vienas kvietimas, upload_document, įkelia failą per „Files API“ ir prideda jį prie kolekcijos:
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
Jei failas „Files API“ jau egzistuoja, add_existing_document(collection_id, file_id) jį prideda neįkeldamas iš naujo.
Pridėjus dokumentą, jis nėra iškart paruoštas užklausoms. Indeksavimas trunka įvairiai, priklausomai nuo failo dydžio, o per anksti paleista paieška tiesiog grąžina mažiau rezultatų nei tikėtasi – tai klaida, kurią ypač sunku diagnozuoti, nes ji neišmeta jokios klaidos. Todėl reikalingas šis laukimo ciklas, kuris tikrina būseną, kol pasiekiamas 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)
Būsena yra enumeracijos reikšmė, o ne tekstas: lyginant ją su tekstu "DOCUMENT_STATUS_PROCESSED", sąlyga niekada nebus tenkinama ir ciklas vyks amžinai. Paprastu atveju upload_document(..., wait_for_indexing=True) šį laukimą atlieka už jus.
Paieška naudojant SDK
Paieška grąžina tuos pačius įvertintus fragmentus kaip ir HTTP galinis taškas, sąraše 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("---")
Pilna端到端 (end-to-end) darbo eiga
Ankstesni blokai sujungiami į scenarijų, kuris sukuria kolekciją, įkelia dokumentus, laukia, kol bus baigtas indeksavimas, atlieka paiešką ir tada generuoja atsakymą naudodamas įrankį 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. Sukurti kolekciją
collection = await client.collections.create(name="project-documentation")
collection_id = collection.collection_id
# 2. Pridėti dokumentus lygiagrečiai
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. Laukti, kol visi dokumentai bus indeksuoti
await asyncio.gather(*[
wait_for_indexing(client, fid, collection_id) for fid in file_ids
])
# 4. Paieška
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. Generuoti atsakymą pagal kolekciją
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())
Du asyncio.gather() kvietimai atlieka visą darbą. Pirmasis paleidžia tris įkėlimus vienu metu, nelaukdamas, kol kiekvienas baigsis; antrasis vienu metu stebi tris indeksavimo užduotis: bendras laikas artėja prie ilgiausiai trunkančio dokumento laiko, o ne visų laikų sumos. Kadangi laukimas neužblokuoja įvykių ciklo, tas pats kodas tiesiogiai tinka „FastAPI“ arba „aiohttp“ programoms, kurios toliau aptarnauja kitas užklausas, kol jūsų dokumentai indeksuojami.
Svarbiausi punktai
- xAI Python SDK egzistuoja sinchronine (
Client) ir asinchronine (AsyncClient) versijomis;awaitreikalauja pastarosios - Abu raktai (API ir valdymo) konfigūruojami kliente
upload_documentįkelia ir prideda vienu kvietimu; stebėkite indeksavimą naudodamiget_documentarbawait_for_indexing=Trueasyncio.gather()leidžia įkelti ir laukti indeksavimo lygiagrečiai- Generavimas naudoja kolekciją su įrankiu
collections_search, pateikdamas atsakymą ir citatas
Patikrinkite savo žinias
Failai, kolekcijos, paieška: RAG, valdomas xAI.
1. Ką leidžia daryti „Files API“?
Atsakymas: Įkelti ir valdyti failus (sąrašas, peržiūra, ištrynimas) palaikomais formatais – tai žaliava kolekcijoms ir užklausoms su dokumentais.
2. Kas yra kolekcija?
Atsakymas: Dokumentų rinkinys, serverio lygmeniu valdomas xAI, su metaduomenimis ir leidimais – tai paruoštas naudoti indeksas, kurį galite užklausti nekurdami savo vektorinės paieškos infrastruktūros.
3. Kokios paieškos rūšys yra galimos?
Atsakymas: Raktažodžių (tikslūs terminai), semantinė (prasmė) ir hibridinė (abu būdai) – pasirinkimas priklauso nuo klausimų pobūdžio, o hibridinė tinka daugeliu atvejų.
4. Kaip RAG integruojamas su generavimu?
Atsakymas: Per kolekcijos paieškos įrankį: collections_search xAI SDK arba file_search su kolekcijų ID „Responses API“. Modelis generavimo metu užklauna jūsų dokumentus ir cituoja šaltinius – tai RAG šablonas be poreikio prižiūrėti infrastruktūrą.
5. Į kokius punktus reikia atkreipti dėmesį gamybinėje aplinkoje?
Atsakymas: Įkeliamų duomenų konfidencialumas (leidimai, gyvavimo ciklas), aktualumo optimizavimas (metaduomenys, skaidymas į dalis) ir asinchroninis SDK didelės apimties duomenų apdorojimui.
Valdomas RAG: jūs pateikiate dokumentus ir klausimus, xAI tvarko indeksą – išlaikykite konfidencialumo ir aktualumo kontrolę.