De xAI Python SDK: Asynchrone bewerkingen
Op deze pagina
Bijgewerkt op 2 november 2026. Gebaseerd op
xai-sdk1.21.0-code en het officiële xAI-voorbeeld:await-aanroepen vereisen de asynchrone clientAsyncClient(deClientis synchroon), geretourneerde objecten biedencollection_id,collections,matchesenchunk_content, de indexeringsstatus wordt vergeleken metcollections_pb2.DOCUMENT_STATUS_PROCESSED, enupload_documentuploadt en koppelt het bestand in één enkele aanroep (het vorige voorbeeld uploadde het tweemaal, waarbij een niet-bestaande methode werd gebruikt). Bronnen: Collections via de API · Collections Search · xai-sdk-python.
Automatiseer uw RAG-workflows in Python
Alles wat u tijdens deze cursus via curl hebt aangeroepen, bestaat ook in Python: documentupload, collectiebeheer, zoeken en genereren. De xAI SDK biedt twee clients, één synchrone (Client) en één asynchrone (AsyncClient), met identieke methoden. Die laatste is de juiste keuze voor een RAG-workflow, die het grootste deel van de tijd wacht—op het voltooien van een upload, het indexeren van een document of het retourneren van een zoekresultaat. Asynchrone code behandelt deze wachttijden parallel in plaats van sequentieel.
Installatie en configuratie
pip install xai-sdk
De client vereist twee sleutels: de standaard API-sleutel voor zoeken en genereren, en de Management API-sleutel voor collecties.
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"),
)
Elke aanvraag heeft standaard een time-out van 27 minuten voordat deze verloopt, wat voldoende is voor het uploaden van een grote PDF. Met de parameter timeout, in seconden, kunt u deze limiet aanscherpen voor een interactieve toepassing.
Collectiebewerkingen
Drie aanroepen dekken de volledige levenscyclus. Creatie retourneert de ID die u overal elders opnieuw zult gebruiken:
collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Collectie gemaakt: {collection_id}")
Het opvragen van een lijst is vooral handig om een ID te herstellen die u niet hebt opgeslagen, of om de status van een account te controleren dat door meerdere projecten wordt gedeeld:
response = await client.collections.list()
for col in response.collections:
print(f"{col.collection_id} — {col.collection_name} ({col.documents_count} documenten)")
Verwijdering is onomkeerbaar en verwijdert de documenten en hun indexen:
await client.collections.delete(collection_id)
Een document toevoegen en wachten op indexering
Eén enkele aanroep, upload_document, uploadt het bestand via de Files API en koppelt het aan de collectie:
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
Als het bestand al bestaat in de Files API, koppelt add_existing_document(collection_id, file_id) het zonder het opnieuw te uploaden.
Het toevoegen van een document maakt het niet direct doorzoekbaar. Indexering kost variabele tijd, afhankelijk van de bestandsgrootte, en een zoekopdracht die te vroeg wordt gestart, levert simpelweg minder resultaten op dan verwacht—een bug die bijzonder pijnlijk is om te diagnosticeren, omdat er geen foutmelding wordt gegenereerd. Vandaar deze wachtlus, die de status peilt totdat DOCUMENT_STATUS_PROCESSED is bereikt:
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 gereed")
return
if doc.status == collections_pb2.DOCUMENT_STATUS_FAILED:
raise RuntimeError(f"Indexering mislukt: {doc.error_message}")
await asyncio.sleep(3)
Status is een enumeratiewaarde, geen string: vergelijken met de tekst "DOCUMENT_STATUS_PROCESSED" zou nooit waar zijn en de lus zou oneindig blijven draaien. Voor een eenvoudig geval regelt upload_document(..., wait_for_indexing=True) dit wachten voor u.
Zoeken via de SDK
Zoeken retourneert dezelfde gescoorde chunks als het HTTP-eindpunt, in de lijst 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"Inhoud: {m.chunk_content[:200]}")
print("---")
Een complete end-to-end pipeline
De vorige blokken vormen samen een script dat de collectie aanmaakt, documenten uploadt, wacht op indexering, zoekt en vervolgens een respons genereert met behulp van de tool 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. De collectie aanmaken
collection = await client.collections.create(name="project-documentation")
collection_id = collection.collection_id
# 2. Documenten parallel toevoegen
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. Wachten tot alle documenten zijn geïndexeerd
await asyncio.gather(*[
wait_for_indexing(client, fid, collection_id) for fid in file_ids
])
# 4. Zoeken
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. Een respons genereren op basis van de collectie
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())
De twee asyncio.gather()-aanroepen doen al het werk. De eerste start de drie uploads tegelijk in plaats van te wachten tot elk voltooid is; de tweede bewaakt de drie indexeringstaken simultaan: de totale tijd benadert die van het langste document, in plaats van de som van allemaal. En omdat het wachten de event loop niet blokkeert, past dezelfde code direct in een FastAPI- of aiohttp-toepassing, die andere verzoeken blijft bedienen terwijl uw documenten worden geïndexeerd.
Belangrijkste punten
- De xAI Python SDK bestaat in synchrone (
Client) en asynchrone (AsyncClient) versies;awaitvereist de laatste - Beide sleutels (API en Management) worden in de client geconfigureerd
upload_documentuploadt en koppelt in één aanroep; bewaak de indexering viaget_documentofwait_for_indexing=Trueasyncio.gather()stelt u in staat om parallel te uploaden en te wachten op indexering- Genereren maakt gebruik van de collectie met de tool
collections_search, compleet met respons en citaten
Test uw kennis
Bestanden, collecties, zoeken: RAG beheerd door xAI.
1. Wat kunt u doen met de Files API?
Antwoord: Bestanden uploaden en beheren (lijst weergeven, bekijken, verwijderen) in ondersteunde formaten—de grondstof voor collecties en query’s met documenten.
2. Wat is een collectie?
Antwoord: Een set documenten die server-side door xAI wordt beheerd, met metadata en rechten—de kant-en-klare index die u doorzoekt zonder uw eigen vectorpijplijn te hoeven bouwen.
3. Welke zoekmodi zijn beschikbaar?
Antwoord: Trefwoord (exacte termen), semantisch (betekenis) en hybride (beide)—de keuze volgt uit de aard van de vragen, waarbij hybride de meeste gevallen dekt.
4. Hoe integreert RAG met genereren?
Antwoord: Via de tool voor collectiezoeken: collections_search in de xAI SDK, file_search met collectie-ID’s in de Responses API. Het model doorzoekt uw documenten tijdens het genereren en citeert zijn bronnen—het RAG-patroon zonder infrastructuur om te onderhouden.
5. Welke punten vereisen aandacht voor productie?
Antwoord: Vertrouwelijkheid van geüploade gegevens (rechten, levenscyclus), relevantie om te optimaliseren (metadata, chunking)—en de asynchrone SDK voor verwerking van grote volumes.
Beheerde RAG: u levert de documenten en vragen, xAI handelt de index af—houd controle over vertrouwelijkheid en relevantie.