Knowledge bases
A knowledge base holds documents that agents can search. Orchestrate splits each document into chunks, turns each chunk into a vector with an embedding model, and stores the vectors in Qdrant inside your cluster. When an agent searches, it gets back the chunks closest in meaning to its question.
Knowledge bases belong to a project. You need the developer or admin role on the project to create one, upload documents, see its documents or search it.
Before you start
You need an embedding model that is built and deployed. A new install comes with a small one in the catalog. See Models and serving.
Create a knowledge base
- Open Knowledge and choose New knowledge base.
- Enter a name, such as
Product documentation. - Choose the embedding model. Only models that are deployed and ready can be picked.
- Choose Create and add files.
The embedding model must be one your project may use. If a platform admin has restricted the model to other projects, Orchestrate refuses it.
If the embedding model stops being served, the knowledge base can be neither searched nor added to until it is deployed again, or until you change to another model.
Change the embedding model
Vectors from different embedding models can't be compared, so changing the model means re-embedding every document. Orchestrate does this in the background, and the knowledge base keeps working while it runs. You need the admin role on the project.
- Open the knowledge base. Under Embedding model, choose Change model.
- Pick another embedding model. It must be built and ready, and one your project may use.
- Choose Re-embed documents, and confirm.
While the change runs:
- Searches keep using the current model and its vectors, so agents get the same answers as before.
- The page shows progress, document by document.
- Uploads, retries, re-indexing and deletes in this knowledge base wait until it finishes.
When every document is re-embedded, Orchestrate switches the knowledge base to the new model in one step. From then on every search uses the new model. The old vectors are removed a little later.
The change is all or nothing. If any document fails, the knowledge base stays on its current model, and the page lists the documents that failed and why. Fix the cause, for example a model that wasn't running, and change again.
You can't start a change while documents are still being processed. Wait for them to finish first.
Each change is recorded in the audit log: when it started, and whether it completed or failed.
Add documents
Drop files onto the knowledge base, or choose them. Each file is processed in the background and its status moves through Fetching, OCR (only with an OCR model, with page progress), Chunking, Embedding and Saving. When it is done, the knowledge base shows how many searchable chunks it has.
- Supported files: text and Markdown (
.txt,.md), PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx), HTML, and images (.png,.jpg,.tif), which are read with OCR. Scanned PDFs are read with OCR too. Every parser runs offline. Other files are refused at upload. - Each document is split into chunks of about 1,000 characters, with 100 characters of overlap between neighbours, ending at a sentence where it can, in the document's own script.
- The original file is kept in the platform's object store.
If a document fails, for example because the embedding model was not running, its row says why. Choose Retry to process it again from the stored file. Only a failed document can be retried.
You can delete a document, or a whole knowledge base. Its chunks, vectors and stored files are removed with it.
For documents in languages other than English, use a multilingual embedding model. See Languages.
Rerank and OCR
Open the knowledge base and find Retrieval and reading models. You need the developer or admin role on the project. Changes apply to the next search and the next upload.
Reranker. Vector search finds chunks close in meaning; a reranker then re-scores the top candidates against the question and returns the best of them. It is slower and usually more accurate. Turn on Rerank search results, pick a Reranker model (a catalog model of kind Reranker, such as the BGE or MiniLM rerankers), and set the Candidates (k) it re-scores. Agents' searches then use it.
OCR model. By default, scanned pages and images are read with the built-in OCR (Tesseract), which keeps plain text only. Pick an OCR model (a catalog model of kind OCR, such as PP-OCRv6) to read them on upload while keeping tables and form fields. A document already uploaded is read again when you re-index it. The text it reads is checked by the PII guardrails before it is stored, like a transcript.
Reranker and OCR calls go through the Model Gateway, so they are policy-checked, metered and audited. A model that is built but not deployed is marked (not deployed).
Test retrieval
Before you give a knowledge base to an agent, check what it returns.
- Open the knowledge base and choose Test retrieval.
- Type a Question and choose how many chunks to return with Top k, from 1 to 20.
- Choose Search.
With a reranker set, choose Use the reranker to search with or without it. Each result shows the chunk text, its score (and its rerank score) and the file it came from. If the reranker fails, the results come back in vector order with the error. Chunks that score below the relevance floor are dropped, and the result says how many were. The default floor is 0.28. This is exactly what an agent would get for the same question.
Give it to an agent
When you create or edit an agent, pick the knowledge base under Knowledge. The agent then gets a search_knowledge_base tool that searches it. An agent can have one knowledge base.
Write the system prompt so the agent knows when to search, for example: "Answer questions about our products from the knowledge base. If it has no answer, say you do not know."
Searching a knowledge base is a read, so it never needs approval. Each search is checked by policy and recorded in the audit log like any other tool call.
Where the data lives
| What | Where |
|---|---|
| Uploaded files | MinIO, in your cluster |
| Chunks and vectors | Qdrant, one collection per knowledge base |
| Knowledge base and document records | Postgres |
The embedding calls go through the Model Gateway, so they are policy-checked and audited like other model calls.
See the Knowledge bases API to script all of this.