Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Tilføj dokumenter til en samling

Lektion 6 af 16 Opdateret 2. november 2026 Udvikler
På denne side
  1. Hvorfor tilføjelse sker i to trin
  2. Trin 1: Upload filen
  3. Trin 2: Kobl til samlingen
  4. Vent på, at indekseringen er færdig
  5. Fjern et dokument uden at miste det
  6. Udfyld en samling i bulk
  7. To nøgler, to områder
  8. Vigtige pointer

Opdateret 2. november 2026. Denne lektion afspejler xai-sdk 1.21.0 og xAI-dokumentationen: await-kald kræver den asynkrone AsyncClient, indekseringsstatus sammenlignes med konstanten collections_pb2.DOCUMENT_STATUS_PROCESSED (ikke en streng), og masseimport bruger upload_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