How knowledge bases work

A knowledge base holds your documents so your agents can search them and answer from them, not only from what the model already knows. Knowledge bases run on aiR, aixplain's retrieval engine. This article explains what you can put in a knowledge base, how aiR finds the passages that answer a question, when to attach files instead, and what it costs.

What is a knowledge base?

A model knows what it learned in training, not your price list, your policies or last month's case files. A knowledge base gives an agent those documents. When a question comes in, the agent searches the knowledge base, reads the passages that match and writes its answer from them. This is often called retrieval-augmented generation, or RAG.

In aixplain, a knowledge base is a connection to the aiR Knowledge Base integration. Each one becomes a tool in your workspace, and you give it to an agent the same way you give it a connected app. To create one, see Create and use a knowledge base.

Key capabilities

• Search by meaning: a question finds the passages that answer it, even when they use different words.
• Files or text: upload files when you create a knowledge base, and add or edit text records later.
• Metadata filters: tag records with fields such as a category, a date or a price, and limit a search to the records that match.
• Chunking that fits your documents: split text by sentence, passage, page, line, word or your own marker, or keep short records whole.
• Your choice of embedding model: keep the default, or choose another model from the Marketplace, such as a multilingual one, when you create it in code.
• Read-only for agents: allow an agent only to search, so it can't change or delete what's stored.
• Personal or shared: keep a knowledge base to yourself, or share it with your team.

What you can put in a knowledge base

• Files: when you create a knowledge base in the web app, you upload files such as PDFs. aiR turns each file into text before it stores it. The upload form lists the file types it accepts and how many files you can add.
• Text records: a piece of text with an optional ID and metadata. Add them on the knowledge base's Index data page in the web app, or with the Agents SDK.

A document with no readable text, such as a scan with no text layer, is reported instead of being added empty.

How aiR finds answers

Every document goes through the same steps when you add it, and every question goes through the last two.

1. Parse: a file is turned into plain text.
2. Split into chunks: by default the text is cut into chunks of 10 sentences, and neighboring chunks share 3 sentences, so an idea that crosses a boundary stays whole.
3. Embed: an embedding model turns each chunk into a vector, a list of numbers that captures its meaning. Every chunk in a knowledge base uses the embedding model chosen when it was created.
4. Search: a question is embedded the same way, and aiR returns the chunks closest to it in meaning, each with a score. Metadata filters narrow the search first.
5. Answer: the agent reads the chunks it got back and writes its answer from them.

Each result carries the document's ID with its chunk number, such as policy-7#chunk2, the chunk's text, its score and its metadata. To change how chunks are cut, what they're tagged with or which model embeds them, see Shape it to your documents.

Update and delete documents

• Update: add a document again with the same ID and it replaces the old version. aiR writes the new chunks before it removes the old ones, so an update that fails leaves the old version in place.
• Delete: deleting a document by its ID removes all of its chunks and nothing else.

Shape it to your documents

Three settings decide how well a knowledge base answers: the metadata on each record, how the text is cut into chunks and the model that embeds it. Each has a default that works for most documents, and you can change it to fit yours.

Metadata

Tag each record with fields of your own, such as a category, a region, a date or a price. A search can then be limited to the records that match, for example only this year's contracts or only products under 300 dollars, before aiR ranks the rest by meaning. Add metadata as a JSON object with each record, on the Index data page in the web app or with the Agents SDK.

Chunking

By default, aiR splits text into chunks of 10 sentences that overlap by 3. With the Agents SDK you choose how text is split, so chunks follow the way your documents are written:

You also set the chunk size and how much neighboring chunks overlap. In the web app, Split into chunks on a new record turns splitting on or off.

Embedding model

The embedding model decides how meaning is captured, so it decides what a search finds. Keep the default, or choose another embedding model from the Marketplace when you create the knowledge base with the Agents SDK, for example a multilingual model such as BGE-M3 for Arabic and other languages. Every chunk uses the same model, so it's set once: to change it, create a new knowledge base and add the documents again.

Knowledge base or attached files?

An agent can also read files you attach to it directly. Pick the one that fits the documents.

To attach files instead, see Files in Build and deploy agents with Omni.

Pricing and usage

A knowledge base uses models to do its work. Parsing a file, embedding each chunk and embedding each search query are model calls, and each one is paid from your workspace credits like any other model. More documents, and longer ones, mean more embedding when you add them. For plans and credits, see Pricing.

Privacy and data

• Who can see it: a knowledge base belongs to your workspace. It is personal to you until you share it with your team, and only its owner can browse and edit its records in the web app.
• Your data stays yours: we never sell your documents or train on them.
• On your own servers: with Enterprise, the aixplain OS runs on-prem, in your VPC or air-gapped, and your knowledge bases stay there. See Run the aixplain OS on-prem.

For more, see Privacy and data.

Limitations

• Each request to add documents takes up to 100 documents, and a file can be up to 100 MB.
• The embedding model is set when you create a knowledge base. To use another one, create a new knowledge base and add the documents again.
• In the web app, files are added when you create the knowledge base. After that, you add text records.
• Chat answers don't show source links yet. To see where an answer came from, tell the agent in its instructions to name the document it used.
• Koder doesn't search knowledge bases. Use Omni or an agent you built.

Frequently asked questions

Get help

• Build with it: see Create and use a knowledge base.
• Report a problem: email care@aixplain.com with the knowledge base's name, what you searched for and what you expected. Remove credentials and private data first.
• See what changed: read the release notes.