Ajouter des documents a une collection

Un processus en deux etapes

L’ajout d’un document a une collection suit un processus sequentiel. Vous ne pouvez pas uploader directement dans une collection. Il faut d’abord uploader le fichier via la Files API, puis l’ajouter a la collection via la Management API.

Cette separation a un avantage concret : un meme fichier peut appartenir a plusieurs collections sans duplication.

Etape 1 : uploader le fichier

Utilisez l’endpoint standard de la Files API :

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

Notez le file_id retourne dans la reponse.

Etape 2 : ajouter a la collection

Avec le file_id obtenu, ajoutez le fichier a votre collection :

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

A ce stade, xAI indexe le contenu du fichier. Le document passe par plusieurs etats de traitement avant d’etre disponible pour la recherche.

Suivre le traitement

Apres l’ajout, le document n’est pas immediatement recherchable. Il doit etre traite et indexe. Vous pouvez verifier son statut :

import asyncio
from xai_sdk import Client

client = Client(
    api_key="votre_cle_api",
    management_api_key="votre_cle_management"
)

response = await client.collections.get_document(
    file_id, collection_id
)

while response.status != "DOCUMENT_STATUS_PROCESSED":
    await asyncio.sleep(3)
    response = await client.collections.get_document(
        file_id, collection_id
    )

print("Document indexe et pret pour la recherche")

Le temps de traitement depend de la taille du fichier. Un PDF de quelques pages est indexe en quelques secondes ; un document de 100 MB peut prendre plusieurs minutes.

Supprimer un document d’une collection

Pour retirer un fichier d’une collection sans le supprimer de la Files API :

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

Le fichier reste disponible via la Files API et peut etre ajoute a d’autres collections.

Automatiser l’ajout en masse

Pour alimenter une collection avec plusieurs fichiers, automatisez le processus :

import os

fichiers = [
    "docs/guide-installation.pdf",
    "docs/reference-api.pdf",
    "docs/faq.md",
    "docs/changelog.txt"
]

for chemin in fichiers:
    # Etape 1 : upload
    with open(chemin, "rb") as f:
        upload = await client.files.create(
            file=f, purpose="assistants"
        )

    # Etape 2 : ajout a la collection
    await client.collections.upload_document(
        collection_id=collection_id,
        name=os.path.basename(chemin),
        data=open(chemin, "rb").read()
    )

    print(f"Ajoute : {chemin}")

Gestion des deux cles API

Ce processus en deux etapes utilise deux cles differentes :

• Etape 1 (upload) : cle API standard (XAI_API_KEY)
• Etape 2 (ajout collection) : cle Management API (XAI_MANAGEMENT_API_KEY)

Assurez-vous que votre cle Management API dispose de la permission AddFileToCollection. Sans cette permission, l’ajout echouera avec une erreur 403.

Points cles a retenir

• L’ajout a une collection se fait en deux etapes : upload puis ajout
• Un fichier peut appartenir a plusieurs collections simultanement
• Le document doit atteindre le statut DOCUMENT_STATUS_PROCESSED avant d’etre recherchable
• La suppression d’un document d’une collection ne supprime pas le fichier sous-jacent
• Deux cles API distinctes sont necessaires : standard pour l’upload, Management pour la collection