xAI Python SDK: Asynkrona operationer
På denna sida
Uppdaterad 2 november 2026. Baserat på
xai-sdk1.21.0-koden och det officiella xAI-exemplet:await-anrop kräver den asynkrona klientenAsyncClient(medanClientär synkron), returnerade objekt exponerarcollection_id,collections,matchesochchunk_content, indexeringsstatus jämförs motcollections_pb2.DOCUMENT_STATUS_PROCESSED, ochupload_documentladdar upp och bifogar filen i ett enda anrop (det tidigare exemplet laddade upp den två gånger, varav en gång med en metod som inte finns). Källor: Collections via the API · Collections Search · xai-sdk-python.
Automatisera dina RAG-arbetsflöden i Python
Allt du har anropat via curl under denna kurs finns tillgängligt i Python: dokumentuppladdning, hantering av samlingar, sökning och generering. xAI SDK erbjuder två klienter, en synkron (Client) och en asynkron (AsyncClient), med identiska metoder. Den senare är det rätta valet för ett RAG-arbetsflöde, som tillbringar mest tid med att vänta – på att en uppladdning ska slutföras, att ett dokument ska indexeras eller att en sökning ska returnera resultat. Asynkron kod hanterar dessa väntetider parallellt istället för sekventiellt.
Installation och konfiguration
pip install xai-sdk
Klienten kräver två nycklar: den vanliga API-nyckeln för sökning och generering, samt Management API-nyckeln för samlingar.
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"),
)
Varje begäran har som standard en tidsgräns på 27 minuter innan den löper ut, vilket täcker uppladdning av stora PDF-filer. Parametern timeout, angiven i sekunder, låter dig skärpa denna gräns för interaktiva applikationer.
Operationer för samlingar
Tre anrop täcker hela livscykeln. Skapande returnerar det ID som du återanvänder överallt annars:
collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Collection created: {collection_id}")
Listning hjälper främst till att återställa ett ID som du inte har sparat, eller för att kontrollera status för ett konto som delas mellan flera projekt:
response = await client.collections.list()
for col in response.collections:
print(f"{col.collection_id} — {col.collection_name} ({col.documents_count} documents)")
Radering är oåterkallelig och tar bort både dokumenten och deras index:
await client.collections.delete(collection_id)
Lägg till ett dokument och vänta på indexering
Ett enda anrop, upload_document, laddar upp filen via Files API och bifogar den till samlingen:
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
Om filen redan finns i Files API kan add_existing_document(collection_id, file_id) bifoga den utan att ladda upp den igen.
Att lägga till ett dokument gör det inte omedelbart sökbart. Indexering tar varierande tid beroende på filstorlek, och en sökning som startas för tidigt returnerar helt enkelt färre resultat än förväntat – en bugg som är särskilt smärtsam att felsöka eftersom den inte kastar något felmeddelande. Därför denna vänteslinga, som pollar status tills DOCUMENT_STATUS_PROCESSED nås:
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)
Status är ett enumerationsvärde, inte en sträng: att jämföra det med texten "DOCUMENT_STATUS_PROCESSED" skulle aldrig bli sant, och slingan skulle köras för evigt. För enkla fall hanterar upload_document(..., wait_for_indexing=True) denna väntan åt dig.
Sökning från SDK
Sökning returnerar samma poängsatta textbitar som HTTP-slutpunkten, i listan 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("---")
En komplett end-to-end-pipeline
De tidigare blocken sätts ihop till ett skript som skapar samlingen, laddar upp dokument, väntar på indexering, söker och genererar sedan ett svar med hjälp av verktyget 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. Skapa samlingen
collection = await client.collections.create(name="project-documentation")
collection_id = collection.collection_id
# 2. Lägg till dokument parallellt
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. Vänta på att alla dokument ska indexeras
await asyncio.gather(*[
wait_for_indexing(client, fid, collection_id) for fid in file_ids
])
# 4. Sök
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. Generera ett svar baserat på samlingen
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 två asyncio.gather()-anropen utför allt arbete. Det första startar de tre uppladdningarna samtidigt istället för att vänta på att var och en ska slutföras; det andra övervakar de tre indexeringsjobben simultant: den totala tiden närmar sig tiden för det längsta dokumentet, snarare än summan av alla. Och eftersom väntan inte blockerar händelseslingan passar samma kod direkt in i en FastAPI- eller aiohttp-applikation, som fortsätter betjäna andra begäranden medan dina dokument indexeras.
Viktiga punkter
- xAI Python SDK finns i synkrona (
Client) och asynkrona (AsyncClient) versioner;awaitkräver den senare - Båda nycklarna (API och Management) konfigureras i klienten
upload_documentladdar upp och bifogar i ett anrop; övervaka indexering viaget_documentellerwait_for_indexing=Trueasyncio.gather()låter dig ladda upp och vänta på indexering parallellt- Generering utnyttjar samlingen med verktyget
collections_search, komplett med svar och källhänvisningar
Testa dina kunskaper
Filer, samlingar, sökning: RAG hanterat av xAI.
1. Vad låter Files API dig göra?
Svar: Ladda upp och hantera filer (lista, visa, radera) i format som stöds – råmaterialet för samlingar och frågor med dokument.
2. Vad är en samling?
Svar: En uppsättning dokument som hanteras server-side av xAI, med metadata och behörigheter – det färdiga indexet du frågar utan att behöva bygga din egen vektorpipeline.
3. Vilka söklägen finns tillgängliga?
Svar: Nyckelord (exakta termer), semantisk (betydelse) och hybrid (båda) – valet följer frågornas natur, där hybrid täcker de flesta fall.
4. Hur integreras RAG med generering?
Svar: Via verktyget för samlingssökning: collections_search i xAI SDK, file_search med samlings-ID:n i Responses API. Modellen frågar dina dokument under genereringen och citerar sina källor – RAG-mönstret utan infrastruktur att underhålla.
5. Vilka punkter kräver uppmärksamhet för produktion?
Svar: Konfidentialitet för uppladdad data (behörigheter, livscykel), relevans att optimera (metadata, chunking) – och den asynkrona SDK:n för bearbetning av stora volymer.
Hanterad RAG: du tillhandahåller dokument och frågor, xAI hanterar indexet – behåll kontrollen över konfidentialitet och relevans.