xAI Python SDK: Asynkrone operationer
På denne side
Opdateret 2. november 2026. Baseret på
xai-sdk1.21.0-koden og det officielle xAI-eksempel:await-kald kræver den asynkrone klientAsyncClient(mensClienter synkron), returnerede objekter eksponerercollection_id,collections,matchesogchunk_content, indekseringsstatus sammenlignes medcollections_pb2.DOCUMENT_STATUS_PROCESSED, ogupload_documentuploader og vedhæfter filen i ét enkelt kald (det tidligere eksempel uploadede den to gange, herunder ved brug af en ikke-eksisterende metode). Kilder: Collections via API’en · Collections Search · xai-sdk-python.
Automatisér dine RAG-workflows i Python
Alt det, du har kaldt via curl gennem dette kursus – dokumentupload, collections-håndtering, søgning og generering – findes i Python. xAI SDK’et tilbyder to klienter: en synkron (Client) og en asynkron (AsyncClient), begge med identiske metoder. Sidstnævnte er det rigtige valg til et RAG-workflow, som bruger det meste af sin tid på at vente – på at et upload bliver færdigt, at et dokument bliver indekseret, eller at en søgning returnerer resultater. Asynkron kode håndterer disse ventetider parallelt i stedet for sekventielt.
Installation og konfiguration
pip install xai-sdk
Klienten kræver to nøgler: den standard API-nøgle til søgning og generering samt Management API-nøglen til 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"),
)
Hver anmodning har som standard en timeout på 27 minutter, før den udløber, hvilket dækker upload af store PDF-filer. Parameteren timeout (i sekunder) giver dig mulighed for at stramme denne grænse for interaktive applikationer.
Collection-operationer
Tre kald dækker hele livscyklussen. Oprettelse returnerer det ID, du vil genbruge overalt andet:
collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Collection oprettet: {collection_id}")
Listning hjælper primært med at genfinde et ID, du ikke har gemt, eller til at tjekke status for en konto, der deles på tværs af flere projekter:
response = await client.collections.list()
for col in response.collections:
print(f"{col.collection_id} — {col.collection_name} ({col.documents_count} dokumenter)")
Sletning er irreversibel og fjerner både dokumenterne og deres indeks:
await client.collections.delete(collection_id)
Tilføj et dokument og vent på indeksering
Et enkelt kald, upload_document, uploader filen via Files API’en og vedhæfter den til collection’en:
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
Hvis filen allerede findes i Files API’en, vil add_existing_document(collection_id, file_id) vedhæfte den uden at uploade den igen.
Når du tilføjer et dokument, er det ikke straks klar til søgning. Indeksering tager variabel tid afhængigt af filstørrelsen, og en søgning, der startes for tidligt, returnerer blot færre resultater end forventet – en fejl, der er særligt smertefuld at diagnosticere, da den ikke udløser nogen fejlmeddelelse. Derfor denne venteløkke, der poller status, indtil DOCUMENT_STATUS_PROCESSED er nået:
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 klar")
return
if doc.status == collections_pb2.DOCUMENT_STATUS_FAILED:
raise RuntimeError(f"Indeksering mislykkedes: {doc.error_message}")
await asyncio.sleep(3)
Status er en enumerationsværdi, ikke en streng: Hvis du sammenligner den med teksten "DOCUMENT_STATUS_PROCESSED", vil betingelsen aldrig blive sand, og løkken vil køre uendeligt. I simple tilfælde kan upload_document(..., wait_for_indexing=True) håndtere denne ventetid for dig.
Søgning via SDK’et
Søgning returnerer de samme scorede chunks som HTTP-endpointet, i listen matches:
results = await client.collections.search(
query="Procedure for ordregodkendelse",
collection_ids=[collection_id],
)
for m in results.matches:
print(f"Score: {m.score:.2f}")
print(f"Indhold: {m.chunk_content[:200]}")
print("---")
En komplet end-to-end-pipeline
De tidligere blokke samles til et script, der opretter collection’en, uploader dokumenter, venter på indeksering, søger og derefter genererer et svar ved hjælp af værktøjet 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. Opret collection'en
collection = await client.collections.create(name="projekt-dokumentation")
collection_id = collection.collection_id
# 2. Tilføj dokumenter parallelt
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. Vent på, at alle dokumenter bliver indekseret
await asyncio.gather(*[
wait_for_indexing(client, fid, collection_id) for fid in file_ids
])
# 4. Søg
results = await client.collections.search(
query="Hvordan deployer jeg til produktion?",
collection_ids=[collection_id],
)
for m in results.matches:
print(f"[{m.score:.2f}] {m.chunk_content[:150]}")
# 5. Generér et svar baseret på collection'en
chat = client.chat.create(
model="grok-4.7",
tools=[collections_search(collection_ids=[collection_id])],
)
chat.append(user("Forklar deploymentsproceduren og citér dine kilder."))
response = await chat.sample()
print(response.content)
print(response.citations)
asyncio.run(rag_pipeline())
De to asyncio.gather()-kald udfører alt arbejdet. Det første lancerer de tre uploads samtidigt i stedet for at vente på, at hvert enkelt bliver færdigt; det andet overvåger de tre indekseringsjobs samtidig: Den samlede tid nærmer sig varigheden for det længstvarende dokument i stedet for summen af alle. Og da ventetiden ikke blokerer event loop’en, passer den samme kode direkte ind i en FastAPI- eller aiohttp-applikation, som fortsætter med at betjene andre anmodninger, mens dine dokumenter bliver indekseret.
Vigtige pointer
- xAI Python SDK findes i både en synkron (
Client) og en asynkron (AsyncClient) version;awaitkræver sidstnævnte - Begge nøgler (API og Management) konfigureres i klienten
upload_documentuploader og vedhæfter i ét kald; overvåg indeksering viaget_documenteller brugwait_for_indexing=Trueasyncio.gather()giver dig mulighed for at uploade og vente på indeksering parallelt- Generering udnytter collection’en med værktøjet
collections_search, komplet med svar og citationer
Test din viden
Filer, collections, søgning: RAG håndteret af xAI.
1. Hvad giver Files API'en dig mulighed for at gøre?
Svar: Uploade og administrere filer (liste, vise, slette) i understøttede formater – råmaterialet til collections og forespørgsler med dokumenter.
2. Hvad er en collection?
Svar: Et sæt dokumenter administreret server-side af xAI, med metadata og tilladelser – det klar-til-brug-indeks, du spørger til uden at skulle bygge din egen vektor-pipeline.
3. Hvilke søgetilstande er tilgængelige?
Svar: Nøgleord (nøjagtige termer), semantisk (betydning) og hybrid (begge dele) – valget afhænger af spørgsmålenes natur, hvor hybrid dækker de fleste tilfælde.
4. Hvordan integreres RAG med generering?
Svar: Via værktøjet til collections-søgning: collections_search i xAI SDK’et eller file_search med collection-ID’er i Responses API’en. Modellen spørger dine dokumenter under genereringen og citérer sine kilder – RAG-mønsteret uden infrastruktur, der skal vedligeholdes.
5. Hvilke punkter kræver særlig opmærksomhed i produktion?
Svar: Fortrolighed for uploadede data (tilladelser, livscyklus), relevans til optimering (metadata, chunking) – og det asynkrone SDK til behandling af store volumener.
Administreret RAG: Du bringer dokumenterne og spørgsmålene, xAI håndterer indekset – behold kontrollen over fortrolighed og relevans.