Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Dokumente einer Sammlung hinzufügen

Lektion 6 von 16 Aktualisiert am 2. November 2026 Entwickler
Auf dieser Seite
  1. Warum der Vorgang in zwei Schritten erfolgt
  2. Schritt 1: Datei hochladen
  3. Schritt 2: An die Sammlung anhängen
  4. Auf die Fertigstellung der Indexierung warten
  5. Ein Dokument entfernen, ohne es zu löschen
  6. Eine Sammlung im Batch füllen
  7. Zwei Schlüssel, zwei Bereiche
  8. Wichtige Erkenntnisse

Aktualisiert am 2. November 2026. Diese Lektion basiert auf xai-sdk 1.21.0 und der xAI-Dokumentation: Aufrufe erfordern den asynchronen AsyncClient, der Indexierungsstatus wird mit der Konstante collections_pb2.DOCUMENT_STATUS_PROCESSED (und nicht mit einem String) verglichen, und die Masseneingabe nutzt upload_document, die beide Schritte in einem einzigen Aufruf kombiniert. Quellen: Sammlungen über die API · xai-sdk-python.

Warum der Vorgang in zwei Schritten erfolgt

Man könnte erwarten, eine PDF-Datei direkt in eine Sammlung zu legen, ähnlich wie man eine Datei in einen Ordner zieht. So funktioniert die xAI-API jedoch nicht: Das Dokument durchläuft zunächst die Files-API, die es speichert und eine file_id zuweist, und anschließend die Management-API, die diesen Identifier mit der Sammlung verknüpft. Zwei Aufrufe, zwei Schlüssel, zwei Schritte.

Diese Trennung hat eine direkte und nützliche Konsequenz: Die Datei existiert auf der Speicherseite nur einmal, kann aber mit so vielen Sammlungen verknüpft werden, wie benötigt. Der gleiche technische Bericht kann die Datenbank des Produktteams und die des Support-Teams versorgen, ohne zweimal hochgeladen zu werden, ohne den Kontingentverbrauch zu verdoppeln und ohne das Risiko einer Divergenz zwischen zwei Kopien.

Schritt 1: Datei hochladen

Hier gibt es nichts Neues; dies ist der Endpunkt, den Sie seit der ersten Lektion beherrschen:

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

Rufen Sie die file_id aus der Antwort ab: Sie ist der Schlüssel für den nächsten Schritt.

Schritt 2: An die Sammlung anhängen

Das Hinzufügen erfolgt als POST-Anfrage an eine URL, die die beiden Identifier, die Sammlungs-ID und die Datei-ID kombiniert, und erfordert keinen Anforderungskörper:

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

Sobald dieser Aufruf akzeptiert wurde, beginnt xAI mit der Indexierung des Inhalts. Das Dokument durchläuft mehrere Verarbeitungszustände, bevor es tatsächlich für die Suche verfügbar ist.

Auf die Fertigstellung der Indexierung warten

Dies ist ein häufiger Fehler im ersten Pipeline-Schritt: Die Hinzufüge-Anfrage gibt Erfolg zurück, Sie folgen sofort mit einer Suche, und die Sammlung antwortet, dass sie nichts findet. Das Dokument existiert, ist aber noch nicht indiziert. Der zu wartende Status ist DOCUMENT_STATUS_PROCESSED, und das SDK ermöglicht es Ihnen, diesen korrekt abzufragen:

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("Dokument indiziert und bereit für die Suche")


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

Die Verzögerung hängt direkt von der Größe ab: Ein PDF mit wenigen Seiten wird in wenigen Sekunden indiziert, während ein 100 MB großes Dokument mehrere Minuten dauern kann. Für eine nächtliche Eingabe ist dieser Schleifenlauf mit einer dreisekündigen Pause ausreichend; in einer Benutzeroberfläche, in der ein Benutzer eine Datei hochlädt und wartet, sollten Sie visuelles Feedback bereitstellen, anstatt einen eingefrorenen Bildschirm anzuzeigen.

Ein Dokument entfernen, ohne es zu löschen

Das Trennen einer Datei von einer Sammlung ist eine separate Operation von deren Löschen:

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

Die Datei verschwindet aus dem Index dieser Sammlung, bleibt aber über die Files-API verfügbar und kann an anderer Stelle verknüpft werden. Genau das sollten Sie tun, wenn ein Produktdatenblatt für den Support veraltet wird, während sein Archivwert erhalten bleibt: Sie entfernen es aus der operativen Datenbank, ohne das Dokument zu zerstören.

Eine Sammlung im Batch füllen

Wenn eine Datenbank aus einem gesamten Ordner initialisiert wird, schreiben Sie den Schleifenlauf einmal; er wird Sie für eine lange Zeit gut bedienen:

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):
        # Schritte 1 und 2 in einem einzigen Aufruf: Upload über die Files-API, dann Anhängen
        await client.collections.upload_document(
            collection_id=collection_id,
            name=file_path.name,
            data=file_path.read_bytes(),
        )
        print(f"Hinzugefügt: {file_path}")


asyncio.run(populate("col_xyz789"))

Beachten Sie die Mischung der Formate in der Liste – PDF, Markdown und reiner Text koexistieren problemlos in derselben Sammlung, was Sie davor bewahrt, Ihre Quellen vor der Eingabe zu standardisieren.

Zwei Schlüssel, zwei Bereiche

Dieser Prozess verwendet zwei Zugangs-Identifikatoren, die Sie nicht verwechseln sollten: den Standard-API-Schlüssel (XAI_API_KEY) für den Upload im Schritt 1 und den Management-Schlüssel (XAI_MANAGEMENT_API_KEY) für die Anhängung im Schritt 2. Das SDK erhält beide bei der Client-Erstellung, und upload_document nutzt sie nacheinander. Stellen Sie sicher, dass der letztere die Berechtigung AddFileToCollection hat: Ohne diese wird Ihr Upload erfolgreich sein, Ihre Anhängung wird mit einem 403-Fehler fehlschlagen, und Sie werden Dateien ansammeln, die korrekt gespeichert, aber in keiner Sammlung vorhanden sind.

Wichtige Erkenntnisse

  • Das Hinzufügen zu einer Sammlung erfolgt in zwei Schritten: Upload, dann Anhängen
  • Eine Datei kann gleichzeitig mehreren Sammlungen angehören
  • Das Dokument muss den Status DOCUMENT_STATUS_PROCESSED erreichen, bevor es durchsuchbar ist
  • Das Entfernen eines Dokuments aus einer Sammlung löscht das zugrundeliegende Dokument nicht
  • Zwei unterschiedliche API-Schlüssel sind erforderlich: Standard für den Upload, Management für die Sammlung