Is-SDK tal-Python ta' xAI: Operazzjonijiet Asinkroni
F'din il-paġna
Aġġornat fit-2 ta’ Novembru, 2026. Ibbażat fuq il-kodiċi
xai-sdk1.21.0 u l-eżempju uffiċjali ta’ xAI: is-sejħietawaitjeħtieġu l-klijent asinkronuAsyncClient(il-Clienthuwa sinkronu), l-oġġetti rritornati jesponucollection_id,collections,matches, uchunk_content, l-istatus tal-indiċjar jitqabbel ma’collections_pb2.DOCUMENT_STATUS_PROCESSED, uupload_documentitella’ u jwaħħal il-fajl f’sejħa waħda (l-eżempju preċedenti kien itellgħu darbtejn, darba bl-użu ta’ metodu li ma jeżistix). Sorsi: Collections via the API · Collections Search · xai-sdk-python.
Awtomatizza l-Flussi tax-Xogħol RAG tiegħek fil-Python
Kollox li sejjaħt permezz ta’ curl matul dan il-kors jeżisti fil-Python: it-tlugħ ta’ dokumenti, il-ġestjoni tal-kollezzjonijiet, it-tfittxija, u l-ġenerazzjoni. L-SDK ta’ xAI joffri żewġ klijenti, wieħed sinkronu (Client) u ieħor asinkronu (AsyncClient), b’metodi identiċi. Dan tal-aħħar huwa l-għażla t-tajba għal fluss tax-xogħol RAG, li jqatta’ l-biċċa l-kbira tal-ħin jistenna—biex titlesta tlugħ, biex jiġi indiċjat dokument, jew biex tirritorna tfittxija. Il-kodiċi asinkronu jimmaniġġja dawn l-istenzi b’mod parallel minflok f’sekwenza.
Installazzjoni u Konfigurazzjoni
pip install xai-sdk
Il-klijent jeħtieġ żewġ ċwievet: iċ-ċavetta standard tal-API għat-tfittxija u l-ġenerazzjoni, u ċ-ċavetta tal-API tal-Ġestjoni għall-kollezzjonijiet.
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"),
)
Kull talba għandha limitu ta’ żmien (timeout) predefinit ta’ 27 minuta qabel ma tiskadi, li jkopri t-tlugħ ta’ PDF kbir. Il-parametru timeout, f’sekondi, jippermettilek tissikka dan il-limitu għal applikazzjoni interattiva.
Operazzjonijiet tal-Kollezzjoni
Tliet sejħiet ikopru ċ-ċiklu tal-ħajja kollu. Il-ħolqien jirritorna l-ID li se terġa’ tużah kullimkien ieħor:
collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Collection created: {collection_id}")
Il-lista tgħin prinċipalment biex tirkupra ID li ma ħżintx, jew biex tiċċekkja l-istatus ta’ kont kondiviż bejn proġetti multipli:
response = await client.collections.list()
for col in response.collections:
print(f"{col.collection_id} — {col.collection_name} ({col.documents_count} documents)")
It-tħassir huwa irreversibbli u jneħħi d-dokumenti u l-indiċi tagħhom:
await client.collections.delete(collection_id)
Żid Dokument u Stenna l-Indiċjar
Sejħa waħda, upload_document, itella’ l-fajl permezz tal-API tal-Fajls u jwaħħlu mal-kollezzjoni:
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
Jekk il-fajl diġà jeżisti fl-API tal-Fajls, add_existing_document(collection_id, file_id) iwaħħlu mingħajr ma jerġa’ jitella’.
Iż-żieda ta’ dokument ma tagħmilux disponibbli għall-mistoqsijiet immedjatament. L-indiċjar jieħu żmien varjabbli skont id-daqs tal-fajl, u tfittxija mnedija kmieni wisq sempliċiment tirritorna inqas riżultati milli mistenni—bug li huwa partikolarment doloruż biex tiddijanostika, peress li ma tqajjem l-ebda żball. Għalhekk dan iċ-ċiklu ta’ stennija, li jivverifika l-istatus sakemm jilħaq 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)
L-istatus huwa valwu ta’ enumerazzjoni, mhux stringa: li tqabblu mat-test "DOCUMENT_STATUS_PROCESSED" qatt ma jkun veru, u ċ-ċiklu jimxi għal dejjem. Għal każ sempliċi, upload_document(..., wait_for_indexing=True) jimmaniġġja din l-istennija għalik.
Tfittxija mill-SDK
It-tfittxija tirritorna l-istess biċċiet (chunks) b’punteġġi bħall-endpoint HTTP, fil-lista 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("---")
Pipeline Sħiħa Minn Truf għal Truf
Il-blokki preċedenti jingħaqdu f’script li joħloq il-kollezzjoni, itella’ d-dokumenti, jistenna l-indiċjar, ifittex, u mbagħad jiġġenera tweġiba bl-użu tal-għodda 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. Oħloq il-kollezzjoni
collection = await client.collections.create(name="project-documentation")
collection_id = collection.collection_id
# 2. Żid id-dokumenti b'mod parallel
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. Stenna sakemm jiġu indiċjati d-dokumenti kollha
await asyncio.gather(*[
wait_for_indexing(client, fid, collection_id) for fid in file_ids
])
# 4. Fittex
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. Iġġenera tweġiba bbażata fuq il-kollezzjoni
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())
Iż-żewġ sejħiet asyncio.gather() jagħmlu x-xogħol kollu. L-ewwel waħda tniedi t-tliet tligħat flimkien minflok ma tistenna li kull waħda tispiċċa; it-tieni waħda timmonitorja t-tliet kompiti ta’ indiċjar simultanjament: il-ħin totali jersaq lejn dak tad-dokument l-itwal, minflok is-somma ta’ kollha kemm huma. U peress li l-istennija ma timblokkax iċ-ċiklu tal-avvenimenti (event loop), l-istess kodiċi jidħol direttament f’applikazzjoni FastAPI jew aiohttp, li tkompli sservi talbiet oħra waqt li d-dokumenti tiegħek qed jiġu indiċjati.
Punti Ewlenin
- L-SDK tal-Python ta’ xAI jeżisti f’verżjonijiet sinkroni (
Client) u asinkroni (AsyncClient);awaitjeħtieġ dan tal-aħħar - Iż-żewġ ċwievet (API u Ġestjoni) jiġu kkonfigurati fil-klijent
upload_documentitella’ u jwaħħal f’sejħa waħda; immonitorja l-indiċjar permezz ta’get_documentjewwait_for_indexing=Trueasyncio.gather()jippermettilek itella’ u tistenna l-indiċjar b’mod parallel- Il-ġenerazzjoni tisfrutta l-kollezzjoni bl-għodda
collections_search, kompluta b’tweġiba u ċitazzjonijiet
Ittestja l-Għarfien Tiegħek
Fajls, kollezzjonijiet, tfittxija: RAG immaniġġjat minn xAI.
1. X'tippermettilek tagħmel l-API tal-Fajls?
Tweġiba: Ittella’ u timmaniġġja fajls (lista, viżwalizzazzjoni, tħassir) f’formati appoġġjati—il-materja prima għall-kollezzjonijiet u l-mistoqsijiet b’dokumenti.
2. X'inhi kollezzjoni?
Tweġiba: Sett ta’ dokumenti ġestiti fuq is-server minn xAI, b’metadejta u permessi—l-indiċi lest għall-użu li tista’ tikkonsulta mingħajr ma tibni l-pipeline vettorjali tiegħek stess.
3. Liema modalitajiet ta' tfittxija huma disponibbli?
Tweġiba: Eżatta (kelmiet eżatti), semantika (tifsira), u ibrida (it-tnejn)—l-għażla ssegwi n-natura tal-mistoqsijiet, bl-ibrida tkopri l-biċċa l-kbira tal-każijiet.
4. Kif tintegra r-RAG mal-ġenerazzjoni?
Tweġiba: Permezz tal-għodda ta’ tfittxija tal-kollezzjoni: collections_search fl-SDK ta’ xAI, file_search b’IDs tal-kollezzjoni fl-API tar-Risposti. Il-mudell jikkonsulta d-dokumenti tiegħek waqt il-ġenerazzjoni u jiċċita s-sorsi tiegħu—il-mudell RAG mingħajr infrastruttura biex tinżamm.
5. Liema punti jeħtieġu attenzjoni għall-produzzjoni?
Tweġiba: Kunfidenzjalità tad-data mtellgħa (permessi, ċiklu tal-ħajja), rilevanza biex tiġi ottimizzata (metadejta, qsim f’biċċiet)—u l-SDK asinkronu għal ipproċessar ta’ volum għoli.
RAG Immaniġġjat: int iġġib id-dokumenti u l-mistoqsijiet, xAI jimmaniġġja l-indiċi—żomm il-kontroll tal-kunfidenzjalità u r-rilevanza.