Documenten aan een collectie toevoegen
Op deze pagina
Bijgewerkt op 2 november 2026. Deze les is gebaseerd op
xai-sdk1.21.0 en de xAI-documentatie:await-aanroepen vereisen de asynchroneAsyncClient, de indexeringsstatus wordt vergeleken met de constantecollections_pb2.DOCUMENT_STATUS_PROCESSED(geen string), en bulkimport gebruiktupload_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_PROCESSEDbereiken 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