Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Documenten aan een collectie toevoegen

Les 6 van 16 Bijgewerkt op 2 november 2026 Ontwikkelaar
Op deze pagina
  1. Waarom toevoegen in twee stappen gebeurt
  2. Stap 1: Het bestand uploaden
  3. Stap 2: Koppelen aan de collectie
  4. Wachten tot de indexering is voltooid
  5. Een document verwijderen zonder het te verliezen
  6. Een collectie in bulk vullen
  7. Twee sleutels, twee reikwijdtes
  8. Belangrijkste punten

Bijgewerkt op 2 november 2026. Deze les is gebaseerd op xai-sdk 1.21.0 en de xAI-documentatie: await-aanroepen vereisen de asynchrone AsyncClient, de indexeringsstatus wordt vergeleken met de constante collections_pb2.DOCUMENT_STATUS_PROCESSED (geen string), en bulkimport gebruikt upload_document, wat beide stappen in één aanroep combineert. Bronnen: Collections via the API · xai-sdk-python.

Waarom toevoegen in twee stappen gebeurt

U zou kunnen verwachten dat u een PDF direct in een collectie kunt plaatsen, alsof u een bestand in een map sleept. Zo werkt de xAI-API echter niet: het document gaat eerst langs de Files API, die het opslaat en een file_id toekent, en vervolgens langs de Management API, die deze identifier aan de collectie koppelt. Twee aanroepen, twee sleutels, twee stappen.

Deze scheiding heeft een direct en nuttig gevolg: het bestand bestaat slechts één keer op de opslag, maar kan aan zoveel collecties worden gekoppeld als nodig is. Hetzelfde technische rapport kan dienen als bron voor de database van het productteam én die van het supportteam, zonder dat het twee keer hoeft te worden geüpload, zonder dat het quota twee keer verbruikt en zonder risico op divergentie tussen twee kopieën.

Stap 1: Het bestand uploaden

Hier is niets nieuws; dit is het eindpunt dat u sinds de eerste les onder de knie heeft:

curl -X POST https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY" \
 -F "[email protected]" \
  -F "purpose=assistants"

Haal de file_id uit het antwoord: dit is de sleutel voor de volgende stap.

Stap 2: Koppelen aan de collectie

Toevoegen gebeurt via een POST-request naar een URL die beide identifiers combineert: de collectie-ID en de bestands-ID. Er is geen request body nodig:

curl -X POST https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"

Zodra deze aanroep is geaccepteerd, start xAI met het indexeren van de inhoud. Het document doorloopt vervolgens verschillende verwerkingsstatussen voordat het daadwerkelijk beschikbaar is voor zoekopdrachten.

Wachten tot de indexering is voltooid

Dit is een veelgemaakte fout in de eerste pipeline: het toevoegverzoek retourneert succes, u voert direct daarna een zoekopdracht uit, en de collectie meldt dat er niets wordt gevonden. Het document bestaat wel, maar is nog niet geïndexeerd. De status waarop u moet wachten is DOCUMENT_STATUS_PROCESSED. De SDK stelt u in staat om hier correct op te poll-en:

import asyncio
import os

from xai_sdk import AsyncClient
from xai_sdk.proto import collections_pb2

client = AsyncClient(
    api_key=os.getenv("XAI_API_KEY"),
    management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
)


async def wait_for_indexing(file_id, collection_id):
    doc = await client.collections.get_document(file_id, collection_id)
    while doc.status != collections_pb2.DOCUMENT_STATUS_PROCESSED:
        if doc.status == collections_pb2.DOCUMENT_STATUS_FAILED:
            raise RuntimeError(f"Indexering mislukt: {doc.error_message}")
        await asyncio.sleep(3)
        doc = await client.collections.get_document(file_id, collection_id)
    print("Document geïndexeerd en klaar voor zoeken")


asyncio.run(wait_for_indexing("file_abc123", "col_xyz789"))

De vertraging hangt direct af van de grootte: een PDF van enkele pagina’s is binnen enkele seconden geïndexeerd, terwijl een document van 100 MB enkele minuten kan duren. Voor nachtelijke import is deze lus met een pauze van drie seconden voldoende; in een interface waar de gebruiker een bestand uploadt en wacht, biedt u beter visuele feedback in plaats van een bevroren scherm.

Een document verwijderen zonder het te verliezen

Het loskoppelen van een bestand van een collectie is een andere bewerking dan het verwijderen ervan:

curl -X DELETE \
  https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"

Het bestand verdwijnt uit de index van deze collectie, maar blijft beschikbaar via de Files API en kan elders worden gekoppeld. Dit is precies wat u moet doen wanneer een productblad verouderd is voor support, maar nog wel archiefwaarde heeft: u verwijdert het uit de operationele database zonder het document zelf te vernietigen.

Een collectie in bulk vullen

Wanneer u een database initialiseert vanuit een volledige map, schrijft u de lus één keer; deze zal u lang van dienst zijn:

import asyncio
import os
from pathlib import Path

from xai_sdk import AsyncClient

client = AsyncClient(
    api_key=os.getenv("XAI_API_KEY"),
    management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
)

files = [
    "docs/guide-installation.pdf",
    "docs/reference-api.pdf",
    "docs/faq.md",
    "docs/changelog.txt",
]


async def populate(collection_id):
    for file_path in map(Path, files):
        # Stap 1 en 2 in één aanroep: uploaden via Files API, vervolgens koppelen
        await client.collections.upload_document(
            collection_id=collection_id,
            name=file_path.name,
            data=file_path.read_bytes(),
        )
        print(f"Toegevoegd: {file_path}")


asyncio.run(populate("col_xyz789"))

Merk op dat de lijst verschillende formaten bevat: PDF, Markdown en platte tekst coëxisteren probleemloos in dezelfde collectie. Dit bespaart u de moeite om uw bronnen vóór import te standaardiseren.

Twee sleutels, twee reikwijdtes

Bij dit proces worden twee toegangsidentifiers gebruikt die u niet mag verwarren: de standaard API-sleutel (XAI_API_KEY) voor de upload in stap 1, en de Management-sleutel (XAI_MANAGEMENT_API_KEY) voor de koppeling in stap 2. De SDK ontvangt beide bij het aanmaken van de client, en upload_document gebruikt ze achter elkaar. Controleer of deze laatste de machtiging AddFileToCollection heeft: zonder deze machtiging slaagt uw upload wel, maar faalt uw toevoeging met een 403-fout. Het resultaat is dat u bestanden correct opslaat, maar ze in geen enkele collectie terugvindt.

Belangrijkste punten

  • Toevoegen aan een collectie gebeurt in twee stappen: uploaden en vervolgens toevoegen
  • Een bestand kan gelijktijdig tot meerdere collecties behoren
  • Het document moet de status DOCUMENT_STATUS_PROCESSED bereiken voordat het doorzoekbaar is
  • Het verwijderen van een document uit een collectie verwijdert het onderliggende bestand niet
  • Er zijn twee verschillende API-sleutels vereist: standaard voor uploaden, Management voor de collectie