Ajouter des documents à une collection
In questa pagina
Mis à jour le 2 novembre 2026. Cette leçon reflète la version
xai-sdk1.21.0 et la documentation xAI : les appelsawaitnécessitent le client asynchroneAsyncClient, le statut d’indexation se compare à la constantecollections_pb2.DOCUMENT_STATUS_PROCESSED(et non à une chaîne), et l’ingestion en masse utiliseupload_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_PROCESSEDavant 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