From 9e66dd41db2008aabe045fceceb8734a036b3afd Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Fri, 20 Feb 2026 21:12:28 +0100 Subject: [PATCH] builtin file handling --- .../extensibility/plugin/tools/index.mdx | 2 + docs/troubleshooting/rag.mdx | 60 ++++++++++++++++++ .../features/plugin/tools/builtin_tools.png | Bin 0 -> 9489 bytes 3 files changed, 62 insertions(+) create mode 100644 static/images/features/plugin/tools/builtin_tools.png diff --git a/docs/features/extensibility/plugin/tools/index.mdx b/docs/features/extensibility/plugin/tools/index.mdx index 2399285e..b9e1c1dd 100644 --- a/docs/features/extensibility/plugin/tools/index.mdx +++ b/docs/features/extensibility/plugin/tools/index.mdx @@ -318,6 +318,8 @@ The **Builtin Tools** capability can be toggled on or off for each model in the When the **Builtin Tools** capability is enabled, you can further control which **categories** of builtin tools are available to the model. This appears in the Model Editor as a set of checkboxes under **Builtin Tools**. +![Builtin Tools categories in the Model Editor](/images/features/plugin/tools/builtin_tools.png) + | Category | Tools Included | Description | |----------|----------------|-------------| | **Time & Calculation** | `get_current_timestamp`, `calculate_timestamp` | Get current time and perform date/time calculations | diff --git a/docs/troubleshooting/rag.mdx b/docs/troubleshooting/rag.mdx index 68ebdb61..729ebaa0 100644 --- a/docs/troubleshooting/rag.mdx +++ b/docs/troubleshooting/rag.mdx @@ -379,5 +379,65 @@ If you are running a version with this fix and still experiencing worker death, --- +### 13. Knowledge Base Attached to Model Not Working + +You attached a knowledge base to a model in **Workspace > Models > Edit**, but when you chat with the model it doesn't seem to know about the knowledge base content at all. + +**The Problem**: Open WebUI has two distinct RAG modes, and they handle model-attached knowledge bases very differently: + +| Mode | How Knowledge Works | +|------|-------------------| +| **Default (non-native)** | Open WebUI automatically performs RAG — it queries the attached knowledge base, retrieves relevant chunks, and injects them into the conversation context. This happens behind the scenes without the model doing anything. | +| **Native Function Calling** | Knowledge is **not auto-injected**. Instead, the model receives tools (like `query_knowledge_bases`) and must actively decide to call them. This is **agentic RAG** — the model autonomously searches when it determines it needs information. | + +If you have **Native Function Calling enabled**, the model needs both the **ability** and the **instruction** to use the knowledge tools. + +#### Knowledge Retrieval Behavior Matrix + +| | **KB Attached to Model** | **No KB Attached** | +|---|---|---| +| **Default Mode** | Open WebUI auto-injects RAG results from the **attached KB(s) only** | No automatic RAG — user must manually add a knowledge base to the chat via `#` | +| **Native Function Calling** | Model receives tools scoped to **attached KB(s) only** — must actively call them | Model receives tools with access to **all accessible KBs** (if Builtin Tools enabled) — must actively call them | + +Key takeaway: in default mode, attaching a KB enables automatic RAG scoped to those KBs. In native mode, the model must use its tools regardless — attaching a KB only restricts *which* KBs are searchable. + +:::tip Preventing Knowledge Base Access in Native Mode +If you want to prevent a model from accessing **any** knowledge base in native mode, you don't need to disable Builtin Tools entirely. Instead, disable only the **Knowledge Base** category in **Workspace > Models > Edit > Builtin Tools**. This removes all knowledge-related tools while keeping other builtin tools (web search, memory, notes, etc.) active. See [Granular Builtin Tool Categories](/features/extensibility/plugin/tools#granular-builtin-tool-categories-per-model) for the full list of categories. +::: + +![Builtin Tools categories in the Model Editor](/images/features/plugin/tools/builtin_tools.png) + +✅ **Solutions (check in order):** + +1. **Ensure Built-in Tools are enabled for the model**: + - Go to **Workspace > Models > Edit** for your model + - Under **Builtin Tools**, make sure the **Knowledge Base** category is enabled (it is by default) + - If this is disabled, the model has no way to query attached knowledge bases + +2. **Add a system prompt hint**: + - Some models need explicit guidance to use their tools. Add something like: + > "When users ask questions, first use list_knowledge_bases to see what knowledge is available, then use query_knowledge_bases to search for relevant information before answering." + +3. **Or disable Native Function Calling** for that model: + - In the model settings, disable Native Function Calling to restore the classic auto-injection RAG behavior from earlier versions + +4. **Or use Full Context mode**: + - Click on the attached knowledge base and select **"Use Entire Document"** + - This bypasses RAG entirely and always injects the full content, regardless of native function calling settings + +:::info Why the Change? +Open WebUI is moving toward **agentic RAG**, where the model autonomously decides when and how to search knowledge bases. This is more powerful than classic RAG because the model can retry searches with different queries if the first attempt didn't yield good results. However, it does require models that are capable of using tools effectively. For smaller or older models that struggle with tool calling, disabling Native Function Calling is the recommended approach. +::: + +For the full explanation of how knowledge scoping and retrieval modes work, see the [Knowledge documentation](/features/ai-knowledge/knowledge#native-mode-agentic-mode-knowledge-tools) and [File Context vs Builtin Tools](/features/chat-conversations/rag#file-context-vs-builtin-tools). + +--- + +| Problem | Fix | +|--------|---------:| +| 🧠 Model ignores attached knowledge base | Enable Builtin Tools, add system prompt hints, or disable native function calling | + +--- + By optimizing these areas—extraction, embedding, retrieval, and model context—you can dramatically improve how accurately your LLM works with your documents. Don't let a 2048-token window or weak retrieval pipeline hold back your AI's power 🎯. diff --git a/static/images/features/plugin/tools/builtin_tools.png b/static/images/features/plugin/tools/builtin_tools.png new file mode 100644 index 0000000000000000000000000000000000000000..d8492bec5c5e14d4b83ecaefdafe03e69914e929 GIT binary patch literal 9489 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