Knowledge bases

The Knowledge bases screen lets you create document collections for retrieval (RAG), ingest documents, test a query with the provenance of each chunk, set who can read and write a base, and move a base to another embedding model. Portal path: /data/knowledge; the detail of a base opens at /data/knowledge/<kb-id>. Developers and tenant administrators use it to feed agents with internal documents; security officers use it to control access.

What the screen shows

The Knowledge bases table lists the bases you can read (the server filters them with the readers ACL). Columns: Name, Description, Embedding model, Dimensions, Vector store, Classification, Created. A click on a row opens the detail page. Without any base, the screen shows "No knowledge base".

The creation form New knowledge base has these fields:

Field	Required	Default	Notes from the code
Name	yes		1 to 120 characters, unique in the tenant
Description	no
Classification	yes		internal, public, confidential, restricted, secret
Embedding model	no	EAI_RAG_EMBEDDING_MODEL	registry model with the embeddings capability, example bge-m3-vllm
Dimensions	no	native size of the model	1 to 16384
Chunk size	no	200	20 to 4000
Chunk overlap	no	40	must be lower than the chunk size

The detail page shows the name of the base, a Back button and four tabs:

• Documents: the Add a document section (fields Title, File, Or paste text; the text area is disabled once a file is chosen) and the Documents table with Title, MIME type, Chunks, Version, Classification, Source connector, Readers (ACL), Status, DLP findings, Created. A click on a document opens a drawer with its record.
• Search: the Query tester form with Query (required), Top K (5), Minimum score (0), Mode (vector or hybrid), Rerank and Rerank model. Each hit shows its rank, its score, the document id, its classification, the text and the provenance JSON. "No result" means nothing matches or you cannot read the matching documents.
• Access control: a JSON editor holding readers, writers and apply_to_documents; "Invalid JSON" appears under it while the text does not parse.
• Reindex: the Reindex form (Embedding model required, Dimensions) and the Reindex jobs table with Id, Status, Model, Processed, Total, Error, Created, Finished.

Actions

Button or action	What it does	API call	Roles
Refresh icon	Reloads the list	GET /v1/knowledge-bases	any tenant user (ACL filtered)
New knowledge base > Create	Creates the base and makes you its owner	POST /v1/knowledge-bases	tenant_admin, developer
Click on a row	Opens the detail page	GET /v1/knowledge-bases/{kb_id}	viewer relation and readers ACL
Delete (row menu)	Shows the impact confirmation (dependents read from GET /v1/lineage/graph), then deletes the base and its vectors	DELETE /v1/knowledge-bases/{kb_id}	owner relation; tenant_admin or the creator
Ingest	Scans, extracts, chunks and embeds the file or the text	POST /v1/knowledge-bases/{kb_id}/documents	editor relation; writers ACL, or tenant_admin, developer, agent when writers is empty
Documents table	Lists the documents you may read	GET /v1/knowledge-bases/{kb_id}/documents	viewer relation
Delete (document menu)	Deletes the document and its chunks after the impact confirmation	DELETE /v1/knowledge-bases/{kb_id}/documents/{doc_id}	same as Ingest
Run (Query tester)	ACL and clearance filtered retrieval	POST /v1/knowledge-bases/{kb_id}/query	can_invoke relation and readers ACL
Save ACL	Replaces readers and writers, and the readers of inherited documents when apply_to_documents is true	PUT /v1/knowledge-bases/{kb_id}/acl	owner relation; tenant_admin, security_officer or the creator
Run (Reindex)	Queues the embeddings reindex job (answer 202)	POST /v1/knowledge-bases/{kb_id}/reindex	owner relation, tenant_admin or developer, and write access
Reindex jobs table	Lists the reindex jobs of the base	GET /v1/knowledge-bases/{kb_id}/reindex-jobs	viewer relation

Roles

The portal hides no button on this screen: the Control Plane decides. The rules come from services/control-plane/src/eai/domains/knowledge/__init__.py:

• creating a base and starting a reindex need tenant_admin or developer (error forbidden otherwise);
• writing documents needs the writers ACL of the base; when it is empty, tenant_admin, developer and agent may write; tenant_admin always may;
• reading needs an identity of the readers ACL (*, user:<id>, role:<role>, group:<group>); administrators get no implicit read;
• the ACL is changed by tenant_admin, security_officer or the creator of the base.

Typical tasks

Create a base and ingest a first document

1. Create the base. A base fixes the embedding model and the chunking of every document it will hold. Open Knowledge bases, click New knowledge base, fill Name and Classification, then Create.

   Expected result: the toast "Created" and a new row in the table.

   If it fails: conflict means the name already exists; invalid_request on chunk_overlap means the overlap is not lower than the chunk size.

2. Ingest a document. The document is scanned by the file security chain before extraction. Click the row, stay on Documents, choose a File or paste text, then click Ingest.

   Expected result: the toast "Document ingested" and a row with its number of Chunks.

   If it fails: read the error code in the table of the Troubleshooting section (file_blocked, unsupported_media).

Test the retrieval of an agent

1. Run a query. The tester applies the same ACL and clearance filters as an agent. Open the Search tab, type a Query, choose Mode hybrid if keywords matter, then Run.

   Expected result: numbered hits with a score, a document id and the provenance of the chunk.

   If it fails: "No result" with existing documents means your identity is not in the readers of the documents; lower Minimum score or check the ACL.

Restrict who can read a base

1. Edit the ACL. Retrieval only returns chunks whose readers match the caller. Open Access control and write the JSON object, for example:

   {
     "readers": ["group:finance", "role:tenant_admin"],
     "writers": ["group:finance-editors"],
     "apply_to_documents": true
   }

   group:finance and group:finance-editors are examples of identity groups of your organization.

2. Save it. Click Save ACL.

   Expected result: the toast "Saved"; the answer counts documents_updated.

   If it fails: "Invalid JSON" keeps the button disabled; forbidden means you are neither tenant_admin, security_officer nor the creator.

Move a base to another embedding model

1. Start the reindex. The current vectors stay searched until the switch. Open Reindex, fill Embedding model (and Dimensions if the model offers several sizes), then Run.

   Expected result: a job in Reindex jobs whose Processed grows up to Total.

   If it fails: the Error column of the job gives the cause; embedding_dimension_mismatch means the dimensions do not match the model.

Troubleshooting

Symptom	Cause	Fix
forbidden (403) on Create or Run (Reindex)	Your role is neither tenant_admin nor developer	Ask a tenant administrator for the developer role
not_permitted_acl (403) on Ingest or Delete	You are not in the writers ACL of the base	Add your identity to writers in Access control
not_found (404) on a base that exists	Your identity is not in the readers ACL	Ask the owner to add you to readers
conflict (409) on Create	A base with this name exists in the tenant	Choose another name
invalid_request (400) with chunk_overlap	The overlap is not lower than the chunk size	Lower Chunk overlap
file_blocked (422) on Ingest	The antivirus, YARA or validation step refused the file	See File security
unsupported_media (422) on Ingest	The extractor cannot read this MIME type	Convert the file (PDF, text, office formats)
embedding_dimension_mismatch (409)	The vectors do not have the size the base expects	Reindex with the right Dimensions
vector_store_unavailable (503)	The vector store (Qdrant) does not answer	Check the vector store service, then retry

Related pages

• RAG quarantine
• Lineage
• DLP tester
• Retention
• File security
• RAG pipelines
• Vector database