OpenWebUI(4)源码学习-后端routers路由模块

📁 引言

目录 open-webui\backend\open_webui\routers 包含多个 FastAPI 路由模块，用于定义后端 API 接口。这些路由模块负责处理用户请求、文件管理、知识库构建、音频处理等功能。以下是该目录下各文件的详细功能解释：

---

📁 audio.py

• 作用：实现与音频相关的接口，如上传音频文件并提取其内容。
• 核心功能：
  • 支持上传音频文件（如 .mp3, .wav）。
  • 使用 Whisper 模型进行语音转文字（ASR）。
  • 提供下载音频和获取音频内容的功能。
• 关键接口：
  • /audio/upload：上传音频文件。
  • /audio/transcribe：对音频进行语音识别。
  • /audio/{id}/content：获取音频对应的文本内容。

---

📁 auths.py

• 作用：处理用户认证相关逻辑，包括登录、注册、Token 验证等。
• 核心功能：
  • 用户注册与登录流程。
  • JWT Token 的生成与验证。
  • OAuth 登录支持。
• 关键接口：
  • /auth/login：用户登录。
  • /auth/register：新用户注册。
  • /auth/verify：Token 校验。

---

📁 channels.py

• 作用：提供与频道（Channel）管理相关的 API，通常用于消息分组或聊天室管理。
• 核心功能：
  • 创建、删除、更新频道信息。
  • 管理频道成员权限。
• 关键接口：
  • /channels/create：创建新频道。
  • /channels/list：列出所有频道。
  • /channels/{id}/members：管理频道成员。

---

📁 chats.py

• 作用：实现聊天会话管理功能，包括创建、读取、更新和删除聊天记录。
• 核心功能：
  • 创建新的聊天会话。
  • 存储和检索聊天历史。
  • 支持将聊天保存到特定文件夹。
• 关键接口：
  • /chats/create：创建新聊天。
  • /chats/{id}：获取指定 ID 的聊天记录。
  • /chats/{id}/update：更新聊天内容。

---

📁 configs.py

• 作用：提供系统配置管理接口，允许管理员动态调整应用设置。
• 核心功能：
  • 获取当前系统配置。
  • 更新系统参数（如 OCR 引擎、模型路径等）。
• 关键接口：
  • /config/get：获取当前配置。
  • /config/update：更新配置项。

---

📁 evaluations.py

• 作用：评估模型输出质量，可能用于 A/B 测试或多模型对比。
• 核心功能：
  • 记录模型输出结果。
  • 对比不同模型在相同输入下的表现。
• 关键接口：
  • /evaluations/compare：比较两个模型的输出。
  • /evaluations/log：记录模型输出以供后续分析。

---

📁 files.py

• 作用：管理文件上传、下载、删除及内容提取。
• 核心功能：
  • 文件上传并存储至指定路径。
  • 支持多种文件格式的内容提取（如 PDF、Word、HTML）。
  • 提供文件元数据管理接口。
• 关键接口：
  • /files/upload：上传文件。
  • /files/{id}/content：获取文件内容。
  • /files/search：按名称搜索文件。

---

📁 folders.py

• 作用：实现文件夹结构管理，用于组织文件、聊天等资源。
• 核心功能：
  • 创建、删除、重命名文件夹。
  • 将文件或聊天归类至特定文件夹。
• 关键接口：
  • /folders/create：创建新文件夹。
  • /folders/list：列出用户所有文件夹。
  • /folders/{id}/update：重命名文件夹。

---

📁 functions.py

• 作用：提供插件函数管理功能，允许用户导入外部 Python 函数。
  主要功能：

1. 插件加载：

   • 支持从任意 URL 加载 .py 插件文件（如 GitHub Raw 链接）。
   • 自动转换 GitHub tree 和 blob 链接为原始文件链接。

2. 函数同步与注册：

   • 提供函数列表获取接口。
   • 支持同步函数状态，确保插件缓存一致性。

3. 安全性控制：

   • 插件加载仅限管理员操作。
   • 不允许加载敏感文件（如 main.py, __init__.py）。

