Das xAI Python SDK: Asynchrone Operationen
Auf dieser Seite
Aktualisiert am 2. November 2026. Basierend auf dem Code von
xai-sdk1.21.0 und dem offiziellen xAI-Beispiel: Aufrufe mitawaiterfordern den asynchronen ClientAsyncClient(derClientist synchron). Die zurückgegebenen Objekte gebencollection_id,collections,matchesundchunk_contentaus. Der Indexierungsstatus wird mitcollections_pb2.DOCUMENT_STATUS_PROCESSEDverglichen.upload_documentlädt und bindet die Datei in einem einzigen Aufruf hoch (das vorherige Beispiel hat sie zweimal hochgeladen, einmal mit einer nicht existierenden Methode). Quellen: Collections via the API · Collections Search · xai-sdk-python.
Automatisieren Sie Ihre RAG-Arbeitsabläufe in Python
Alles, was Sie in diesem Kurs über curl aufgerufen haben, existiert auch in Python: Dokumenthochladen, Verwaltung von Collections, Suche und Generierung. Das xAI SDK bietet zwei Clients, einen synchronen (Client) und einen asynchronen (AsyncClient), mit identischen Methoden. Letzterer ist die richtige Wahl für einen RAG-Arbeitsablauf, der die meiste Zeit wartet – auf das Beenden eines Hochladens, das Indexieren eines Dokuments oder das Zurückgeben einer Suche. Asynchroner Code behandelt diese Wartezeiten parallel statt sequentiell.
Installation und Konfiguration
pip install xai-sdk
Der Client benötigt zwei Schlüssel: den Standard-API-Schlüssel für Suche und Generierung sowie den Management-API-Schlüssel für Collections.
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"),
)
Jede Anfrage hat standardmäßig ein Timeout von 27 Minuten, bevor sie abläuft, was das Hochladen eines großen PDFs abdeckt. Der Parameter timeout in Sekunden ermöglicht es Ihnen, diese Grenze für eine interaktive Anwendung zu verkürzen.
Collection-Operationen
Drei Aufrufe decken den gesamten Lebenszyklus ab. Die Erstellung gibt die ID zurück, die Sie überall sonst wieder verwenden:
collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Collection created: {collection_id}")
Das Auflisten hilft hauptsächlich dabei, eine ID wiederzufinden, die Sie nicht persistiert haben, oder den Status eines Kontos zu überprüfen, das über mehrere Projekte hinweg geteilt wird:
response = await client.collections.list()
for col in response.collections:
print(f"{col.collection_id} — {col.collection_name} ({col.documents_count} Dokumente)")
Das Löschen ist irreversibel und entfernt die Dokumente sowie deren Indizes:
await client.collections.delete(collection_id)
Ein Dokument hinzufügen und auf das Indexieren warten
Ein einziger Aufruf, upload_document, lädt die Datei über die Files API hoch und bindet sie an die Collection an:
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
Wenn die Datei bereits in der Files API existiert, bindet add_existing_document(collection_id, file_id) sie an, ohne sie erneut hochzuladen.
Das Hinzufügen eines Dokuments macht es nicht sofort abfragbar. Das Indexieren dauert eine variable Zeit, abhängig von der Dateigröße, und eine Suche, die zu früh gestartet wird, liefert einfach weniger Ergebnisse als erwartet – ein Fehler, der besonders schmerzhaft zu diagnostizieren ist, da er keine Fehlermeldung auslöst. Daher dieser Warteschleife, die den Status abfragt, bis DOCUMENT_STATUS_PROCESSED erreicht ist:
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("Dokument bereit")
return
if doc.status == collections_pb2.DOCUMENT_STATUS_FAILED:
raise RuntimeError(f"Indexierung fehlgeschlagen: {doc.error_message}")
await asyncio.sleep(3)
Der Status ist ein Aufzählungswert, kein String: Der Vergleich mit dem Text "DOCUMENT_STATUS_PROCESSED" wäre niemals wahr, und die Schleife würde ewig laufen. Für einen einfachen Fall übernimmt upload_document(..., wait_for_indexing=True) dieses Warten für Sie.
Suche über das SDK
Die Suche gibt dieselben bewerteten Chunks wie das HTTP-Endpunkt zurück, in der Liste 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("---")
Eine vollständige End-to-End-Pipeline
Die vorherigen Blöcke setzen sich zu einem Skript zusammen, das die Collection erstellt, Dokumente hochlädt, auf das Indexieren wartet, sucht und dann eine Antwort generiert, indem es das Werkzeug collections_search verwendet:
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. Collection erstellen
collection = await client.collections.create(name="project-documentation")
collection_id = collection.collection_id
# 2. Dokumente parallel hinzufügen
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. Auf das Indexieren aller Dokumente warten
await asyncio.gather(*[
wait_for_indexing(client, fid, collection_id) for fid in file_ids
])
# 4. Suche
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. Eine Antwort basierend auf der Collection generieren
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())
Die beiden asyncio.gather()-Aufrufe erledigen die gesamte Arbeit. Der erste startet die drei Hochladungen gleichzeitig, anstatt auf jede einzeln zu warten; der zweite überwacht die drei Indexierungsaufgaben gleichzeitig: Die Gesamtzeit nähert sich der des längsten Dokuments an, statt der Summe aller. Und da das Warten den Event-Loop nicht blockiert, passt derselbe Code direkt in eine FastAPI- oder aiohttp-Anwendung, die andere Anfragen weiter bedient, während Ihre Dokumente indiziert werden.
Kernaussagen
- Das xAI Python SDK existiert in synchroner (
Client) und asynchroner (AsyncClient) Version;awaiterfordert letztere - Beide Schlüssel (API und Management) werden im Client konfiguriert
upload_documentlädt und bindet in einem einzigen Aufruf; überwachen Sie das Indexieren überget_documentoderwait_for_indexing=Trueasyncio.gather()ermöglicht es Ihnen, das Hochladen und das Warten auf das Indexieren parallel durchzuführen- Die Generierung nutzt die Collection mit dem Werkzeug
collections_search, komplett mit Antwort und Zitaten
Testen Sie Ihr Wissen
Dateien, Collections, Suche: RAG, verwaltet von xAI.
1. Was ermöglicht die Files API?
Antwort: Hochladen und Verwalten von Dateien (Listen, Anzeigen, Löschen) in unterstützten Formaten – das Rohmaterial für Collections und Abfragen mit Dokumenten.
2. Was ist eine Collection?
Antwort: Eine Menge von Dokumenten, die serverseitig von xAI verwaltet wird, mit Metadaten und Berechtigungen – der sofort einsatzbereite Index, den Sie abfragen, ohne Ihren eigenen Vektor-Pipeline zu bauen.
3. Welche Suchmodi sind verfügbar?
Antwort: Keyword (exakte Begriffe), semantisch (Bedeutung) und hybrid (beides) – die Wahl folgt der Natur der Fragen, wobei hybrid die meisten Fälle abdeckt.
4. Wie integriert sich RAG in die Generierung?
Antwort: Über das Collection-Such-Werkzeug: collections_search im xAI SDK, file_search mit Collection-IDs in der Responses API. Das Modell fragt Ihre Dokumente während der Generierung ab und zitiert seine Quellen – das RAG-Muster ohne Infrastruktur zum Unterhalten.
5. Welche Punkte erfordern Aufmerksamkeit für die Produktion?
Antwort: Vertraulichkeit der hochgeladenen Daten (Berechtigungen, Lebenszyklus), Relevanz zur Optimierung (Metadaten, Chunking) – und das asynchrone SDK für Hochvolumenverarbeitung.
Gemanaged RAG: Sie bringen die Dokumente und Fragen, xAI übernimmt den Index – behalten Sie die Kontrolle über Vertraulichkeit und Relevanz.