How a RAG Topic Works — From Upload to Answer

This page follows one file and one question through a RAG Topic. You learn what happens to a file after you upload it, and what happens between your question in the chat and the answer you read.

You do not need this page to use a Topic. Read it when you want to understand why a Topic answers the way it does, which setting changes which step, and where to look when an answer is not what you expected.

A Topic does its work in two separate phases:

Phase	When it runs	What it does
A · Upload	Once per file, when you upload it	Reads the file, cuts it into small pieces and stores them so they can be found
B · Chat	For every question	Finds the pieces that match the question and lets the model write an answer from them

Phase

When it runs

What it does

A · Upload

Once per file, when you upload it

Reads the file, cuts it into small pieces and stores them so they can be found

B · Chat

For every question

Finds the pieces that match the question and lets the model write an answer from them

The two phases only meet in the stored pieces. A setting for phase A (for example the chunk size) changes only files you upload afterwards. A setting for phase B (for example Top-K) works on the very next question.

flowchart LR subgraph A["A · Upload (once per file)"] direction TB U1["File"] --> U2["Read the text"] --> U3["Cut into pieces"] --> U4["Turn pieces into numbers"] end S[("Stored pieces
+ keyword index
+ pictures")] subgraph B["B · Chat (every question)"] direction TB Q1["Question"] --> Q2["Search the pieces"] --> Q3["Model writes the answer"] --> Q4["Answer + sources"] end A --> S --> B

1. Phase A — From file to stored pieces

The whole path

flowchart TD F["You upload a file"] --> C1{"File type?"} C1 -->|"Text file
txt, md, source code"| T1["Read as text"] C1 -->|"Structured file
json, xml, yaml, toml, csv, tsv"| T2["One record at a time"] C1 -->|"Document
pdf, docx, xlsx, pptx"| T3["Docling converts it to text
and lifts out the pictures"] C1 -->|"Image
jpg, png, ..."| T4["One picture"] T2 --> T2a{"Import Strategy?"} T2a -->|"Flatten (default)"| T2b["Each record becomes
'key: value' lines"] T2a -->|"Narrate"| T2c["The model rewrites each record
as a short paragraph"] T4 --> T4a["Vision model describes it
(if switched on)"] T1 --> X["Text"] T2b --> X T2c --> X T3 --> X T3 --> P["Pictures from the document
(described and stored, if switched on)"] T4a --> X X --> K{"Chunking Strategy?"} K -->|"RECURSIVE (default)"| K1["Cut at paragraphs,
then sentences, then words"] K -->|"SEMANTIC"| K2["Same cut, then the model adds
a short context line to every piece"] K1 --> L["Link pictures to the pieces
that mention them"] K2 --> L P --> L L --> E["Embedding model turns every piece
into numbers"] E --> V[("Vector database")] L --> H{"Retrieval Strategy
HYBRID?"} H -->|"Yes"| I[("Keyword index")] H -->|"No"| Z["No keyword index"]

Step by step

# Step What happens What you can influence What you notice

#	Step	What happens	What you can influence	What you notice
1	Receive	The Topic checks the file name and the file type. A file whose type the Topic does not accept is refused at once.	File Types in the wizard (step 2)	A refused file shows a message at upload
2	Read the text	The text is taken out of the file in the way its type needs (see the table below). A document needs a Docling server. Without one, the upload is refused.	Docling Server, Docling Settings (advanced), Import Strategy	PDF and Office files take longest. Large scans can take minutes
3	Replace the old version	If a file with the same name is already stored, its pieces, keywords and pictures are removed. The old version stays intact while a Docling conversion is still running.	—	A re-upload fully replaces the file
4	Pictures	Pictures inside documents, and uploaded image files, can be described by a vision model. The description becomes searchable text. Each picture can also be stored, so an answer can show it later.	Describe pictures with a vision model, Store pictures in the database, Show pictures in answers	Uploads with many pictures take longer. Without a description, an image can only be found by its file name
5	Cut into pieces (chunks)	The text is cut into pieces of at most Chunk Size characters, and each piece repeats Chunk Overlap characters of the one before it. Code blocks are not split. With SEMANTIC, a model writes one short line for every piece that says where the piece belongs in the document.	Chunking Strategy, Chunk Size, Chunk Overlap	SEMANTIC finds pieces better, but needs one model call per piece, so large files take much longer
6	Link pictures	A piece that contains a picture’s description, caption or neighbouring text is tagged with that picture.	—	The chat can later show the picture next to an answer that uses this piece
7	Embed and store	The embedding model turns each piece into a list of numbers that stands for its meaning. The numbers and the text are written to the vector database. The original file is kept so that source links can open it.	Embedding Model, Vector Database	If the embedding model is not reachable, the upload fails
8	Keyword index	Only with HYBRID: each piece is also written to a keyword index. With Keyword Enrichment `ALGORITHMIC`, the words of the piece are used. With `LLM`, a model writes keywords for each piece.	Retrieval Strategy, Keyword Enrichment	`LLM` adds one model call per piece. It applies only to files uploaded afterwards

Receive

The Topic checks the file name and the file type. A file whose type the Topic does not accept is refused at once.

File Types in the wizard (step 2)

A refused file shows a message at upload

Read the text

The text is taken out of the file in the way its type needs (see the table below). A document needs a Docling server. Without one, the upload is refused.

Docling Server, Docling Settings (advanced), Import Strategy

PDF and Office files take longest. Large scans can take minutes

Replace the old version

If a file with the same name is already stored, its pieces, keywords and pictures are removed. The old version stays intact while a Docling conversion is still running.

—

A re-upload fully replaces the file

Pictures

Pictures inside documents, and uploaded image files, can be described by a vision model. The description becomes searchable text. Each picture can also be stored, so an answer can show it later.

Describe pictures with a vision model, Store pictures in the database, Show pictures in answers

Uploads with many pictures take longer. Without a description, an image can only be found by its file name

Cut into pieces (chunks)

The text is cut into pieces of at most Chunk Size characters, and each piece repeats Chunk Overlap characters of the one before it. Code blocks are not split. With SEMANTIC, a model writes one short line for every piece that says where the piece belongs in the document.

Chunking Strategy, Chunk Size, Chunk Overlap

SEMANTIC finds pieces better, but needs one model call per piece, so large files take much longer

Link pictures

A piece that contains a picture’s description, caption or neighbouring text is tagged with that picture.

—

The chat can later show the picture next to an answer that uses this piece

Embed and store

The embedding model turns each piece into a list of numbers that stands for its meaning. The numbers and the text are written to the vector database. The original file is kept so that source links can open it.

Embedding Model, Vector Database

If the embedding model is not reachable, the upload fails

Keyword index

Only with HYBRID: each piece is also written to a keyword index. With Keyword Enrichment ALGORITHMIC, the words of the piece are used. With LLM, a model writes keywords for each piece.

Retrieval Strategy, Keyword Enrichment

LLM adds one model call per piece. It applies only to files uploaded afterwards

How the text is read, by file type

File type How the text is read Model calls

File type	How the text is read	Model calls
Text files (txt, md, source code, …)	Read as plain text	None
Structured files (json, xml, yaml, toml, csv, tsv)	Split into records first — for example one table row or one array entry — so that a record is never cut in the middle. Flatten writes each record as `key: value` lines. Narrate lets the model rewrite each record as a short paragraph.	Flatten: none. Narrate: one per record
Documents (pdf, docx, xlsx, pptx, scans)	The Docling server converts the file to text and lifts out its pictures	One conversion call per file
Images (jpg, png, gif, …)	The picture is stored as one piece. Its description (from the vision model) is the text	One per picture, if description is on

Text files (txt, md, source code, …)

Read as plain text

None

Structured files (json, xml, yaml, toml, csv, tsv)

Split into records first — for example one table row or one array entry — so that a record is never cut in the middle. Flatten writes each record as key: value lines. Narrate lets the model rewrite each record as a short paragraph.

Flatten: none. Narrate: one per record

Documents (pdf, docx, xlsx, pptx, scans)

The Docling server converts the file to text and lifts out its pictures

One conversion call per file

Images (jpg, png, gif, …)

The picture is stored as one piece. Its description (from the vision model) is the text

One per picture, if description is on

What is stored afterwards

What	Where	Used for
The text pieces and their numbers	Vector database	Finding pieces by meaning
The keyword index	In the Topic (only with HYBRID)	Finding exact words, names and codes
The pictures of documents	In the Topic	Showing them in answers
The original file	In the Topic	Download links on sources

What

Where

Used for

The text pieces and their numbers

Vector database

Finding pieces by meaning

The keyword index

In the Topic (only with HYBRID)

Finding exact words, names and codes

The pictures of documents

In the Topic

Showing them in answers

The original file

In the Topic

Download links on sources

If something goes wrong during an upload

A document without a Docling server is refused. The message says that Docling is needed.
A file with no readable text (an empty file, or a scan that Docling could not read) is stored, but nothing of it can be found. The Topic logs a warning.
An upload that fails after the old version was removed leaves the file without pieces. Upload it again. There is no automatic rollback.

2. Phase B — From question to answer

The whole path

flowchart TD Q["You send a question
(and maybe a file)"] --> M["Add the earlier messages of this chat"] M --> R{"Route before retrieval
switched on?"} R -->|"Yes"| R1["One model call decides:
search, or answer without searching"] R -->|"No"| S R1 -->|"Chit-chat, thanks,
'make it shorter'"| D["DIRECT answer
from the conversation"] R1 -->|"Question the attached
file answers alone"| AT["ATTACHMENT answer
from the file"] R1 -->|"Needs your documents
or unsure"| S["Search the stored pieces"] D -->|"Model says it needs documents"| S AT -->|"Model says it needs documents"| S S --> S1{"Retrieval Strategy"} S1 -->|"DENSE"| S2["Search by meaning"] S1 -->|"HYBRID"| S3["Search by meaning
and by keywords, then merge"] S2 --> F["Drop pieces below
Min. Similarity Score
keep the Top-K best"] S3 --> F F --> RR{"Reranking Strategy"} RR -->|"LLM"| RR1["Model sorts the candidates
by how well they answer"] RR -->|"NONE"| P RR1 --> P["Build the prompt:
instructions + pieces + history + question"] P --> G["Language model writes the answer
(may ask other Topics as tools)"] G --> W["Place pictures, turn citations into file names,
check which documents the answer used"] W --> OUT["Answer, streamed word by word,
with sources"] D --> OUT AT --> OUT G -.->|"No piece and no tool
contributed"| NA["No-answer response"] OUT --> H["Saved in the chat history"]

Step by step

# Step What happens What you can influence What you notice

#	Step	What happens	What you can influence	What you notice
1	Receive the question	The question arrives with the chat’s session. A text file you attach is read and its text is added to the question. A picture you attach goes to the model as it is.	Chat Attachments (allowed types, Largest Chat Attachment)	A picture needs a chat model that can see pictures. Files over the size limit are refused with a message
2	Add the history	The model sees the last messages of this chat, so a follow-up such as "and for the second one?" makes sense. Older messages drop out.	Memory on the LLM Overrides tab	Raising the memory keeps more context, but makes each answer slower and more expensive
3	Route (optional)	With Route before retrieval on, one model call decides if a search is needed. DIRECT answers thanks, small talk and requests like "shorter" or "as a table" from the conversation alone. ATTACHMENT answers a question that only the attached file can answer. Everything else, and every unsure case, is searched. If the model finds that it cannot answer after all, the question is searched.	Route before retrieval, Router Confidence Threshold (default 0.9)	Answers to chit-chat come fast and show no sources. A higher threshold sends more messages to the search: safer, slower
4	Search	The question is turned into numbers. The pieces with the closest numbers are found (DENSE). With HYBRID, a keyword search runs too, and both lists are merged into one. Keywords help with product codes, error numbers and names.	Retrieval Strategy	HYBRID finds exact terms better. It needs the keyword index, which is written during upload: files uploaded while the Topic used DENSE have none
5	Filter	Pieces that match less than the Min. Similarity Score are dropped. At most Top-K Results pieces are kept.	Top-K Results, Min. Similarity Score	A high score: only close matches, but more "I don’t know". A high Top-K: fuller answers, slower, and more unrelated content
6	Rerank (optional)	With `LLM`, the search first collects about three times as many pieces as Top-K. A model reads them and sorts them by how well they answer the question. The best Top-K go on.	Reranking Strategy	More exact answers, but one more model call per question
7	Build the prompt	The model gets: the shared system prompt with your Custom System Prompt, the chosen pieces (each with a short code so the model can cite it), the rules for citing, the history and the question.	Custom System Prompt (wizard, step 1), the Prompts tab, Admin → LLM Configuration	The wording and tone of the answer. This does not change which pieces are found
8	Answer	The language model writes the answer from the pieces. If the Topic is connected to other Topics (MCP Interfaces), the model can ask them for more and use their answer.	Language Model, MCP Interfaces	The answer appears word by word. Stop ends what you see and nothing is saved, but the model server may still finish the call in the background. A tool-capable model is needed for connected Topics
9	Finish the answer	Pictures the model placed are shown at their position. Citation codes become file names. A check keeps only the documents the answer really used (cited, quoted, or confirmed by a model check).	Show pictures in answers	Sources show below the answer as badges. A source link works for about 10 minutes
10	No answer	If no piece and no tool contributed, the Topic does not show the model’s text. It shows the configured no-answer response instead.	No-answer response on the Prompts tab	You see a fixed sentence instead of an invented answer
11	Save	The question and answer are saved in the chat history, so you can reopen them later. A turn that you stopped is not saved.	—	History in the chat window

Receive the question

The question arrives with the chat’s session. A text file you attach is read and its text is added to the question. A picture you attach goes to the model as it is.

Chat Attachments (allowed types, Largest Chat Attachment)

A picture needs a chat model that can see pictures. Files over the size limit are refused with a message

Add the history

The model sees the last messages of this chat, so a follow-up such as "and for the second one?" makes sense. Older messages drop out.

Memory on the LLM Overrides tab

Raising the memory keeps more context, but makes each answer slower and more expensive

Route (optional)

With Route before retrieval on, one model call decides if a search is needed. DIRECT answers thanks, small talk and requests like "shorter" or "as a table" from the conversation alone. ATTACHMENT answers a question that only the attached file can answer. Everything else, and every unsure case, is searched. If the model finds that it cannot answer after all, the question is searched.

Route before retrieval, Router Confidence Threshold (default 0.9)

Answers to chit-chat come fast and show no sources. A higher threshold sends more messages to the search: safer, slower

Search

The question is turned into numbers. The pieces with the closest numbers are found (DENSE). With HYBRID, a keyword search runs too, and both lists are merged into one. Keywords help with product codes, error numbers and names.

Retrieval Strategy

HYBRID finds exact terms better. It needs the keyword index, which is written during upload: files uploaded while the Topic used DENSE have none

Filter

Pieces that match less than the Min. Similarity Score are dropped. At most Top-K Results pieces are kept.

Top-K Results, Min. Similarity Score

A high score: only close matches, but more "I don’t know". A high Top-K: fuller answers, slower, and more unrelated content

Rerank (optional)

With LLM, the search first collects about three times as many pieces as Top-K. A model reads them and sorts them by how well they answer the question. The best Top-K go on.

Reranking Strategy

More exact answers, but one more model call per question

Build the prompt

The model gets: the shared system prompt with your Custom System Prompt, the chosen pieces (each with a short code so the model can cite it), the rules for citing, the history and the question.

Custom System Prompt (wizard, step 1), the Prompts tab, Admin → LLM Configuration

The wording and tone of the answer. This does not change which pieces are found

Answer

The language model writes the answer from the pieces. If the Topic is connected to other Topics (MCP Interfaces), the model can ask them for more and use their answer.

Language Model, MCP Interfaces

The answer appears word by word. Stop ends what you see and nothing is saved, but the model server may still finish the call in the background. A tool-capable model is needed for connected Topics

Finish the answer

Pictures the model placed are shown at their position. Citation codes become file names. A check keeps only the documents the answer really used (cited, quoted, or confirmed by a model check).

Show pictures in answers

Sources show below the answer as badges. A source link works for about 10 minutes

No answer

If no piece and no tool contributed, the Topic does not show the model’s text. It shows the configured no-answer response instead.

No-answer response on the Prompts tab

You see a fixed sentence instead of an invented answer

Save

The question and answer are saved in the chat history, so you can reopen them later. A turn that you stopped is not saved.

—

History in the chat window

Where the model calls happen

Each model call costs time and, for cloud models, money. This is where a Topic uses them:

When Call Only if

When	Call	Only if
Upload	Docling conversion	The file is a document
Upload	Picture description	Describe pictures with a vision model is on
Upload	Narration, one per record	Narrate
Upload	Context line, one per piece	SEMANTIC
Upload	Keywords, one per piece	Keyword Enrichment `LLM`
Upload	Embedding of every piece	Always
Chat	Router	Route before retrieval is on
Chat	Embedding of the question	Always
Chat	Reranking	Reranking Strategy `LLM`
Chat	Answer	Always
Chat	Source check	When the answer does not clearly cite its sources

Upload

Docling conversion

The file is a document

Upload

Picture description

Describe pictures with a vision model is on

Upload

Narration, one per record

Narrate

Upload

Context line, one per piece

SEMANTIC

Upload

Keywords, one per piece

Keyword Enrichment LLM

Upload

Embedding of every piece

Always

Chat

Router

Route before retrieval is on

Chat

Embedding of the question

Always

Chat

Reranking

Reranking Strategy LLM

Chat

Answer

Always

Chat

Source check

When the answer does not clearly cite its sources

3. Seeing it happen — the DEV Reports tab

If you need to know exactly what a Topic did, use the DEV Reports tab of the Topic. Switch on Report uploads or Report chat answers, upload a file or ask a question, and the tab shows every step above: the text that was read, each piece, the pieces found for a question with their scores, the prompt the model received, and the answer before and after the final checks.

The switches are off after every start of the Topic. Reports contain full prompts and documents. Only users with the permission DEV_REPORTING can see them. How to read a report: DEV Reports. The Logs tab shows the same steps in short form.

4. Which setting fixes which problem

Symptom Step What to try

Symptom	Step	What to try
A file is accepted, but the chat never finds its content	2, 5	Check the Indexed Documents list on the Data Upload tab. A scan without readable text yields no pieces. Check Docling Settings
Exact codes or names are not found	4	Use HYBRID. Upload the files again, because the keyword index is only written at upload
Answers contain unrelated content	5, 6	Raise Min. Similarity Score, lower Top-K Results, or use Reranking `LLM`
Answers say "I don’t know" too often	5	Lower Min. Similarity Score, or raise Top-K Results
Facts in a long document are missing	5	Smaller Chunk Size: more exact pieces. Use SEMANTIC so every piece says where it belongs
Uploads take very long	2, 4, 5	Check SEMANTIC, Narrate, picture description and Keyword Enrichment `LLM`: each adds a model call per piece or record
A chat message gets no sources	3	The router may have answered from the conversation. Switch Route before retrieval off, or raise the threshold
The answer is correct, but its tone is wrong	7	Change Custom System Prompt or the prompts on the Prompts tab

A file is accepted, but the chat never finds its content

2, 5

Check the Indexed Documents list on the Data Upload tab. A scan without readable text yields no pieces. Check Docling Settings

Exact codes or names are not found

Use HYBRID. Upload the files again, because the keyword index is only written at upload

Answers contain unrelated content

5, 6

Raise Min. Similarity Score, lower Top-K Results, or use Reranking LLM

Answers say "I don’t know" too often

Lower Min. Similarity Score, or raise Top-K Results

Facts in a long document are missing

Smaller Chunk Size: more exact pieces. Use SEMANTIC so every piece says where it belongs

Uploads take very long

2, 4, 5

Check SEMANTIC, Narrate, picture description and Keyword Enrichment LLM: each adds a model call per piece or record

A chat message gets no sources

The router may have answered from the conversation. Switch Route before retrieval off, or raise the threshold

The answer is correct, but its tone is wrong

Change Custom System Prompt or the prompts on the Prompts tab

RAG Topics — Overview — what a Topic is and what it can do
Creating a Topic — every wizard setting named above
Configuring a Topic — settings after creation
Prompts — the texts the model receives
Using the chat — sources, pictures and attachments
GraphRAG: how it works — the same path for a GraphRAG Topic

How a RAG Topic Works — From Upload to Answer

1. Phase A — From file to stored pieces

The whole path

Step by step

How the text is read, by file type

What is stored afterwards

If something goes wrong during an upload

2. Phase B — From question to answer

The whole path

Step by step

Where the model calls happen

3. Seeing it happen — the DEV Reports tab

4. Which setting fixes which problem

Related