4. 缓存机制：

   • 使用本地缓存避免重复下载插件文件。

---

📁 groups.py

核心作用：
实现用户组管理接口，支持创建用户组、分配权限、批量管理成员。

主要功能：

1. 组管理：

   • 创建、更新、删除用户组。
   • 添加/移除组成员。

2. 权限继承：

   • 组权限继承至组内所有成员。
   • 支持为组设置模型访问权限、功能使用权限等。

3. 组内资源访问控制：

   • 组内成员可共享知识库、模型、插件等资源。

---

📁 images.py

核心作用：
处理图像生成、上传、下载及图像内容分析相关逻辑。

主要功能：

1. 图像生成接口：

   • 接收文本描述，调用图像生成模型（如 Stable Diffusion）生成图片。

2. 图像上传与管理：

   • 支持图像上传、存储、按 ID 下载。
   • 图像文件存储由 [Storage](file://D:\GiteeDownloadProject\AIStudyProject\open-webui\backend\open_webui\storage\provider.py#L372-L372) 模块统一管理。

3. 图像内容理解（CV）：

   • 支持图像描述生成（Image Captioning）。
   • 支持图像内嵌文字识别（OCR）。

4. 访问控制：

   • 用户只能访问自己上传的图像。
   • 管理员可访问所有图像。

---

📁 knowledge.py

核心作用：
实现知识库管理接口，支持创建、删除、更新知识库，并将文件内容导入知识库以支持语义搜索。

主要功能：

1. 知识库 CRUD：

   • 创建新知识库。
   • 删除已有知识库及其关联数据。
   • 更新知识库元数据（如名称、描述、访问控制策略）。

2. 文件与知识库绑定：

   • 支持将多个文件批量导入知识库。
   • 自动调用 [process_file](file://D:\GiteeDownloadProject\AIStudyProject\open-webui\backend\open_webui\routers\retrieval.py#L1233-L1422) 提取文件内容并写入向量数据库。
   • 支持失败重试和错误汇总反馈。

3. 访问控制：

   • 基于用户 ID 和访问控制策略（ACL）判断用户是否有权限读写知识库。
   • 管理员拥有最高权限。

4. 向量数据库交互：

   • 使用 [VECTOR_DB_CLIENT](file://D:\GiteeDownloadProject\AIStudyProject\open-webui\backend\open_webui\retrieval\vector\factory.py#L54-L54) 操作向量数据库。
   • 支持根据知识库名称进行内容检索。

典型应用场景：

• 构建企业级私有知识库。
• 为聊天机器人提供上下文增强能力。
• 实现基于文档的问答系统。

---

📁memories.py

memories.py 是 Open WebUI 系统中用于管理用户对话记忆的模块，主要负责在多轮对话中保存、读取和管理上下文信息。它为聊天机器人提供长期记忆能力，使得模型能够在多个对话回合中记住用户的历史交互内容。

🔍 memories.py的核心作用

1. 维护用户对话历史：

   • 存储用户与 AI 之间的多轮对话记录。
   • 支持将历史对话作为上下文传递给模型，提升对话连贯性。

2. 实现长期记忆机制：

   • 即使在页面刷新或会话结束后，仍能保留关键信息。
   • 可选择性地持久化重要记忆片段（如用户偏好、关键事实等）。

3. 支持个性化记忆管理：

   • 每个用户拥有独立的记忆空间。
   • 记忆数据可按时间排序、检索、更新或清除。

4. 增强 RAG 和提示工程能力：

   • 将记忆内容注入到提示词中，帮助模型更好地理解上下文。
   • 可结合知识库使用，实现“记忆 + 知识”的混合推理。

🧠 主要接口说明

接口路径	方法	功能描述
/memories/user/memory	GET	获取当前登录用户的记忆数据
/memories/user/memory/update	POST	添加/更新一条记忆记录
/memories/user/memory/clear	DELETE	清空当前用户的所有记忆

💡 典型应用场景

• 用户连续提问时保持上下文一致性（如：“上一个问题中的参数是多少？”）。
• 记录用户偏好（如语言、主题、常用模型等），实现个性化响应。
• 在多轮对话中自动引用之前的结论或数据，避免重复输入。
• 构建具有“长期记忆”的虚拟助手，支持跨会话对话。

🔐 权限控制

• 仅授权用户访问自己的记忆数据。
• 管理员无特殊权限，除非显式配置允许全局访问。
• 使用 get_verified_user 中间件确保身份验证。

🧩 与其他模块的关系

模块	关系说明
chats.py	提供对话上下文，供 memories 提取记忆
prompts.py	可将记忆注入提示词模板中
models.py	结合模型调用逻辑，实现上下文感知
knowledge.py	可将记忆内容写入知识库，形成永久记忆

---

📁models.py

核心作用：
管理模型相关的路由，包括模型列表展示、模型状态同步、模型权限控制等。

主要功能：

1. 模型列表展示：

   • 显示所有可用模型及其元信息（如类型、来源、最后更新时间）。
   • 支持管理员查看隐藏模型。

2. 模型状态同步：

   • 定期拉取模型列表（如 Ollama、OpenAI 等模型源）。
   • 同步模型信息到数据库。

3. 模型访问控制：

   • 控制哪些用户可以访问特定模型。
   • 支持全局模型和私有模型两种模式。

4. 模型元信息管理：

   • 支持编辑模型别名、描述、可见性等属性。

---

📁notes.py

核心作用：
实现便签管理接口，支持用户创建、编辑、删除笔记内容。

主要功能：

1. 笔记增删改查：

   • 支持 Markdown 编辑。
   • 笔记内容可关联到知识库或聊天记录。

2. 笔记组织：

   • 支持按文件夹分类管理笔记。
   • 支持全文搜索笔记内容。

3. 权限控制：

   • 用户只能访问自己的笔记。
   • 管理员可访问所有笔记。

---

📁 ollama.py

核心作用：
对接 Ollama 本地模型服务，提供模型列表获取、模型下载、模型信息同步等功能。

主要功能：

1. Ollama 模型管理：

   • 列出本地已安装模型。
   • 拉取新模型。
   • 删除模型。

2. 模型调用接口：

   • 提供兼容 Ollama 原生接口的代理服务。
   • 支持流式输出。

3. 模型缓存与优化：

   • 支持模型自动更新。
   • 缓存模型元数据。

---

📁 openai.py

核心作用：
实现 OpenAI 兼容的 API 接口，使系统能够代理 OpenAI 请求，同时支持自定义模型参数、缓存、转发用户信息等扩展功能。

主要功能：

1. 请求代理：

   • 接收标准 OpenAI 格式的请求（如 /chat/completions）。
   • 转发至目标模型服务（如本地运行的 LLM 或远程 API）。

2. 模型参数注入：

   • 动态注入系统提示词、模型参数（temperature, top_p, etc.）。
   • 支持 logit_bias 等高级参数的预处理。

3. 缓存支持：

   • 对重复请求启用缓存机制（通过 aiocache 实现）。

4. 权限与访问控制：

   • 验证用户是否有权访问特定模型。
   • 支持 BYPASS 模式绕过模型访问控制（管理员专用）。

5. 流式响应支持：

   • 返回 StreamingResponse 支持实时流式输出。

---

📁 pipelines.py

核心作用：
实现流程自动化接口，支持构建端到端的 AI 流水线（如“上传 PDF -> 提取内容 -> 生成摘要”）。

主要功能：

1. 流水线定义：

   • 通过 JSON 定义流程节点（输入、处理、输出）。
   • 支持链式调用多个服务（如 OCR + NLP + 输出）。

2. 流水线执行：

   • 自动执行整个流程并返回最终结果。
   • 支持异步执行和进度跟踪。

3. 流水线复用：

   • 可保存常用流程模板供重复使用。

---

📁 prompts.py

核心作用：
管理预设提示词模板，支持用户自定义 prompt 并用于模型推理。

主要功能：

1. 提示词管理：

   • 支持增删改查预设提示词。
   • 提示词可绑定到特定模型或用户。

2. 提示词应用：

   • 在聊天过程中引用预设提示词。
   • 支持提示词变量替换机制。

3. 权限控制：

   • 全局提示词对所有用户可见。
   • 私有提示词仅创建者可见。

---

📁 retrieval.py

核心作用：
提供文档内容处理和检索接口，用于将上传的文件进行内容提取，并将其转换为可用于 RAG（Retrieval-Augmented Generation）的结构化文档。

主要功能：

1. process_file 函数：

   • 接收一个文件 ID 和可选的内容或知识库集合名称。
   • 根据是否有指定collection_name或content来决定是否重新处理文件内容。
   • 若未提供内容但有路径，则使用Loader调用底层解析引擎（如 Tika、Docling、Mistral OCR 等）来提取文件内容。
   • 提取后的文档内容会被存储到向量数据库中（如 ChromaDB），以便后续进行语义检索。

2. 与知识库联动：

   • 支持将文件内容添加到指定的知识库集合中。
   • 可查询已有知识库中的文件内容并返回。

3. 调用时机：

   • 当用户上传文件后自动触发。
   • 在知识库管理界面中手动添加/更新文件时调用。

关键依赖：

• 使用了 [VECTOR_DB_CLIENT]open-webui\backend\open_webui\retrieval\vector\factory.py#L54-L54进行向量数据库操作。
• 通过 [Loader]open-webui\backend\open_webui\retrieval\loaders\main.py#L193-L378类统一调度不同文档解析引擎（Tika、Docling、Mistral OCR 等）。

---

📁 tasks.py

核心作用：
实现后台任务队列管理接口，支持异步任务调度（如大规模文件处理、模型训练等）。

主要功能：

1. 任务提交与监控：

   • 提交长时间运行的任务。
   • 查询任务状态和日志。

2. 任务队列管理：

   • 支持优先级、重试、超时等任务控制选项。
   • 支持任务取消和暂停。

3. 事件通知：

   • 支持任务完成时发送通知（如 WebSocket、邮件）。

---

📁 tools.py

核心作用：
提供工具调用接口，支持调用外部工具（如计算器、天气查询等）并返回结果。

主要功能：

1. 工具调用接口：

   • 支持调用已注册的工具。
   • 工具调用支持同步和异步执行。

2. 工具注册与发现：

   • 支持从插件目录自动加载工具。
   • 支持通过 /tools/load 接口远程加载工具脚本。

3. 权限控制：

   • 只有管理员可以注册或删除工具。
   • 普通用户可以调用工具。

---

📁 users.py

核心作用：
管理用户账户、角色、权限、设置等信息，提供用户认证、权限校验等功能。

主要功能：

1. 用户权限配置：

   • 定义用户在工作区、共享、聊天、功能等维度的权限。
   • 控制是否允许使用 Web 搜索、图像生成、代码解释器等功能。

2. 角色管理：

   • 支持管理员 (admin) 和普通用户 (user)
   • 允许修改用户角色（仅管理员）。

3. 用户设置获取与更新：

   • 获取当前用户的个性化设置（如偏好模型、语言、主题等）。
   • 修改用户资料信息。

4. 安全机制：

   • 基于 JWT 的身份认证。
   • 使用中间件校验用户身份和权限。

---

📁 utils.py

核心作用：
通用工具函数集，为其他模块提供辅助功能。

主要功能：

1. 文件操作：

   • 文件路径处理、编码检测、缓存清理等。

2. 网络请求封装：

   • 提供带超时、SSL 设置的 HTTP 客户端封装。
   • 支持异步请求（AioHTTP）。

3. 日志与调试：

   • 日志级别控制。
   • 错误信息封装。

4. 缓存机制：

   • 支持内存缓存、文件缓存、Redis 缓存。

5. 权限检查：

   • 提供通用权限判断函数（如 [has_access]open-webui\backend\open_webui\utils\access_control.py#L109-L125。

---