Créer et gérer des collections

Du fichier isolé à la base de connaissances

Jusqu’ici, chaque document vivait seul : vous l’uploadiez, vous le référenciez, et l’index construit pour l’occasion disparaissait avec la requête. Les collections changent d’échelle : elles regroupent vos fichiers en bases de connaissances structurées, indexées une fois pour toutes et interrogeables en permanence. C’est le fondement du RAG — Retrieval-Augmented Generation — avec Grok, et la différence se voit dès qu’une équipe support interroge deux cents fiches produit plutôt qu’un PDF unique.

Représentez-vous une collection comme un dossier intelligent. Vous y déposez des documents, xAI les indexe pour la recherche sémantique, et Grok fouille cette base pour répondre avec précision, en allant chercher les trois passages utiles parmi des milliers.

Une API à part, et pourquoi

Les collections ne se pilotent pas depuis l’API que vous utilisez depuis le début du cours. Elles relèvent de la Management API, hébergée sur management-api.x.ai, dont l’URL de base est :

https://management-api.x.ai/v1

Cette séparation n’est pas un caprice d’architecture. Créer, modifier ou supprimer une collection sont des opérations d’administration aux conséquences lourdes, et xAI exige pour elles une clé dédiée : une Management API Key, portant la permission AddFileToCollection. Le bénéfice est immédiat en équipe : le service qui interroge la base depuis votre application publique reçoit la clé standard et ne peut rien détruire, seul votre pipeline d’ingestion détient la clé de gestion.

Créer sa première collection

La création se réduit à un appel avec un nom :

curl -X POST https://management-api.x.ai/v1/collections \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"collection_name": "documentation-technique"}'

La réponse vous rend l’identifiant à conserver :

{
  "collection_id": "col_xyz789",
  "collection_name": "documentation-technique",
  "created_at": "2026-04-01T10:00:00Z"
}

Soignez ce nom : il apparaîtra dans toutes vos listes et sera, six mois plus tard, le seul indice permettant de distinguer deux bases voisines. documentation-technique remplit ce rôle, test2 non. Adoptez une convention dès la première collection, car renommer une base déjà référencée par trois applications coûte plus cher que bien nommer au départ.

Les cinq opérations disponibles

La Management API expose un jeu CRUD complet sur les collections :

Lister vos collections se fait sans paramètre et donne une vue d’ensemble utile avant toute opération de maintenance :

curl https://management-api.x.ai/v1/collections \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"

La suppression suit la même logique, en désignant l’identifiant obtenu à la création :

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

Un point rassure au moment d’appuyer sur cette commande : supprimer une collection retire l’indexation, pas les fichiers. Vos documents restent accessibles via la Files API et peuvent être réindexés ailleurs. Vous perdez la structure de recherche, pas la matière première — ce qui rend la reconstruction d’une base mal organisée bien moins risquée qu’il n’y paraît.

Points clés à retenir

• Les collections regroupent vos fichiers en bases de connaissances indexées pour le RAG
• La gestion passe par la Management API (management-api.x.ai), pas l’API standard
• Une Management API Key avec permission AddFileToCollection est requise
• Les limites sont de 100 000 fichiers et 100 GB par compte
• Les cinq opérations CRUD couvrent la création, la lecture, la modification et la suppression