Spring til hovedindhold
Dansk— Vælg et sprog
Menu

xAI Python SDK: Asynkrone operationer

Lektion 16 af 16 Opdateret 2. november 2026 Udvikler
På denne side
  1. Automatisér dine RAG-workflows i Python
  2. Installation og konfiguration
  3. Collection-operationer
  4. Tilføj et dokument og vent på indeksering
  5. Søgning via SDK’et
  6. En komplet end-to-end-pipeline
  7. Vigtige pointer
  8. Test din viden

Opdateret 2. november 2026. Baseret på xai-sdk 1.21.0-koden og det officielle xAI-eksempel: await-kald kræver den asynkrone klient AsyncClient (mens Client er synkron), returnerede objekter eksponerer collection_id, collections, matches og chunk_content, indekseringsstatus sammenlignes med collections_pb2.DOCUMENT_STATUS_PROCESSED, og upload_document uploader 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; await kræver sidstnævnte
  • Begge nøgler (API og Management) konfigureres i klienten
  • upload_document uploader og vedhæfter i ét kald; overvåg indeksering via get_document eller brug wait_for_indexing=True
  • asyncio.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.