Tilføj dokumenter til en samling
På denne side
Opdateret 2. november 2026. Denne lektion afspejler
xai-sdk1.21.0 og xAI-dokumentationen:await-kald kræver den asynkroneAsyncClient, indekseringsstatus sammenlignes med konstantencollections_pb2.DOCUMENT_STATUS_PROCESSED(ikke en streng), og masseimport brugerupload_document, som kombinerer begge trin i ét kald. Kilder: Samlinger via API’en · xai-sdk-python.
Hvorfor tilføjelse sker i to trin
Du forventer måske at kunne droppe en PDF direkte ind i en samling, ligesom man trækker en fil ind i en mappe. Sådan fungerer xAI-API’en ikke: Dokumentet går først gennem Files-API’en, der gemmer det og tildeler et file_id, og derefter gennem Management-API’en, der kobler dette identifikator til samlingen. To kald, to nøgler, to trin.
Denne opdeling har en direkte og nyttig konsekvens: Filen eksisterer kun én gang på lagringssiden, men kan kobles til lige så mange samlinger, som du har brug for. Den samme tekniske rapport kan fodre både produktteamets database og supportteamets uden at blive uploadet to gange, uden at bruge kvota to gange og uden risiko for uoverensstemmelser mellem to kopier.
Trin 1: Upload filen
Intet nyt her; dette er det endpoint, du har mestret siden første lektion:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Hent file_id’et fra svaret: Det er nøglen til næste trin.
Trin 2: Kobl til samlingen
Tilføjelsen sker som et POST-kald til en URL, der kombinerer de to identifikatorer (samlings-ID og fil-ID), og kræver ingen request body:
curl -X POST https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Når dette kald er accepteret, begynder xAI at indeksere indholdet. Dokumentet gennemgår derefter flere behandlingstilstande, før det faktisk er tilgængeligt til søgning.
Vent på, at indekseringen er færdig
Dette er en fælde, mange falder i ved den første pipeline: Tilføjelseskaldet returnerer succes, du følger straks op med en søgning, og samlingen svarer, at den finder ingenting. Dokumentet eksisterer, men det er ikke indekseret endnu. Den status, du skal vente på, er DOCUMENT_STATUS_PROCESSED, og SDK’et lader dig pollere det korrekt:
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"Indexing failed: {doc.error_message}")
await asyncio.sleep(3)
doc = await client.collections.get_document(file_id, collection_id)
print("Document indexed and ready for search")
asyncio.run(wait_for_indexing("file_abc123", "col_xyz789"))
Forsinkelsen afhænger direkte af størrelsen: En PDF på få sider indekseres på få sekunder, mens et dokument på 100 MB kan tage flere minutter. Til nattenlig indlæsning er denne løkke med et pause på tre sekunder tilstrækkelig; i en grænseflade, hvor brugeren uploader en fil og venter, skal du give visuel feedback i stedet for en frossen skærm.
Fjern et dokument uden at miste det
At frakoble en fil fra en samling er en separat operation fra at slette den:
curl -X DELETE \
https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Filen forsvinder fra denne samlings indeks, men forbliver tilgængelig via Files-API’en og kan kobles andre steder hen. Det er præcis, hvad du skal gøre, når et produktark bliver forældet for supporten, mens det stadig har arkivværdi: Du fjerner det fra den operationelle database uden at ødelægge dokumentet.
Udfyld en samling i bulk
Når du initialiserer en database fra en hel mappe, skal du bare skrive løkken én gang; den vil tjene dig godt i lang tid:
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):
# Trin 1 og 2 i ét kald: upload via Files API, derefter tilknyt
await client.collections.upload_document(
collection_id=collection_id,
name=file_path.name,
data=file_path.read_bytes(),
)
print(f"Added: {file_path}")
asyncio.run(populate("col_xyz789"))
Bemærk blandingen af formater i listen – PDF, Markdown og almindelig tekst sameksisterer uden problemer i samme samling, hvilket sparer dig for at standardisere dine kilder før indlæsning.
To nøgler, to områder
Denne proces bruger to adgangskoder, som du ikke må forveksle: Den almindelige API-nøgle (XAI_API_KEY) til upload i trin 1 og Management-nøglen (XAI_MANAGEMENT_API_KEY) til tilknytning i trin 2. SDK’et modtager begge ved oprettelse af klienten, og upload_document bruger dem én efter én. Sørg for, at sidstnævnte har tilladelsen AddFileToCollection: Uden den vil dit upload lykkes, men din tilføjelse vil fejle med en 403-fejl, og du vil ende med filer, der er korrekt gemt, men fraværende fra alle samlinger.
Vigtige pointer
- Tilføjelse til en samling sker i to trin: upload og derefter tilføj
- En fil kan tilhøre flere samlinger samtidigt
- Dokumentet skal nå statussen
DOCUMENT_STATUS_PROCESSED, før det kan søges i - Fjernelse af et dokument fra en samling sletter ikke den underliggende fil
- Der kræves to forskellige API-nøgler: Standard til upload, Management til samlingen