Multiple UI elements deciding on full context vs. chunks

[jdeepwell]

I've tried to find this in the documentation and also searched the discussions in docs and in the code repo but could not get a clear answer there. As this is not about a request for a functionality change/addition but about how things currently work, I am posting here.

There are three user interface elements regarding which part of an uploaded document is used in the context.

1. Admin Panel / Settings / Documents / "Bypass Embedding and Retrieval" (enable/disable)
2. Admin Panel / Settings / Documents / "Full Context Mode" (enable/disable)
3. In the chat window, when uploading a document and after it was digested (converted to markdown) clicking on it (document preview), I see a "Use Entire Document" / "Use Focused Retrieval" toggle

Question 1

What is the difference between enabling "Bypass Embedding and Retrieval" and enabling "Full Context Mode" in the admin settings? I don't understand what use it is to have chunking and embedding configured when "Full Context" mode forces the whole document content into the context anyway.

Question 2

When I enable "Full Context Mode" in the admin settings, I still see the "Use Entire Document"/"Use Focused Retrieval" toggle in the document panel of the chat window. Does this toggle then do nothing?

Question 3

If I disable "Full Context Mode" in the admin settings, will the uploaded document then always be chunked right after digesting? Even when I select "Use Entire Document" in the document panel of the chat window? Or does the chunking only happen after I submit the first prompt, depending on whether I chose "Use Entire Document" or "Use Focused Retrieval"?
(I am assuming that chunking big documents takes time, so I would prefer it to only happen when needed)

Question 4

Is there a way to disable "Full Context Mode" in the admin settings, but still choose "Use Entire Document" as the default, so users do not need to enter the documents panel in the chat windows for each uploaded document to switch to it? ("Use Entire Document" is the most common case on our server, but I don't want to rob the users of the RAG option)

If anyone would spend the time to shed some light on these questions I would be enormously grateful!

[Classic298]

Good questions, the three controls overlap in a confusing way. Here is exactly how they behave in the current code.

The three controls

• Bypass Embedding and Retrieval (admin, global) acts at upload time. The file is digested to text and stored, but it is not chunked or embedded and no vector collection is created. At chat time the whole content is injected.
• Full Context Mode (admin, global) acts at query time: the whole document is injected instead of retrieved chunks. It does not change upload processing, the document is still chunked and embedded at upload.
• Use Entire Document / Use Focused Retrieval (the per-file toggle in the chat document panel) is a per-file, per-chat override that forces that file to full content at query time. The effective rule is full_context = (attached file is set to "Use Entire Document") OR (Full Context Mode is on).

Q1, Bypass vs Full Context Mode. Both inject the whole document at chat time. The difference is at upload:

• Full Context Mode still chunks and embeds every uploaded file (the embeddings still land in the vector DB; they are just not used for retrieval in that chat). You pay the embedding cost.
• Bypass skips chunking and embedding entirely. Faster upload, no embedding cost, no vector entries.

So if your goal is "always use the whole document and don't waste embedding", Bypass is the one you want. Full Context Mode mainly makes sense if you still want documents embedded for other retrieval while defaulting chats to full content.

Q2, does the toggle still do anything with Full Context Mode on? Effectively no. With Full Context Mode on, the query-time rule is forced to full for every file, so the toggle cannot switch a file back to focused retrieval. UI gotcha: a normally-uploaded file shows the toggle as "Use Focused Retrieval" by default, yet the system still uses full content because the global setting overrides it.

Q3, when does chunking happen? At upload, right after the document is digested, inside process_file. It is gated only by Bypass Embedding and Retrieval. Neither Full Context Mode nor the per-file toggle defers or skips it. So with both admin toggles off (the default), every uploaded document is chunked and embedded immediately, even if you intend to use "Use Entire Document". There is no "chunk only on first prompt" or "chunk only if needed" path. The only way to avoid upload-time chunking is Bypass.

Q4, default to "Use Entire Document" without forcing it globally? Not currently. For regular file uploads the default is "Use Focused Retrieval"; the per-file full default only applies to pasted large text and pasted URLs. There is no setting to make "Use Entire Document" the default for normal uploads without turning on Full Context Mode (or Bypass) globally, and those force it for everyone with no per-file focused option. A "default to full, still allow per-file focused" toggle would be a reasonable feature request.

In short: for "whole document is the common case but keep RAG available", there is no single perfect switch today. Bypass gives whole-document-always with no embedding cost but removes RAG; leaving both off keeps RAG as the default and relies on the per-file toggle.

[jdeepwell]

@Classic298
I dug through the issues and discussion posts around this topic. There are several overlapping and duplicate ones. I am working on a text consolidating it all into one feature request, referencing the others, so effort and discussion can be focused there.

If I could trouble you for some more clarifications, that would be great. I want to make sure I fully understand the current behavior before posting.

1. Regarding the fomula full_context = (every attached file is set to "Use Entire Document") OR (Full Context Mode is on)
   I'm a bit confused by the "every" in that formula. Does this mean that e.g. in a chat, all uploaded documents must be set to "Use Entire Document" so that any of them will be injected in full? So if any document is set to "Use Focused Retrieval", the whole chat will use focused retrieval for all documents, even those set to "Use Entire Document"?

2. Documents attached to chat vs. Knowledge Base
   The Use Entire Document / Use Focused Retrieval toggle is available for both, document and knowledge base items. In case of the single document it seems clear. But what does it mean for an attached knowledge base? Inside a knowledge base the individual documents do not have the toggle – it's the Knowledge Base itself that has the toggle when attached to a chat or custom model. My interpretation: When a Knowledge Base is attached to a chat or model, the toggle applies to the attached knowledge base as a whole. If the attached knowledge base item is set to "Use Entire Document", then all documents within that Knowledge Base will be injected in full at query time. Conversely, if the attached knowledge base item is set to "Use Focused Retrieval", then all documents within it will be retrieved in chunks - correct?

3. "Bypass Embedding and Retrieval" OFF but "Full Context Mode" ON
   That would mean that every document would be chunked and embedded on upload, but those chunks and embeddings would never be used in retrieval - right? Or is there any other way in OpenWebUI to use the chunks and embeddings?

[Classic298]

1. where do you have that formula from? those files attached as full context will be attached as full context, those that don't, will not.
2. then the entire knowledge base is attached as full context.
3. neither toggle has an effect on how files are handled on upload. chunks and embeddings are always created.

[jdeepwell]

Many thx for getting back to be!

where do you have that formula from?

From your first answer above :)

neither toggle has an effect on how files are handled on upload. chunks and embeddings are always created.

I understand that the toggles that the user can adjust for uploaded documents or when attaching a knowledge base have no effect on wether the documents are chunked/embedded when uploaded. But there are those two admin settings "Bypass Embedding and Retrieval" and "Full Context Mode" and there is a possible combination of "Bypass Embedding and Retrieval" OFF but "Full Context Mode" ON – that would create chunks/embeddings on upload, but they would never be used for normal retrieval in an chat.

That didn't sense to me, so I just wanted to make sure there is no other way to use the chunks and embeddings in OpenWebUI that I am maybe missing.

[Classic298]

Okay, the context mattered, the formula is wrong in the way you applied it haha. this confused me. thanks.

[Classic298]

" But there are those two admin settings "Bypass Embedding and Retrieval" and "Full Context Mode" and there is a possible combination of "Bypass Embedding and Retrieval" OFF but "Full Context Mode" ON – that would create chunks/embeddings on upload, but they would never be used for normal retrieval in an chat."

yes and thats intended, you might turn it on later