L'SDK Python di xAI: Operazioni Asincrone
In questa pagina
Aggiornato il 2 novembre 2026. Basato sul codice
xai-sdk1.21.0 e sull’esempio ufficiale di xAI: le chiamateawaitrichiedono il client asincronoAsyncClient(ilClientè sincrono), gli oggetti restituiti espongonocollection_id,collections,matchesechunk_content, lo stato dell’indicizzazione si confronta concollections_pb2.DOCUMENT_STATUS_PROCESSED, eupload_documentcarica e allega il file in un’unica chiamata (l’esempio precedente lo caricava due volte, usando un metodo inesistente). Fonti: Collections via the API · Collections Search · xai-sdk-python.
Automatizza i tuoi flussi di lavoro RAG in Python
Tutto ciò che hai chiamato tramite curl durante questo corso esiste in Python: caricamento documenti, gestione collezioni, ricerca, generazione. L’SDK di xAI offre due client, uno sincrono (Client) e uno asincrono (AsyncClient), con metodi identici. Quest’ultimo è la scelta giusta per un flusso di lavoro RAG, che passa la maggior parte del tempo in attesa—che un caricamento finisca, che un documento venga indicizzato, che una ricerca restituisca risultati. Il codice asincrono gestisce queste attese in parallelo invece che in sequenza.
Installazione e Configurazione
pip install xai-sdk
Il client richiede due chiavi: la chiave API standard per ricerca e generazione, e la chiave Management API per le collezioni.
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"),
)
Ogni richiesta ha un timeout predefinito di 27 minuti prima di scadere, sufficiente per caricare un PDF di grandi dimensioni. Il parametro timeout, in secondi, ti permette di restringere questo limite per un’applicazione interattiva.
Operazioni sulle Collezioni
Tre chiamate coprono l’intero ciclo di vita. La creazione restituisce l’ID che riutilizzerai ovunque altro:
collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Collection created: {collection_id}")
L’elenco serve principalmente a recuperare un ID che non hai persistito, o a verificare lo stato di un account condiviso tra più progetti:
response = await client.collections.list()
for col in response.collections:
print(f"{col.collection_id} — {col.collection_name} ({col.documents_count} documents)")
L’eliminazione è irreversibile e rimuove i documenti e i loro indici:
await client.collections.delete(collection_id)
Aggiungere un Documento e Attendere l’Indicizzazione
Un’unica chiamata, upload_document, carica il file tramite le Files API e lo allega alla collezione:
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
Se il file esiste già nelle Files API, add_existing_document(collection_id, file_id) lo allega senza ricaricarlo.
Aggiungere un documento non lo rende immediatamente interrogabile. L’indicizzazione richiede un tempo variabile a seconda delle dimensioni del file, e una ricerca avviata troppo presto restituisce semplicemente meno risultati del previsto—un bug particolarmente doloroso da diagnosticare, poiché non genera alcun errore. Da qui questo ciclo di attesa, che interroga lo stato fino a 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)
Lo stato è un valore di enumerazione, non una stringa: confrontarlo con il testo "DOCUMENT_STATUS_PROCESSED" non sarebbe mai vero e il ciclo girerebbe all’infinito. Per un caso semplice, upload_document(..., wait_for_indexing=True) gestisce questa attesa per te.
Ricerca dall’SDK
La ricerca restituisce gli stessi chunk valutati dell’endpoint HTTP, nella 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("---")
Una Pipeline End-to-End Completa
I blocchi precedenti si assemblano in uno script che crea la collezione, carica i documenti, attende l’indicizzazione, esegue una ricerca, quindi genera una risposta utilizzando lo strumento 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. Creare la collezione
collection = await client.collections.create(name="project-documentation")
collection_id = collection.collection_id
# 2. Aggiungere documenti in parallelo
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. Attendere che tutti i documenti siano indicizzati
await asyncio.gather(*[
wait_for_indexing(client, fid, collection_id) for fid in file_ids
])
# 4. Ricerca
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. Generare una risposta basata sulla collezione
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())
Le due chiamate asyncio.gather() fanno tutto il lavoro. La prima avvia i tre caricamenti insieme invece di attendere il completamento di ciascuno; la seconda monitora simultaneamente i tre lavori di indicizzazione: il tempo totale si avvicina a quello del documento più lungo, piuttosto che alla somma di tutti. E poiché l’attesa non blocca il loop degli eventi, lo stesso codice si integra direttamente in un’applicazione FastAPI o aiohttp, che continua a servire altre richieste mentre i tuoi documenti vengono indicizzati.
Punti chiave
- L’SDK Python di xAI esiste nelle versioni sincrona (
Client) e asincrona (AsyncClient);awaitrichiede quest’ultima - Entrambe le chiavi (API e Management) si configurano nel client
upload_documentcarica e allega in un’unica chiamata; monitora l’indicizzazione tramiteget_documentowait_for_indexing=Trueasyncio.gather()ti permette di caricare e attendere l’indicizzazione in parallelo- La generazione sfrutta la collezione con lo strumento
collections_search, completo di risposta e citazioni
Metti alla prova le tue conoscenze
File, collezioni, ricerca: RAG gestito da xAI.
1. Cosa ti permette di fare le Files API?
Risposta: Caricare e gestire file (elencare, visualizzare, eliminare) nei formati supportati—la materia prima per collezioni e query con documenti.
2. Cos'è una collezione?
Risposta: Un insieme di documenti gestiti lato server da xAI, con metadati e permessi—l’indice pronto all’uso che interroghi senza costruire la tua pipeline vettoriale.
3. Quali modalità di ricerca sono disponibili?
Risposta: Per parole chiave (termini esatti), semantica (significato) e ibrida (entrambe)—la scelta segue la natura delle domande, con l’ibrida che copre la maggior parte dei casi.
4. Come si integra il RAG con la generazione?
Risposta: Tramite lo strumento di ricerca sulla collezione: collections_search nell’SDK xAI, file_search con ID collezione nelle Responses API. Il modello interroga i tuoi documenti durante la generazione e cita le sue fonti—il pattern RAG senza infrastruttura da mantenere.
5. Quali punti richiedono attenzione per la produzione?
Risposta: Riservatezza dei dati caricati (permessi, ciclo di vita), rilevanza da ottimizzare (metadati, chunking)—e l’SDK asincrono per l’elaborazione ad alto volume.
RAG gestito: tu porti i documenti e le domande, xAI gestisce l’indice—mantieni il controllo su riservatezza e rilevanza.