Open WebUI 是怎么让 LLM挑对工具的一次工具调用的完整链路拆解【免费下载链接】open-webuiUser-friendly AI Interface (Supports Ollama, OpenAI API, ...)项目地址: https://gitcode.com/GitHub_Trending/op/open-webuiOpen WebUI 解决的核心痛点是自托管 AI 界面里模型只会聊天不会动手。它把工具调用做成了数据库驱动的插件系统——你注册一段 Python 代码模型就能在对话里调用它。读完本文你能独立画出一句话请求从输入到执行再到返回的完整链路并知道加一个自定义工具要动哪几个文件。能力全景它不是静态 API 网关而是模型自己点菜的工具市场传统做法是你写好 if-else 路由把用户意图映射到固定接口。Open WebUI 反过来把所有工具的函数规格OpenAPI 风格 JSON交给模型让模型自己在候选池里点名。核心能力一共四块工具注册工具就是一行数据库记录content字段存 Python 源码specs字段存函数规格条件注入内置工具文件、知识库、日历、自动化等 60 个按模型能力和用户权限动态拼装不是一股脑全塞给模型远程工具服务器通过server:前缀的 ID 接入外部 OpenAPI 或 MCP 服务运行时参数valves机制让管理员不用改代码就能给工具配密钥、改阈值这张图是 Open WebUI 的完整界面左侧工具栏和右侧聊天区对应着本文要拆解的工具调用链路。一次完整调用的旅程以你在对话框输入查一下我的知识库里关于部署流程的内容整理成笔记为例走一遍全链路。意图解析——Open WebUI 自己并不听懂你的话反直觉的第一点Open WebUI 没有写任何 NLP 意图识别或关键词匹配算法。它做的是准备一份高质量的菜单——get_builtin_tools会根据当前模型的能力声明capabilities、模型挂载的知识库、以及全局开关决定这次请求把哪些内置函数塞进菜单你手动勾选的自定义工具则通过tool_ids显式传入。菜单以函数规格的形式发给模型听懂这一步由 LLM 的 function calling 能力完成。这个取舍后面设计决策章节会专门展开这里先记住系统只负责备菜点菜的是模型。工具匹配——从候选池到可调用对象真正干活的是get_tools它拿着一批tool_id把数据库里的代码变成进程里可调用的函数。权限不过关的工具会被静默跳过代码长这样# backend/open_webui/utils/tools.py if ( not (user.role admin and BYPASS_ADMIN_ACCESS_CONTROL) and tool.user_id ! user.id and not await AccessGrants.has_access( user_iduser.id, resource_typetool, resource_idtool.id, permissionread, user_group_idsuser_group_ids, ) ): continue # ← 没权限就跳过不告诉模型它的存在能过权限的工具接着发生三件事模块加载与缓存首次遇到某个工具时exec它的 Python 源码之后命中缓存直接复用。缓存判断比对了内容# backend/open_webui/utils/tools.py module tools_cache.get(tool_id) if module is None or tool_contents_cache.get(tool_id) ! tool.content: module, _ await load_tool_module_by_id(tool_id, contenttool.content) # ← 内容变了才重新 exec tools_cache[tool_id] module tool_contents_cache[tool_id] tool.content内部参数注入每个函数被包一层模型只能看到业务参数__id__、__user__这些上下文由后端偷偷塞进函数签名所有__前缀的字段会从 spec 里剥掉避免泄露给模型。命名冲突处理两个工具定义了同名函数时后注册的会自动改名成{tool_id}_{function_name}不会互相覆盖。权限关卡——三道校验层层收窄第一道在刚才的get_tools里read 权限决定工具能不能进菜单。第二道在工具函数内部——内置工具对敏感操作会再做细粒度检查比如改笔记前要验证你对这条笔记的 write 权限见backend/open_webui/tools/builtin.py里的_has_write_access_to_note。第三道是数据隔离__user__参数贯穿整个调用链工具函数只能看到当前用户的视图view_file这类函数会显式核对文件归属或 access grants。也就是说模型即使被诱导调用了不该调的工具数据层也拿不到别人的东西。执行引擎——异步 exec不阻塞事件循环自定义工具的源码是存在数据库content字段里的 Python 代码。加载逻辑在backend/open_webui/utils/plugin.py的load_tool_module_by_id里# backend/open_webui/utils/plugin.py module types.ModuleType(ftool_{tool_id}) sys.modules[module_name] module # ← 先注册import 才不炸 ... exec(content, module.__dict__) if hasattr(module, Tools): return module.Tools(), frontmatter # ← 约定必须有 Tools 类源码通过 frontmatter文件头 YAML 块声明requirements加载时会pip install缺的依赖——这一步用asyncio.to_thread丢到线程池避免阻塞事件循环。整个工具函数都是async的模型一次请求点多个工具时并发执行主线程不卡。结果回传——工具输出是模型的下一句话工具执行完返回值以tool角色的消息追加回上下文模型基于结果生成最终回复。整个对话流通过 SSE 逐 token 推给前端有些内置工具比如写笔记还会顺手通过 socket 发一个events:note事件让笔记列表实时刷新不用你手动刷新页面。前端拿到的就是和普通回复无差别的流式文本工具痕迹以可折叠的调用块形式展示在消息里。这张图展示的是首次进入 Open WebUI 时的对话界面工具调用结果最终就渲染在这个流式消息区。值得注意的设计决策工具代码存数据库 运行时 exec而不是打包进镜像决策点自定义工具的实现代码放哪。备选方案是像传统插件那样放在磁盘目录、随服务镜像分发。Open WebUI 选了存数据库Tool.content字段、首次调用时exec。为什么多租户场景下每个用户都能在界面里即时创建和修改自己的工具改完立刻生效不用重新部署或同步文件load_tool_module_by_id里甚至有replace_imports自动纠正用户写错的 import 路径。代价没有沙箱——你的工具代码和后端同权限运行一个恶意或手滑的工具可以读到open_webui的任何东西。这是把信任前置给了工具注册人而不是执行层。让 LLM 选工具而不是写匹配算法决策点谁来决定调用哪个工具。备选是系统自己做意图分类关键词、嵌入相似度。Open WebUI 把所有选择权交给模型的 function calling。为什么匹配逻辑的质量天花板取决于你的分类器而 function calling 的天花板取决于模型后者每年都在涨且工具数量少几十个时把 spec 全给模型完全可行。代价spec 里的description直接决定匹配准确率——get_tools里会刻意从 docstring 第一行提取描述写回 spec就是在提醒你的注释写烂了工具就永远不会被选中。模块级缓存挂在 request.app.state而不是 Redis决策点加载好的模块对象缓存在哪。备选是 Redis 这类外部缓存项目里确实有 Redis 配置。Open WebUI 选了request.app.state上的两个 dictTOOLS/TOOL_CONTENTS进程内共享。为什么模块对象本身不可序列化放 Redis 没意义进程内 dict 零开销且天然一致。代价多 worker 部署时每个进程各持一份且只在工具内容变更时失效——你删了工具但没改内容旧模块会一直赖在内存里。安全防线怎么串起来的换个攻击者视角走一遍。你的输入先经过提示词进入模型模型可能幻觉出不存在的参数或调用——这层靠 spec 的类型约束挡掉clean_openai_tool_schema负责清理发给模型前的 schema。参数拿到手不等于能执行get_tools的 access grants 校验上一节贴过决定工具进不进菜单。就算菜单里的工具被恶意调用函数体内部还有第二层数据权限核对。而最危险的入口其实是工具源码本身——exec没有隔离所以防线的设计是把关口前移谁能创建工具、谁能编辑工具由AccessGrants的 write 权限管住backend/open_webui/models/tools.py里创建时同步写授权记录。输出侧execute_code等高危工具的代码会先过sanitize_code清洗。整条链的衔接逻辑是每一层都假设上一层失效而不是指望单一入口。二次开发最短路径5 步注册一个自定义工具假设你想加一个查公司内部 Jira的工具。注册界面上点 New Tool 填名字或直接调 API前端封装就是这 5 行// src/lib/apis/tools/index.ts const res await fetch(${WEBUI_API_BASE_URL}/tools/create, { method: POST, headers: { authorization: Bearer ${token} }, body: JSON.stringify(tool) })写代码tool的content是一段 Python约定必须有Tools类类方法就是可调用函数class Tools: def search_issues(self, query: str) - str: 按关键词搜索 Jira 缺陷单返回标题和状态列表 ...写 docstring它就是 spec 的 description模型靠它决定何时调用你配 valves可选定义class Valves管理员就能在界面给工具配 API Key存进加密的valves字段调通保存后首次调用会触发load_tool_module_by_id自动 exec之后在聊天里 提及或直接让模型用观察调用块是否出现三个落地场景场景一知识库问答。你说查一下知识库里关于回滚操作的内容 → 模型看到菜单里的query_knowledge_bases自己填了查询参数向量检索命中相关段落 → 回复里直接引用了检索到的文档片段调用块里能看到命中的条目。场景二附件变笔记。你拖进一个 PDF 说总结要点存成笔记 → 模型先调view_file读文件先过归属校验再调write_note落库socket 事件让笔记列表即时多出一条 → 你不用刷新就能看到新笔记。场景三定时提醒。你说明天上午 9 点提醒我交周报 → 模型调create_automation建任务、配timer定时间 → 到点自动化触发notify推送到你配置的通知渠道。性能与扩展性使用者能直接感知到的三点工具列表接口支持defer_content列几十个工具时跳过content大字段列表秒开批量加载工具走单条IN查询get_tools_by_ids不是一工具一查pip install依赖离线程执行冷启动不卡住整个事件循环。缓存策略一句话加载好的模块和源码指纹存在request.app.state的进程内 dict 里内容不变就永远命中变更检测靠比对tool.content。插件扩展的入口就 5 行约定这也是你二次开发要遵守的全部接口# 自定义工具模块的最小约定content 字段内容 class Tools: def my_tool(self, arg: str) - str: 一句描述模型靠它选你 return result接下来往哪走仓库里已经出现三个明确信号Terminal 服务器get_terminal_servers、terminal_context_*系列函数已进utils/tools.py工具开始跑在后端 shell 里而不是纯 HTTP 调用对使用者意味着你的工具能操作本地文件系统而不仅是查 APIMCP 协议接入backend/open_webui/utils/mcp/外部 MCP 工具服务器可以和本地工具混排在同一菜单里意味着你不用重写已有 MCP 生态的工具子代理委派内置工具里的delegate_task、配置项subagents.enable模型可以派子任务出去意味着单轮工具调用会扩展成多轮自主执行valves 和 access grants 的权限边界会更重要写在最后想动手验证的话从backend/open_webui/utils/tools.py的get_tools开始读起——它一个函数就串起了权限、缓存、参数注入三件事读完再对照backend/open_webui/utils/plugin.py的load_tool_module_by_id整条链路就通了。【免费下载链接】open-webuiUser-friendly AI Interface (Supports Ollama, OpenAI API, ...)项目地址: https://gitcode.com/GitHub_Trending/op/open-webui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Open WebUI 是怎么让 LLM“挑对工具“的：一次工具调用的完整链路拆解
Open WebUI 是怎么让 LLM挑对工具的一次工具调用的完整链路拆解【免费下载链接】open-webuiUser-friendly AI Interface (Supports Ollama, OpenAI API, ...)项目地址: https://gitcode.com/GitHub_Trending/op/open-webuiOpen WebUI 解决的核心痛点是自托管 AI 界面里模型只会聊天不会动手。它把工具调用做成了数据库驱动的插件系统——你注册一段 Python 代码模型就能在对话里调用它。读完本文你能独立画出一句话请求从输入到执行再到返回的完整链路并知道加一个自定义工具要动哪几个文件。能力全景它不是静态 API 网关而是模型自己点菜的工具市场传统做法是你写好 if-else 路由把用户意图映射到固定接口。Open WebUI 反过来把所有工具的函数规格OpenAPI 风格 JSON交给模型让模型自己在候选池里点名。核心能力一共四块工具注册工具就是一行数据库记录content字段存 Python 源码specs字段存函数规格条件注入内置工具文件、知识库、日历、自动化等 60 个按模型能力和用户权限动态拼装不是一股脑全塞给模型远程工具服务器通过server:前缀的 ID 接入外部 OpenAPI 或 MCP 服务运行时参数valves机制让管理员不用改代码就能给工具配密钥、改阈值这张图是 Open WebUI 的完整界面左侧工具栏和右侧聊天区对应着本文要拆解的工具调用链路。一次完整调用的旅程以你在对话框输入查一下我的知识库里关于部署流程的内容整理成笔记为例走一遍全链路。意图解析——Open WebUI 自己并不听懂你的话反直觉的第一点Open WebUI 没有写任何 NLP 意图识别或关键词匹配算法。它做的是准备一份高质量的菜单——get_builtin_tools会根据当前模型的能力声明capabilities、模型挂载的知识库、以及全局开关决定这次请求把哪些内置函数塞进菜单你手动勾选的自定义工具则通过tool_ids显式传入。菜单以函数规格的形式发给模型听懂这一步由 LLM 的 function calling 能力完成。这个取舍后面设计决策章节会专门展开这里先记住系统只负责备菜点菜的是模型。工具匹配——从候选池到可调用对象真正干活的是get_tools它拿着一批tool_id把数据库里的代码变成进程里可调用的函数。权限不过关的工具会被静默跳过代码长这样# backend/open_webui/utils/tools.py if ( not (user.role admin and BYPASS_ADMIN_ACCESS_CONTROL) and tool.user_id ! user.id and not await AccessGrants.has_access( user_iduser.id, resource_typetool, resource_idtool.id, permissionread, user_group_idsuser_group_ids, ) ): continue # ← 没权限就跳过不告诉模型它的存在能过权限的工具接着发生三件事模块加载与缓存首次遇到某个工具时exec它的 Python 源码之后命中缓存直接复用。缓存判断比对了内容# backend/open_webui/utils/tools.py module tools_cache.get(tool_id) if module is None or tool_contents_cache.get(tool_id) ! tool.content: module, _ await load_tool_module_by_id(tool_id, contenttool.content) # ← 内容变了才重新 exec tools_cache[tool_id] module tool_contents_cache[tool_id] tool.content内部参数注入每个函数被包一层模型只能看到业务参数__id__、__user__这些上下文由后端偷偷塞进函数签名所有__前缀的字段会从 spec 里剥掉避免泄露给模型。命名冲突处理两个工具定义了同名函数时后注册的会自动改名成{tool_id}_{function_name}不会互相覆盖。权限关卡——三道校验层层收窄第一道在刚才的get_tools里read 权限决定工具能不能进菜单。第二道在工具函数内部——内置工具对敏感操作会再做细粒度检查比如改笔记前要验证你对这条笔记的 write 权限见backend/open_webui/tools/builtin.py里的_has_write_access_to_note。第三道是数据隔离__user__参数贯穿整个调用链工具函数只能看到当前用户的视图view_file这类函数会显式核对文件归属或 access grants。也就是说模型即使被诱导调用了不该调的工具数据层也拿不到别人的东西。执行引擎——异步 exec不阻塞事件循环自定义工具的源码是存在数据库content字段里的 Python 代码。加载逻辑在backend/open_webui/utils/plugin.py的load_tool_module_by_id里# backend/open_webui/utils/plugin.py module types.ModuleType(ftool_{tool_id}) sys.modules[module_name] module # ← 先注册import 才不炸 ... exec(content, module.__dict__) if hasattr(module, Tools): return module.Tools(), frontmatter # ← 约定必须有 Tools 类源码通过 frontmatter文件头 YAML 块声明requirements加载时会pip install缺的依赖——这一步用asyncio.to_thread丢到线程池避免阻塞事件循环。整个工具函数都是async的模型一次请求点多个工具时并发执行主线程不卡。结果回传——工具输出是模型的下一句话工具执行完返回值以tool角色的消息追加回上下文模型基于结果生成最终回复。整个对话流通过 SSE 逐 token 推给前端有些内置工具比如写笔记还会顺手通过 socket 发一个events:note事件让笔记列表实时刷新不用你手动刷新页面。前端拿到的就是和普通回复无差别的流式文本工具痕迹以可折叠的调用块形式展示在消息里。这张图展示的是首次进入 Open WebUI 时的对话界面工具调用结果最终就渲染在这个流式消息区。值得注意的设计决策工具代码存数据库 运行时 exec而不是打包进镜像决策点自定义工具的实现代码放哪。备选方案是像传统插件那样放在磁盘目录、随服务镜像分发。Open WebUI 选了存数据库Tool.content字段、首次调用时exec。为什么多租户场景下每个用户都能在界面里即时创建和修改自己的工具改完立刻生效不用重新部署或同步文件load_tool_module_by_id里甚至有replace_imports自动纠正用户写错的 import 路径。代价没有沙箱——你的工具代码和后端同权限运行一个恶意或手滑的工具可以读到open_webui的任何东西。这是把信任前置给了工具注册人而不是执行层。让 LLM 选工具而不是写匹配算法决策点谁来决定调用哪个工具。备选是系统自己做意图分类关键词、嵌入相似度。Open WebUI 把所有选择权交给模型的 function calling。为什么匹配逻辑的质量天花板取决于你的分类器而 function calling 的天花板取决于模型后者每年都在涨且工具数量少几十个时把 spec 全给模型完全可行。代价spec 里的description直接决定匹配准确率——get_tools里会刻意从 docstring 第一行提取描述写回 spec就是在提醒你的注释写烂了工具就永远不会被选中。模块级缓存挂在 request.app.state而不是 Redis决策点加载好的模块对象缓存在哪。备选是 Redis 这类外部缓存项目里确实有 Redis 配置。Open WebUI 选了request.app.state上的两个 dictTOOLS/TOOL_CONTENTS进程内共享。为什么模块对象本身不可序列化放 Redis 没意义进程内 dict 零开销且天然一致。代价多 worker 部署时每个进程各持一份且只在工具内容变更时失效——你删了工具但没改内容旧模块会一直赖在内存里。安全防线怎么串起来的换个攻击者视角走一遍。你的输入先经过提示词进入模型模型可能幻觉出不存在的参数或调用——这层靠 spec 的类型约束挡掉clean_openai_tool_schema负责清理发给模型前的 schema。参数拿到手不等于能执行get_tools的 access grants 校验上一节贴过决定工具进不进菜单。就算菜单里的工具被恶意调用函数体内部还有第二层数据权限核对。而最危险的入口其实是工具源码本身——exec没有隔离所以防线的设计是把关口前移谁能创建工具、谁能编辑工具由AccessGrants的 write 权限管住backend/open_webui/models/tools.py里创建时同步写授权记录。输出侧execute_code等高危工具的代码会先过sanitize_code清洗。整条链的衔接逻辑是每一层都假设上一层失效而不是指望单一入口。二次开发最短路径5 步注册一个自定义工具假设你想加一个查公司内部 Jira的工具。注册界面上点 New Tool 填名字或直接调 API前端封装就是这 5 行// src/lib/apis/tools/index.ts const res await fetch(${WEBUI_API_BASE_URL}/tools/create, { method: POST, headers: { authorization: Bearer ${token} }, body: JSON.stringify(tool) })写代码tool的content是一段 Python约定必须有Tools类类方法就是可调用函数class Tools: def search_issues(self, query: str) - str: 按关键词搜索 Jira 缺陷单返回标题和状态列表 ...写 docstring它就是 spec 的 description模型靠它决定何时调用你配 valves可选定义class Valves管理员就能在界面给工具配 API Key存进加密的valves字段调通保存后首次调用会触发load_tool_module_by_id自动 exec之后在聊天里 提及或直接让模型用观察调用块是否出现三个落地场景场景一知识库问答。你说查一下知识库里关于回滚操作的内容 → 模型看到菜单里的query_knowledge_bases自己填了查询参数向量检索命中相关段落 → 回复里直接引用了检索到的文档片段调用块里能看到命中的条目。场景二附件变笔记。你拖进一个 PDF 说总结要点存成笔记 → 模型先调view_file读文件先过归属校验再调write_note落库socket 事件让笔记列表即时多出一条 → 你不用刷新就能看到新笔记。场景三定时提醒。你说明天上午 9 点提醒我交周报 → 模型调create_automation建任务、配timer定时间 → 到点自动化触发notify推送到你配置的通知渠道。性能与扩展性使用者能直接感知到的三点工具列表接口支持defer_content列几十个工具时跳过content大字段列表秒开批量加载工具走单条IN查询get_tools_by_ids不是一工具一查pip install依赖离线程执行冷启动不卡住整个事件循环。缓存策略一句话加载好的模块和源码指纹存在request.app.state的进程内 dict 里内容不变就永远命中变更检测靠比对tool.content。插件扩展的入口就 5 行约定这也是你二次开发要遵守的全部接口# 自定义工具模块的最小约定content 字段内容 class Tools: def my_tool(self, arg: str) - str: 一句描述模型靠它选你 return result接下来往哪走仓库里已经出现三个明确信号Terminal 服务器get_terminal_servers、terminal_context_*系列函数已进utils/tools.py工具开始跑在后端 shell 里而不是纯 HTTP 调用对使用者意味着你的工具能操作本地文件系统而不仅是查 APIMCP 协议接入backend/open_webui/utils/mcp/外部 MCP 工具服务器可以和本地工具混排在同一菜单里意味着你不用重写已有 MCP 生态的工具子代理委派内置工具里的delegate_task、配置项subagents.enable模型可以派子任务出去意味着单轮工具调用会扩展成多轮自主执行valves 和 access grants 的权限边界会更重要写在最后想动手验证的话从backend/open_webui/utils/tools.py的get_tools开始读起——它一个函数就串起了权限、缓存、参数注入三件事读完再对照backend/open_webui/utils/plugin.py的load_tool_module_by_id整条链路就通了。【免费下载链接】open-webuiUser-friendly AI Interface (Supports Ollama, OpenAI API, ...)项目地址: https://gitcode.com/GitHub_Trending/op/open-webui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考