Topic Prompts
This guide describes the Prompts tab of a RAG Topic. You find it on the Topic detail page, next to LLM Overrides. The tab shows every instruction text that the topic sends to an AI model, and lets you change the wording for this topic only.
1. What the tab is for
A topic uses AI models for several jobs. During upload, a model can describe pictures, rewrite table rows as text, or write keywords. In the chat, a model decides if a question needs a search, sorts the found text passages, writes the answer and picks the sources. Each job gets an instruction text, the prompt.
Every prompt has a working default. You change a prompt when you want different behaviour for this topic, for example:
-
answers in a fixed tone or language,
-
picture descriptions with more detail,
-
keywords that also include synonyms,
-
a citation word in your users' language.
Your text replaces the default completely. Nothing is added to it. Prompts you do not change keep their default, and they get its improvements with new versions or with changes under Admin → LLM Configuration.
|
Many prompts only run under certain settings. For example, the keyword prompt runs only with
Retrieval Strategy |
2. How the tab is organised
At the top, the box How these are used explains the basic rules. Below it, the prompts are grouped by the model that runs them. The order follows the work of the topic: first the steps during upload, then the steps in the chat.
| Section | Runs | Prompts |
|---|---|---|
Vision Model |
Upload |
Image description |
Structured Data Narrator |
Upload |
Record narration |
Chunk enrichment & keywords |
Upload |
Chunk enrichment, Keyword generation |
Routing |
Chat |
Router, Direct answer, Attachment answer |
Reranking |
Chat |
Reranking |
Language Model |
Chat |
System prompt, Context template, Citation rules, Attachment citation token, Image sources block, No-answer response |
Source filter |
Chat |
Source filter check |
Three texts in Language Model — System prompt, Context template and No-answer response — take their default from Admin → LLM Configuration, which all topics share. All other prompts take their default from the topic’s built-in text. See section 5.
3. Working with a prompt
Each prompt is one row:
| Part | Shows |
|---|---|
Title |
The name of the prompt, for example Router |
Badge |
What the text must contain, see below |
State |
Customised for this topic, or where the default comes from: Container default (built-in text) or Global default (Admin → LLM Configuration) |
Description |
Where the prompt is used, what it does, what changes if you edit it, what you must keep, and what fills its gaps |
Preview |
The first three lines of the text the topic uses now. You cannot type here |
Edit |
Opens the full editor in a dialog |
The badge can be:
| Badge | Meaning |
|---|---|
1 × %s, 2 × %s, … |
The text must contain exactly this many |
No placeholders |
The text has no |
Requires {context} |
The text must contain |
One word |
A single word (Attachment citation token) |
Plain text |
Free text, shown to users as written (No-answer response) |
Editing in the dialog
The editor always opens with the text the topic uses now: your own text, or the default. The dialog shows the description again above the editor. It has three buttons:
| Button | Does |
|---|---|
Restore default |
Puts the default text back into the editor. Nothing is saved yet |
Cancel |
Closes the dialog and keeps the last saved text. The Escape key and a click outside the dialog do the same |
Save |
Checks the text and saves it for this topic. There is no other Save button on the tab |
When the check fails, the dialog stays open. A red message below the editor says why, and ends with "The prompt is not saved." Fix the text and click Save again, or click Cancel.
After a successful save you see one of these messages:
-
"Title saved." — the topic now uses your text.
-
"Title is back on its default." — your text was equal to the default.
Both messages add a note about the restart, see section 8.
Your text or the default
-
Save the default text unchanged, and the topic stores no own text. The state goes back to the default, and the topic keeps following the default when it changes later. This is also how you undo a change: Restore default, then Save.
-
An empty prompt is refused with "This prompt cannot be empty. Use Restore default to go back to the shipped text."
-
A saved own text stays fixed. Later changes of the default, for example in Admin → LLM Configuration, do not reach this prompt any more.
4. Gaps and fixed answer formats
%s gaps
Many prompts contain %s. Each %s is a gap that the system fills when the prompt runs, for example
with the question or with a piece of text. The description of each prompt says what fills each gap
(Placeholders:, numbered in order).
-
Keep the same number of
%sas the badge shows, in the same order. -
To write a percent sign, write
%%.
A wrong number is refused on save:
This prompt needs exactly n %s placeholder(s) and has m. The container checks the same thing on startup and would ignore the prompt entirely.
A single % that is not %s or %% is refused too:
"…" is neither a %s slot nor an escaped percent sign. Write a literal percent sign as %% — the container rejects the prompt otherwise.
These checks do not apply to the prompts with the badge No placeholders that are free text (Image description, Citation rules), to the One word and Plain text rows, or to the three texts from the global configuration.
Fixed answer formats
Some steps read the model’s answer automatically, for example as JSON or as fixed lines. If a prompt asks for such a format, keep it. The tab cannot check this. A broken format shows no error — the step just stops working as intended. The Important: line of each description says what to keep. The prompts with such a format are Router, Reranking, Source filter check, Direct answer and Attachment answer.
5. The three texts from the global LLM configuration
These three rows are in the Language Model section. Their default is the matching text under Admin → LLM Configuration, shared by all topics. Their state shows Global default (Admin → LLM Configuration) until you save an own text for this topic.
System prompt
-
Where: in the chat, in every step that writes an answer the user sees — with or without a search, also the direct and attachment answers. Never in the router or the source filter.
-
What it does: sets the role, tone and style of the assistant. It changes how answers sound, not which content is found.
-
Placeholders: none in the
%ssense. The text{{USER_EDITABLE_PROMPT}}marks where the topic’s own instructions go.
How the topic’s own instructions fit in. The field Custom System Prompt on the
Configuration tab holds extra instructions for this topic only, for example
"Always answer in German." The topic puts this text in place of {{USER_EDITABLE_PROMPT}} in the
system prompt. So:
System prompt contains {{USER_EDITABLE_PROMPT}} |
Custom System Prompt | Result |
|---|---|---|
Yes |
Filled |
The instructions are placed inside the system prompt |
Yes |
Empty |
The placeholder is removed, the system prompt is used alone |
No |
Empty |
The system prompt is used alone |
No |
Filled |
Not allowed — the save is refused |
The refusal on this tab reads:
This topic has a Custom System Prompt (Configuration tab), and without the {{USER_EDITABLE_PROMPT}} placeholder it would never reach the container. Put the placeholder back, or clear it there.
The same rule applies the other way round. If this topic’s own system prompt has no placeholder, a Custom System Prompt saved later on the Configuration tab is refused as well.
Context template
-
Where: in the chat, in every answer that searched your documents.
-
What it does: the text around the found passages that the model gets together with the question. Use it to say how the passages should be used, for example "Answer only from these passages."
-
If you change it: stricter → answers stay close to your documents, but say "I don’t know" more often. Looser → more complete answers, but the model may add its own knowledge. The citation rules and the image sources block are always added after it.
-
Important: the text must contain
{context}. The topic replaces it with the found passages. Without it, the save is refused:
This template must contain {context} — without it the retrieved excerpts never reach the model.
No-answer response
-
Where: in the chat, when the search found nothing that fits and no other tool was used.
-
What it does: this text is shown instead of an answer, so users never get an answer that your documents do not support. It is shown exactly as written. No model changes it.
-
If you change it: write it in your users' language, and tell them what to do next, for example ask in other words or contact support.
6. Prompts during upload
These prompts run while documents are uploaded. A change affects only documents uploaded after the change reached the topic. Documents already stored keep what was written for them. Upload them again to apply the new prompt.
Image description — section Vision Model
Runs |
During upload, for every image file and every picture inside a document. Also for an image attached to a chat message. Only while the topic describes pictures: Describe pictures with a vision model under Image Handling on the Configuration tab |
What it does |
Tells the vision model how to describe a picture. Only this description can be found later — the picture itself is not searchable |
If you change it |
More detail (labels, numbers, parts) → more facts from pictures can be found, but uploads get slower. Less → faster uploads, but details shown only in pictures are lost |
Placeholders |
None. The picture is sent together with this text |
While the topic does not describe pictures, your saved text is kept but not used.
Record narration — section Structured Data Narrator
Runs |
During upload of JSON, XML, YAML, TOML, CSV or TSV files, once per record (for example one table row). Only with the Import Strategy |
What it does |
Rewrites the record as a short paragraph in normal language. This paragraph is stored and searched instead of the raw record |
If you change it |
More natural text → questions in normal language find the record better. Shorter text → faster, but fields the model leaves out can no longer be found |
Keep |
The instruction to keep every field |
Placeholders |
1. the record as "key: value" lines |
Chunk enrichment — section Chunk enrichment & keywords
Runs |
During upload, once for every text piece (chunk), on the Language Model. Only with the Chunking Strategy |
What it does |
Writes a short note on where the chunk belongs in the document, for example "from the maintenance section of manual X". The note is put in front of the chunk and helps the search find it |
If you change it |
Longer notes → chunks are found by more of the document’s context, but uploads are slower and chunks can match questions they do not answer. Shorter notes → faster, but chunks that make no sense alone are found less often |
Placeholders |
1. the whole document, 2. the chunk |
Keyword generation — section Chunk enrichment & keywords
Runs |
During upload, once for every chunk, on the Language Model. Only with Retrieval Strategy |
What it does |
Writes the keywords that the keyword search uses for this chunk |
If you change it |
More keywords (for example synonyms, other languages) → the chunk is found by more search words, but also by questions it does not answer. Fewer → more exact, but questions in other words miss it |
Keep |
Ask for a plain list of keywords. Any other text is indexed as well and makes the keyword search less exact |
Placeholders |
1. the chunk |
7. Prompts in the chat
Routing
The three routing prompts run on the Language Model, and only while Route before retrieval is on (section Routing on the Configuration tab). With routing off, every message is searched and these prompts are never used.
Router
Runs |
Once per message, before anything is searched |
What it does |
Decides if a message needs a search in your documents. DIRECT: thanks, small talk or reworking an earlier answer — answered from the conversation. ATTACHMENT: the attached file alone answers it. RETRIEVAL: search your documents |
If you change it |
More examples for DIRECT or ATTACHMENT → more messages are answered without a search (faster), but some may miss facts from your documents. Fewer → more searches (safer, slower) |
Keep |
The JSON answer format with |
Placeholders |
1. the earlier answers of the assistant (empty for the first message), 2. the message |
Direct answer
Runs |
When the router chose DIRECT: thanks, small talk, or requests like "shorter", "as a table", "in German" |
What it does |
Answers from the conversation only, without a search. Uses the system prompt |
If you change it |
Stricter → more messages are passed on to a real search (safer, but slower). Looser → more messages are answered without a search (faster), but the model may answer facts from its own knowledge instead of your documents |
Keep |
The model must be allowed to answer with only the "needs a search" word. This is how a message that should not have come here still gets a search |
Placeholders |
1. the "needs a search" word, 2. the message |
Attachment answer
Runs |
When the router chose ATTACHMENT: the question is only about a file the user attached |
What it does |
Answers from the attached file only, without searching your documents. Uses the system prompt |
If you change it |
Stricter → more questions also search your documents (more complete, but slower). Looser → faster, but answers ignore your documents even where they would help |
Keep |
The model must be allowed to answer with only the "needs a search" word. This is how a question that also needs your documents still gets a search |
Placeholders |
1. the "needs a search" word, 2. the message |
The system fills in the "needs a search" word itself (today NEEDS_RETRIEVAL). Keep the first %s
where the default has it, so the model knows which word to answer with.
Reranking
Runs |
Once per question, after the search, on the Language Model. Only with the Reranking Strategy |
What it does |
Sorts the found text passages by how well they fit the question. Only the best ones are used for the answer |
If you change it |
You decide what "fits best" means, for example prefer newer documents or exact figures. A stricter rule → answers focus on fewer, better passages. A looser rule → the order stays close to the search result |
Keep |
The answer format: only the passage numbers, separated by commas, best first. Otherwise the search order is kept, and no error is shown |
Placeholders |
1. the question, 2. the numbered text passages |
Language Model
This section holds the prompts for the answer the user sees. The System prompt, Context template and No-answer response are described in section 5.
Citation rules
Runs |
Added after the found text passages in every answer that searched your documents |
What it does |
Tells the model to mark each statement with the code of the passage it comes from (for example |
If you change it |
Stricter rules → more statements carry a source, answers are easier to check. Looser rules → smoother text, but sources go missing and cannot be matched to statements |
Keep |
The code format, and the attachment word in square brackets (default |
Placeholders |
None |
Attachment citation token
Runs |
In answers that use a file attached to the message |
What it does |
The word the model writes in square brackets after a statement taken from the attached file instead of your documents. Only one word, without the brackets. The default is |
If you change it |
Translate it, for example into German ( |
Keep |
The citation rules must use the same word, or statements from attachments are not recognised as sources |
The save refuses an empty word ("The token cannot be empty.") and a word with square brackets or a line break ("Write the token as a single line without square brackets — the container adds those.").
Keep the two in step. After you save Citation rules or Attachment citation token, the tab checks if the citation rules still contain the word in square brackets. If not, the save goes through, but you see a warning:
The citation rules no longer mention [word], the attachment citation token. Update the other one too, or claims drawn from attachments will not be recognised as citations.
This is a warning, not a refusal, because changing both takes two saves. Save the other one next.
Image sources block
Runs |
Added after the found text passages, only when stored pictures belong to these passages. This needs Store pictures in the database and Show pictures in answers (Image Handling, Configuration tab) |
What it does |
Lists the available pictures and tells the model how to place one in the answer |
If you change it |
Ask to use pictures more often → more answers show pictures, also less fitting ones. Less often → cleaner answers, but helpful pictures may be left out |
Placeholders |
1. the list of pictures, one line per picture with its marker |
Source filter check — section Source filter
Runs |
After the answer is written, for found passages the answer did not mark with a source code. It runs on the Language Model |
What it does |
Checks which of these passages the answer really used. Only those are shown as sources below the answer |
If you change it |
Stricter (only clearly used passages) → fewer, more exact sources. Looser (also passages on the same subject) → more sources, some of them not really used |
Keep |
The answer lines in the form |
Placeholders |
1. the answer, 2. the numbered passages (E1, E2, …), 3. the "used" word, 4. the "not used" word |
8. When changes take effect
The topic receives its prompts when it starts. A saved prompt does not reach a topic that is already running.
-
Topic is running (or starting): the save message says "This topic is running — stop and start it again for the change to reach the container." Stop the topic and start it again in the topic list.
-
Topic is stopped: the save message says "A restart is required for it to reach the container." The next start uses the new text.
Upload prompts then apply to documents uploaded after the start. Chat prompts apply to the next message.
|
A prompt that no longer fits is skipped at start. If a new version changes the number of gaps
in a default, an older own text of that prompt may no longer match. The topic then uses the
built-in default for this prompt instead, and the chat shows no error. Open the prompt, compare it
with Restore default, and save it again with the right number of |
9. Permissions
| Permission | Allows |
|---|---|
|
Open the topic and read every prompt. The tab shows "You have view access only — the editors below are read-only." The button is View instead of Edit, and the dialog has only Close |
|
Change and save prompts |
You also need access to the topic itself: one of your roles must be among the topic’s roles. See Roles and Permissions.
The prompts can also be changed through the management REST API, with the same checks. See REST API.
10. Troubleshooting
| Symptom | Cause and fix |
|---|---|
A saved prompt has no effect |
The topic was running when you saved. Stop and start it. Also check that the job runs at all: for example keyword generation needs |
"This prompt needs exactly n %s placeholder(s) and has m." |
Put back the missing |
"… is neither a %s slot nor an escaped percent sign." |
A single |
"This template must contain {context} …" |
Put |
"This topic has a Custom System Prompt …" |
Put |
"This prompt cannot be empty." |
Use Restore default, then Save, to go back to the default |
"Could not save the prompt. Please try again." |
The save failed for another reason. Try again; if it repeats, check the application log |
Every chat message is slow, also "thanks" |
The router answer cannot be read, so every message is searched. Check that your Router text still asks for the JSON with |
Answers show too many sources |
The Source filter check answer cannot be read. Keep the |
Statements from attached files show no source |
Citation rules and Attachment citation token use different words. Make them the same |
Pictures are not described with the new text |
The topic does not describe pictures (Describe pictures with a vision model is off), or the documents were uploaded before the restart. Turn it on, restart, and upload again |
Old documents do not change after editing an upload prompt |
Upload prompts only affect new uploads. Upload the documents again |
A change in Admin → LLM Configuration does not reach this topic |
The topic has its own text for that row (Customised for this topic). Restore default and Save to follow the global text again |
No Edit button, only View |
Your role lacks |
Related
-
Topic Configuration — Custom System Prompt, routing, retrieval, chunking and image settings
-
Global LLM Configuration — the shared system prompt, context template and no-answer response