Salt la conținutul principal
Română— Alege o limbă
Meniu

SDK-ul Python xAI: Operațiuni asincrone

Lecția 16 din 16 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Automatizați fluxurile de lucru RAG în Python
  2. Instalare și configurare
  3. Operațiuni cu colecții
  4. Adăugarea unui document și așteptarea indexării
  5. Căutare prin SDK
  6. Un pipeline complet cap-la-cap
  7. Puncte cheie
  8. Testați-vă cunoștințele

Actualizat la 2 noiembrie 2026. Bazat pe codul xai-sdk 1.21.0 și pe exemplul oficial xAI: apelurile await necesită clientul asincron AsyncClient (în timp ce Client este sincron), obiectele returnate expun collection_id, collections, matches și chunk_content, starea indexării se compară cu collections_pb2.DOCUMENT_STATUS_PROCESSED, iar upload_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); await necesită后者
  • Ambele chei (API și Management) se configurează în client
  • upload_document încarcă și atașează într-un singur apel; monitorizați indexarea prin get_document sau wait_for_indexing=True
  • asyncio.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.