Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Ajouter des documents à une collection

Lezione 6 di 16 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Pourquoi l’ajout se fait en deux étapes
  2. Étape 1 : Télécharger le fichier
  3. Étape 2 : Attacher à la collection
  4. Attendre la fin de l’indexation
  5. Supprimer un document sans le perdre
  6. Peupler une collection en masse
  7. Deux clés, deux périmètres
  8. Punti chiave

Mis à jour le 2 novembre 2026. Cette leçon reflète la version xai-sdk 1.21.0 et la documentation xAI : les appels await nécessitent le client asynchrone AsyncClient, le statut d’indexation se compare à la constante collections_pb2.DOCUMENT_STATUS_PROCESSED (et non à une chaîne), et l’ingestion en masse utilise upload_document, qui combine les deux étapes en un seul appel. Sources : Collections via l’API · xai-sdk-python.

Pourquoi l’ajout se fait en deux étapes

Tu t’attends peut-être à pouvoir déposer directement un PDF dans une collection, comme on glisse un fichier dans un dossier. Ce n’est pas ainsi que fonctionne l’API xAI : le document passe d’abord par l’API Files, qui le stocke et lui attribue un file_id, puis par l’API Management, qui lie cet identifiant à la collection. Deux appels, deux clés, deux étapes.

Cette séparation a une conséquence directe et utile : le fichier n’existe qu’une seule fois côté stockage, mais peut être lié à autant de collections que nécessaire. Le même rapport technique peut alimenter la base de données de l’équipe produit et celle de l’équipe support sans être téléchargé deux fois, sans consommer deux fois le quota et sans risquer de divergence entre deux copies.

Étape 1 : Télécharger le fichier

Rien de nouveau ici, c’est le point de terminaison que tu maîtrises depuis la première leçon :

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

Récupère le file_id dans la réponse : c’est la clé pour l’étape suivante.

Étape 2 : Attacher à la collection

L’ajout prend la forme d’un POST vers une URL combinant les deux identifiants, l’ID de la collection et l’ID du fichier, et ne nécessite aucun corps de requête :

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

Une fois cet appel accepté, xAI commence l’indexation du contenu. Le document traverse alors plusieurs états de traitement avant d’être réellement disponible pour la recherche.

Attendre la fin de l’indexation

C’est un piège courant dans le premier pipeline : la requête d’ajout renvoie un succès, tu enchaînes immédiatement avec une recherche, et la collection répond qu’elle ne trouve rien. Le document existe, mais il n’est pas encore indexé. Le statut à attendre est DOCUMENT_STATUS_PROCESSED, et le SDK te permet de le surveiller correctement :

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"))

Le délai dépend directement de la taille : un PDF de quelques pages s’indexe en quelques secondes, tandis qu’un document de 100 Mo peut prendre plusieurs minutes. Pour une ingestion nocturne, cette boucle avec une pause de trois secondes suffit ; dans une interface où l’utilisateur télécharge un fichier et attend, prévois un retour visuel plutôt qu’un écran figé.

Supprimer un document sans le perdre

Détacher un fichier d’une collection est une opération distincte de sa suppression :

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

Le fichier disparaît de l’index de cette collection mais reste disponible via l’API Files, et peut être lié ailleurs. C’est exactement ce que tu dois faire lorsqu’une fiche produit devient obsolète pour le support tout en conservant sa valeur d’archive : tu la retires de la base opérationnelle sans détruire le document.

Peupler une collection en masse

Lors de l’initialisation d’une base de données à partir d’un dossier entier, écris la boucle une fois ; elle te servira longtemps :

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):
        # Étapes 1 et 2 en un seul appel : upload via Files API, puis attachement
        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"))

Remarque le mélange de formats dans la liste : PDF, Markdown et texte brut coexistent sans problème dans la même collection, ce qui t’évite de standardiser tes sources avant l’ingestion.

Deux clés, deux périmètres

Ce processus utilise deux identifiants d’accès que tu ne dois pas confondre : la clé API standard (XAI_API_KEY) pour l’étape 1 de téléchargement, et la clé Management (XAI_MANAGEMENT_API_KEY) pour l’étape 2 d’attachement. Le SDK reçoit les deux à la création du client, et upload_document les utilise l’une après l’autre. Vérifie que cette dernière dispose de la permission AddFileToCollection : sans elle, ton téléchargement réussira, ton ajout échouera avec une erreur 403, et tu accumuleras des fichiers correctement stockés mais absents de toute collection.

Punti chiave

  • L’ajout à une collection se fait en deux étapes : téléchargement puis ajout
  • Un fichier peut appartenir à plusieurs collections simultanément
  • Le document doit atteindre le statut DOCUMENT_STATUS_PROCESSED avant d’être consultable
  • Retirer un document d’une collection ne supprime pas le fichier sous-jacent
  • Deux clés API distinctes sont requises : standard pour le téléchargement, Management pour la collection