SDK-ul Python xAI: Operațiuni asincrone
Pe această pagină
Actualizat la 2 noiembrie 2026. Bazat pe codul
xai-sdk1.21.0 și pe exemplul oficial xAI: apelurileawaitnecesită clientul asincronAsyncClient(în timp ceClienteste sincron), obiectele returnate expuncollection_id,collections,matchesșichunk_content, starea indexării se compară cucollections_pb2.DOCUMENT_STATUS_PROCESSED, iarupload_documentîncarcă și atașează fișierul într-un singur apel (exemplul anterior îl încărca de două ori, folosind o metodă inexistentă). Surse: Colecții prin API · Căutare în colecții · xai-sdk-python.
Automatizați fluxurile de lucru RAG în Python
Tot ceea ce ați apelat prin curl pe parcursul acestui curs există și în Python: încărcarea documentelor, gestionarea colecțiilor, căutarea și generarea. SDK-ul xAI oferă doi clienți, unul sincron (Client) și unul asincron (AsyncClient), cu metode identice. Cel din urmă este alegerea corectă pentru un flux de lucru RAG, care își petrece majoritatea timpului așteptând—finalizarea unei încărcări, indexarea unui document sau returnarea unui rezultat la căutare. Codul asincron gestionează aceste așteptări în paralel, nu secvențial.
Instalare și configurare
pip install xai-sdk
Clientul necesită două chei: cheia API standard pentru căutare și generare, și cheia API de Management pentru colecții.
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"),
)
Fiecare cerere are implicit un timp de expirare (timeout) de 27 de minute, suficient pentru încărcarea unui PDF voluminos. Parametrul timeout, exprimat în secunde, vă permite să reduceți această limită pentru o aplicație interactivă.
Operațiuni cu colecții
Trei apeluri acoperă întregul ciclu de viață. Crearea returnează ID-ul pe care îl veți reutiliza peste tot:
collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Collection created: {collection_id}")
Listarea ajută în principal la recuperarea unui ID pe care nu l-ați persistat sau la verificarea stării unui cont partajat între mai multe proiecte:
response = await client.collections.list()
for col in response.collections:
print(f"{col.collection_id} — {col.collection_name} ({col.documents_count} documents)")
Ștergerea este ireversibilă și elimină documentele împreună cu indexurile lor:
await client.collections.delete(collection_id)
Adăugarea unui document și așteptarea indexării
Un singur apel, upload_document, încarcă fișierul prin API-ul Files și îl atașează la colecție:
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
Dacă fișierul există deja în API-ul Files, add_existing_document(collection_id, file_id) îl atașează fără a-l reîncărca.
Adăugarea unui document nu îl face interogabil imediat. Indexarea durează un timp variabil în funcție de dimensiunea fișierului, iar o căutare lansată prea devreme va returna pur și simplu mai puține rezultate decât se aștepta—o eroare deosebit de dureroasă pentru diagnosticare, deoarece nu generează nicio excepție. De aici această buclă de așteptare, care interoghează starea până când devine 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)
Starea este o valoare de enumerare, nu un șir de caractere: compararea ei cu textul "DOCUMENT_STATUS_PROCESSED" nu ar fi niciodată adevărată, iar bucla ar rula la infinit. Pentru un caz simplu, upload_document(..., wait_for_indexing=True) gestionează această așteptare în locul dumneavoastră.
Căutare prin SDK
Căutarea returnează aceleași fragmente punctate ca și endpoint-ul HTTP, în 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("---")
Un pipeline complet cap-la-cap
Blocurile anterioare se asamblează într-un script care creează colecția, încarcă documentele, așteptă indexarea, efectuează căutarea și apoi generează un răspuns folosind instrumentul 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. Crearea colecției
collection = await client.collections.create(name="project-documentation")
collection_id = collection.collection_id
# 2. Adăugarea documentelor în paralel
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. Așteptarea indexării tuturor documentelor
await asyncio.gather(*[
wait_for_indexing(client, fid, collection_id) for fid in file_ids
])
# 4. Căutare
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. Generarea unui răspuns bazat pe colecție
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())
Cele două apeluri asyncio.gather() fac toată treaba. Primul lansează cele trei încărcări simultan, în loc să aștepte finalizarea fiecăreia; al doilea monitorizează cele trei joburi de indexare în același timp: timpul total se apropie de durata celui mai lung document, nu de suma tuturor. Și deoarece așteptarea nu blochează bucla de evenimente, același cod se integrează direct într-o aplicație FastAPI sau aiohttp, care continuă să servească alte cereri în timp ce documentele dumneavoastră se indexează.
Puncte cheie
- SDK-ul Python xAI există în versiuni sincronă (
Client) și asincronă (AsyncClient);awaitnecesită后者 - Ambele chei (API și Management) se configurează în client
upload_documentîncarcă și atașează într-un singur apel; monitorizați indexarea pringet_documentsauwait_for_indexing=Trueasyncio.gather()vă permite să încărcați și să așteptați indexarea în paralel- Generarea utilizează colecția cu instrumentul
collections_search, incluzând răspunsul și citările
Testați-vă cunoștințele
Fișiere, colecții, căutare: RAG gestionat de xAI.
1. Ce vă permite să faceți API-ul Files?
Răspuns: Încărcarea și gestionarea fișierelor (listare, vizualizare, ștergere) în formatele suportate—materia primă pentru colecții și interogări cu documente.
2. Ce este o colecție?
Răspuns: Un set de documente gestionat lato sensu de xAI, cu metadate și permisiuni—indexul gata de utilizare pe care îl interogați fără a construi propriul pipeline vectorial.
3. Ce moduri de căutare sunt disponibile?
Răspuns: Pe cuvinte cheie (termeni exacți), semantic (sens) și hibrid (ambele)—alegerea depinde de natura întrebărilor, iar hibridul acoperă majoritatea cazurilor.
4. Cum se integrează RAG cu generarea?
Răspuns: Prin instrumentul de căutare în colecții: collections_search în SDK-ul xAI, file_search cu ID-uri de colecții în API-ul Responses. Modelul interoghează documentele dumneavoastră în timpul generării și își citează sursele—modelul RAG fără infrastructură de menținut.
5. Ce aspecte necesită atenție pentru producție?
Răspuns: Confidențialitatea datelor încărcate (permisiuni, ciclu de viață), relevanța de optimizat (metadate, fragmentare)—și SDK-ul asincron pentru procesarea la volum mare.
RAG gestionat: dumneavoastră aduceți documentele și întrebările, xAI se ocupă de index—păstrați controlul asupra confidențialității și relevanței.