Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

De xAI Python SDK: Asynchrone bewerkingen

Les 16 van 16 Bijgewerkt op 2 november 2026 Ontwikkelaar
Op deze pagina
  1. Automatiseer uw RAG-workflows in Python
  2. Installatie en configuratie
  3. Collectiebewerkingen
  4. Een document toevoegen en wachten op indexering
  5. Zoeken via de SDK
  6. Een complete end-to-end pipeline
  7. Belangrijkste punten
  8. Test uw kennis

Bijgewerkt op 2 november 2026. Gebaseerd op xai-sdk 1.21.0-code en het officiële xAI-voorbeeld: await-aanroepen vereisen de asynchrone client AsyncClient (de Client is synchroon), geretourneerde objecten bieden collection_id, collections, matches en chunk_content, de indexeringsstatus wordt vergeleken met collections_pb2.DOCUMENT_STATUS_PROCESSED, en upload_document uploadt 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; await vereist de laatste
  • Beide sleutels (API en Management) worden in de client geconfigureerd
  • upload_document uploadt en koppelt in één aanroep; bewaak de indexering via get_document of wait_for_indexing=True
  • asyncio.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.