Lägg till dokument i en samling
På denna sida
Uppdaterat den 2 november 2026. Denna lektion speglar
xai-sdk1.21.0 och xAI:s dokumentation:await-anrop kräver den asynkronaAsyncClient, indexeringsstatus jämförs mot konstantencollections_pb2.DOCUMENT_STATUS_PROCESSED(inte en sträng), och massinmatning använderupload_document, vilket kombinerar båda stegen till ett enda anrop. Källor: Collections via the API · xai-sdk-python.
Varför tillägg sker i två steg
Du kanske förväntar dig att kunna släppa en PDF direkt i en samling, precis som att dra en fil till en mapp. Så fungerar inte xAI:s API: dokumentet går först genom Files API, som lagrar det och tilldelar ett file_id, och därefter genom Management API, som länkar detta identifierare till samlingen. Två anrop, två nycklar, två steg.
Denna uppdelning har en direkt och användbar konsekvens: filen finns bara en gång på lagringssidan, men kan länkas till hur många samlingar som helst. Samma tekniska rapport kan mata både produktteamets databas och supportteamets utan att laddas upp två gånger, utan att förbruka kvot två gånger och utan risk för avvikelser mellan två kopior.
Steg 1: Ladda upp filen
Inget nytt här, detta är slutpunkten du behärskat sedan den första lektionen:
curl -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F "[email protected]" \
-F "purpose=assistants"
Hämta file_id från svaret: det är nyckeln för nästa steg.
Steg 2: Koppla till samlingen
Tillägget sker via ett POST-anrop till en URL som kombinerar de två identifierarna, samlings-ID:t och fil-ID:t, och kräver ingen begärandekropp:
curl -X POST https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
När detta anrop har accepterats börjar xAI indexera innehållet. Dokumentet passerar sedan genom flera bearbetningsstatus innan det faktiskt är tillgängligt för sökning.
Vänta på att indexeringen slutförs
Detta är en vanlig fallgrop i den första pipeline:n: tilläggsbegäran returnerar framgång, du följer omedelbart upp med en sökning, och samlingen svarar att den inte hittar något. Dokumentet finns, men det är inte indexerat än. Statusen du ska vänta på är DOCUMENT_STATUS_PROCESSED, och SDK:t låter dig polla detta 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"))
Fördröjningen beror direkt på storleken: en PDF på några sidor indexeras på några sekunder, medan ett dokument på 100 MB kan ta flera minuter. För inmatning över natten räcker denna loop med en paus på tre sekunder; i ett gränssnitt där användaren laddar upp en fil och väntar bör du istället tillhandahålla visuell återkoppling snarare än en fryst skärm.
Ta bort ett dokument utan att förlora det
Att koppla loss en fil från en samling är en separat operation från att radera den:
curl -X DELETE \
https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Filen försvinner från denna samlings index men förblir tillgänglig via Files API och kan länkas någon annanstans. Detta är exakt vad du bör göra när ett produktblad blir föråldrat för supporten men fortfarande har arkivvärde: du tar bort det från den operativa databasen utan att förstöra dokumentet.
Fyll en samling i bulk
När du initierar en databas från en hel mapp skriver du loopen en gång; den kommer att tjäna dig väl under lång 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):
# Steg 1 och 2 i ett enda anrop: ladda upp via Files API, koppla sedan
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"))
Lägg märke till blandningen av format i listan – PDF, Markdown och vanlig text samexisterar utan problem i samma samling, vilket sparar dig från att behöva standardisera dina källor före inmatning.
Två nycklar, två omfång
Denna process använder två åtkomstidentifierare som du inte får förväxla: den vanliga API-nyckeln (XAI_API_KEY) för uppladdningen i steg 1, och Management-nyckeln (XAI_MANAGEMENT_API_KEY) för kopplingen i steg 2. SDK:t tar emot båda vid klientkapandet, och upload_document använder dem i följd. Kontrollera att den senare har behörigheten AddFileToCollection: utan den kommer din uppladdning att lyckas, men ditt tillägg misslyckas med ett 403-fel, och du kommer att ackumulera filer som är korrekt lagrade men frånvarande från alla samlingar.
Viktiga punkter
- Tillägg till en samling sker i två steg: ladda upp och sedan lägg till
- En fil kan tillhöra flera samlingar samtidigt
- Dokumentet måste nå statusen
DOCUMENT_STATUS_PROCESSEDinnan det är sökbart - Att ta bort ett dokument från en samling raderar inte den underliggande filen
- Två distinkta API-nycklar krävs: standard för uppladdning, Management för samlingen