Bases de connaissances

L'écran Bases de connaissances permet de créer des collections de documents pour la recherche (RAG), d'ingérer des documents, de tester une requête avec la provenance de chaque extrait, de régler qui peut lire et écrire une base et de faire passer une base à un autre modèle d'embedding. Chemin du portail : /data/knowledge ; le détail d'une base s'ouvre sur /data/knowledge/<kb-id>. Les développeurs et les administrateurs du tenant l'utilisent pour alimenter les agents en documents internes ; les responsables sécurité l'utilisent pour contrôler les accès.

Ce que montre l'écran

La table Bases de connaissances liste les bases que vous pouvez lire (le serveur les filtre avec l'ACL readers). Colonnes : Nom, Description, Modèle d'embedding, Dimensions, Base vectorielle, Classification, Créé. Un clic sur une ligne ouvre la page de détail. Sans aucune base, l'écran affiche « Aucune base de connaissances ».

Le formulaire de création Nouvelle base contient ces champs :

Champ	Obligatoire	Défaut	Notes tirées du code
Nom	oui		1 à 120 caractères, unique dans le tenant
Description	non
Classification	oui		`internal`, `public`, `confidential`, `restricted`, `secret`
Modèle d'embedding	non	`EAI_RAG_EMBEDDING_MODEL`	modèle du registre avec la capacité embeddings, exemple `bge-m3-vllm`
Dimensions	non	taille native du modèle	1 à 16384
Taille des segments	non	200	20 à 4000
Chevauchement des segments	non	40	doit être inférieur à la taille des segments

La page de détail affiche le nom de la base, un bouton Retour et quatre onglets :

Documents : la section Ajouter un document (champs Titre, Fichier, Ou collez du texte ; la zone de texte est désactivée dès qu'un fichier est choisi) et la table Documents avec Titre, Type MIME, Extraits, Version, Classification, Connecteur source, Lecteurs (ACL), Statut, Détections DLP, Créé. Un clic sur un document ouvre un panneau avec sa fiche.
Recherche : le formulaire Testeur de requête avec Requête (obligatoire), Top K (5), Score minimal (0), Mode (vector ou hybrid), Reclassement et Modèle de reclassement. Chaque résultat affiche son rang, son score, l'identifiant du document, sa classification, le texte et le JSON de provenance. « Aucun résultat » signifie que rien ne correspond ou que vous ne pouvez pas lire les documents correspondants.
Contrôle d'accès : un éditeur JSON contenant readers, writers et apply_to_documents ; « JSON invalide » s'affiche dessous tant que le texte n'est pas lisible.
Réindexation : le formulaire Réindexation (Modèle d'embedding obligatoire, Dimensions) et la table Tâches de réindexation avec Identifiant, Statut, Modèle, Traités, Total, Erreur, Créé, Terminé.

Actions

Bouton ou action	Ce qu'il fait	Appel API	Rôles
Icône d'actualisation	Recharge la liste	`GET /v1/knowledge-bases`	tout utilisateur du tenant (filtré par ACL)
Nouvelle base > Créer	Crée la base et vous en rend propriétaire	`POST /v1/knowledge-bases`	`tenant_admin`, `developer`
Clic sur une ligne	Ouvre la page de détail	`GET /v1/knowledge-bases/{kb_id}`	relation `viewer` et ACL `readers`
Supprimer (menu de ligne)	Affiche la confirmation d'impact (dépendances lues sur `GET /v1/lineage/graph`), puis supprime la base et ses vecteurs	`DELETE /v1/knowledge-bases/{kb_id}`	relation `owner` ; `tenant_admin` ou le créateur
Ingérer	Analyse, extrait, découpe et vectorise le fichier ou le texte	`POST /v1/knowledge-bases/{kb_id}/documents`	relation `editor` ; ACL `writers`, ou `tenant_admin`, `developer`, `agent` quand `writers` est vide
Table des documents	Liste les documents que vous pouvez lire	`GET /v1/knowledge-bases/{kb_id}/documents`	relation `viewer`
Supprimer (menu d'un document)	Supprime le document et ses extraits après la confirmation d'impact	`DELETE /v1/knowledge-bases/{kb_id}/documents/{doc_id}`	comme Ingérer
Exécuter (Testeur de requête)	Recherche filtrée par ACL et habilitation	`POST /v1/knowledge-bases/{kb_id}/query`	relation `can_invoke` et ACL `readers`
Enregistrer l'ACL	Remplace lecteurs et rédacteurs, et les lecteurs des documents hérités quand `apply_to_documents` vaut true	`PUT /v1/knowledge-bases/{kb_id}/acl`	relation `owner` ; `tenant_admin`, `security_officer` ou le créateur
Exécuter (Réindexation)	Met en file la tâche de réindexation des embeddings (réponse 202)	`POST /v1/knowledge-bases/{kb_id}/reindex`	relation `owner`, `tenant_admin` ou `developer`, et droit d'écriture
Table des tâches de réindexation	Liste les réindexations de la base	`GET /v1/knowledge-bases/{kb_id}/reindex-jobs`	relation `viewer`

Rôles

Le portail ne masque aucun bouton sur cet écran : le Control Plane décide. Les règles viennent de services/control-plane/src/eai/domains/knowledge/__init__.py :

créer une base et lancer une réindexation exigent tenant_admin ou developer (erreur forbidden sinon) ;
écrire des documents exige l'ACL writers de la base ; quand elle est vide, tenant_admin, developer et agent peuvent écrire ; tenant_admin le peut toujours ;
lire exige une identité de l'ACL readers (*, user:<id>, role:<role>, group:<groupe>) ; les administrateurs n'ont aucune lecture implicite ;
l'ACL est modifiée par tenant_admin, security_officer ou le créateur de la base.

Tâches courantes

Créer une base et ingérer un premier document

Créer la base. Une base fixe le modèle d'embedding et le découpage de tous ses documents. Ouvrez Bases de connaissances, cliquez sur Nouvelle base, remplissez Nom et Classification, puis Créer.

Résultat attendu : le message « Créé » et une nouvelle ligne dans la table.

En cas d'échec : conflict signifie que le nom existe déjà ; invalid_request sur chunk_overlap signifie que le chevauchement n'est pas inférieur à la taille des segments.
Ingérer un document. Le document passe par la chaîne de sécurité des fichiers avant l'extraction. Cliquez sur la ligne, restez sur Documents, choisissez un Fichier ou collez du texte, puis cliquez sur Ingérer.

Résultat attendu : le message « Document ingéré » et une ligne avec son nombre d'Extraits.

En cas d'échec : lisez le code d'erreur dans la table de la section Dépannage (file_blocked, unsupported_media).

Tester la recherche d'un agent

Lancer une requête. Le testeur applique les mêmes filtres d'ACL et d'habilitation qu'un agent. Ouvrez l'onglet Recherche, saisissez une Requête, choisissez le Mode hybrid si les mots clés comptent, puis Exécuter.

Résultat attendu : des résultats numérotés avec un score, un identifiant de document et la provenance de l'extrait.

En cas d'échec : « Aucun résultat » avec des documents présents signifie que votre identité n'est pas dans les readers des documents ; baissez le Score minimal ou vérifiez l'ACL.

Restreindre la lecture d'une base

Modifier l'ACL. La recherche ne renvoie que les extraits dont les lecteurs correspondent à l'appelant. Ouvrez Contrôle d'accès et écrivez l'objet JSON, par exemple :
```
{
  "readers": ["group:finance", "role:tenant_admin"],
  "writers": ["group:finance-editors"],
  "apply_to_documents": true
}
```
group:finance et group:finance-editors sont des exemples de groupes d'identités de votre organisation.
L'enregistrer. Cliquez sur Enregistrer l'ACL.

Résultat attendu : le message « Enregistré » ; la réponse compte documents_updated.

En cas d'échec : « JSON invalide » laisse le bouton désactivé ; forbidden signifie que vous n'êtes ni tenant_admin, ni security_officer, ni le créateur.

Faire passer une base à un autre modèle d'embedding

Lancer la réindexation. Les vecteurs actuels restent interrogés jusqu'à la bascule. Ouvrez Réindexation, remplissez Modèle d'embedding (et Dimensions si le modèle propose plusieurs tailles), puis Exécuter.

Résultat attendu : une tâche dans Tâches de réindexation dont Traités monte jusqu'à Total.

En cas d'échec : la colonne Erreur de la tâche donne la cause ; embedding_dimension_mismatch signifie que les dimensions ne correspondent pas au modèle.

Dépannage

Symptôme	Cause	Correction
`forbidden` (403) sur Créer ou Exécuter (Réindexation)	Votre rôle n'est ni `tenant_admin` ni `developer`	Demandez le rôle `developer` à un administrateur du tenant
`not_permitted_acl` (403) sur Ingérer ou Supprimer	Vous n'êtes pas dans l'ACL `writers` de la base	Ajoutez votre identité à `writers` dans Contrôle d'accès
`not_found` (404) sur une base qui existe	Votre identité n'est pas dans l'ACL `readers`	Demandez au propriétaire de vous ajouter à `readers`
`conflict` (409) sur Créer	Une base de ce nom existe dans le tenant	Choisissez un autre nom
`invalid_request` (400) avec `chunk_overlap`	Le chevauchement n'est pas inférieur à la taille des segments	Baissez Chevauchement des segments
`file_blocked` (422) sur Ingérer	L'antivirus, YARA ou la validation a refusé le fichier	Voir Sécurité des fichiers
`unsupported_media` (422) sur Ingérer	L'extracteur ne sait pas lire ce type MIME	Convertissez le fichier (PDF, texte, formats bureautiques)
`embedding_dimension_mismatch` (409)	Les vecteurs n'ont pas la taille attendue par la base	Réindexez avec les bonnes Dimensions
`vector_store_unavailable` (503)	La base vectorielle (Qdrant) ne répond pas	Vérifiez le service de base vectorielle, puis réessayez

Ce que montre l'écran​

Actions​

Rôles​

Tâches courantes​

Créer une base et ingérer un premier document​

Tester la recherche d'un agent​

Restreindre la lecture d'une base​

Faire passer une base à un autre modèle d'embedding​

Dépannage​

Pages liées​