Creating a RAG Topic — Step by Step

Say clearly what knowledge the Topic holds. Agents that use this Topic as a tool read this text to decide when to ask it. A clear description means the agent picks the right Topic more often.

The port where this Topic is reached on the server. It also makes the REST interface reachable. Every Topic needs its own port, and no other program on the server may use it. The wizard does not check this. A port that is already taken shows up only when you start the Topic. Pick a simple scheme you can keep track of, for example 8081, 8082, 8083.

Only the roles you tick here can see and use the Topic. This works on top of the TOPIC_VIEW permission — see Roles & Permissions.

The ADMIN role and your own roles are always ticked and cannot be unticked. So you never lock yourself out of a Topic you created. Tick more roles to give other users access.

Here you give the Topic its own instructions, for example "Always answer in German." or "You are an HR assistant. Cite the section you used." These instructions change how answers sound. They do not change which content the search finds. Leave the field empty to use only the shared system prompt.

Your text is added to the shared system prompt (Admin → LLM Configuration). So you don’t need to repeat general rules, only what is special for this Topic. See Global LLM Configuration.

Above the field, Quick-fill from template: shows one button per prompt template from Admin → Prompt Templates. A click replaces the content of the field with the template. So pick a template first and edit it afterwards. The buttons only appear when at least one template exists.

The other texts of the Topic — for example the shared system prompt for this Topic only, or the instructions of single model steps — are on the Topic’s Prompts tab after creation. See Prompts.

Each Select Model button opens a dialog with one tab per AI server. The list comes from a stored copy of each server’s model list. So the dialog opens fast, even when a server is slow. The line above the list says how old the list is, for example Models on MyServer · 4 min ago. Click a row to select. Click Refresh to get the list from the server again, for example after you installed a new model.

After a choice, the button reads Change, and the selection shows as server ─ model.

File Types decides which files the Topic’s Data Upload tab accepts. Other files are refused at upload. If you leave all boxes empty, every file is accepted. Ticking the types that match your content gives you a clear message at upload instead of a failed upload later.

The choice also changes the rest of this step:

Docling turns PDF, Office files and scanned pages into text that the search can use. The part appears as soon as Documents is ticked among the File Types, or Allow binary documents as chat attachments is ticked. Without a Docling server such files are refused, at upload and in the chat.

Without a server, the message Select a Docling server — binary formats cannot be read without one. appears.

Timeout (min): a higher value lets long scanned PDFs finish; without a graphics card they can take minutes. A lower value lets a stuck upload fail sooner. If the value is longer than the server’s own Max Conversion Time (Admin → Docling Servers), a warning says so: that server stops first, so the longer timeout has no effect. Raise the limit on the server instead.

Docling Settings (advanced): a text with settings in JSON form, for example text recognition in scans (OCR), its languages, tables and small pictures. Click Edit to open the editor. The template switches nothing on, so Docling keeps the settings of its server. Remove the // in front of a setting to use it. Apply takes the settings into the wizard. The settings are used for every upload of this Topic, not for files attached in the chat. A misspelt setting name is not reported — Docling ignores it. The line above the preview says Docling server defaults or Customised for this topic.

Applies to structured files: JSON, XML, YAML, TOML, CSV and TSV. They are recognized by their file ending. They are always split into records — for example one table row each — so a record is never cut in the middle.

The Narrator Model shows Reuses chat LLM until you pick one. Then the Topic’s Language Model does the work. A small, fast model keeps large uploads short. Reuse Chat LLM removes your pick again.

This part has two separate topics: pictures that arrive during upload, and images that users attach in the chat.

Pictures in documents and uploaded pictures:

When Describe pictures with a vision model is on, three more fields appear:

You must either pick a model or tick Use the topic’s Language Model. Otherwise the message Select a model to describe images, or tick the box to use the topic’s Language Model. appears. With the box ticked, you must also pick the Language Model below, otherwise the message is Pick the topic’s Language Model below before inheriting it here.

Images in the chat:

An attached image goes directly to the Topic’s Language Model, not to the Image Describer Model, which works only during upload. So the Language Model must be able to read images. Nothing checks this for you.

Which files users may attach to a chat message is decided on this step:

The embedding model turns each text piece and each question into numbers. That way the search finds text with the same meaning, even when it uses other words. A better model finds better matches, but makes uploads slower.

When Images is a File Type, a hint says This source type usually needs a multimodal embedding model.

Dimension. Each embedding model produces a list of numbers of a fixed length, the dimension. The Topic must know it. What happens after you click a model depends on the server:

The dimension is required. Without it, the Topic could not start. The selection shows it after the model name, for example (768d). Messages you can see:

The Language Model writes the chat answers from the text pieces the search found. It also does the other model steps of this Topic unless they have their own model — for example narrating records, describing pictures (when inherited), sorting results (reranking), routing and writing keywords. A larger model gives better answers, but is slower and costs more.

Check two things:

Without a model, the message Please select a language model and a server appears.

Messages you can see: Please select a retrieval strategy, Top-K must be at least 1.

What these settings do to a question, in order:

The defaults are a good start. Then adjust:

Before the search, the Language Model checks if a chat message needs your documents at all. Thanks, small talk or a request to rework an earlier answer, and a question that an attached file alone answers, are answered without a search. This makes these answers faster. All other messages — and every message the model is unsure about — are searched as usual.

Router Confidence Threshold is how sure the model must be before a message is answered without a search. Higher: fewer messages skip the search — safer, but slower. Lower: more messages skip it — faster, but a real question may be answered without your documents. While routing is on, the field must not be empty; otherwise the message is Enter a value between 0.0 and 1.0.

With RECURSIVE, a piece can lose its context, for example "it" without saying what "it" is. Choose SEMANTIC when a piece means little on its own — a table row, a numbered clause, a paragraph that refers to something named pages earlier. Despite the name, it does not cut by meaning. It improves what each piece says about itself. Try it on a few documents first.

Click Save. The wizard checks everything once more, including the license. If all is fine, the message Topic saved successfully appears and the Topic list opens. If a check fails, a message The topic was not saved appears, and the wizard jumps to the step with the problem.