{
"canonical_name": "open-webui/open-webui",
"compilation_id": "pack_33079cfa87fb4b27b38dcacc3ba0dbae",
"created_at": "2026-05-11T10:23:04.011570+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install open-webui` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install open-webui",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_3d92df2ee3954299aa37f167b336a655"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_a0af59ccc17b5415b1863b9767e3cb81",
"canonical_name": "open-webui/open-webui",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/open-webui/open-webui",
"slug": "open-webui",
"source_packet_id": "phit_80754f987a8943d8b8eb7e3ea37fa9e0",
"source_validation_id": "dval_e2f0e782f2844612b65d669f75051cd6"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 19495,
"github_stars": 136844,
"one_liner_en": "User-friendly AI Interface (Supports Ollama, OpenAI API, ...)",
"one_liner_zh": "User-friendly AI Interface (Supports Ollama, OpenAI API, ...)",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, api, github"
},
"target_user": "使用 mcp_host, chatgpt 等宿主 AI 的用户",
"title_en": "open-webui",
"title_zh": "open-webui 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Structured Extraction",
"label_zh": "结构化提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-structured-extraction",
"type": "core_capability"
},
{
"label_en": "Verifiable Workflow",
"label_zh": "可验证工作流",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-verifiable-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_80754f987a8943d8b8eb7e3ea37fa9e0",
"page_model": {
"artifacts": {
"artifact_slug": "open-webui",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install open-webui",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/open-webui/open-webui#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"结构化提取",
"可验证工作流",
"评测体系"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "User-friendly AI Interface (Supports Ollama, OpenAI API, ...)"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, chatgpt",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:701547123 | https://github.com/open-webui/open-webui | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:701547123 | https://github.com/open-webui/open-webui | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:701547123 | https://github.com/open-webui/open-webui | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:701547123 | https://github.com/open-webui/open-webui | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:701547123 | https://github.com/open-webui/open-webui | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:701547123 | https://github.com/open-webui/open-webui | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 826,
"forks": 19495,
"license": "unknown",
"note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。",
"stars": 136844,
"open_issues": 249,
"pushed_at": "2026-05-13T06:41:31.000Z"
},
"source_url": "https://github.com/open-webui/open-webui",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "User-friendly AI Interface (Supports Ollama, OpenAI API, ...)",
"title": "open-webui 能力包",
"trial_prompt": "# open-webui - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 open-webui 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: User-friendly AI Interface (Supports Ollama, OpenAI API, ...) 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 暂无明确的运行时能力线索。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-backend-routers：后端路由与 API。围绕“后端路由与 API”模拟一次用户任务，不展示安装或运行结果。\n4. page-backend-models：数据模型层。围绕“数据模型层”模拟一次用户任务，不展示安装或运行结果。\n5. page-auth-security：认证与安全。围绕“认证与安全”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-backend-routers\n输入：用户提供的“后端路由与 API”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-backend-models\n输入：用户提供的“数据模型层”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-auth-security\n输入：用户提供的“认证与安全”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-backend-routers：Step 3 必须围绕“后端路由与 API”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-backend-models：Step 4 必须围绕“数据模型层”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-auth-security：Step 5 必须围绕“认证与安全”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/open-webui/open-webui\n- https://github.com/open-webui/open-webui#readme\n- README.md\n- backend/open_webui/__init__.py\n- backend/open_webui/constants.py\n- backend/open_webui/main.py\n- backend/open_webui/config.py\n- backend/open_webui/socket/main.py\n- src/app.html\n- svelte.config.js\n- backend/open_webui/routers/chats.py\n- backend/open_webui/routers/auths.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 open-webui 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: [BUG] v0.9.3 - Notes completely broken: cannot open or create notes (Typ（https://github.com/open-webui/open-webui/issues/24484）；github/github_issue: issue: llamacpp load/unload indicator doesn't work（https://github.com/open-webui/open-webui/issues/24544）；github/github_issue: issue: When continuing a conversation in the new version using a chat cr（https://github.com/open-webui/open-webui/issues/24522）；github/github_issue: issue: image_gen is exposed to the model even when image generation is d（https://github.com/open-webui/open-webui/issues/24532）；github/github_issue: feat: Add file types per MCP Integration（https://github.com/open-webui/open-webui/issues/24496）；github/github_issue: feat: apply filter in tool call loop（https://github.com/open-webui/open-webui/issues/24500）；github/github_issue: issue: Cmd+r on Mac (refresh page) causes chat to generate a new respons（https://github.com/open-webui/open-webui/issues/24530）；github/github_release: v0.9.5（https://github.com/open-webui/open-webui/releases/tag/v0.9.5）；github/github_release: v0.9.4（https://github.com/open-webui/open-webui/releases/tag/v0.9.4）；github/github_release: v0.9.3（https://github.com/open-webui/open-webui/releases/tag/v0.9.3）；github/github_release: v0.9.2（https://github.com/open-webui/open-webui/releases/tag/v0.9.2）；github/github_release: v0.9.1（https://github.com/open-webui/open-webui/releases/tag/v0.9.1）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "[BUG] v0.9.3 - Notes completely broken: cannot open or create notes (Typ",
"url": "https://github.com/open-webui/open-webui/issues/24484"
},
{
"kind": "github_issue",
"source": "github",
"title": "issue: llamacpp load/unload indicator doesn't work",
"url": "https://github.com/open-webui/open-webui/issues/24544"
},
{
"kind": "github_issue",
"source": "github",
"title": "issue: When continuing a conversation in the new version using a chat cr",
"url": "https://github.com/open-webui/open-webui/issues/24522"
},
{
"kind": "github_issue",
"source": "github",
"title": "issue: image_gen is exposed to the model even when image generation is d",
"url": "https://github.com/open-webui/open-webui/issues/24532"
},
{
"kind": "github_issue",
"source": "github",
"title": "feat: Add file types per MCP Integration",
"url": "https://github.com/open-webui/open-webui/issues/24496"
},
{
"kind": "github_issue",
"source": "github",
"title": "feat: apply filter in tool call loop",
"url": "https://github.com/open-webui/open-webui/issues/24500"
},
{
"kind": "github_issue",
"source": "github",
"title": "issue: Cmd+r on Mac (refresh page) causes chat to generate a new respons",
"url": "https://github.com/open-webui/open-webui/issues/24530"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.9.5",
"url": "https://github.com/open-webui/open-webui/releases/tag/v0.9.5"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.9.4",
"url": "https://github.com/open-webui/open-webui/releases/tag/v0.9.4"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.9.3",
"url": "https://github.com/open-webui/open-webui/releases/tag/v0.9.3"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.9.2",
"url": "https://github.com/open-webui/open-webui/releases/tag/v0.9.2"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.9.1",
"url": "https://github.com/open-webui/open-webui/releases/tag/v0.9.1"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "User-friendly AI Interface (Supports Ollama, OpenAI API, ...)",
"effort": "安装已验证",
"forks": 19412,
"icon": "link",
"name": "open-webui 能力包",
"risk": "可发布",
"slug": "open-webui",
"stars": 136324,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"结构化提取",
"可验证工作流",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/open-webui/open-webui 项目说明书\n\n生成时间：2026-05-11 06:57:26 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [系统架构](#page-architecture)\n- [后端路由与 API](#page-backend-routers)\n- [数据模型层](#page-backend-models)\n- [认证与安全](#page-auth-security)\n- [前端组件结构](#page-frontend-structure)\n- [前端路由页面](#page-frontend-routes)\n- [模型集成与支持](#page-model-integration)\n- [检索增强生成 (RAG)](#page-retrieval-rag)\n- [工具与函数系统](#page-tools-functions)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/open-webui/open-webui/blob/main/README.md)\n- [src/lib/constants.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)\n- [backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)\n- [backend/open_webui/env.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/env.py)\n- [backend/open_webui/retrieval/utils.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/retrieval/utils.py)\n- [backend/open_webui/routers/knowledge.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)\n- [src/lib/utils/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/utils/index.ts)\n \n\n# 项目概述\n\n## 1. 项目简介\n\nOpen WebUI 是一个开源的自托管 Web 用户界面，专为大型语言模型（LLM）交互而设计。该项目提供了一个现代化、功能丰富的 Web 界面，让用户能够轻松地与本地部署的 Ollama 模型或其他兼容的 LLM API 进行交互。\n\n项目支持多种安装方式，包括 pip 包安装和 Docker 容器化部署，并提供了丰富的功能集，涵盖对话管理、RAG（检索增强生成）、图像生成、语音模式、代码解释器等高级特性。\n\n**核心目标**：为本地 LLM 提供一个类似 ChatGPT 的流畅、直观的 Web 交互体验，同时保持数据的私密性和本地化处理。\n\n资料来源：[README.md:1-20](https://github.com/open-webui/open-webui/blob/main/README.md)\n\n---\n\n## 2. 技术架构\n\n### 2.1 整体架构\n\nOpen WebUI 采用前后端分离的架构设计：\n\n```mermaid\ngraph TD\n subgraph 前端层[\"前端层 (SvelteKit)\"]\n A[Web UI] --> B[API 客户端]\n B --> C[状态管理]\n end\n \n subgraph 后端层[\"后端层 (Python/FastAPI)\"]\n D[API 路由] --> E[业务逻辑]\n E --> F[数据访问层]\n F --> G[(SQLite/PostgreSQL)]\n end\n \n subgraph 外部服务[\"外部服务集成\"]\n H[Ollama]\n I[RAG 检索器]\n J[图像生成引擎]\n K[语音服务]\n end\n \n A --> D\n C --> E\n E --> H\n E --> I\n E --> J\n E --> K\n```\n\n### 2.2 目录结构\n\n```\nopen-webui/\n├── backend/\n│ └── open_webui/\n│ ├── __init__.py\n│ ├── config.py # 配置管理\n│ ├── env.py # 环境变量\n│ ├── constants.py # 常量定义\n│ ├── routers/ # API 路由\n│ │ └── knowledge.py # 知识库路由\n│ ├── retrieval/ # RAG 检索模块\n│ │ ├── utils.py # 文档处理工具\n│ │ └── loaders/ # 文档加载器\n│ └── utils/ # 工具函数\n│ └── middleware.py # 中间件处理\n└── src/\n ├── lib/\n │ ├── constants.ts # 前端常量\n │ ├── utils/ # 前端工具\n │ └── apis/ # API 客户端\n └── app.html # 主 HTML 模板\n```\n\n资料来源：[backend/open_webui/env.py:1-50](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/env.py)\n\n### 2.3 环境配置\n\n后端通过 `env.py` 模块管理环境配置，支持从 `.env` 文件加载配置：\n\n```python\n# 目录定义\nENV_FILE_PATH = Path(__file__).resolve()\nOPEN_WEBUI_DIR = ENV_FILE_PATH.parent # open_webui/\nBACKEND_DIR = OPEN_WEBUI_DIR.parent # backend/\nBASE_DIR = BACKEND_DIR.parent # 项目根目录\n```\n\n支持的设备类型：\n\n| 设备类型 | 说明 | 配置值 |\n|---------|------|--------|\n| CPU | 默认模式，兼容所有系统 | `USE_CUDA_DOCKER=false` |\n| CUDA | NVIDIA GPU 加速 | `USE_CUDA_DOCKER=true` |\n| MPS | Apple Silicon 加速 | 自动检测 |\n\n资料来源：[backend/open_webui/env.py:30-45](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/env.py)\n\n---\n\n## 3. 核心功能特性\n\n### 3.1 功能总览\n\nOpen WebUI 提供以下核心功能模块：\n\n| 功能模块 | 描述 | 支持范围 |\n|---------|------|---------|\n| **对话管理** | 多模型并行对话、对话历史管理 | Ollama、OpenAI 兼容 API |\n| **RAG 检索** | 文档解析、向量检索、上下文注入 | 15+ 搜索提供商 |\n| **Web 搜索** | 实时网络搜索增强回答 | SearXNG、Google PSE、Bing 等 |\n| **图像生成** | DALL-E、Gemini、ComfyUI、AUTOMATIC1111 | 本地/云端引擎 |\n| **语音模式** | 语音输入输出交互 | TTS/ASR 集成 |\n| **代码解释器** | Python 代码执行与结果展示 | Pyodide/Jupyter |\n| **多模型对话** | 同时调用多个模型协作回答 | 任意支持的模型 |\n\n资料来源：[README.md:60-100](https://github.com/open-webui/open-webui/blob/main/README.md)\n\n### 3.2 RAG 检索系统\n\n检索系统支持多种文档格式和加载器：\n\n```mermaid\ngraph LR\n A[用户上传文档] --> B[文档解析器]\n B --> C[文本提取]\n C --> D[向量存储]\n E[用户查询] --> F[向量检索]\n F --> G[上下文组装]\n G --> H[LLM 生成回答]\n D --> F\n```\n\n**支持的文档类型**：\n\n| 格式 | MIME 类型 |\n|-----|----------|\n| PDF | `application/pdf` |\n| EPUB | `application/epub+zip` |\n| Markdown | `text/markdown` |\n| Word | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |\n| 纯文本 | `text/plain` |\n| CSV | `text/csv` |\n| HTML | `text/html` |\n| Python | `text/x-python` |\n| CSS | `text/css` |\n| JavaScript | `application/x-javascript` |\n| 音频 | `audio/mpeg`, `audio/wav` |\n\n**支持的 OCR 和文档处理服务**：\n\n- TIKA Server\n- Docling\n- Mistral OCR\n- PaddleOCR VL\n- MinerU\n- Azure Document Intelligence\n\n资料来源：[src/lib/constants.ts:20-40](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)\n资料来源：[backend/open_webui/retrieval/utils.py:1-50](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/retrieval/utils.py)\n\n### 3.3 Web 搜索提供商\n\n| 提供商 | 配置标识 |\n|-------|---------|\n| SearXNG | `searxng` |\n| Google PSE | `google PSE` |\n| Brave Search | `brave` |\n| Bing | `bing` |\n| DuckDuckGo | `duckduckgo` |\n| Tavily | `tavily` |\n| Perplexity | `perplexity` |\n| Jina | `jina` |\n| Exa | `exa` |\n| Ollama Cloud | `ollama` |\n| Azure AI Search | `azure` |\n\n资料来源：[README.md:70-80](https://github.com/open-webui/open-webui/blob/main/README.md)\n\n---\n\n## 4. API 架构\n\n### 4.1 API 端点结构\n\n```mermaid\ngraph TD\n A[WebUI API] --> B[/api/v1/*]\n A --> C[/ollama/*]\n A --> D[/openai/*]\n \n B --> E[音频处理]\n B --> F[图像处理]\n B --> G[检索服务]\n B --> H[知识库管理]\n```\n\n**基础 API 路径**：\n\n| 服务 | 路径 |\n|-----|------|\n| WebUI API | `/api/v1` |\n| Ollama | `/ollama` |\n| OpenAI | `/openai` |\n| 音频 | `/api/v1/audio` |\n| 图像 | `/api/v1/images` |\n| 检索 | `/api/v1/retrieval` |\n\n资料来源：[src/lib/constants.ts:8-15](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)\n\n### 4.2 知识库 API\n\n知识库模块提供完整的 CRUD 操作：\n\n| 端点 | 方法 | 描述 |\n|-----|------|------|\n| `/knowledge/create` | POST | 创建知识库 |\n| `/knowledge/` | GET | 获取知识库列表 |\n| `/knowledge/{id}` | GET | 获取知识库详情 |\n| `/knowledge/{id}/file/add` | POST | 添加文件到知识库 |\n| `/knowledge/{id}/files/search` | GET | 搜索知识库文件 |\n\n**访问控制**：\n\n- 管理员（`admin`）拥有完全访问权限\n- 知识库创建者拥有完全访问权限\n- 其他用户需要通过访问授权（`AccessGrants`）获得读取权限\n\n资料来源：[backend/open_webui/routers/knowledge.py:1-80](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)\n资料来源：[src/lib/apis/knowledge/index.ts:1-60](https://github.com/open-webui/open-webui/blob/main/src/lib/apis/knowledge/index.ts)\n\n---\n\n## 5. 安装与部署\n\n### 5.1 安装方式对比\n\n| 安装方式 | 适用场景 | Python 版本要求 |\n|---------|---------|----------------|\n| pip 安装 | 本地开发、快速体验 | Python 3.11+ |\n| Docker | 生产环境、跨平台部署 | 无 |\n| 开发分支 | 测试最新功能 | 无 |\n\n### 5.2 pip 安装\n\n```bash\n# 安装\npip install open-webui\n\n# 启动服务\nopen-webui serve\n# 访问地址：http://localhost:8080\n```\n\n### 5.3 Docker 部署\n\n```bash\n# 标准部署\ndocker run -d -p 3000:8080 \\\n -v open-webui:/app/backend/data \\\n --name open-webui \\\n --add-host=host.docker.internal:host-gateway \\\n --restart always \\\n ghcr.io/open-webui/open-webui:main\n\n# CUDA 加速版本\ndocker run -d -p 3000:8080 \\\n -v open-webui:/app/backend/data \\\n --gpus all \\\n --name open-webui \\\n ghcr.io/open-webui/open-webui:cuda\n\n# Ollama 集成版本\ndocker run -d -p 3000:8080 \\\n -v open-webui:/app/backend/data \\\n --name open-webui \\\n ghcr.io/open-webui/open-webui:ollama\n```\n\n> [!WARNING]\n> Docker 部署时必须挂载数据卷 `-v open-webui:/app/backend/data`，否则数据库数据将在容器重建时丢失。\n\n> [!NOTE]\n> 离线环境可设置 `HF_HUB_OFFLINE=1` 环境变量阻止模型下载。\n\n资料来源：[README.md:25-120](https://github.com/open-webui/open-webui/blob/main/README.md)\n\n---\n\n## 6. 配置与定制\n\n### 6.1 系统常量配置\n\n前端通过 `src/lib/constants.ts` 定义系统级常量：\n\n```typescript\nexport const APP_NAME = 'Open WebUI';\nexport const WEBUI_VERSION = APP_VERSION;\nexport const WEBUI_BUILD_HASH = APP_BUILD_HASH;\nexport const REQUIRED_OLLAMA_VERSION = '0.1.16';\n```\n\n### 6.2 内容处理管道\n\n前端对 LLM 输出进行标准化处理：\n\n```mermaid\ngraph LR\n A[原始输出] --> B[sanitizeResponseContent]\n B --> C[processChineseContent]\n C --> D[Markdown 渲染]\n```\n\n**处理功能**：\n\n- 移除未闭合的 tokenizer 标记（`<|...`）\n- HTML 实体转义\n- 中文内容特殊格式优化\n- Markdown/LaTeX 格式标准化\n\n资料来源：[src/lib/utils/index.ts:1-50](https://github.com/open-webui/open-webui/blob/main/src/lib/utils/index.ts)\n\n### 6.3 代码解释器配置\n\n代码解释器支持两种执行引擎：\n\n| 引擎 | 执行环境 | 提示词追加 |\n|-----|---------|-----------|\n| Jupyter | 服务器端 | 无 |\n| Pyodide | 浏览器端 | Pyodide 环境提示 |\n\n**关键配置参数**：\n\n- 允许使用多种数据处理、可视化、API 调用库\n- 强制使用 `` XML 标签包裹代码\n- 输出结果需显式打印\n\n资料来源：[backend/open_webui/config.py:200-280](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)\n\n---\n\n## 7. 安全特性\n\n### 7.1 角色权限控制\n\n| 角色 | Ollama 访问 | 模型拉取 | 模型创建 | 知识库管理 |\n|-----|------------|---------|---------|-----------|\n| 管理员 | ✅ 完全 | ✅ | ✅ | ✅ |\n| 普通用户 | 受限 | ❌ | ❌ | 受限 |\n| 访客 | 受限 | ❌ | ❌ | ❌ |\n\n### 7.2 访问授权机制\n\n知识库使用 `AccessGrants` 系统控制资源访问：\n\n```python\nawait AccessGrants.has_access(\n user_id=user.id,\n resource_type='knowledge',\n resource_id=knowledge.id,\n permission='read',\n db=db,\n)\n```\n\n资料来源：[backend/open_webui/routers/knowledge.py:40-60](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)\n\n---\n\n## 8. 版本与依赖\n\n### 8.1 版本要求\n\n| 组件 | 最低版本 |\n|-----|---------|\n| Python | 3.11 |\n| Ollama | 0.1.16 |\n\n### 8.2 数据存储\n\n支持多种数据库后端：\n\n| 数据库 | 特点 | 加密支持 |\n|-------|------|---------|\n| SQLite | 默认、轻量 | ✅ 可选 |\n| PostgreSQL | 生产级、高并发 | ❌ |\n\n资料来源：[README.md:100-110](https://github.com/open-webui/open-webui/blob/main/README.md)\n\n---\n\n## 9. 相关资源\n\n- **官方文档**：https://docs.openwebui.com/\n- **更新指南**：https://docs.openwebui.com/getting-started/updating\n- **路线图**：https://docs.openwebui.com/roadmap/\n- **许可证**：项目采用 Open WebUI License，需保留品牌标识\n\n资料来源：[README.md:140-160](https://github.com/open-webui/open-webui/blob/main/README.md)\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[后端路由与 API](#page-backend-routers), [前端组件结构](#page-frontend-structure)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [backend/open_webui/main.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/main.py)\n- [backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)\n- [backend/open_webui/env.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/env.py)\n- [src/lib/constants.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)\n- [src/lib/utils/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/utils/index.ts)\n- [backend/open_webui/utils/middleware.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/middleware.py)\n \n\n# 系统架构\n\n## 概述\n\nOpen WebUI 是一个功能丰富的 Web 用户界面，专为大型语言模型（LLM）交互设计。该项目采用前后端分离的现代化架构，后端基于 FastAPI 构建 Python REST API 与 WebSocket 服务，前端使用 SvelteKit 框架实现响应式单页应用。\n\n系统支持多模型并行对话、检索增强生成（RAG）、代码解释器执行、语音模式等高级功能，同时提供灵活的数据库与存储选项（SQLite、PostgreSQL、S3 等）。\n\n资料来源：[backend/open_webui/main.py:1-50]()\n\n## 整体架构图\n\n```mermaid\ngraph TB\n subgraph 前端层[\"前端层 (SvelteKit)\"]\n UI[用户界面]\n WS_CLIENT[WebSocket 客户端]\n API_CLIENT[API 客户端]\n end\n\n subgraph 后端层[\"后端层 (FastAPI)\"]\n API_GATEWAY[API 网关]\n \n subgraph API路由[\"API 路由模块\"]\n TASKS[tasks 路由]\n IMAGES[images 路由]\n AUDIO[audio 路由]\n RETRIEVAL[retrieval 路由]\n CONFIGS[configs 路由]\n AUTHS[auths 路由]\n USERS[users 路由]\n CHANNELS[channels 路由]\n CHATS[chats 路由]\n NOTES[notes 路由]\n MODELS[models 路由]\n KNOWLEDGE[knowledge 路由]\n PROMPTS[prompts 路由]\n TOOLS[tools 路由]\n SKILLS[skills 路由]\n MEMORIES[memories 路由]\n FOLDERS[folders 路由]\n GROUPS[groups 路由]\n FILES[files 路由]\n end\n \n WS_SERVER[WebSocket 服务]\n MIDDLEWARE[中间件处理]\n end\n\n subgraph 外部服务[\"外部服务\"]\n OLLAMA[Ollama API]\n OPENAI[OpenAI API]\n DOCLING[Docling OCR]\n TIKA[Tika Server]\n end\n\n UI --> WS_CLIENT\n UI --> API_CLIENT\n WS_CLIENT --> WS_SERVER\n API_CLIENT --> API_GATEWAY\n API_GATEWAY --> API路由\n MIDDLEWARE --> API路由\n WS_SERVER --> MIDDLEWARE\n API_GATEWAY --> OLLAMA\n API_GATEWAY --> OPENAI\n API路由 --> DOCLING\n API路由 --> TIKA\n```\n\n资料来源：[backend/open_webui/main.py:1-50]()\n\n## 核心组件架构\n\n### 前端架构\n\n前端基于 SvelteKit 框架构建，采用单页应用（SPA）模式。主要组件包括：\n\n| 组件路径 | 功能描述 |\n|---------|---------|\n| `src/app.html` | 应用主 HTML 模板，包含启动画面和主题样式 |\n| `src/lib/constants.ts` | 前端常量定义，包含 API 端点配置 |\n| `src/lib/utils/index.ts` | 响应内容处理工具函数 |\n| `src/lib/utils/codeHighlight.ts` | 代码语法高亮映射配置 |\n\n#### 前端 API 端点配置\n\n前端通过 `constants.ts` 中定义的常量与后端通信：\n\n```typescript\n// 资料来源：src/lib/constants.ts:1-20\nexport const WEBUI_BASE_URL = browser ? (dev ? `http://${WEBUI_HOSTNAME}` : ``) : ``;\nexport const WEBUI_API_BASE_URL = `${WEBUI_BASE_URL}/api/v1`;\n\nexport const OLLAMA_API_BASE_URL = `${WEBUI_BASE_URL}/ollama`;\nexport const OPENAI_API_BASE_URL = `${WEBUI_BASE_URL}/openai`;\nexport const AUDIO_API_BASE_URL = `${WEBUI_BASE_URL}/api/v1/audio`;\nexport const IMAGES_API_BASE_URL = `${WEBUI_BASE_URL}/api/v1/images`;\nexport const RETRIEVAL_API_BASE_URL = `${WEBUI_BASE_URL}/api/v1/retrieval`;\n```\n\n### 后端架构\n\n后端采用 FastAPI 框架，按照功能模块划分为多个路由组件：\n\n```mermaid\ngraph LR\n subgraph REST_API[\"REST API (/api/v1/*)\"]\n TASKS_API[任务 API]\n FILE_API[文件 API]\n CHAT_API[聊天 API]\n MODEL_API[模型 API]\n RAG_API[RAG 检索 API]\n end\n \n subgraph WEBSOCKET[\"WebSocket (/ws)\"]\n STREAM[流式响应]\n REALTIME[实时事件]\n end\n \n subgraph MIDDLEWARE[\"中间件\"]\n AUTH[身份验证]\n SANITIZE[内容清理]\n PIPELINE[管道处理]\n end\n```\n\n资料来源：[backend/open_webui/main.py:1-50]()\n\n## API 路由体系\n\n### 路由模块一览\n\n| 前缀路径 | 路由模块 | 标签 | 功能 |\n|---------|---------|------|------|\n| `/api/v1/tasks` | tasks | tasks | 异步任务管理 |\n| `/api/v1/images` | images | images | 图片处理与生成 |\n| `/api/v1/audio` | audio | audio | 音频处理 |\n| `/api/v1/retrieval` | retrieval | retrieval | RAG 检索功能 |\n| `/api/v1/configs` | configs | configs | 系统配置 |\n| `/api/v1/auths` | auths | auths | 身份认证 |\n| `/api/v1/users` | users | users | 用户管理 |\n| `/api/v1/channels` | channels | channels | 通道管理 |\n| `/api/v1/chats` | chats | chats | 对话管理 |\n| `/api/v1/notes` | notes | notes | 笔记功能 |\n| `/api/v1/models` | models | models | 模型管理 |\n| `/api/v1/knowledge` | knowledge | knowledge | 知识库 |\n| `/api/v1/prompts` | prompts | prompts | 提示词管理 |\n| `/api/v1/tools` | tools | tools | 工具扩展 |\n| `/api/v1/skills` | skills | skills | 技能管理 |\n| `/api/v1/memories` | memories | memories | 记忆功能 |\n| `/api/v1/folders` | folders | folders | 文件夹组织 |\n| `/api/v1/groups` | groups | groups | 分组管理 |\n| `/api/v1/files` | files | files | 文件存储 |\n\n资料来源：[backend/open_webui/main.py:30-50]()\n\n## 配置系统\n\n### 环境配置架构\n\n```python\n# 资料来源：backend/open_webui/env.py:1-50\nOPEN_WEBUI_DIR = ENV_FILE_PATH.parent # open_webui/\nBACKEND_DIR = OPEN_WEBUI_DIR.parent # backend/\nBASE_DIR = BACKEND_DIR.parent # 项目根目录\n```\n\n### 关键配置项\n\n| 配置项 | 环境变量 | 默认值 | 说明 |\n|-------|---------|-------|------|\n| Docker 模式 | `DOCKER` | `'False'` | 是否运行在 Docker 容器中 |\n| CUDA 支持 | `USE_CUDA_DOCKER` | `'false'` | 是否启用 NVIDIA GPU 加速 |\n| 设备类型 | `DEVICE_TYPE` | `'cpu'` | 嵌入模型运行设备 |\n| 版本哈希 | `APP_VERSION` | - | 构建版本标识 |\n| 构建哈希 | `APP_BUILD_HASH` | - | Git 提交哈希 |\n\n资料来源：[backend/open_webui/env.py:1-50]()\n\n### 任务配置模板\n\n系统支持可配置的提示词模板：\n\n```python\n# 资料来源：backend/open_webui/config.py:1-30\nCODE_INTERPRETER_PROMPT = \"\"\"\n代码解释器允许 AI 在沙箱环境中执行 Python 代码...\n\"\"\"\n```\n\n## 中间件处理\n\n### 响应处理管道\n\n```mermaid\ngraph TD\n LLM_Response[LLM 响应] --> STREAM[流式响应处理]\n STREAM --> REASONING[推理内容检测]\n REASONING --> CODE_INTERPRETER{代码解释器?}\n CODE_INTERPRETER -->|是| SANITIZE[内容清理]\n CODE_INTERPRETER -->|否| FORMAT[格式处理]\n SANITIZE --> HTML[HTML 渲染]\n FORMAT --> HTML\n HTML --> FINAL[最终响应]\n```\n\n资料来源：[backend/open_webui/utils/middleware.py:1-50]()\n\n### 内容处理功能\n\n中间件提供以下核心处理功能：\n\n- **推理链渲染**：将模型的思维过程渲染为可折叠的 `` HTML 元素\n- **代码解释器集成**：识别并执行代码块，渲染执行结果\n- **HTML 转义**：对非信任内容进行安全转义\n- **Markdown 处理**：支持 Markdown 格式解析\n\n```python\n# 资料来源：backend/open_webui/utils/middleware.py:1-30\nif item_type == 'reasoning':\n if duration is not None or not is_last_item:\n parts.append(\n f'\\nThought for {duration or 0} seconds
\\n{display}\\n '\n )\n```\n\n## 前端响应处理\n\n### 内容处理流程\n\n```mermaid\ngraph LR\n RAW[原始响应] --> PROCESS[processResponseContent]\n PROCESS --> CHINESE{包含中文?}\n CHINESE -->|是| CHINESE_PROC[中文内容处理]\n CHINESE -->|否| SANITIZE[内容清理]\n CHINESE_PROC --> SANITIZE\n SANITIZE --> HTML_ESCAPE[HTML 转义]\n HTML_ESCAPE --> OUTPUT[最终输出]\n```\n\n资料来源：[src/lib/utils/index.ts:1-50]()\n\n### 响应清理函数\n\n```typescript\n// 资料来源：src/lib/utils/index.ts:1-30\nexport const sanitizeResponseContent = (content: string) => {\n\treturn content\n\t\t.replace(/<\\|[a-z]*$/, '')\n\t\t.replace(/<\\|[a-z]+\\|$/, '')\n\t\t.replace(/<$/, '')\n\t\t.replaceAll('<', '<')\n\t\t.replaceAll('>', '>')\n\t\t.replaceAll(/<\\|[a-z]+\\|>/g, ' ')\n\t\t.trim();\n};\n```\n\n## 代码语法高亮\n\n### 文件类型映射配置\n\n```typescript\n// 资料来源：src/lib/utils/codeHighlight.ts:1-50\nconst EXT_OVERRIDE: Record = {\n\tpy: 'python',\n\tjs: 'javascript',\n\tts: 'typescript',\n\tjsx: 'jsx',\n\ttsx: 'tsx',\n\trb: 'ruby',\n\trs: 'rust',\n\tyml: 'yaml',\n\tmd: 'markdown',\n\tdockerfile: 'dockerfile',\n\tproto: 'proto',\n\tgraphql: 'graphql',\n\tgql: 'graphql',\n};\n```\n\n支持的语言标识符集合包含超过 50 种编程语言和配置格式，确保前端代码展示的准确性。\n\n## 部署架构\n\n### Docker 部署模式\n\n```mermaid\ngraph TB\n USER[用户] --> BROWSER[浏览器]\n BROWSER --> DOCKER[Docker 容器]\n \n subgraph DOCKER[Docker 容器]\n NGINX[反向代理]\n FASTAPI[FastAPI 后端]\n SVELTE[构建静态文件]\n end\n \n FASTAPI --> OLLAMA[(Ollama 服务)]\n FASTAPI --> DATA[数据卷 /app/backend/data]\n \n subgraph OLLAMA[(Ollama 服务)]\n MODEL1[模型 1]\n MODEL2[模型 2]\n MODEL_N[模型 N]\n end\n```\n\n### 离线模式支持\n\n系统支持完全离线运行，通过设置以下环境变量禁用所有网络请求：\n\n```bash\nexport HF_HUB_OFFLINE=1\n```\n\n资料来源：[README.md](https://github.com/open-webui/open-webui/blob/main/README.md)\n\n## 技术栈总结\n\n| 层级 | 技术选型 | 说明 |\n|-----|---------|------|\n| 前端框架 | SvelteKit | 现代化响应式框架 |\n| 后端框架 | FastAPI | 高性能 Python ASGI 框架 |\n| 数据库 | SQLite (默认) / PostgreSQL | 灵活的数据存储选项 |\n| 存储 | S3 / GCS / Azure Blob | 云端对象存储支持 |\n| LLM 运行时 | Ollama / OpenAI API | 多模型支持 |\n| 文档处理 | Tika / Docling / Mistral OCR | 多格式文档解析 |\n| WebSocket | 原生 FastAPI WebSocket | 实时双向通信 |\n\n资料来源：[README.md](https://github.com/open-webui/open-webui/blob/main/README.md), [backend/open_webui/env.py:1-50]()\n\n---\n\n\n\n## 后端路由与 API\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [认证与安全](#page-auth-security), [模型集成与支持](#page-model-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [backend/open_webui/routers/chats.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/chats.py)\n- [backend/open_webui/routers/auths.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/auths.py)\n- [backend/open_webui/routers/models.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/models.py)\n- [backend/open_webui/routers/ollama.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/ollama.py)\n- [backend/open_webui/routers/openai.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/openai.py)\n- [backend/open_webui/routers/retrieval.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/retrieval.py)\n- [backend/open_webui/routers/tasks.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/tasks.py)\n \n\n# 后端路由与 API\n\n## 1. 概述\n\nOpen WebUI 的后端采用 FastAPI 框架构建，提供了完整的 RESTful API 接口层。系统通过模块化的路由设计，将不同功能域的 API 逻辑分离到独立的路由器（Router）中，实现了代码的高内聚低耦合。\n\n### 1.1 架构设计原则\n\n后端 API 层遵循以下核心设计原则：\n\n| 设计原则 | 说明 |\n|---------|------|\n| **分层架构** | 路由层 → 服务层 → 数据访问层分离 |\n| **依赖注入** | 使用 FastAPI 的 Depends 机制管理依赖 |\n| **异步优先** | 全面采用 AsyncIO 异步编程模型 |\n| **权限控制** | 基于角色的访问控制（RBAC） |\n| **统一响应** | 标准化的响应格式和错误处理 |\n\n### 1.2 核心路由模块\n\n系统的主要路由模块位于 `backend/open_webui/routers/` 目录下：\n\n```mermaid\ngraph TD\n A[客户端请求] --> B[API 网关层]\n B --> C[认证路由 auths]\n B --> D[聊天路由 chats]\n B --> E[模型路由 models]\n B --> F[知识库路由 knowledge]\n B --> G[检索路由 retrieval]\n B --> H[任务路由 tasks]\n B --> I[外部集成 ollama/openai]\n \n C --> K[用户认证服务]\n D --> L[对话管理服务]\n E --> M[模型配置服务]\n F --> N[文档处理服务]\n G --> O[向量检索服务]\n H --> P[异步任务服务]\n```\n\n资料来源：[backend/open_webui/routers/](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/)\n\n---\n\n## 2. 认证与授权系统\n\n### 2.1 认证路由（auths）\n\n认证路由负责处理用户身份验证、会话管理和访问授权。\n\n资料来源：[backend/open_webui/routers/auths.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/auths.py)\n\n#### 2.1.1 主要 API 端点\n\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/auth/login` | POST | 用户登录 |\n| `/api/auth/logout` | POST | 用户登出 |\n| `/api/auth/user` | GET | 获取当前用户信息 |\n| `/api/auth/modelfiles` | GET | 获取用户自定义模型文件 |\n\n#### 2.1.2 认证流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant API as 认证 API\n participant DB as 数据库\n participant Session as 会话管理\n\n Client->>API: POST /api/auth/login\n API->>DB: 验证用户凭据\n DB-->>API: 用户信息\n API->>Session: 创建会话\n Session-->>API: 会话令牌\n API-->>Client: 返回认证令牌\n```\n\n### 2.2 访问控制机制\n\n系统通过 `AccessGrants` 模块实现细粒度的资源访问控制：\n\n```python\nif not (\n user.role == 'admin'\n or knowledge.user_id == user.id\n or await AccessGrants.has_access(\n user_id=user.id,\n resource_type='knowledge',\n resource_id=knowledge.id,\n permission='read',\n db=db,\n )\n):\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=ERROR_MESSAGES.ACCESS_PROHIBITED,\n )\n```\n\n资料来源：[backend/open_webui/routers/knowledge.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)\n\n---\n\n## 3. 对话管理 API\n\n### 3.1 聊天路由（chats）\n\n聊天路由是系统的核心模块，负责处理所有与对话相关的功能，包括消息发送、对话历史管理和对话状态维护。\n\n资料来源：[backend/open_webui/routers/chats.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/chats.py)\n\n#### 3.1.1 核心功能\n\n| 功能 | 描述 |\n|------|------|\n| 创建对话 | 初始化新的聊天会话 |\n| 发送消息 | 向对话中添加用户消息和助手回复 |\n| 获取历史 | 检索指定对话的消息历史 |\n| 删除对话 | 删除整个对话及其关联数据 |\n| 分享对话 | 将对话导出为可分享格式 |\n\n#### 3.1.2 消息处理流程\n\n```mermaid\ngraph TD\n A[用户发送消息] --> B[消息验证]\n B --> C{工具调用检测}\n C -->|是| D[执行工具函数]\n C -->|否| E[模型推理]\n D --> F[返回工具结果]\n E --> G[生成回复]\n F --> G\n G --> H[保存消息]\n H --> I[流式返回]\n```\n\n### 3.2 消息处理工具函数\n\n系统提供了丰富的消息处理工具函数：\n\n| 函数名 | 功能 |\n|--------|------|\n| `get_message_list` | 获取消息列表 |\n| `add_or_update_system_message` | 添加/更新系统消息 |\n| `add_or_update_user_message` | 添加/更新用户消息 |\n| `get_last_user_message` | 获取最后用户消息 |\n| `get_last_assistant_message` | 获取最后助手消息 |\n| `replace_system_message_content` | 替换系统消息内容 |\n\n资料来源：[backend/open_webui/utils/chat.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/chat.py)\n\n---\n\n## 4. 模型管理 API\n\n### 4.1 模型路由（models）\n\n模型路由负责管理系统中的大语言模型配置，包括模型列表管理、配置更新和模型选择。\n\n资料来源：[backend/open_webui/routers/models.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/models.py)\n\n#### 4.1.1 配置参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `title` | string | 模型显示名称 |\n| `base_url` | string | 模型服务地址 |\n| `api_key` | string | API 密钥 |\n| `max_tokens` | int | 最大生成 token 数 |\n| `temperature` | float | 生成温度参数 |\n| `stream` | boolean | 是否启用流式输出 |\n\n### 4.2 外部模型集成\n\n系统支持多种外部模型服务的集成，通过统一的适配器接口实现。\n\n---\n\n## 5. 外部服务集成\n\n### 5.1 Ollama 集成\n\nOllama 路由提供了与本地 Ollama 服务通信的接口。\n\n资料来源：[backend/open_webui/routers/ollama.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/ollama.py)\n\n```mermaid\ngraph LR\n A[Open WebUI] -->|API 请求| B[Ollama 适配层]\n B --> C[Ollama 服务]\n C -->|模型响应| B\n B -->|标准化响应| A\n```\n\n#### 5.1.1 Ollama API 端点映射\n\n| Open WebUI 端点 | Ollama API |\n|----------------|-----------|\n| `/ollama/chat` | `/api/chat` |\n| `/ollama/models` | `/api/tags` |\n| `/ollama/generate` | `/api/generate` |\n| `/ollama/embeddings` | `/api/embeddings` |\n\n### 5.2 OpenAI 兼容 API\n\nOpenAI 路由实现了与 OpenAI API 兼容的接口，支持使用 OpenAI SDK 的应用无缝接入。\n\n资料来源：[backend/open_webui/routers/openai.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/openai.py)\n\n#### 5.2.1 支持的端点\n\n| 端点 | 描述 |\n|------|------|\n| `/openai/v1/chat/completions` | 聊天补全 |\n| `/openai/v1/completions` | 文本补全 |\n| `/openai/v1/embeddings` | 向量嵌入 |\n| `/openai/v1/models` | 模型列表 |\n\n---\n\n## 6. 知识库与检索系统\n\n### 6.1 知识库路由\n\n知识库路由负责文档上传、内容处理和知识库管理。\n\n资料来源：[backend/open_webui/routers/knowledge.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)\n\n#### 6.1.1 文件操作 API\n\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/{id}/files` | GET | 列出知识库文件 |\n| `/{id}/file/add` | POST | 添加文件到知识库 |\n| `/{id}/file/delete` | DELETE | 删除知识库文件 |\n| `/{id}/search` | POST | 搜索知识库内容 |\n\n#### 6.1.2 访问控制流程\n\n```mermaid\ngraph TD\n A[请求访问知识库] --> B{用户角色检查}\n B -->|管理员| C[允许访问]\n B -->|普通用户| D{是否为所有者}\n D -->|是| C\n D -->|否| E{检查访问权限}\n E -->|有读权限| C\n E -->|无权限| F[拒绝访问 400]\n```\n\n### 6.2 检索路由\n\n检索路由提供了向量检索和全文搜索功能。\n\n资料来源：[backend/open_webui/routers/retrieval.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/retrieval.py)\n\n#### 6.2.1 检索处理流程\n\n```mermaid\ngraph TD\n A[用户查询] --> B[查询预处理]\n B --> C[向量嵌入]\n C --> D[向量数据库检索]\n D --> E[结果重排序]\n E --> F[格式化输出]\n F --> G[返回检索结果]\n```\n\n---\n\n## 7. 异步任务系统\n\n### 7.1 任务路由\n\n任务路由管理系统中的异步任务，包括任务创建、状态查询和结果获取。\n\n资料来源：[backend/open_webui/routers/tasks.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/tasks.py)\n\n#### 7.1.1 任务类型\n\n| 任务类型 | 描述 |\n|---------|------|\n| `chat` | 聊天消息生成任务 |\n| `title` | 对话标题生成任务 |\n| `summarize` | 消息摘要任务 |\n| `rerank` | 检索结果重排序任务 |\n\n#### 7.1.2 任务状态流转\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending: 创建任务\n Pending --> Processing: 开始执行\n Processing --> Completed: 执行成功\n Processing --> Failed: 执行失败\n Completed --> [*]\n Failed --> [*]\n```\n\n### 7.2 任务处理配置\n\n系统通过配置文件管理任务处理参数：\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| `TASK_MODEL` | 任务处理模型 | auto |\n| `TASK_MODEL_EXTERNAL` | 外部任务模型 | - |\n\n资料来源：[backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)\n\n---\n\n## 8. 代码执行系统\n\n### 8.1 代码解释器配置\n\n系统支持在聊天中执行代码，提供强大的动态执行能力。\n\n资料来源：[backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)\n\n#### 8.1.1 配置参数\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `ENABLE_CODE_EXECUTION` | boolean | 启用代码执行 |\n| `CODE_EXECUTION_ENGINE` | string | 执行引擎 (pyodide) |\n| `CODE_EXECUTION_JUPYTER_URL` | string | Jupyter 服务地址 |\n| `CODE_EXECUTION_JUPYTER_AUTH` | string | Jupyter 认证信息 |\n\n#### 8.1.2 架构设计\n\n```mermaid\ngraph TD\n A[代码块检测] --> B{启用代码执行}\n B -->|是| C[隔离执行环境]\n C --> D[Pyodide/Jupyter]\n B -->|否| E[普通代码展示]\n D --> F[执行结果捕获]\n F --> G[格式化返回]\n```\n\n---\n\n## 9. 工具系统\n\n### 9.1 工具函数管理\n\n系统提供灵活的函数调用机制，支持自定义工具扩展。\n\n资料来源：[backend/open_webui/utils/tools.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/tools.py)\n\n| 函数 | 功能 |\n|------|------|\n| `get_tools` | 获取可用工具列表 |\n| `get_updated_tool_function` | 获取更新后的工具定义 |\n| `get_terminal_tools` | 获取终端级工具 |\n\n### 9.2 工具调用处理\n\n```mermaid\ngraph TD\n A[模型输出] --> B{检测工具调用}\n B -->|function_call| C[解析工具名和参数]\n C --> D[加载工具模块]\n D --> E[执行工具函数]\n E --> F[返回执行结果]\n F --> G[模型生成最终回复]\n```\n\n---\n\n## 10. 流水线处理\n\n### 10.1 管道过滤器\n\n系统支持在请求处理流程中插入自定义过滤器，实现功能的灵活扩展。\n\n资料来源：[backend/open_webui/routers/pipelines.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/pipelines.py)\n\n| 处理阶段 | 描述 |\n|---------|------|\n| `pipeline_inlet_filter` | 请求预处理过滤器 |\n| `pipeline_outlet_filter` | 响应后处理过滤器 |\n\n### 10.2 处理流程\n\n```mermaid\ngraph LR\n A[用户请求] --> B[输入过滤器]\n B --> C[核心业务处理]\n C --> D[输出过滤器]\n D --> E[返回响应]\n```\n\n---\n\n## 11. API 响应格式规范\n\n### 11.1 统一响应结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 资源唯一标识符 |\n| `object` | string | 对象类型 |\n| `created` | int | 创建时间戳 |\n| `model` | string | 使用的模型 |\n| `choices` | array | 生成选项列表 |\n| `usage` | object | Token 使用统计 |\n\n### 11.2 错误响应\n\n| 状态码 | 说明 |\n|--------|------|\n| 400 | 请求参数错误 |\n| 401 | 认证失败 |\n| 403 | 权限不足 |\n| 404 | 资源不存在 |\n| 500 | 服务器内部错误 |\n\n---\n\n## 12. 总结\n\nOpen WebUI 的后端 API 系统采用模块化设计，通过清晰的路由划分实现了功能的有效分离。系统提供了完整的用户认证、对话管理、模型配置、知识库管理和异步任务处理能力，同时支持与 Ollama、OpenAI 等外部服务的高效集成。\n\n该架构的核心优势包括：\n\n- **可扩展性**：通过流水线过滤器支持自定义扩展\n- **安全性**：基于角色的访问控制和细粒度的资源权限管理\n- **性能**：全面采用异步编程模型，支持高并发处理\n- **兼容性**：提供 OpenAI 兼容接口，无缝对接现有生态系统\n\n---\n\n\n\n## 数据模型层\n\n### 相关页面\n\n相关主题：[后端路由与 API](#page-backend-routers)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [backend/open_webui/models/users.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/users.py)\n- [backend/open_webui/models/chats.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/chats.py)\n- [backend/open_webui/models/messages.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/messages.py)\n- [backend/open_webui/models/files.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/files.py)\n- [backend/open_webui/models/functions.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/functions.py)\n- [backend/open_webui/models/tools.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/tools.py)\n- [backend/open_webui/models/knowledge.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/knowledge.py)\n- [backend/open_webui/internal/db.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/internal/db.py)\n \n\n# 数据模型层\n\n## 概述\n\nOpen WebUI 的数据模型层是整个系统的核心基础设施，负责管理和持久化所有业务数据。该层采用了**分层架构设计**，将数据访问逻辑、业务模型定义和数据库交互分离到不同的模块中，以实现高内聚、低耦合的代码结构。\n\n数据模型层的主要职责包括：\n\n- **用户认证与授权**：管理用户账户信息、权限配置和会话状态\n- **对话历史管理**：存储和检索聊天记录，支持消息的增删改查操作\n- **文件与媒体处理**：管理上传文件、元数据和访问控制\n- **工具与函数集成**：维护可扩展的工具和函数定义\n- **知识库管理**：支持向量化的知识检索和文档管理\n\n资料来源：[backend/open_webui/internal/db.py:1-50]()\n\n## 架构设计\n\n### 整体架构图\n\n```mermaid\ngraph TB\n subgraph \"表现层 (API Routes)\"\n A[API 路由层]\n end\n \n subgraph \"服务层 (Services)\"\n B[业务逻辑服务]\n end\n \n subgraph \"数据模型层 (Models)\"\n C[用户模型
users.py]\n D[对话模型
chats.py]\n E[消息模型
messages.py]\n F[文件模型
files.py]\n G[函数模型
functions.py]\n H[工具模型
tools.py]\n I[知识模型
knowledge.py]\n end\n \n subgraph \"数据访问层 (Internal)\"\n J[数据库连接
db.py]\n K[数据仓库
Repositories]\n end\n \n subgraph \"存储层 (Storage)\"\n L[(SQLite/MySQL
PostgreSQL)]\n M[(文件存储
S3/本地)]\n end\n \n A --> B\n B --> C\n B --> D\n B --> E\n B --> F\n B --> G\n B --> H\n B --> I\n \n C --> J\n D --> J\n E --> J\n F --> J\n G --> J\n H --> J\n I --> J\n \n J --> K\n K --> L\n K --> M\n```\n\n### 模块职责划分\n\n| 模块文件 | 主要职责 | 核心数据结构 |\n|---------|---------|-------------|\n| `users.py` | 用户账户、认证、权限 | UserModel |\n| `chats.py` | 对话会话、聊天历史 | ChatModel |\n| `messages.py` | 单条消息、消息内容 | MessageModel |\n| `files.py` | 文件上传、元数据管理 | FileModel |\n| `functions.py` | 可调用函数定义 | FunctionModel |\n| `tools.py` | 外部工具集成 | ToolModel |\n| `knowledge.py` | 知识库、向量存储 | KnowledgeModel |\n| `db.py` | 数据库连接、查询构建 | Database Connection |\n\n资料来源：[backend/open_webui/internal/db.py:1-30]()\n\n## 核心数据模型详解\n\n### 1. 用户模型 (User Model)\n\n用户模型是系统的基础实体，包含了用户身份验证和授权所需的所有信息。\n\n```mermaid\nclassDiagram\n class UserModel {\n +str id\n +str email\n +str name\n +str password_hash\n +str role\n +datetime created_at\n +datetime updated_at\n +dict settings\n +dict preferences\n }\n \n class UserSettings {\n +str theme\n +str language\n +list allowed_models\n +bool consent_analytics\n }\n```\n\n**主要字段说明：**\n\n| 字段名 | 类型 | 说明 | 必填 |\n|-------|------|------|-----|\n| `id` | str | 唯一标识符 (UUID) | 是 |\n| `email` | str | 用户邮箱地址 | 是 |\n| `name` | str | 显示名称 | 是 |\n| `password_hash` | str | 密码哈希值 (bcrypt) | 是 |\n| `role` | str | 角色 (admin/user/guest) | 是 |\n| `created_at` | datetime | 创建时间戳 | 自动 |\n| `updated_at` | datetime | 更新时间戳 | 自动 |\n| `settings` | dict | 用户偏好设置 | 否 |\n\n资料来源：[backend/open_webui/models/users.py:1-100]()\n\n### 2. 对话模型 (Chat Model)\n\n对话模型采用扁平化的 JSON 结构存储聊天会话，包含完整的对话历史和元数据。\n\n```mermaid\ngraph LR\n A[ChatModel] --> B[\"chat: Dict\"]\n B --> C[\"history: Dict\"]\n C --> D[\"messages: Dict
message_id → message\"]\n C --> E[\"metadata: Dict\"]\n B --> F[\"share_id: str\"]\n B --> G[\"archived: bool\"]\n B --> H[\"pinned: bool\"]\n```\n\n**关键特性：**\n\n- **消息存储方式**：对话消息存储在 `chat.history.messages` 字典中，以 `message_id` 为键\n- **双轨存储**：支持从独立的 `chat_message` 表快速查询，同时保持向后兼容的 JSON blob 存储\n- **自动清理**：对消息内容进行特殊字符清理，防止数据库存储问题\n\n资料来源：[backend/open_webui/models/chats.py:1-50]()\n\n### 3. 消息模型 (Message Model)\n\n消息是对话的原子单位，每条消息包含发送者、内容、附件和时间戳等完整信息。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | str | 消息唯一标识 |\n| `chat_id` | str | 所属对话 ID |\n| `role` | str | 发送者角色 (user/assistant/system) |\n| `content` | str | 消息文本内容 |\n| `attachments` | list | 附件列表 |\n| `metadata` | dict | 额外元数据 |\n| `created_at` | datetime | 创建时间 |\n\n资料来源：[backend/open_webui/models/messages.py:1-80]()\n\n### 4. 文件模型 (File Model)\n\n文件模型管理用户上传的所有文件，包括图片、文档、音频等。\n\n```mermaid\nstateDiagram-v2\n [*] --> Uploaded: 用户上传\n Uploaded --> Processing: 开始处理\n Processing --> Ready: 处理完成\n Processing --> Failed: 处理失败\n Failed --> [*]\n Ready --> Deleted: 用户删除\n Ready --> [*]\n```\n\n**文件类型支持：**\n\n| 类型 | 说明 | 存储方式 |\n|------|------|---------|\n| `image` | 图片文件 | 对象存储 |\n| `document` | 文档 (PDF, DOCX等) | 对象存储 |\n| `audio` | 音频文件 | 对象存储 |\n| `video` | 视频文件 | 对象存储 |\n| `html` | HTML 内容 | 内联存储 |\n\n资料来源：[backend/open_webui/models/files.py:1-100]()\n\n### 5. 函数与工具模型\n\n函数和工具模型为系统提供了扩展能力，允许用户和开发者自定义功能。\n\n```mermaid\ngraph TD\n A[FunctionModel/ToolModel] --> B[\"id: str\"]\n A --> C[\"name: str\"]\n A --> D[\"description: str\"]\n A --> E[\"parameters: dict\"]\n A --> F[\"source_code: str\"]\n A --> G[\"enabled: bool\"]\n \n H[函数调用流程] --> I[解析参数]\n H --> J[执行函数]\n H --> K[返回结果]\n```\n\n资料来源：[backend/open_webui/models/functions.py:1-60]()\n\n### 6. 知识库模型 (Knowledge Model)\n\n知识库模型支持向量化的文档存储和语义检索。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | str | 知识库唯一标识 |\n| `name` | str | 知识库名称 |\n| `description` | str | 描述信息 |\n| `documents` | list | 文档列表 |\n| `embeddings` | list | 向量化数据 |\n| `created_by` | str | 创建者 ID |\n\n资料来源：[backend/open_webui/models/knowledge.py:1-80]()\n\n## 数据库交互层\n\n### 数据库连接管理\n\n`db.py` 模块负责建立和管理数据库连接，支持多种数据库后端：\n\n```python\n# 核心配置参数\nDB_HOST = os.environ.get('DB_HOST', 'localhost')\nDB_PORT = os.environ.get('DB_PORT', '5432')\nDB_NAME = os.environ.get('DB_NAME', 'openwebui')\nDB_USER = os.environ.get('DB_USER', 'postgres')\nDB_PASSWORD = os.environ.get('DB_PASSWORD', '')\n```\n\n**支持的数据库类型：**\n\n| 数据库 | 配置项 | 说明 |\n|-------|-------|------|\n| SQLite | 默认 | 轻量级开发环境 |\n| PostgreSQL | `DATABASE_URL` | 生产环境推荐 |\n| MySQL | `DATABASE_URL` | 兼容模式支持 |\n\n资料来源：[backend/open_webui/internal/db.py:30-80]()\n\n### 数据仓库模式\n\n系统采用 Repository 模式封装数据访问逻辑，提供统一的 CRUD 操作接口：\n\n```mermaid\ngraph TB\n A[Service Layer] --> B[Repository Interface]\n B --> C[UserRepository]\n B --> D[ChatRepository]\n B --> E[MessageRepository]\n B --> F[FileRepository]\n \n C --> G[(Database)]\n D --> G\n E --> G\n F --> G\n```\n\n### 数据清理与安全\n\n消息内容在存入数据库前会经过严格的安全处理：\n\n```python\ndef sanitize_text_for_db(text: str) -> str:\n \"\"\"移除可能导致数据库问题的特殊字符\"\"\"\n # 移除空字符和其他控制字符\n return text.replace('\\x00', '')\n```\n\n**安全措施包括：**\n\n- 移除空字符 (`\\x00`)\n- 转义 HTML 特殊字符\n- 验证字符串长度\n- 类型检查和类型转换\n\n资料来源：[backend/open_webui/models/chats.py:40-60]()\n\n## 数据流程与生命周期\n\n### 消息创建流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant API as API路由\n participant S as 服务层\n participant M as MessageModel\n participant D as 数据库\n \n U->>API: 发送消息\n API->>S: create_message()\n S->>M: 构建消息对象\n M->>D: sanitize_text_for_db()\n D-->>M: 清理后的文本\n M->>D: INSERT INTO messages\n D-->>M: 返回插入结果\n M-->>S: MessageModel\n S-->>API: 响应\n API-->>U: 返回消息\n```\n\n### 对话历史查询流程\n\n系统采用两级缓存策略优化查询性能：\n\n1. **优先路径**：从 `chat_message` 表直接查询（推荐）\n2. **回退路径**：从 `chat.chat.history.messages` JSON blob 读取（兼容旧数据）\n\n```mermaid\nflowchart TD\n A[get_messages_map] --> B{chat_message表存在?}\n B -->|是| C[快速查询
ChatMessages.get_messages_map_by_chat_id]\n B -->|否| D[查询Chat表]\n D --> E{Chat存在?}\n E -->|是| F[解析chat.history.messages]\n E -->|否| G[返回None]\n C --> H[返回消息映射]\n F --> H\n```\n\n资料来源：[backend/open_webui/models/chats.py:15-35]()\n\n## 配置与环境变量\n\n数据模型层的行为受以下环境变量控制：\n\n| 环境变量 | 默认值 | 说明 |\n|---------|-------|------|\n| `DATABASE_URL` | sqlite | 数据库连接字符串 |\n| `DB_HOST` | localhost | 数据库主机 |\n| `DB_PORT` | 5432 | 数据库端口 |\n| `DB_NAME` | openwebui | 数据库名称 |\n| `DB_USER` | postgres | 数据库用户 |\n| `DEVICE_TYPE` | cpu | 嵌入模型设备类型 |\n| `USE_CUDA_DOCKER` | false | 是否使用GPU加速 |\n\n资料来源：[backend/open_webui/env.py:1-60]()\n\n## 扩展与自定义\n\n### 添加新数据模型\n\n在 Open WebUI 中添加新的数据模型需要遵循以下步骤：\n\n1. 在 `backend/open_webui/models/` 目录创建新的模型文件\n2. 定义 Pydantic 模型类继承基础类\n3. 在 `db.py` 中注册新的数据库表\n4. 实现 CRUD 操作方法\n\n```python\n# 示例：新模型结构\nfrom pydantic import BaseModel\nfrom typing import Optional\nfrom datetime import datetime\n\nclass NewModel(BaseModel):\n id: str\n name: str\n description: Optional[str] = None\n created_at: datetime\n updated_at: datetime\n```\n\n### 数据迁移策略\n\n系统支持平滑的数据迁移，确保向后兼容性：\n\n- 新字段添加使用默认值\n- 旧数据结构在读取时自动转换\n- 迁移脚本支持批量更新历史数据\n\n## 最佳实践\n\n### 数据访问规范\n\n1. **始终使用模型方法**：通过模型层访问数据，不要直接操作数据库\n2. **处理空值情况**：使用 `Optional` 类型注解，明确空值处理逻辑\n3. **批量操作优化**：对于大量数据使用批量插入和查询\n4. **事务管理**：相关操作使用数据库事务保证一致性\n\n### 性能优化建议\n\n| 场景 | 优化方案 |\n|------|---------|\n| 频繁读取对话 | 使用 `get_messages_map_by_chat_id` 快速路径 |\n| 大量文件存储 | 配置对象存储而非数据库 |\n| 向量检索 | 使用专门的向量数据库后端 |\n| 复杂查询 | 添加适当的数据库索引 |\n\n## 相关文档\n\n- [API 路由层](../api/routes)\n- [服务层架构](../services)\n- [存储配置](../storage)\n- [安全机制](../security)\n\n---\n\n\n\n## 认证与安全\n\n### 相关页面\n\n相关主题：[后端路由与 API](#page-backend-routers), [数据模型层](#page-backend-models)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [backend/open_webui/utils/auth.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/auth.py)\n- [backend/open_webui/utils/oauth.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/oauth.py)\n- [backend/open_webui/routers/auths.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/auths.py)\n- [backend/open_webui/models/users.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/users.py)\n- [backend/open_webui/routers/scim.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/scim.py)\n- [src/lib/constants/permissions.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/constants/permissions.ts)\n- [backend/open_webui/utils/asgi_middleware.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/asgi_middleware.py)\n- [backend/open_webui/env.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/env.py)\n \n\n# 认证与安全\n\n## 概述\n\nOpen WebUI 的认证与安全系统是一套完整的多层防护机制，支持多种认证方式，包括本地账号认证、OAuth 2.0 单点登录、API Key 认证以及 SCIM 用户管理协议。该系统采用基于角色的访问控制（RBAC）模型，确保不同权限级别的用户只能访问其授权范围内的资源。安全架构的核心设计理念是将认证逻辑与业务逻辑分离，通过中间件统一处理身份验证和授权检查。\n\n整个认证体系构建在 FastAPI 框架之上，利用 Python 的异步特性实现高性能的请求处理。密码存储采用行业标准的加密算法，用户凭证在传输过程中全程使用 HTTPS 加密保护。系统还提供了细粒度的权限控制机制，支持对知识库、提示词、模型等资源进行独立的读写权限配置。\n\n## 认证方式\n\n### 本地账号认证\n\n本地账号认证是 Open WebUI 的基础认证方式，用户通过用户名和密码注册和登录系统。注册时系统会验证邮箱格式并确保用户名唯一性，密码则通过 bcrypt 算法进行加盐哈希存储，确保即使数据库泄露也无法直接还原用户密码。\n\n登录流程中，系统首先根据用户名查找用户记录，验证密码哈希是否匹配。认证成功后，系统生成 JWT（JSON Web Token）格式的访问令牌，令牌中包含用户 ID、角色和过期时间等信息。令牌的有效期默认为 24 小时，用户可以在此期间无需重新登录访问系统资源。\n\n```mermaid\nsequenceDiagram\n participant 用户\n participant 前端 as 前端应用\n participant API as 认证 API\n participant 数据库 as 用户数据库\n\n 用户->>前端: 输入用户名和密码\n 前端->>API: POST /auth/login\n API->>数据库: 查询用户信息\n 数据库-->>API: 用户记录\n API->>API: 验证密码哈希\n API->>API: 生成 JWT Token\n API-->>前端: 返回 Token 和用户信息\n 前端->>前端: 存储 Token 到本地\n 前端-->>用户: 登录成功\n```\n\n用户注册功能默认启用，但管理员可通过配置禁用注册或将系统设置为只读模式。在只读模式下，新用户注册将被阻止，但现有用户仍可正常登录使用系统。密码修改功能允许用户随时更新密码，系统会要求输入当前密码以确认身份。\n\n资料来源：[backend/open_webui/routers/auths.py:1-100](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/auths.py)\n资料来源：[backend/open_webui/models/users.py:1-150](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/users.py)\n\n### OAuth 2.0 单点登录\n\nOpen WebUI 支持通过 OAuth 2.0 协议与企业身份提供商集成，实现单点登录（SSO）。系统目前支持 OIDC（OpenID Connect）标准，能够与主流的身份服务如 Keycloak、Authentik、Okta、Auth0 等无缝对接。OAuth 认证流程遵循标准授权码模式，用户首先被重定向到身份提供商进行身份验证，验证成功后返回授权码，再由后端交换为访问令牌和用户信息。\n\nOAuth 配置通过环境变量进行管理，主要配置项包括提供商类型、客户端 ID、客户端密钥和授权端点 URL。系统会自动发现 OIDC 提供商的配置元数据，包括令牌颁发者地址、用户信息端点和 JWKS（JSON Web Key Set）用于验证令牌签名。\n\n```mermaid\ngraph TD\n A[用户访问 Open WebUI] --> B{是否已登录}\n B -->|否| C[点击 OAuth 登录]\n C --> D[重定向到身份提供商]\n D --> E[用户输入凭证]\n E --> F{身份验证成功}\n F -->|是| G[返回授权码]\n F -->|否| H[显示错误信息]\n G --> I[后端交换授权码]\n I --> J[获取访问令牌]\n J --> K[获取用户信息]\n K --> L[创建或更新本地用户]\n L --> M[生成 JWT 会话]\n M --> N[用户登录成功]\n B -->|是| O[直接访问受保护资源]\n```\n\n用户首次通过 OAuth 登录时，系统会自动创建本地用户记录，将 OAuth 提供商返回的用户信息映射到本地用户模型。后续登录时，系统会识别已有用户并更新其信息，实现用户数据的同步。管理员可以为不同用户分配不同的角色，或将 OAuth 用户自动映射到特定角色组。\n\n资料来源：[backend/open_webui/utils/oauth.py:1-200](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/oauth.py)\n\n### API Key 认证\n\n对于程序化访问场景，Open WebUI 提供了 API Key 认证方式，允许外部应用或服务使用 API Key 访问系统接口。API Key 通过自定义 HTTP 头传输，默认头名称为 `x-api-key`，可在配置中修改以适应不同的反向代理环境。\n\nAPI Key 的创建和管理完全由管理员控制，每个 API Key 可以关联到特定用户或配置为全局密钥。全局密钥绕过用户关联，适用于服务间通信或系统集成场景。API Key 采用一次性哈希存储，后端仅保存密钥的 SHA-256 摘要，用户创建后无法再次查看完整密钥，必须保存后妥善保管。\n\n当 API Key 通过中间件验证时，系统会将其映射到关联的用户身份，后续的权限检查逻辑与普通用户登录完全一致。这意味着 API Key 持有者受到与普通用户相同的 RBAC 约束，确保程序化访问不会绕过安全策略。\n\n资料来源：[backend/open_webui/utils/asgi_middleware.py:1-80](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/asgi_middleware.py)\n\n### SCIM 用户管理\n\nOpen WebUI 实现了 SCIM（System for Cross-domain Identity Management）2.0 协议，支持与企业身份管理系统（如 Okta、Azure AD、OneLogin）集成进行用户自动化配置和生命周期管理。SCIM 接口允许外部系统推送用户创建、更新和禁用操作，实现用户账号的集中管理。\n\n```mermaid\ngraph LR\n A[身份管理系统] -->|POST /Users| B[创建用户]\n A -->|PUT /Users/:id| C[更新用户]\n A -->|PATCH /Users/:id| D[修改用户属性]\n A -->|DELETE /Users/:id| E[禁用用户]\n A -->|GET /Users| F[查询用户列表]\n B --> G{验证数据}\n G -->|通过| H[创建本地用户]\n G -->|失败| I[返回错误]\n H --> J[分配默认角色]\n J --> K[返回用户信息]\n```\n\nSCIM 端点位于 `/scim/v2` 路径下，支持标准的 RESTful 操作。创建用户时，系统会验证请求体的 schema 合规性，提取用户名、邮箱、姓名和活跃状态等核心属性。成功创建的用户会被分配默认角色，并生成对应的本地账号。用户更新操作会同步修改本地用户记录，包括角色变更和状态切换。\n\n资料来源：[backend/open_webui/routers/scim.py:1-300](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/scim.py)\n\n## 令牌与会话管理\n\n### JWT 令牌机制\n\nOpen WebUI 使用 JWT（JSON Web Token）作为主要的会话令牌格式。JWT 包含三个部分：头部（Header）、载荷（Payload）和签名（Signature）。令牌在用户登录成功后生成，包含用户 ID、用户名、角色、权限范围和过期时间等声明。签名使用 HS256 算法，确保令牌内容不可被篡改。\n\n令牌的有效期通过配置管理，默认设置为 24 小时。系统在每个请求中验证令牌的签名和过期时间，过期令牌将被拒绝并返回 401 未授权响应。用户可以通过设置中的\"记住我\"功能延长令牌有效期，延长后的有效期可达 30 天。\n\n```json\n{\n \"id\": \"user-uuid\",\n \"name\": \"username\",\n \"email\": \"user@example.com\",\n \"role\": \"user\",\n \"exp\": 1699999999,\n \"iat\": 1699913599\n}\n```\n\n令牌刷新机制允许用户在令牌即将过期时获取新令牌，无需重新输入密码。刷新令牌通过独立的端点交换，系统会验证原令牌的有效性后颁发新令牌并使旧令牌失效。这种机制在保持安全性的同时提供了流畅的用户体验。\n\n资料来源：[backend/open_webui/utils/auth.py:50-150](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/auth.py)\n\n### Cookie 与 Header 认证\n\n系统支持两种令牌传输方式：通过 HTTP Cookie 或 Authorization Header。Cookie 方式适用于浏览器环境，令牌自动随请求发送并在浏览器关闭后清除。Header 方式则需要客户端手动在请求头中添加 `Authorization: Bearer `，适用于 API 客户端和程序化访问。\n\n```mermaid\ngraph TD\n A[收到 HTTP 请求] --> B{检查 Authorization 头}\n B -->|存在| C[提取 Bearer Token]\n B -->|不存在| D{检查 Cookie}\n D -->|存在| E[提取 token Cookie]\n D -->|不存在| F{检查 API Key 头}\n F -->|存在| G[验证 API Key]\n F -->|不存在| H[返回 401]\n C --> I[验证 JWT 签名]\n E --> I\n G --> J{API Key 有效}\n J -->|是| K[获取关联用户]\n J -->|否| H\n I --> L{JWT 有效}\n L -->|是| M[设置请求状态]\n L -->|否| H\n K --> M\n```\n\n中间件优先检查 Authorization 头，若不存在则回退到 Cookie，最后才检查 API Key。这种优先级设计确保了最佳的安全性：Bearer Token 提供了最细粒度的控制，而 Cookie 认证则为 Web 界面提供了便利。\n\n资料来源：[backend/open_webui/utils/asgi_middleware.py:20-100](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/asgi_middleware.py)\n\n## 基于角色的访问控制\n\n### 角色定义\n\nOpen WebUI 实现了三级角色体系，每种角色对应不同的权限级别：\n\n| 角色 | 描述 | 主要权限 |\n|------|------|----------|\n| admin | 管理员 | 全部功能、用户管理、系统配置、模型管理 |\n| user | 普通用户 | 聊天、创建知识库、使用提示词 |\n| pending | 待审核用户 | 仅登录，无功能权限 |\n\n管理员拥有系统的完全控制权，可以创建和删除用户、修改系统配置、管理 Ollama 模型和知识库。普通用户可以正常使用对话功能，创建个人知识库和提示词，但无法访问管理功能。待审核用户是注册后等待管理员审批的临时状态，此状态下用户只能登录无法使用任何功能。\n\n默认情况下，管理员需要在用户管理界面手动审核新注册用户。但系统也支持配置为自动批准模式，新用户注册后自动获得普通用户角色，立即可以使用系统全部基础功能。\n\n资料来源：[src/lib/constants/permissions.ts:1-100](https://github.com/open-webui/open-webui/blob/main/src/lib/constants/permissions.ts)\n资料来源：[backend/open_webui/models/users.py:50-120](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/users.py)\n\n### 资源权限授予\n\n除了基于角色的粗粒度控制，系统还支持对特定资源进行细粒度的权限授予。资源类型包括知识库（knowledge）、提示词（prompt）、文件（file）等，每种资源可以独立设置读（read）、写（write）和删除（delete）权限。\n\n```mermaid\ngraph TD\n A[用户请求访问资源] --> B[获取资源信息]\n B --> C{用户是管理员?}\n C -->|是| D[允许访问]\n C -->|否| E{用户是资源所有者?}\n E -->|是| D\n E -->|否| F[查询访问授权表]\n F --> G{存在匹配授权?}\n G -->|是| H{授权类型匹配请求?}\n H -->|是| D\n H -->|否| I[拒绝访问]\n G -->|否| I[拒绝访问]\n```\n\n访问授权表（Access Grants）存储用户与资源之间的权限关系。授权可以针对个人用户或用户组设置，支持灵活的权限继承和覆盖机制。管理员可以授予其他用户访问自己创建的知识库的权限，实现团队协作。\n\n资源级别的权限检查贯穿于各个路由处理函数。系统在处理请求前首先验证用户身份，然后在执行业务逻辑前检查用户是否具有相应资源的访问权限。若权限不足，请求将被拒绝并返回 403 Forbidden 响应。\n\n资料来源：[backend/open_webui/routers/knowledge.py:50-150](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)\n\n## 安全中间件\n\n### 请求认证中间件\n\nASGI 中间件是请求处理流程的第一道关卡，负责从 HTTP 请求中提取并验证认证凭证。该中间件实现了统一的认证逻辑，封装在 FastAPI 的请求处理管道中，对所有路由生效。\n\n```python\nasync def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:\n # 仅处理 HTTP 请求\n if scope['type'] != 'http':\n await self.app(scope, receive, send)\n return\n \n request = Request(scope)\n # 尝试多种认证方式\n token = self._extract_bearer_token(request)\n if not token:\n token = self._extract_cookie_token(request)\n if not token:\n token = self._extract_api_key(request)\n \n # 将认证结果存入请求状态\n request.state.token = token\n request.state.enable_api_keys = self._snapshot_config()\n```\n\n中间件按优先级依次尝试 Bearer Token、Cookie Token 和 API Key 三种认证方式。一旦找到有效凭证，中间件会将用户信息和权限快照存入 `request.state`，供后续处理函数使用。这种设计使得业务逻辑可以专注于权限检查，无需关心认证细节。\n\n中间件还会添加响应头 `X-Process-Time`，记录请求处理耗时，便于监控和性能分析。处理时间会被记录但不会影响正常响应，主要用于调试和运维目的。\n\n资料来源：[backend/open_webui/utils/asgi_middleware.py:1-150](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/asgi_middleware.py)\n\n### CSRF 保护\n\n系统实现了 CSRF（跨站请求伪造）保护机制，防止恶意网站诱导已登录用户发起非预期请求。CSRF 防护通过验证请求头中的自定义字段实现，敏感操作（如表单提交、状态变更）必须携带有效的 CSRF 令牌。\n\nWeb 界面在发起跨域请求前会自动获取并附加 CSRF 令牌，确保用户操作的合法性。API 客户端则需要在请求头中手动添加令牌，或使用 Cookie 认证方式（Cookie 请求会自动携带同源策略保护）。\n\n## 环境配置\n\n### 认证相关环境变量\n\nOpen WebUI 通过环境变量配置认证和安全相关的各项参数。这些变量在服务启动时读取，决定了系统的安全行为。\n\n| 环境变量 | 默认值 | 描述 |\n|----------|--------|------|\n| WEBUI_AUTH | True | 是否启用认证（False 为公开访问） |\n| ADMIN_USER_EMAIL | - | 管理员邮箱（首次启动时创建） |\n| ADMIN_USER_PASSWORD | - | 管理员密码 |\n| JWT_EXPIRY | 24h | JWT 令牌有效期 |\n| OIDC_CLIENT_ID | - | OAuth 客户端 ID |\n| OIDC_CLIENT_SECRET | - | OAuth 客户端密钥 |\n| OIDC_PROVIDER_URL | - | OIDC 提供商 URL |\n| CUSTOM_API_KEY_HEADER | x-api-key | API Key 传输头名称 |\n| SCIM_AUTH_HEADER | - | SCIM 认证头 |\n\n管理员邮箱和密码在首次启动时用于创建初始管理员账号。如果未设置，系统会在控制台输出随机生成的初始密码。生产环境中强烈建议设置强密码并妥善保管凭证。\n\n资料来源：[backend/open_webui/env.py:30-100](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/env.py)\n\n### OAuth 提供商配置\n\nOAuth 认证需要配置提供商的详细信息。以下是常见的 OAuth 提供商配置示例：\n\n```bash\n# Keycloak 配置示例\nOIDC_PROVIDER_URL=https://keycloak.example.com/realms/myrealm\nOIDC_CLIENT_ID=open-webui\nOIDC_CLIENT_SECRET=your-client-secret\n\n# Authentik 配置示例\nOIDC_PROVIDER_URL=https://authentik.example.com/application/oauth2/open-webui\nOIDC_CLIENT_ID=open-webui\nOIDC_CLIENT_SECRET=your-client-secret\n\n# 通用 OIDC 配置（系统自动发现元数据）\nOIDC_PROVIDER_URL=https://provider.example.com\nOIDC_CLIENT_ID=open-webui\nOIDC_CLIENT_SECRET=your-client-secret\n```\n\n配置完成后，管理员需要在 OAuth 提供商的应用注册中设置回调 URL，格式为 `{WEBUI_URL}/auth/oidc/callback`。用户点击登录页的 SSO 按钮后将自动跳转到提供商进行身份验证。\n\n资料来源：[backend/open_webui/utils/oauth.py:100-250](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/oauth.py)\n\n## 安全最佳实践\n\n### 部署建议\n\n在生产环境中部署 Open WebUI 时，应遵循以下安全最佳实践：\n\n- **启用 HTTPS**：所有生产部署必须使用 HTTPS，确保传输层加密。使用反向代理（如 Nginx、Caddy）终止 TLS 连接并转发 HTTP 请求到后端。\n- **配置强管理员密码**：首次部署时使用包含大小写字母、数字和特殊字符的强密码。定期更换密码，建议周期为 90 天。\n- **限制 API Key 访问**：API Key 适合机器对机器通信，应限制其访问范围，优先使用最小权限原则。\n- **启用审计日志**：配置日志记录所有认证事件和敏感操作，便于安全审计和异常检测。\n- **定期更新**：保持 Open WebUI 和所有依赖项为最新版本，及时应用安全补丁。\n\n### 常见安全威胁防护\n\n系统内置了针对常见 Web 安全威胁的防护机制：\n\n- **SQL 注入防护**：使用参数化查询处理所有数据库操作，阻止恶意 SQL 代码注入。\n- **XSS 防护**：前端对用户输入进行转义处理，防止跨站脚本执行。\n- **CSRF 防护**：敏感操作需要有效的 CSRF 令牌，防止跨站请求伪造。\n- **暴力破解防护**：登录失败后实施渐进式延迟，阻止自动化暴力猜测攻击。\n\n## 总结\n\nOpen WebUI 的认证与安全系统提供了全面而灵活的访问控制能力，支持从简单的单用户部署到复杂的企业级 SSO 集成。通过 JWT 令牌、OAuth 2.0、API Key 和 SCIM 协议的多重支持，系统可以适应各种使用场景和安全需求。基于角色的访问控制与细粒度资源权限的结合，确保了权限管理的精确性和灵活性。管理员应根据实际需求选择合适的认证方式，并遵循安全最佳实践进行部署和运维。\n\n---\n\n\n\n## 前端组件结构\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [前端路由页面](#page-frontend-routes)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/lib/components/chat/Chat.svelte](https://github.com/open-webui/open-webui/blob/main/src/lib/components/chat/Chat.svelte)\n- [src/lib/components/chat/Messages.svelte](https://github.com/open-webui/open-webui/blob/main/src/lib/components/chat/Messages.svelte)\n- [src/lib/components/workspace/Models.svelte](https://github.com/open-webui/open-webui/blob/main/src/lib/components/workspace/Models.svelte)\n- [src/lib/components/admin/Settings.svelte](https://github.com/open-webui/open-webui/blob/main/src/lib/components/admin/Settings.svelte)\n- [src/lib/stores/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/stores/index.ts)\n- [src/lib/i18n/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/i18n/index.ts)\n \n\n# 前端组件结构\n\n## 概述\n\nOpen WebUI 的前端采用现代化的 SvelteKit 框架构建，采用组件化架构设计。前端代码位于 `src/` 目录下，主要包含组件（components）、状态管理（stores）、工具函数（utils）、国际化（i18n）等核心模块。整个前端架构遵循高内聚低耦合的设计原则，通过 Svelte 的响应式系统和 Store 模式实现状态共享与组件通信。\n\n## 目录结构\n\n```\nsrc/\n├── lib/\n│ ├── components/ # UI 组件目录\n│ │ ├── chat/ # 聊天相关组件\n│ │ ├── workspace/ # 工作区组件\n│ │ ├── admin/ # 管理面板组件\n│ │ └── ...\n│ ├── stores/ # Svelte 状态存储\n│ ├── utils/ # 工具函数\n│ ├── i18n/ # 国际化模块\n│ └── constants.ts # 常量定义\n├── app.html # 应用主模板\n└── routes/ # 页面路由\n```\n\n## 核心组件架构\n\n### 聊天组件体系\n\n聊天模块是 Open WebUI 的核心功能之一，主要由以下组件构成：\n\n| 组件名称 | 文件路径 | 功能描述 |\n|---------|---------|---------|\n| Chat.svelte | src/lib/components/chat/ | 聊天主容器组件，处理用户输入和消息流 |\n| Messages.svelte | src/lib/components/chat/ | 消息展示组件，负责渲染对话内容 |\n| Collapsible | - | 可折叠容器，用于渲染思考过程和代码解释器 |\n\n#### 消息处理流程\n\n```mermaid\ngraph TD\n A[用户输入] --> B[Chat.svelte]\n B --> C[验证输入]\n C --> D[发送API请求]\n D --> E[流式响应]\n E --> F[Messages.svelte]\n F --> G[内容处理sanitizeResponseContent]\n G --> H[渲染消息]\n H --> I[显示完成状态]\n \n J[代码块] --> K[Collapsible组件]\n K --> L[代码解释器执行]\n L --> M[展示执行结果]\n```\n\n聊天组件通过 Store 模式实现与全局状态的同步，支持流式输出和多模态交互。\n\n### 工作区组件\n\nModels.svelte 是工作区中的重要组件，负责模型管理和配置界面：\n\n```mermaid\ngraph LR\n A[模型列表] --> B[模型选择器]\n B --> C[配置面板]\n C --> D[参数调整]\n D --> E[模型切换]\n E --> A\n```\n\n工作区组件与后端 API 通过统一的接口层进行通信，支持模型的动态加载和配置管理。\n\n### 管理面板组件\n\n管理面板通过 Settings.svelte 组件实现用户设置和系统配置功能：\n\n| 配置类别 | 功能模块 |\n|---------|---------|\n| 用户设置 | 主题切换、语言选择、音频配置 |\n| 系统设置 | API 配置、数据库连接、存储后端 |\n| 安全设置 | RBAC 权限管理、访问控制 |\n\n## 状态管理\n\n### Store 架构\n\nOpen WebUI 使用 Svelte 的 writable store 模式实现全局状态管理。核心状态存储定义在 `src/lib/stores/index.ts` 中：\n\n```typescript\n// 关键状态定义示例\nexport const settings: Writable = writable({});\nexport const chatRequestQueues: Writable> = writable({});\nexport const showSidebar = writable(false);\nexport const showSettings = writable(false);\n```\n\n#### 状态分类表\n\n| 状态类型 | 变量名 | 用途 |\n|---------|-------|------|\n| 用户界面 | showSidebar, showSettings | 控制面板显示/隐藏 |\n| 聊天状态 | chatRequestQueues | 管理请求队列 |\n| 全局配置 | settings | 存储用户偏好设置 |\n| 临时状态 | temporaryChatEnabled | 临时会话标记 |\n\n### 响应式数据流\n\n```mermaid\ngraph LR\n A[用户操作] --> B[Store 更新]\n B --> C[响应式订阅]\n C --> D[组件重渲染]\n D --> E[UI 更新]\n```\n\n## 国际化支持\n\n### i18n 模块\n\n国际化系统位于 `src/lib/i18n/` 目录，支持多语言切换功能：\n\n- 语言检测与自动切换\n- 实时翻译文本替换\n- 聊天历史上下文保留\n\n国际化配置通过后端 `backend/open_webui/config.py` 中的配置项管理：\n\n```python\nVOICE_MODE_PROMPT_TEMPLATE = PersistentConfig(...)\nENABLE_VOICE_MODE_PROMPT = PersistentConfig(...)\n```\n\n## 工具函数库\n\n### 核心工具模块\n\n`src/lib/utils/index.ts` 提供了丰富的前端工具函数：\n\n| 函数名称 | 功能描述 |\n|---------|---------|\n| sanitizeResponseContent | 清理响应内容，移除特殊标记 |\n| processResponseContent | 处理中文内容显示 |\n| extractSentences | 提取音频用句子 |\n| extractParagraphsForAudio | 提取音频用段落 |\n| extractCodeBlocks | 提取并处理代码块 |\n\n#### 内容处理流程\n\n```mermaid\ngraph TD\n A[原始内容] --> B[移除特殊标记]\n B --> C[中文处理processChineseContent]\n C --> D[代码块提取]\n D --> E[清理敏感字符]\n E --> F[最终输出]\n```\n\n### 响应内容清理\n\n系统通过 `sanitizeResponseContent` 函数处理模型输出：\n\n```typescript\nexport const sanitizeResponseContent = (content: string) => {\n return content\n .replace(/<\\|[a-z]*$/, '')\n .replace(/<\\|[a-z]+\\|$/, '')\n .replace(/<$/, '')\n .replaceAll('<', '<')\n .replaceAll('>', '>')\n .replaceAll(/<\\|[a-z]+\\|>/g, ' ')\n .trim();\n};\n```\n\n## 常量与配置\n\n### 前端常量定义\n\n`src/lib/constants.ts` 定义了应用级别的常量：\n\n```typescript\nexport const APP_NAME = 'Open WebUI';\nexport const WEBUI_API_BASE_URL = `${WEBUI_BASE_URL}/api/v1`;\nexport const REQUIRED_OLLAMA_VERSION = '0.1.16';\n```\n\n#### 支持的文件类型\n\n| 类型分类 | 文件格式 |\n|---------|---------|\n| 文档 | PDF, EPUB, DOCX, Markdown |\n| 代码 | Python, JavaScript, CSS, XML |\n| 音频 | MPEG, WAV |\n| 其他 | CSV, HTML, Plain Text |\n\n### API 端点常量\n\n| 常量名称 | 用途 |\n|---------|------|\n| OLLAMA_API_BASE_URL | Ollama 模型 API |\n| OPENAI_API_BASE_URL | OpenAI 兼容 API |\n| AUDIO_API_BASE_URL | 音频处理 API |\n| IMAGES_API_BASE_URL | 图像生成 API |\n| RETRIEVAL_API_BASE_URL | 检索增强 API |\n\n## 数据流转架构\n\n### 消息流转\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant C as Chat.svelte\n participant S as Stores\n participant M as Messages.svelte\n participant API as Backend API\n \n U->>C: 发送消息\n C->>API: POST /api/v1/chat\n API-->>C: 流式响应\n C->>S: 更新状态\n S->>M: 触发响应式更新\n M-->>U: 渲染消息内容\n```\n\n### 状态同步机制\n\n组件间通过 Svelte 的响应式系统实现高效状态同步，无需手动订阅和取消订阅。\n\n## 组件通信模式\n\n### 父子组件通信\n\n- Props 传递：父组件向子组件传递数据和回调函数\n- 事件分发：子组件通过 `createEventDispatcher` 触发事件\n\n### 跨组件通信\n\n- Store 共享：多个组件订阅同一 Store 实现状态共享\n- Context API：深层嵌套组件间的数据传递\n\n## 样式与主题\n\n### 主题系统\n\n`src/app.html` 中定义了主题切换的基础样式：\n\n```css\nhtml.dark #splash-screen {\n background: #000;\n}\n\nhtml.her #splash-screen {\n background: #983724;\n}\n```\n\n### 加载屏幕\n\n应用启动时显示统一的加载界面，包含 Logo、进度条等元素，通过 CSS 控制显示与隐藏。\n\n## 技术栈总结\n\n| 层级 | 技术选型 | 说明 |\n|-----|---------|------|\n| 框架 | SvelteKit | 现代化的 Svelte 框架 |\n| 状态管理 | Svelte Stores | 轻量级响应式状态管理 |\n| 路由 | SvelteKit Routes | 基于文件的路由系统 |\n| 构建工具 | Vite | 快速开发与构建 |\n| 样式 | CSS + Custom Properties | 原生 CSS 变量支持主题 |\n| 国际化 | 自定义 i18n 模块 | 多语言支持 |\n\n本页面详细介绍了 Open WebUI 前端组件的组织结构、核心组件功能、状态管理机制以及数据流转方式，为开发者理解和扩展前端功能提供了系统性参考。\n\n---\n\n\n\n## 前端路由页面\n\n### 相关页面\n\n相关主题：[前端组件结构](#page-frontend-structure), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/routes/(app)/+page.svelte](https://github.com/open-webui/open-webui/blob/main/src/routes/(app)/+page.svelte) *(未在当前上下文中提供)*\n- [src/routes/(app)/+layout.svelte](https://github.com/open-webui/open-webui/blob/main/src/routes/(app)/+layout.svelte) *(未在当前上下文中提供)*\n- [src/routes/(app)/admin/+page.svelte](https://github.com/open-webui/open-webui/blob/main/src/routes/(app)/admin/+page.svelte) *(未在当前上下文中提供)*\n- [src/routes/(app)/workspace/+page.svelte](https://github.com/open-webui/open-webui/blob/main/src/routes/(app)/workspace/+page.svelte) *(未在当前上下文中提供)*\n- [src/routes/(app)/c/[id]/+page.svelte](https://github.com/open-webui/open-webui/blob/main/src/routes/(app)/c/[id]/+page.svelte) *(未在当前上下文中提供)*\n- [src/lib/constants.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)\n- [src/lib/utils/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/utils/index.ts)\n- [src/lib/apis/terminal/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/apis/terminal/index.ts)\n- [backend/open_webui/main.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/main.py)\n- [backend/open_webui/routers/knowledge.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)\n- [backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)\n \n\n# 前端路由页面\n\n## 概述\n\nOpen WebUI 的前端采用 **SvelteKit** 作为核心框架，通过文件路由系统（File-based Routing）组织页面结构。路由系统遵循 SvelteKit 的约定式路由规范，使用 `(app)` 路由组来封装应用的主要功能页面。\n\n前端路由页面的主要职责包括：\n\n- 提供用户交互的主界面（聊天、对话管理）\n- 实现管理员控制台\n- 支持工作区功能\n- 处理动态路由参数（如对话 ID）\n\n## 路由架构\n\n### 路由目录结构\n\n```\nsrc/routes/\n├── (app)/\n│ ├── +layout.svelte # 应用布局组件\n│ ├── +page.svelte # 首页/主聊天页面\n│ ├── admin/\n│ │ └── +page.svelte # 管理后台页面\n│ ├── workspace/\n│ │ └── +page.svelte # 工作区页面\n│ └── c/\n│ └── [id]/\n│ └── +page.svelte # 动态对话详情页\n```\n\n### 路由与后端 API 的映射关系\n\n| 前端路由 | 后端 API 前缀 | 功能描述 |\n|----------|---------------|----------|\n| `(app)/+page.svelte` | `/api/v1/chats` | 聊天列表与主界面 |\n| `(app)/admin/+page.svelte` | `/api/v1/*` | 系统管理与配置 |\n| `(app)/workspace/+page.svelte` | `/api/v1/knowledge` | 知识库与 RAG 工作区 |\n| `(app)/c/[id]/+page.svelte` | `/api/v1/chats/{id}` | 特定对话详情与消息 |\n\n## 核心组件说明\n\n### 布局组件 (`+layout.svelte`)\n\n`(app)/+layout.svelte` 作为全局布局，包裹所有 `(app)` 路由组下的页面。主要功能包括：\n\n- 初始化全局状态管理\n- 配置应用级导航栏\n- 加载用户会话信息\n- 设置主题与语言偏好\n\n### 主页面 (`+page.svelte`)\n\n`(app)/+page.svelte` 是用户首次访问时的默认页面，提供：\n\n- 对话列表展示\n- 新建对话入口\n- 模型选择器\n- 聊天消息输入框\n\n### 管理员页面\n\n`(app)/admin/+page.svelte` 提供系统管理功能：\n\n- 用户管理 (RBAC)\n- 模型配置\n- 系统设置\n- 日志与审计\n\n资料来源：[backend/open_webui/main.py:1-50]()\n\n### 工作区页面\n\n`(app)/workspace/+page.svelte` 面向知识管理场景：\n\n- 知识库文件上传与管理\n- RAG 配置\n- 文档处理状态监控\n\n资料来源：[backend/open_webui/routers/knowledge.py:1-50]()\n\n### 动态对话页面\n\n`(app)/c/[id]/+page.svelte` 处理动态路由参数 `[id]`，该页面用于：\n\n- 加载特定对话的消息历史\n- 渲染对话流内容\n- 处理代码解释器等特殊消息类型\n\n资料来源：[src/lib/utils/index.ts:1-80]()\n\n## API 路由集成\n\n### 后端 FastAPI 路由注册\n\nOpen WebUI 后端使用 FastAPI 的.include_router()方法注册所有 API 路由：\n\n```python\napp.include_router(chats.router, prefix='/api/v1/chats', tags=['chats'])\napp.include_router(knowledge.router, prefix='/api/v1/knowledge', tags=['knowledge'])\napp.include_router(models.router, prefix='/api/v1/models', tags=['models'])\napp.include_router(files.router, prefix='/api/v1/files', tags=['files'])\n```\n\n资料来源：[backend/open_webui/main.py:50-80]()\n\n### 前端 API 端点常量\n\n前端通过 `src/lib/constants.ts` 定义 API 基础 URL：\n\n| 常量名 | 值 | 用途 |\n|--------|-----|------|\n| `WEBUI_API_BASE_URL` | `/api/v1` | 主 API 端点 |\n| `AUDIO_API_BASE_URL` | `/api/v1/audio` | 音频处理 |\n| `IMAGES_API_BASE_URL` | `/api/v1/images` | 图像处理 |\n| `RETRIEVAL_API_BASE_URL` | `/api/v1/retrieval` | RAG 检索 |\n\n资料来源：[src/lib/constants.ts:1-20]()\n\n## 状态管理与数据流\n\n```mermaid\ngraph TD\n A[用户交互] --> B[SvelteKit 路由]\n B --> C{页面组件}\n \n C --> D[加载对话数据]\n C --> E[管理知识库]\n C --> F[管理员操作]\n \n D --> G[调用 /api/v1/chats]\n E --> H[调用 /api/v1/knowledge]\n F --> I[调用 /api/v1/users, /api/v1/configs]\n \n G --> J[后端 Chat 路由处理器]\n H --> K[后端 Knowledge 路由处理器]\n I --> L[后端 Admin 路由处理器]\n \n J --> M[(SQLite/PostgreSQL)]\n K --> N[(向量数据库)]\n L --> M\n```\n\n## 消息内容处理\n\n前端路由页面使用 `sanitizeResponseContent` 和 `processResponseContent` 函数处理 AI 响应：\n\n```typescript\nexport const sanitizeResponseContent = (content: string) => {\n return content\n .replace(/<\\|[a-z]*$/, '')\n .replace(/<\\|[a-z]+\\|$/, '')\n .replace(/<$/, '')\n .replaceAll('<', '<')\n .replaceAll('>', '>')\n .replaceAll(/<\\|[a-z]+\\|>/g, ' ')\n .trim();\n};\n```\n\n资料来源：[src/lib/utils/index.ts:50-70]()\n\n### 中文内容特殊处理\n\n针对中文内容，框架进行了特殊处理以解决 Markdown/LaTeX 格式问题：\n\n```typescript\nfunction processChineseContent(content: string): string {\n if (!/[\\u4e00-\\u9fa5]/.test(content)) return content;\n // 中文内容处理逻辑\n}\n```\n\n资料来源：[src/lib/utils/index.ts:75-90]()\n\n## 文件 API 与终端集成\n\n前端通过 `src/lib/apis/terminal/index.ts` 提供文件操作能力：\n\n| 函数 | 功能 |\n|------|------|\n| `listFiles` | 列出目录中的文件 |\n| `readFile` | 读取文件内容 |\n| `downloadFileBlob` | 下载文件为 Blob |\n\n资料来源：[src/lib/apis/terminal/index.ts:1-60]()\n\n## 代码解释器集成\n\n路由页面支持代码解释器功能，通过后端中间件处理 `code_interpreter` 类型消息：\n\n```python\nelif item_type == 'open_webui:code_interpreter':\n # 代码解释器消息处理\n code = item.get('code', '').strip()\n lang = item.get('lang', 'python')\n status = item.get('status', 'in_progress')\n```\n\n资料来源：[backend/open_webui/utils/middleware.py:1-50]()\n\n### 代码执行引擎配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `ENABLE_CODE_EXECUTION` | True | 是否启用代码执行 |\n| `CODE_EXECUTION_ENGINE` | pyodide | 执行引擎 (pyodide/jupyter) |\n| `CODE_EXECUTION_JUPYTER_URL` | - | Jupyter 服务地址 |\n| `CODE_EXECUTION_JUPYTER_AUTH` | - | Jupyter 认证信息 |\n\n资料来源：[backend/open_webui/config.py:1-50]()\n\n## 访问控制与权限\n\n路由页面通过后端 RBAC 系统实现访问控制：\n\n```python\nif not (\n user.role == 'admin'\n or knowledge.user_id == user.id\n or await AccessGrants.has_access(...)\n):\n raise HTTPException(status_code=400, detail=ERROR_MESSAGES.ACCESS_PROHIBITED)\n```\n\n资料来源：[backend/open_webui/routers/knowledge.py:50-80]()\n\n## 相关页面\n\n- [后端 API 路由](backend/open_webui/main.py)\n- [前端工具函数](src/lib/utils/index.ts)\n- [应用常量定义](src/lib/constants.ts)\n- [知识库路由](backend/open_webui/routers/knowledge.py)\n- [终端 API](src/lib/apis/terminal/index.ts)\n\n---\n\n\n\n## 模型集成与支持\n\n### 相关页面\n\n相关主题：[检索增强生成 (RAG)](#page-retrieval-rag), [工具与函数系统](#page-tools-functions)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [backend/open_webui/main.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/main.py)\n- [backend/open_webui/routers/models.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/models.py)\n- [backend/open_webui/routers/ollama.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/ollama.py)\n- [backend/open_webui/routers/openai.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/openai.py)\n- [backend/open_webui/utils/models.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/models.py)\n- [backend/open_webui/models/models.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/models.py)\n- [backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)\n- [src/lib/constants.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)\n- [src/lib/components/chat/ModelSelector.svelte](https://github.com/open-webui/open-webui/blob/main/src/lib/components/chat/ModelSelector.svelte)\n- [src/lib/components/workspace/Models.svelte](https://github.com/open-webui/open-webui/blob/main/src/lib/components/workspace/Models.svelte)\n \n\n# 模型集成与支持\n\n## 概述\n\nOpen WebUI 的模型集成与支持系统是整个平台的核心功能模块，负责管理与接入多种大语言模型（LLM）提供方。该系统通过统一的 API 网关架构，将 Ollama、OpenAI 兼容 API 等多种模型服务进行抽象封装，为用户提供无缝的模型切换与交互体验。\n\n系统支持多模型并发对话、模型热度管理、角色权限控制等功能，并提供完整的模型生命周期管理，包括模型的发现、拉取、配置与删除操作。资料来源：[backend/open_webui/main.py:48]()\n\n```mermaid\ngraph TD\n A[用户界面] --> B[前端 ModelSelector]\n B --> C[API 网关层]\n C --> D[Ollama 路由器]\n C --> E[OpenAI 路由器]\n C --> F[Models 路由器]\n D --> G[Ollama 服务]\n E --> H[OpenAI 兼容服务]\n F --> I[模型数据库]\n G --> I\n H --> I\n```\n\n## 架构设计\n\n### API 端点结构\n\nOpen WebUI 采用 FastAPI 框架构建后端服务，通过路由器（Router）模式组织 API 端点。模型相关的 API 端点分布在多个路由器中，形成统一的接口体系。\n\n| 路由器 | 前缀路径 | 标签 | 功能描述 |\n|--------|----------|------|----------|\n| models | `/api/v1/models` | models | 模型 CRUD 操作 |\n| ollama | `/api/v1/ollama` | ollama | Ollama 专属 API |\n| openai | `/api/v1/openai` | openai | OpenAI 兼容 API |\n| functions | `/api/v1/functions` | functions | 函数调用管理 |\n\n资料来源：[backend/open_webui/main.py:48-54]()\n\n### 服务地址配置\n\n前端通过 `src/lib/constants.ts` 集中管理所有 API 服务地址，支持开发环境与生产环境的动态切换。\n\n```typescript\nexport const WEBUI_HOSTNAME = browser ? (dev ? `${location.hostname}:8080` : ``) : '';\nexport const WEBUI_BASE_URL = browser ? (dev ? `http://${WEBUI_HOSTNAME}` : ``) : ``;\nexport const WEBUI_API_BASE_URL = `${WEBUI_BASE_URL}/api/v1`;\nexport const OLLAMA_API_BASE_URL = `${WEBUI_BASE_URL}/ollama`;\nexport const OPENAI_API_BASE_URL = `${WEBUI_BASE_URL}/openai`;\n```\n\n资料来源：[src/lib/constants.ts:4-11]()\n\n## 支持的模型类型\n\n### Ollama 模型\n\nOllama 是 Open WebUI 的核心本地模型运行引擎，支持在本地部署和运行各类开源大语言模型。系统通过 Ollama API 进行模型管理，支持超过 1000 种开源模型。\n\n支持的模型类型包括：\n\n- **对话模型**：Llama 2/3、Mistral、Qwen 等\n- **嵌入模型**：用于向量检索和语义搜索\n- **多模态模型**：支持图像理解和分析的模型\n\n### OpenAI 兼容模型\n\nOpen WebUI 通过 OpenAI 兼容层支持接入任何符合 OpenAI API 规范的服务提供方，包括：\n\n- OpenAI 官方 API（GPT-4、GPT-3.5-turbo）\n- Azure OpenAI Service\n- 自定义 OpenAI 兼容 API 服务器\n- 云端模型服务（如 Groq、Perplexity 等）\n\n资料来源：[src/lib/apis/openai/index.ts:1-10]()\n\n## 前端模型选择组件\n\n### ModelSelector 组件\n\n`ModelSelector.svelte` 是聊天界面中的模型选择器组件，提供直观的模型切换交互界面。该组件支持以下功能：\n\n- 模型搜索与过滤\n- 模型热度排序\n- 快捷键切换模型\n- 模型图标与描述显示\n\n```mermaid\ngraph LR\n A[用户点击选择器] --> B[展开模型列表]\n B --> C[搜索/过滤模型]\n C --> D[选择目标模型]\n D --> E[更新会话上下文]\n E --> F[发送请求至后端]\n```\n\n资料来源：[src/lib/components/chat/ModelSelector.svelte]()\n\n### Workspace Models 组件\n\n`Models.svelte` 是工作区中的模型管理界面，提供更全面的模型管理功能，包括：\n\n- 模型列表展示与排序\n- 模型添加与配置\n- 模型删除与禁用\n- 模型使用统计\n\n资料来源：[src/lib/components/workspace/Models.svelte]()\n\n## 模型管理 API\n\n### 获取模型列表\n\n```\nGET /api/v1/models\n```\n\n返回系统中所有已配置的模型列表，包括模型的元数据、状态和配置信息。\n\n### 获取模型详情\n\n```\nGET /api/v1/models/{model_id}\n```\n\n获取指定模型的详细信息，包括：\n\n- 模型 ID 和名称\n- 模型类型和提供者\n- 上下文长度\n- 支持的功能（函数调用、视觉等）\n\n### 创建模型配置\n\n```\nPOST /api/v1/models\n```\n\n创建新的模型配置，支持配置模型参数和连接信息。\n\n### 更新模型配置\n\n```\nPUT /api/v1/models/{model_id}\n```\n\n更新现有模型的配置参数。\n\n### 删除模型\n\n```\nDELETE /api/v1/models/{model_id}\n```\n\n从系统中移除指定的模型配置。\n\n资料来源：[backend/open_webui/main.py:48]()\n\n## 配置选项\n\n### 环境变量配置\n\n系统通过环境变量和配置文件管理模型相关的设置。主要配置项包括：\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| `OLLAMA_API_BASE_URL` | Ollama API 地址 | `/ollama` |\n| `OPENAI_API_BASE_URL` | OpenAI API 地址 | `/openai` |\n| `OPENAI_API_KEY` | OpenAI API 密钥 | - |\n| `ENABLE_OPENAI_API` | 启用 OpenAI API | True |\n| `DEFAULT_MODEL` | 默认模型 | - |\n\n资料来源：[backend/open_webui/config.py]()\n\n### 运行时配置\n\n系统支持通过管理员界面动态调整模型配置，包括：\n\n- 模型调用参数（温度、最大 token 等）\n- API 超时设置\n- 重试策略配置\n- 代理设置\n\n## 多模型对话支持\n\nOpen WebUI 支持在单一对话中使用多个模型，通过并行调用不同模型获取响应，实现更优的回答质量。\n\n### 多模型对话流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant F as 前端\n participant B as 后端\n participant M1 as 模型A\n participant M2 as 模型B\n \n U->>F: 发送消息\n F->>B: 转发请求\n B->>M1: 并发请求模型A\n B->>M2: 并发请求模型B\n M1-->>B: 返回响应A\n M2-->>B: 返回响应B\n B-->>F: 合并响应\n F-->>U: 展示结果\n```\n\n### 模型选择策略\n\n系统支持多种模型选择策略：\n\n1. **自动选择**：根据请求类型自动选择最合适的模型\n2. **手动选择**：用户显式指定使用的模型\n3. **智能路由**：基于模型能力与请求特征的动态路由\n\n资料来源：[src/lib/components/chat/ModelSelector.svelte]()\n\n## 角色权限控制\n\nOpen WebUI 实现基于角色的访问控制（RBAC），模型访问权限与用户角色挂钩：\n\n| 角色 | 权限级别 | 可用功能 |\n|------|----------|----------|\n| 管理员 | 完全权限 | 所有模型操作 |\n| 普通用户 | 受限权限 | 使用已授权模型 |\n| 访客 | 最小权限 | 仅使用公开模型 |\n\n资料来源：[README.md]()\n\n## 最佳实践\n\n### 模型选择建议\n\n1. **性能优先场景**：选择量化模型或较小的模型以降低延迟\n2. **质量优先场景**：使用较大的基础模型或 GPT-4 系列\n3. **成本敏感场景**：优先使用本地 Ollama 模型\n4. **多模态场景**：选择支持视觉的模型（如 Llava）\n\n### 安全配置\n\n- 生产环境务必配置 API 密钥\n- 启用模型访问审计日志\n- 定期轮换 API 密钥\n- 限制敏感模型的访问权限\n\n## 相关文档\n\n- [Ollama 官方文档](https://github.com/ollama/ollama)\n- [OpenAI API 文档](https://platform.openai.com/docs/api-reference)\n- [Open WebUI 安装指南](./installation.md)\n- [管理员配置手册](./admin-guide.md)\n\n---\n\n\n\n## 检索增强生成 (RAG)\n\n### 相关页面\n\n相关主题：[模型集成与支持](#page-model-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [backend/open_webui/retrieval/vector/factory.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/retrieval/vector/factory.py)\n- [backend/open_webui/retrieval/loaders/main.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/retrieval/loaders/main.py)\n- [backend/open_webui/retrieval/web/main.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/retrieval/web/main.py)\n- [backend/open_webui/routers/knowledge.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)\n- [backend/open_webui/routers/retrieval.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/retrieval.py)\n \n\n# 检索增强生成 (RAG)\n\n## 概述\n\n检索增强生成（Retrieval-Augmented Generation，简称 RAG）是一种将信息检索与语言模型生成相结合的技术架构。在 Open WebUI 项目中，RAG 模块负责从外部知识库、文档集合或网络资源中检索相关内容，并将检索结果注入到大语言模型（LLM）的上下文窗口中，从而提升模型回答的准确性、时效性和可信度。\n\nOpen WebUI 的 RAG 系统支持多种文档格式、多种向量存储后端以及多种网络搜索提供者，形成了完整的**文档处理 → 向量化 → 存储 → 检索 → 上下文注入**链路。\n\n## 核心架构\n\nRAG 系统在整体上分为三大子模块：\n\n1. **文档加载与处理（Loaders）**：负责从各类文件格式中提取文本内容\n2. **向量存储与检索（Vector Stores）**：负责文本的向量化、存储和相似度检索\n3. **网络搜索（Web Retrieval）**：支持通过外部搜索引擎获取实时信息\n\n```mermaid\ngraph TD\n A[用户查询] --> B[检索模块]\n B --> C{检索类型}\n C -->|知识库检索| D[向量存储检索]\n C -->|网络搜索| E[Web Search Providers]\n \n D --> F[文档加载器]\n F --> G[文本分块]\n G --> H[向量化]\n H --> I[向量数据库]\n I --> J[相似度检索]\n J --> K[上下文构建]\n \n E --> L[搜索结果处理]\n L --> K\n \n K --> M[LLM 生成响应]\n```\n\n## 文档加载与处理\n\n### 支持的文件格式\n\n文档加载模块支持以下文件类型（资料来源：[src/lib/constants.ts](src/lib/constants.ts)）：\n\n| 文件类型 | MIME 类型 |\n|---------|-----------|\n| PDF | `application/pdf` |\n| EPUB | `application/epub+zip` |\n| Word 文档 | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |\n| 纯文本 | `text/plain` |\n| CSV | `text/csv` |\n| XML | `text/xml` |\n| HTML | `text/html` |\n| Markdown | `text/markdown` |\n| Python 代码 | `text/x-python` |\n| CSS | `text/css` |\n| JavaScript | `application/x-javascript` |\n| 音频 | `audio/mpeg`, `audio/wav` |\n\n### 加载器实现\n\n文档加载器的核心实现在 `backend/open_webui/retrieval/loaders/` 目录下。加载器采用统一的接口设计，主要包括：\n\n- **PDF 处理**：支持多种 PDF 解析后端，包括 Tika、DOCLING、文档智能（Document Intelligence）、Mistral OCR、PaddleOCR VL、MinerU 等\n- **图片 OCR**：通过 PaddleOCR VL 等引擎从图片中提取文字（资料来源：[backend/open_webui/retrieval/loaders/paddleocr_vl.py](backend/open_webui/retrieval/loaders/paddleocr_vl.py)）\n\n```mermaid\ngraph LR\n A[上传文件] --> B{文件类型判断}\n B -->|PDF| C[PDF Loader]\n B -->|图片| D[OCR Engine]\n B -->|文本| E[Text Loader]\n \n C --> F[文本提取]\n D --> G[OCR 识别]\n E --> H[直接读取]\n \n F --> I[Document 对象]\n G --> I\n H --> I\n \n I --> J[分块处理]\n J --> K[元数据附加]\n K --> L[输出片段列表]\n```\n\n### 配置参数\n\n文档处理支持以下关键配置（资料来源：[backend/open_webui/retrieval/utils.py](backend/open_webui/retrieval/utils.py)）：\n\n| 参数名 | 说明 |\n|-------|------|\n| `EXTERNAL_DOCUMENT_LOADER_URL` | 外部文档加载器服务地址 |\n| `TIKA_SERVER_URL` | Apache Tika 服务器地址 |\n| `DOCLING_SERVER_URL` | DOCLING 服务地址 |\n| `DOCLING_API_KEY` | DOCLING API 密钥 |\n| `PDF_EXTRACT_IMAGES` | 是否从 PDF 提取图片 |\n| `PDF_LOADER_MODE` | PDF 加载模式 |\n| `DOCUMENT_INTELLIGENCE_ENDPOINT` | Azure 文档智能端点 |\n| `MISTRAL_OCR_API_BASE_URL` | Mistral OCR API 地址 |\n| `PADDLEOCR_VL_BASE_URL` | PaddleOCR VL 服务地址 |\n| `MINERU_API_URL` | MinerU API 地址 |\n\n## 向量存储与检索\n\n### 向量存储后端\n\nOpen WebUI 支持多种向量数据库作为存储后端，通过工厂模式（Factory Pattern）进行统一管理（资料来源：[backend/open_webui/retrieval/vector/factory.py](backend/open_webui/retrieval/vector/factory.py)）：\n\n| 向量存储 | 说明 |\n|---------|------|\n| Chroma | 本地向量数据库 |\n| FAISS | Facebook AI 相似度搜索 |\n| Qdrant | 高性能向量数据库 |\n| Milvus | 分布式向量数据库 |\n| Weaviate | 云原生向量搜索引擎 |\n| Pinecone | 云端向量数据库 |\n| Elasticsearch | 混合搜索能力 |\n| Chroma Legacy | 向后兼容模式 |\n\n### 检索流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant A as API 路由\n participant R as 检索路由器\n participant V as 向量存储\n participant L as LLM\n \n U->>A: 发送查询请求\n A->>R: 转发查询\n R->>V: 执行相似度搜索\n V-->>R: 返回 Top-K 相关片段\n R->>L: 构建提示词上下文\n L-->>U: 生成增强响应\n```\n\n### 检索 API\n\n检索功能通过 RESTful API 暴露，主要端点包括（资料来源：[backend/open_webui/routers/retrieval.py](backend/open-webui/routers/retrieval.py)）：\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/api/v1/retrieval/search` | POST | 执行知识库检索 |\n| `/api/v1/retrieval/process` | POST | 处理并索引文档 |\n| `/api/v1/retrieval/config` | GET | 获取检索配置 |\n\n## 网络搜索\n\n### 支持的搜索提供者\n\nOpen WebUI 集成了超过 15 种网络搜索提供者，可在 RAG 流程中注入实时网络信息（资料来源：[README.md](README.md)）：\n\n| 提供者 | 说明 |\n|-------|------|\n| SearXNG | 开源自托管元搜索引擎 |\n| Google PSE | Google Programmable Search Engine |\n| Brave Search | Brave 浏览器搜索 API |\n| Kagi | 高质量搜索服务 |\n| Mojeek | 独立搜索索引 |\n| Tavily | AI 优化的搜索 API |\n| Perplexity | AI 搜索服务 |\n| DuckDuckGo | 隐私导向搜索 |\n| Bing | Microsoft 搜索 API |\n| Jina | AI 驱动的搜索与摘要 |\n| Exa | 语义搜索 API |\n| Azure AI Search | Azure 云搜索服务 |\n| Ollama Cloud | Ollama 云端服务 |\n\n### 搜索结果处理\n\n搜索结果经过标准化处理后返回统一的 `SearchResult` 数据结构（资料来源：[backend/open_webui/retrieval/web/ydc.py](backend/open_webui/retrieval/web/ydc.py)）：\n\n```python\n@dataclass\nclass SearchResult:\n link: str # 结果链接\n title: str # 结果标题\n snippet: str # 摘要内容\n```\n\n对于不同的搜索 API，Open WebUI 进行了结果格式统一，包括：\n- 标题提取与清理\n- 摘要/片段（Snippet）的合并构建\n- URL 解析与规范化\n- 评分与排序\n\n## 知识库管理\n\n### 知识库 API\n\n知识库管理功能提供了完整的 CRUD 操作（资料来源：[backend/open_webui/routers/knowledge.py](backend/open-webui/routers/knowledge.py)）：\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/api/v1/knowledge` | GET | 列出所有知识库 |\n| `/api/v1/knowledge` | POST | 创建新知识库 |\n| `/api/v1/knowledge/{id}` | GET | 获取知识库详情 |\n| `/api/v1/knowledge/{id}` | PUT | 更新知识库配置 |\n| `/api/v1/knowledge/{id}` | DELETE | 删除知识库 |\n| `/api/v1/knowledge/{id}/file` | POST | 上传文件到知识库 |\n| `/api/v1/knowledge/{id}/file/{file_id}` | DELETE | 从知识库删除文件 |\n\n### 知识库数据模型\n\n```\nKnowledge {\n id: string # 唯一标识符\n name: string # 知识库名称\n description: string # 描述信息\n user_id: string # 所有者 ID\n created_at: timestamp # 创建时间\n updated_at: timestamp # 更新时间\n settings: {\n embeddings: object # 嵌入模型配置\n chunk_size: int # 分块大小\n chunk_overlap: int # 分块重叠\n }\n}\n```\n\n## RAG 与 LLM 集成\n\n### 上下文注入流程\n\nRAG 检索结果通过以下方式注入到 LLM 对话中：\n\n```mermaid\ngraph LR\n A[用户消息] --> B[检索查询生成]\n B --> C[并行执行]\n C --> D[向量检索]\n C --> E[网络搜索]\n D --> F[结果合并]\n E --> F\n F --> G[上下文构建]\n G --> H[提示词组装]\n H --> I[LLM 生成]\n I --> J[响应输出]\n```\n\n### 提示词模板\n\nRAG 系统使用专门的提示词模板来引导模型正确利用检索到的上下文：\n\n- **默认检索模板**：通用问答场景\n- **中文内容处理**：针对中文文档的特殊格式化处理（资料来源：[src/lib/utils/index.ts](src/lib/utils/index.ts)）\n- **引用标注**：在回答中标注信息来源\n\n## 配置管理\n\n### 环境变量配置\n\nRAG 系统的核心配置通过环境变量管理：\n\n| 变量名 | 默认值 | 说明 |\n|-------|-------|------|\n| `ENABLE_RAG_WEB` | `True` | 启用网络搜索 RAG |\n| `RAG_TOP_K` | `5` | 检索返回的 Top-K 结果数 |\n| `RAG_EMBEDDING_MODEL` | - | 嵌入模型选择 |\n| `RAG_VECTOR_DB` | `chroma` | 向量数据库选择 |\n| `WEB_SEARCH_API_KEY` | - | 搜索 API 密钥 |\n| `SEARXNG_QUERY_URL` | - | SearXNG 实例地址 |\n\n## 使用场景\n\n1. **私有知识问答**：上传内部文档创建私有知识库\n2. **实时信息补充**：通过网络搜索获取最新资讯\n3. **多模态文档理解**：处理 PDF、图片混合文档\n4. **跨语言检索**：支持多语言文档的统一检索\n\n## 最佳实践\n\n- **分块策略**：根据文档类型选择合适的分块大小，代码类文档建议较小分块\n- **向量模型选择**：根据文档语言选择对应语言的嵌入模型\n- **混合检索**：结合向量检索与关键词检索以平衡精确度与召回率\n- **定期更新**：知识库内容变更后需重新索引\n\n---\n\n\n\n## 工具与函数系统\n\n### 相关页面\n\n相关主题：[模型集成与支持](#page-model-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [backend/open_webui/main.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/main.py)\n- [backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)\n- [src/lib/utils/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/utils/index.ts)\n- [backend/open_webui/utils/middleware.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/middleware.py)\n- [src/lib/constants.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)\n \n\n# 工具与函数系统\n\n## 概述\n\nOpen WebUI 的工具与函数系统是平台的核心扩展机制之一，允许用户通过自定义工具和函数来增强 AI 助手的交互能力。该系统支持在对话过程中动态调用外部工具、执行代码、访问外部数据源，从而实现更丰富的智能助手体验。\n\n系统通过 API 路由层统一管理工具的注册、调用和生命周期维护，支持多种工具类型，包括内置工具、用户自定义工具以及通过函数定义的工具。\n\n## 系统架构\n\n### 整体架构流程\n\n```mermaid\ngraph TD\n A[用户请求] --> B[API 路由层
routers/tools.py]\n B --> C[工具注册表
tools/__init__.py]\n C --> D{工具类型}\n D --> E[内置工具
builtin.py]\n D --> F[用户自定义函数
models/functions.py]\n D --> G[外部工具]\n E --> H[工具执行引擎]\n F --> H\n G --> H\n H --> I[结果返回]\n I --> J[前端展示
Tools.svelte]\n```\n\n### 组件层级\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| API 层 | routers/tools.py | HTTP 接口、请求验证、响应格式化 |\n| 核心层 | tools/__init__.py | 工具注册表、调度逻辑、生命周期管理 |\n| 内置工具层 | tools/builtin.py | 系统内置工具实现 |\n| 数据模型层 | models/functions.py | 函数数据结构、序列化/反序列化 |\n| 前端层 | Tools.svelte | 工具管理界面、用户交互 |\n| 中间件层 | utils/middleware.py | 工具输出渲染、内容处理 |\n\n## 工具注册与路由\n\n### API 路由配置\n\n工具系统通过 FastAPI 路由模块挂载到主应用，所有工具相关的 HTTP 接口均以 `/api/v1/tools` 为前缀。\n\n```python\napp.include_router(tools.router, prefix='/api/v1/tools', tags=['tools'])\n```\n资料来源：[backend/open_webui/main.py]()\n\n### 路由端点\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/` | GET | 获取工具列表 |\n| `/{tool_id}` | GET | 获取特定工具详情 |\n| `/` | POST | 注册新工具 |\n| `/{tool_id}` | PUT | 更新工具配置 |\n| `/{tool_id}` | DELETE | 删除工具 |\n\n## 函数数据模型\n\n### 数据结构定义\n\n函数（Function）是工具系统的核心数据结构，用于描述可调用的工具逻辑。\n\n```python\nclass Function:\n id: str # 唯一标识符\n name: str # 函数名称\n description: str # 函数描述\n parameters: dict # 参数定义（JSON Schema）\n return_type: str # 返回值类型\n is_enabled: bool # 是否启用\n created_at: datetime # 创建时间\n updated_at: datetime # 更新时间\n```\n\n### 参数定义规范\n\n函数参数采用 JSON Schema 格式定义，支持以下类型：\n\n| 类型 | 描述 | 示例 |\n|------|------|------|\n| string | 字符串类型 | `\"type\": \"string\"` |\n| integer | 整数类型 | `\"type\": \"integer\"` |\n| number | 数字类型 | `\"type\": \"number\"` |\n| boolean | 布尔类型 | `\"type\": \"boolean\"` |\n| array | 数组类型 | `\"type\": \"array\", \"items\": {...}` |\n| object | 对象类型 | `\"type\": \"object\", \"properties\": {...}` |\n\n## 工具执行流程\n\n### 执行时序\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant A as API路由\n participant T as 工具注册表\n participant E as 执行引擎\n participant R as 结果渲染器\n\n U->>A: 调用工具请求\n A->>T: 查询工具定义\n T-->>A: 返回工具元数据\n A->>E: 提交执行任务\n E->>E: 执行工具逻辑\n E-->>A: 返回执行结果\n A->>R: 渲染结果内容\n R-->>A: 格式化输出\n A-->>U: 返回响应\n```\n\n### 内置工具类型\n\n系统预置多种内置工具，覆盖常见的扩展场景：\n\n| 工具类别 | 功能描述 |\n|----------|----------|\n| 搜索工具 | 集成 SearXNG、Google PSE、Brave Search 等搜索引擎 |\n| 知识库工具 | 支持知识库检索、文档问答 |\n| 计算工具 | 数学计算、公式求解 |\n| 代码执行 | 代码解释器执行 Python 代码 |\n| 图像生成 | 集成 DALL-E、Stable Diffusion 等图像生成服务 |\n\n## 前端集成\n\n### 工具管理界面\n\n前端工具管理组件位于 `src/lib/components/workspace/Tools.svelte`，提供以下功能：\n\n- **工具列表视图**：展示所有已注册工具，支持按名称、类型筛选\n- **工具详情面板**：查看工具描述、参数说明、使用示例\n- **工具调试控制台**：测试工具调用、查看执行结果\n- **工具创建向导**：引导用户创建自定义工具\n\n### 响应内容处理\n\n前端通过 `sanitizeResponseContent` 函数处理工具执行后的响应内容，确保内容安全展示：\n\n```typescript\nexport const sanitizeResponseContent = (content: string) => {\n\treturn content\n\t\t.replace(/<\\|[a-z]*$/, '')\n\t\t.replace(/<\\|[a-z]+\\|$/, '')\n\t\t.replace(/<$/, '')\n\t\t.replaceAll('<', '<')\n\t\t.replaceAll('>', '>')\n\t\t.replaceAll(/<\\|[a-z]+\\|>/g, ' ')\n\t\t.trim();\n};\n```\n资料来源：[src/lib/utils/index.ts]()\n\n## 中间件渲染\n\n### 工具输出渲染机制\n\n系统中间件负责将工具执行结果渲染为可展示的 HTML 格式，支持代码解释器等特殊工具类型：\n\n```python\nelif item_type == 'open_webui:code_interpreter':\n # 代码解释器需要检查/修改先前的累积内容\n # 去除尾部未闭合的代码块\n content = '\\n'.join(parts)\n content_stripped, original_whitespace = split_content_and_whitespace(content)\n if is_opening_code_block(content_stripped):\n content = content_stripped.rstrip('`').rstrip() + original_whitespace\n else:\n content = content_stripped + original_whitespace\n```\n资料来源：[backend/open_webui/utils/middleware.py]()\n\n### 渲染输出格式\n\n| 工具类型 | 渲染格式 | 说明 |\n|----------|----------|------|\n| 通用工具 | `` | 折叠面板展示 |\n| 代码解释器 | `` | 带执行状态 |\n| 思考过程 | `` | 显示思考耗时 |\n\n## 配置管理\n\n### 环境变量配置\n\n工具系统支持通过环境变量进行全局配置：\n\n| 变量名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `TOOLS_ENABLED` | bool | true | 启用/禁用工具系统 |\n| `TOOLS_LIMIT` | int | 10 | 单次对话最大工具调用数 |\n| `CODE_INTERPRETER_ENABLED` | bool | true | 启用代码解释器 |\n\n### 配置持久化\n\n工具配置通过 `PersistentConfig` 类实现持久化存储：\n\n```python\nTOOLS_ENABLED = PersistentConfig(\n 'TOOLS_ENABLED',\n 'tools.enabled',\n os.environ.get('TOOLS_ENABLED', 'True'),\n)\n```\n资料来源：[backend/open_webui/config.py]()\n\n## 安全机制\n\n### 权限控制\n\n工具系统集成基于角色的访问控制（RBAC）机制：\n\n- **管理员**：可创建、编辑、删除所有工具\n- **普通用户**：仅可使用已启用的工具\n- **访客**：无法使用工具功能\n\n### 代码执行沙箱\n\n代码解释器工具使用 RestrictedPython 库限制可执行的代码范围：\n\n```\nRestrictedPython==8.1\n```\n资料来源：[backend/requirements-min.txt]()\n\n## API 常量定义\n\n### 前端 API 端点配置\n\n| 常量名 | 值 | 用途 |\n|--------|-----|------|\n| `RETRIEVAL_API_BASE_URL` | `/api/v1/retrieval` | 检索工具 API |\n| `WEBUI_API_BASE_URL` | `/api/v1` | 通用 API 基础地址 |\n\n资料来源：[src/lib/constants.ts]()\n\n## 扩展开发指南\n\n### 创建自定义工具步骤\n\n1. **定义工具元数据**：在 `models/functions.py` 中添加函数定义\n2. **实现工具逻辑**：在 `tools/` 目录下创建工具实现文件\n3. **注册工具**：在 `tools/__init__.py` 中注册工具\n4. **挂载路由**：确保路由在 `routers/tools.py` 中可用\n5. **前端集成**：在 `Tools.svelte` 中添加工具管理界面\n\n### 工具接口规范\n\n所有自定义工具需遵循统一接口规范：\n\n```python\nclass BaseTool:\n name: str # 工具名称（唯一）\n description: str # 工具描述\n parameters: dict # JSON Schema 参数定义\n \n async def execute(self, **kwargs) -> dict:\n \"\"\"执行工具逻辑\"\"\"\n raise NotImplementedError\n```\n\n## 总结\n\nOpen WebUI 的工具与函数系统为平台提供了强大的扩展能力，通过标准化的 API 路由、数据模型和前端组件，实现了工具的注册、调用、管理全流程支持。系统架构清晰，安全机制完善，支持从内置工具到用户自定义工具的多种场景，是构建智能助手生态的重要基础设施。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：open-webui/open-webui\n\n摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:701547123 | https://github.com/open-webui/open-webui | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:701547123 | https://github.com/open-webui/open-webui | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:701547123 | https://github.com/open-webui/open-webui | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:701547123 | https://github.com/open-webui/open-webui | no_demo; severity=medium\n\n## 5. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:701547123 | https://github.com/open-webui/open-webui | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:701547123 | https://github.com/open-webui/open-webui | release_recency=unknown\n\n\n",
"markdown_key": "open-webui",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:701547123",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/open-webui/open-webui"
},
{
"evidence_id": "art_24eeae53acef4d4d93d4a4da03164209",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/open-webui/open-webui#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "open-webui 说明书",
"toc": [
"https://github.com/open-webui/open-webui 项目说明书",
"目录",
"项目概述",
"1. 项目简介",
"2. 技术架构",
"目录定义",
"3. 核心功能特性",
"4. API 架构",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": false,
"repo_commit": null,
"repo_inspection_error": null,
"repo_inspection_files": [],
"repo_inspection_verified": false,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# open-webui - Doramagic AI Context Pack\n\n> 定位：给用户宿主 AI 装载的开工前上下文。它不代表已经安装、运行或验证目标项目。\n\n## 项目\n\n- canonical_name: `open-webui/open-webui`\n- capability: User-friendly AI Interface (Supports Ollama, OpenAI API, ...)\n- expected_user_outcome: User-friendly AI Interface (Supports Ollama, OpenAI API, ...)\n\n## 基础边界\n\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 项目事实必须来自 repo evidence、Claim Graph 或明确来源。\n- 遇到未验证能力时，必须标记为待验证，而不是补全为事实。\n- publish_status: `publishable`\n- blocking_gaps: none\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n - source_paths: README.md, backend/open_webui/__init__.py, backend/open_webui/constants.py\n- **系统架构**：importance `high`\n - source_paths: backend/open_webui/main.py, backend/open_webui/config.py, backend/open_webui/socket/main.py, src/app.html, svelte.config.js\n- **后端路由与 API**：importance `high`\n - source_paths: backend/open_webui/routers/chats.py, backend/open_webui/routers/auths.py, backend/open_webui/routers/models.py, backend/open_webui/routers/ollama.py, backend/open_webui/routers/openai.py\n- **数据模型层**：importance `high`\n - source_paths: backend/open_webui/models/users.py, backend/open_webui/models/chats.py, backend/open_webui/models/messages.py, backend/open_webui/models/files.py, backend/open_webui/models/functions.py\n- **认证与安全**：importance `high`\n - source_paths: backend/open_webui/utils/auth.py, backend/open_webui/utils/oauth.py, backend/open_webui/routers/auths.py, backend/open_webui/models/users.py, backend/open_webui/routers/scim.py\n- **前端组件结构**：importance `high`\n - source_paths: src/lib/components/chat/Chat.svelte, src/lib/components/chat/Messages.svelte, src/lib/components/workspace/Models.svelte, src/lib/components/admin/Settings.svelte, src/lib/stores/index.ts\n- **前端路由页面**：importance `medium`\n - source_paths: src/routes/(app)/+page.svelte, src/routes/(app)/+layout.svelte, src/routes/(app)/admin/+page.svelte, src/routes/(app)/workspace/+page.svelte, src/routes/(app)/c/[id]/+page.svelte\n- **模型集成与支持**：importance `high`\n - source_paths: backend/open_webui/routers/ollama.py, backend/open_webui/routers/openai.py, backend/open_webui/utils/models.py, src/lib/components/chat/ModelSelector.svelte, src/lib/components/workspace/Models.svelte\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: false\n- repo_inspection_verified: false\n- repo_commit: `unknown`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:701547123 | https://github.com/open-webui/open-webui | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:701547123 | https://github.com/open-webui/open-webui | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:701547123 | https://github.com/open-webui/open-webui | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:701547123 | https://github.com/open-webui/open-webui | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:701547123 | https://github.com/open-webui/open-webui | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:701547123 | https://github.com/open-webui/open-webui | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：open-webui/open-webui\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, chatgpt\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- issue/PR 响应质量未知（low）：用户无法判断遇到问题后是否有人维护。 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/open-webui/open-webui 项目说明书\n\n生成时间：2026-05-11 06:57:26 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [系统架构](#page-architecture)\n- [后端路由与 API](#page-backend-routers)\n- [数据模型层](#page-backend-models)\n- [认证与安全](#page-auth-security)\n- [前端组件结构](#page-frontend-structure)\n- [前端路由页面](#page-frontend-routes)\n- [模型集成与支持](#page-model-integration)\n- [检索增强生成 (RAG)](#page-retrieval-rag)\n- [工具与函数系统](#page-tools-functions)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/open-webui/open-webui/blob/main/README.md)\n- [src/lib/constants.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)\n- [backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)\n- [backend/open_webui/env.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/env.py)\n- [backend/open_webui/retrieval/utils.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/retrieval/utils.py)\n- [backend/open_webui/routers/knowledge.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)\n- [src/lib/utils/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/utils/index.ts)\n \n\n# 项目概述\n\n## 1. 项目简介\n\nOpen WebUI 是一个开源的自托管 Web 用户界面，专为大型语言模型（LLM）交互而设计。该项目提供了一个现代化、功能丰富的 Web 界面，让用户能够轻松地与本地部署的 Ollama 模型或其他兼容的 LLM API 进行交互。\n\n项目支持多种安装方式，包括 pip 包安装和 Docker 容器化部署，并提供了丰富的功能集，涵盖对话管理、RAG（检索增强生成）、图像生成、语音模式、代码解释器等高级特性。\n\n**核心目标**：为本地 LLM 提供一个类似 ChatGPT 的流畅、直观的 Web 交互体验，同时保持数据的私密性和本地化处理。\n\n资料来源：[README.md:1-20](https://github.com/open-webui/open-webui/blob/main/README.md)\n\n---\n\n## 2. 技术架构\n\n### 2.1 整体架构\n\nOpen WebUI 采用前后端分离的架构设计：\n\n```mermaid\ngraph TD\n subgraph 前端层[\"前端层 (SvelteKit)\"]\n A[Web UI] --> B[API 客户端]\n B --> C[状态管理]\n end\n \n subgraph 后端层[\"后端层 (Python/FastAPI)\"]\n D[API 路由] --> E[业务逻辑]\n E --> F[数据访问层]\n F --> G[(SQLite/PostgreSQL)]\n end\n \n subgraph 外部服务[\"外部服务集成\"]\n H[Ollama]\n I[RAG 检索器]\n J[图像生成引擎]\n K[语音服务]\n end\n \n A --> D\n C --> E\n E --> H\n E --> I\n E --> J\n E --> K\n```\n\n### 2.2 目录结构\n\n```\nopen-webui/\n├── backend/\n│ └── open_webui/\n│ ├── __init__.py\n│ ├── config.py # 配置管理\n│ ├── env.py # 环境变量\n│ ├── constants.py # 常量定义\n│ ├── routers/ # API 路由\n│ │ └── knowledge.py # 知识库路由\n│ ├── retrieval/ # RAG 检索模块\n│ │ ├── utils.py # 文档处理工具\n│ │ └── loaders/ # 文档加载器\n│ └── utils/ # 工具函数\n│ └── middleware.py # 中间件处理\n└── src/\n ├── lib/\n │ ├── constants.ts # 前端常量\n │ ├── utils/ # 前端工具\n │ └── apis/ # API 客户端\n └── app.html # 主 HTML 模板\n```\n\n资料来源：[backend/open_webui/env.py:1-50](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/env.py)\n\n### 2.3 环境配置\n\n后端通过 `env.py` 模块管理环境配置，支持从 `.env` 文件加载配置：\n\n```python\n# 目录定义\nENV_FILE_PATH = Path(__file__).resolve()\nOPEN_WEBUI_DIR = ENV_FILE_PATH.parent # open_webui/\nBACKEND_DIR = OPEN_WEBUI_DIR.parent # backend/\nBASE_DIR = BACKEND_DIR.parent # 项目根目录\n```\n\n支持的设备类型：\n\n| 设备类型 | 说明 | 配置值 |\n|---------|------|--------|\n| CPU | 默认模式，兼容所有系统 | `USE_CUDA_DOCKER=false` |\n| CUDA | NVIDIA GPU 加速 | `USE_CUDA_DOCKER=true` |\n| MPS | Apple Silicon 加速 | 自动检测 |\n\n资料来源：[backend/open_webui/env.py:30-45](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/env.py)\n\n---\n\n## 3. 核心功能特性\n\n### 3.1 功能总览\n\nOpen WebUI 提供以下核心功能模块：\n\n| 功能模块 | 描述 | 支持范围 |\n|---------|------|---------|\n| **对话管理** | 多模型并行对话、对话历史管理 | Ollama、OpenAI 兼容 API |\n| **RAG 检索** | 文档解析、向量检索、上下文注入 | 15+ 搜索提供商 |\n| **Web 搜索** | 实时网络搜索增强回答 | SearXNG、Google PSE、Bing 等 |\n| **图像生成** | DALL-E、Gemini、ComfyUI、AUTOMATIC1111 | 本地/云端引擎 |\n| **语音模式** | 语音输入输出交互 | TTS/ASR 集成 |\n| **代码解释器** | Python 代码执行与结果展示 | Pyodide/Jupyter |\n| **多模型对话** | 同时调用多个模型协作回答 | 任意支持的模型 |\n\n资料来源：[README.md:60-100](https://github.com/open-webui/open-webui/blob/main/README.md)\n\n### 3.2 RAG 检索系统\n\n检索系统支持多种文档格式和加载器：\n\n```mermaid\ngraph LR\n A[用户上传文档] --> B[文档解析器]\n B --> C[文本提取]\n C --> D[向量存储]\n E[用户查询] --> F[向量检索]\n F --> G[上下文组装]\n G --> H[LLM 生成回答]\n D --> F\n```\n\n**支持的文档类型**：\n\n| 格式 | MIME 类型 |\n|-----|----------|\n| PDF | `application/pdf` |\n| EPUB | `application/epub+zip` |\n| Markdown | `text/markdown` |\n| Word | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |\n| 纯文本 | `text/plain` |\n| CSV | `text/csv` |\n| HTML | `text/html` |\n| Python | `text/x-python` |\n| CSS | `text/css` |\n| JavaScript | `application/x-javascript` |\n| 音频 | `audio/mpeg`, `audio/wav` |\n\n**支持的 OCR 和文档处理服务**：\n\n- TIKA Server\n- Docling\n- Mistral OCR\n- PaddleOCR VL\n- MinerU\n- Azure Document Intelligence\n\n资料来源：[src/lib/constants.ts:20-40](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)\n资料来源：[backend/open_webui/retrieval/utils.py:1-50](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/retrieval/utils.py)\n\n### 3.3 Web 搜索提供商\n\n| 提供商 | 配置标识 |\n|-------|---------|\n| SearXNG | `searxng` |\n| Google PSE | `google PSE` |\n| Brave Search | `brave` |\n| Bing | `bing` |\n| DuckDuckGo | `duckduckgo` |\n| Tavily | `tavily` |\n| Perplexity | `perplexity` |\n| Jina | `jina` |\n| Exa | `exa` |\n| Ollama Cloud | `ollama` |\n| Azure AI Search | `azure` |\n\n资料来源：[README.md:70-80](https://github.com/open-webui/open-webui/blob/main/README.md)\n\n---\n\n## 4. API 架构\n\n### 4.1 API 端点结构\n\n```mermaid\ngraph TD\n A[WebUI API] --> B[/api/v1/*]\n A --> C[/ollama/*]\n A --> D[/openai/*]\n \n B --> E[音频处理]\n B --> F[图像处理]\n B --> G[检索服务]\n B --> H[知识库管理]\n```\n\n**基础 API 路径**：\n\n| 服务 | 路径 |\n|-----|------|\n| WebUI API | `/api/v1` |\n| Ollama | `/ollama` |\n| OpenAI | `/openai` |\n| 音频 | `/api/v1/audio` |\n| 图像 | `/api/v1/images` |\n| 检索 | `/api/v1/retrieval` |\n\n资料来源：[src/lib/constants.ts:8-15](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)\n\n### 4.2 知识库 API\n\n知识库模块提供完整的 CRUD 操作：\n\n| 端点 | 方法 | 描述 |\n|-----|------|------|\n| `/knowledge/create` | POST | 创建知识库 |\n| `/knowledge/` | GET | 获取知识库列表 |\n| `/knowledge/{id}` | GET | 获取知识库详情 |\n| `/knowledge/{id}/file/add` | POST | 添加文件到知识库 |\n| `/knowledge/{id}/files/search` | GET | 搜索知识库文件 |\n\n**访问控制**：\n\n- 管理员（`admin`）拥有完全访问权限\n- 知识库创建者拥有完全访问权限\n- 其他用户需要通过访问授权（`AccessGrants`）获得读取权限\n\n资料来源：[backend/open_webui/routers/knowledge.py:1-80](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)\n资料来源：[src/lib/apis/knowledge/index.ts:1-60](https://github.com/open-webui/open-webui/blob/main/src/lib/apis/knowledge/index.ts)\n\n---\n\n## 5. 安装与部署\n\n### 5.1 安装方式对比\n\n| 安装方式 | 适用场景 | Python 版本要求 |\n|---------|---------|----------------|\n| pip 安装 | 本地开发、快速体验 | Python 3.11+ |\n| Docker | 生产环境、跨平台部署 | 无 |\n| 开发分支 | 测试最新功能 | 无 |\n\n### 5.2 pip 安装\n\n```bash\n# 安装\npip install open-webui\n\n# 启动服务\nopen-webui serve\n# 访问地址：http://localhost:8080\n```\n\n### 5.3 Docker 部署\n\n```bash\n# 标准部署\ndocker run -d -p 3000:8080 \\\n -v open-webui:/app/backend/data \\\n --name open-webui \\\n --add-host=host.docker.internal:host-gateway \\\n --restart always \\\n ghcr.io/open-webui/open-webui:main\n\n# CUDA 加速版本\ndocker run -d -p 3000:8080 \\\n -v open-webui:/app/backend/data \\\n --gpus all \\\n --name open-webui \\\n ghcr.io/open-webui/open-webui:cuda\n\n# Ollama 集成版本\ndocker run -d -p 3000:8080 \\\n -v open-webui:/app/backend/data \\\n --name open-webui \\\n ghcr.io/open-webui/open-webui:ollama\n```\n\n> [!WARNING]\n> Docker 部署时必须挂载数据卷 `-v open-webui:/app/backend/data`，否则数据库数据将在容器重建时丢失。\n\n> [!NOTE]\n> 离线环境可设置 `HF_HUB_OFFLINE=1` 环境变量阻止模型下载。\n\n资料来源：[README.md:25-120](https://github.com/open-webui/open-webui/blob/main/README.md)\n\n---\n\n## 6. 配置与定制\n\n### 6.1 系统常量配置\n\n前端通过 `src/lib/constants.ts` 定义系统级常量：\n\n```typescript\nexport const APP_NAME = 'Open WebUI';\nexport const WEBUI_VERSION = APP_VERSION;\nexport const WEBUI_BUILD_HASH = APP_BUILD_HASH;\nexport const REQUIRED_OLLAMA_VERSION = '0.1.16';\n```\n\n### 6.2 内容处理管道\n\n前端对 LLM 输出进行标准化处理：\n\n```mermaid\ngraph LR\n A[原始输出] --> B[sanitizeResponseContent]\n B --> C[processChineseContent]\n C --> D[Markdown 渲染]\n```\n\n**处理功能**：\n\n- 移除未闭合的 tokenizer 标记（`<|...`）\n- HTML 实体转义\n- 中文内容特殊格式优化\n- Markdown/LaTeX 格式标准化\n\n资料来源：[src/lib/utils/index.ts:1-50](https://github.com/open-webui/open-webui/blob/main/src/lib/utils/index.ts)\n\n### 6.3 代码解释器配置\n\n代码解释器支持两种执行引擎：\n\n| 引擎 | 执行环境 | 提示词追加 |\n|-----|---------|-----------|\n| Jupyter | 服务器端 | 无 |\n| Pyodide | 浏览器端 | Pyodide 环境提示 |\n\n**关键配置参数**：\n\n- 允许使用多种数据处理、可视化、API 调用库\n- 强制使用 `` XML 标签包裹代码\n- 输出结果需显式打印\n\n资料来源：[backend/open_webui/config.py:200-280](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)\n\n---\n\n## 7. 安全特性\n\n### 7.1 角色权限控制\n\n| 角色 | Ollama 访问 | 模型拉取 | 模型创建 | 知识库管理 |\n|-----|------------|---------|---------|-----------|\n| 管理员 | ✅ 完全 | ✅ | ✅ | ✅ |\n| 普通用户 | 受限 | ❌ | ❌ | 受限 |\n| 访客 | 受限 | ❌ | ❌ | ❌ |\n\n### 7.2 访问授权机制\n\n知识库使用 `AccessGrants` 系统控制资源访问：\n\n```python\nawait AccessGrants.has_access(\n user_id=user.id,\n resource_type='knowledge',\n resource_id=knowledge.id,\n permission='read',\n db=db,\n)\n```\n\n资料来源：[backend/open_webui/routers/knowledge.py:40-60](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)\n\n---\n\n## 8. 版本与依赖\n\n### 8.1 版本要求\n\n| 组件 | 最低版本 |\n|-----|---------|\n| Python | 3.11 |\n| Ollama | 0.1.16 |\n\n### 8.2 数据存储\n\n支持多种数据库后端：\n\n| 数据库 | 特点 | 加密支持 |\n|-------|------|---------|\n| SQLite | 默认、轻量 | ✅ 可选 |\n| PostgreSQL | 生产级、高并发 | ❌ |\n\n资料来源：[README.md:100-110](https://github.com/open-webui/open-webui/blob/main/README.md)\n\n---\n\n## 9. 相关资源\n\n- **官方文档**：https://docs.openwebui.com/\n- **更新指南**：https://docs.openwebui.com/getting-started/updating\n- **路线图**：https://docs.openwebui.com/roadmap/\n- **许可证**：项目采用 Open WebUI License，需保留品牌标识\n\n资料来源：[README.md:140-160](https://github.com/open-webui/open-webui/blob/main/README.md)\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[后端路由与 API](#page-backend-routers), [前端组件结构](#page-frontend-structure)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [backend/open_webui/main.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/main.py)\n- [backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)\n- [backend/open_webui/env.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/env.py)\n- [src/lib/constants.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)\n- [src/lib/utils/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/utils/index.ts)\n- [backend/open_webui/utils/middleware.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/middleware.py)\n \n\n# 系统架构\n\n## 概述\n\nOpen WebUI 是一个功能丰富的 Web 用户界面，专为大型语言模型（LLM）交互设计。该项目采用前后端分离的现代化架构，后端基于 FastAPI 构建 Python REST API 与 WebSocket 服务，前端使用 SvelteKit 框架实现响应式单页应用。\n\n系统支持多模型并行对话、检索增强生成（RAG）、代码解释器执行、语音模式等高级功能，同时提供灵活的数据库与存储选项（SQLite、PostgreSQL、S3 等）。\n\n资料来源：[backend/open_webui/main.py:1-50]()\n\n## 整体架构图\n\n```mermaid\ngraph TB\n subgraph 前端层[\"前端层 (SvelteKit)\"]\n UI[用户界面]\n WS_CLIENT[WebSocket 客户端]\n API_CLIENT[API 客户端]\n end\n\n subgraph 后端层[\"后端层 (FastAPI)\"]\n API_GATEWAY[API 网关]\n \n subgraph API路由[\"API 路由模块\"]\n TASKS[tasks 路由]\n IMAGES[images 路由]\n AUDIO[audio 路由]\n RETRIEVAL[retrieval 路由]\n CONFIGS[configs 路由]\n AUTHS[auths 路由]\n USERS[users 路由]\n CHANNELS[channels 路由]\n CHATS[chats 路由]\n NOTES[notes 路由]\n MODELS[models 路由]\n KNOWLEDGE[knowledge 路由]\n PROMPTS[prompts 路由]\n TOOLS[tools 路由]\n SKILLS[skills 路由]\n MEMORIES[memories 路由]\n FOLDERS[folders 路由]\n GROUPS[groups 路由]\n FILES[files 路由]\n end\n \n WS_SERVER[WebSocket 服务]\n MIDDLEWARE[中间件处理]\n end\n\n subgraph 外部服务[\"外部服务\"]\n OLLAMA[Ollama API]\n OPENAI[OpenAI API]\n DOCLING[Docling OCR]\n TIKA[Tika Server]\n end\n\n UI --> WS_CLIENT\n UI --> API_CLIENT\n WS_CLIENT --> WS_SERVER\n API_CLIENT --> API_GATEWAY\n API_GATEWAY --> API路由\n MIDDLEWARE --> API路由\n WS_SERVER --> MIDDLEWARE\n API_GATEWAY --> OLLAMA\n API_GATEWAY --> OPENAI\n API路由 --> DOCLING\n API路由 --> TIKA\n```\n\n资料来源：[backend/open_webui/main.py:1-50]()\n\n## 核心组件架构\n\n### 前端架构\n\n前端基于 SvelteKit 框架构建，采用单页应用（SPA）模式。主要组件包括：\n\n| 组件路径 | 功能描述 |\n|---------|---------|\n| `src/app.html` | 应用主 HTML 模板，包含启动画面和主题样式 |\n| `src/lib/constants.ts` | 前端常量定义，包含 API 端点配置 |\n| `src/lib/utils/index.ts` | 响应内容处理工具函数 |\n| `src/lib/utils/codeHighlight.ts` | 代码语法高亮映射配置 |\n\n#### 前端 API 端点配置\n\n前端通过 `constants.ts` 中定义的常量与后端通信：\n\n```typescript\n// 资料来源：src/lib/constants.ts:1-20\nexport const WEBUI_BASE_URL = browser ? (dev ? `http://${WEBUI_HOSTNAME}` : ``) : ``;\nexport const WEBUI_API_BASE_URL = `${WEBUI_BASE_URL}/api/v1`;\n\nexport const OLLAMA_API_BASE_URL = `${WEBUI_BASE_URL}/ollama`;\nexport const OPENAI_API_BASE_URL = `${WEBUI_BASE_URL}/openai`;\nexport const AUDIO_API_BASE_URL = `${WEBUI_BASE_URL}/api/v1/audio`;\nexport const IMAGES_API_BASE_URL = `${WEBUI_BASE_URL}/api/v1/images`;\nexport const RETRIEVAL_API_BASE_URL = `${WEBUI_BASE_URL}/api/v1/retrieval`;\n```\n\n### 后端架构\n\n后端采用 FastAPI 框架，按照功能模块划分为多个路由组件：\n\n```mermaid\ngraph LR\n subgraph REST_API[\"REST API (/api/v1/*)\"]\n TASKS_API[任务 API]\n FILE_API[文件 API]\n CHAT_API[聊天 API]\n MODEL_API[模型 API]\n RAG_API[RAG 检索 API]\n end\n \n subgraph WEBSOCKET[\"WebSocket (/ws)\"]\n STREAM[流式响应]\n REALTIME[实时事件]\n end\n \n subgraph MIDDLEWARE[\"中间件\"]\n AUTH[身份验证]\n SANITIZE[内容清理]\n PIPELINE[管道处理]\n end\n```\n\n资料来源：[backend/open_webui/main.py:1-50]()\n\n## API 路由体系\n\n### 路由模块一览\n\n| 前缀路径 | 路由模块 | 标签 | 功能 |\n|---------|---------|------|------|\n| `/api/v1/tasks` | tasks | tasks | 异步任务管理 |\n| `/api/v1/images` | images | images | 图片处理与生成 |\n| `/api/v1/audio` | audio | audio | 音频处理 |\n| `/api/v1/retrieval` | retrieval | retrieval | RAG 检索功能 |\n| `/api/v1/configs` | configs | configs | 系统配置 |\n| `/api/v1/auths` | auths | auths | 身份认证 |\n| `/api/v1/users` | users | users | 用户管理 |\n| `/api/v1/channels` | channels | channels | 通道管理 |\n| `/api/v1/chats` | chats | chats | 对话管理 |\n| `/api/v1/notes` | notes | notes | 笔记功能 |\n| `/api/v1/models` | models | models | 模型管理 |\n| `/api/v1/knowledge` | knowledge | knowledge | 知识库 |\n| `/api/v1/prompts` | prompts | prompts | 提示词管理 |\n| `/api/v1/tools` | tools | tools | 工具扩展 |\n| `/api/v1/skills` | skills | skills | 技能管理 |\n| `/api/v1/memories` | memories | memories | 记忆功能 |\n| `/api/v1/folders` | folders | folders | 文件夹组织 |\n| `/api/v1/groups` | groups | groups | 分组管理 |\n| `/api/v1/files` | files | files | 文件存储 |\n\n资料来源：[backend/open_webui/main.py:30-50]()\n\n## 配置系统\n\n### 环境配置架构\n\n```python\n# 资料来源：backend/open_webui/env.py:1-50\nOPEN_WEBUI_DIR = ENV_FILE_PATH.parent # open_webui/\nBACKEND_DIR = OPEN_WEBUI_DIR.parent # backend/\nBASE_DIR = BACKEND_DIR.parent # 项目根目录\n```\n\n### 关键配置项\n\n| 配置项 | 环境变量 | 默认值 | 说明 |\n|-------|---------|-------|------|\n| Docker 模式 | `DOCKER` | `'False'` | 是否运行在 Docker 容器中 |\n| CUDA 支持 | `USE_CUDA_DOCKER` | `'false'` | 是否启用 NVIDIA GPU 加速 |\n| 设备类型 | `DEVICE_TYPE` | `'cpu'` | 嵌入模型运行设备 |\n| 版本哈希 | `APP_VERSION` | - | 构建版本标识 |\n| 构建哈希 | `APP_BUILD_HASH` | - | Git 提交哈希 |\n\n资料来源：[backend/open_webui/env.py:1-50]()\n\n### 任务配置模板\n\n系统支持可配置的提示词模板：\n\n```python\n# 资料来源：backend/open_webui/config.py:1-30\nCODE_INTERPRETER_PROMPT = \"\"\"\n代码解释器允许 AI 在沙箱环境中执行 Python 代码...\n\"\"\"\n```\n\n## 中间件处理\n\n### 响应处理管道\n\n```mermaid\ngraph TD\n LLM_Response[LLM 响应] --> STREAM[流式响应处理]\n STREAM --> REASONING[推理内容检测]\n REASONING --> CODE_INTERPRETER{代码解释器?}\n CODE_INTERPRETER -->|是| SANITIZE[内容清理]\n CODE_INTERPRETER -->|否| FORMAT[格式处理]\n SANITIZE --> HTML[HTML 渲染]\n FORMAT --> HTML\n HTML --> FINAL[最终响应]\n```\n\n资料来源：[backend/open_webui/utils/middleware.py:1-50]()\n\n### 内容处理功能\n\n中间件提供以下核心处理功能：\n\n- **推理链渲染**：将模型的思维过程渲染为可折叠的 `` HTML 元素\n- **代码解释器集成**：识别并执行代码块，渲染执行结果\n- **HTML 转义**：对非信任内容进行安全转义\n- **Markdown 处理**：支持 Markdown 格式解析\n\n```python\n# 资料来源：backend/open_webui/utils/middleware.py:1-30\nif item_type == 'reasoning':\n if duration is not None or not is_last_item:\n parts.append(\n f'\\nThought for {duration or 0} seconds
\\n{display}\\n '\n )\n```\n\n## 前端响应处理\n\n### 内容处理流程\n\n```mermaid\ngraph LR\n RAW[原始响应] --> PROCESS[processResponseContent]\n PROCESS --> CHINESE{包含中文?}\n CHINESE -->|是| CHINESE_PROC[中文内容处理]\n CHINESE -->|否| SANITIZE[内容清理]\n CHINESE_PROC --> SANITIZE\n SANITIZE --> HTML_ESCAPE[HTML 转义]\n HTML_ESCAPE --> OUTPUT[最终输出]\n```\n\n资料来源：[src/lib/utils/index.ts:1-50]()\n\n### 响应清理函数\n\n```typescript\n// 资料来源：src/lib/utils/index.ts:1-30\nexport const sanitizeResponseContent = (content: string) => {\n\treturn content\n\t\t.replace(/<\\|[a-z]*$/, '')\n\t\t.replace(/<\\|[a-z]+\\|$/, '')\n\t\t.replace(/<$/, '')\n\t\t.replaceAll('<', '<')\n\t\t.replaceAll('>', '>')\n\t\t.replaceAll(/<\\|[a-z]+\\|>/g, ' ')\n\t\t.trim();\n};\n```\n\n## 代码语法高亮\n\n### 文件类型映射配置\n\n```typescript\n// 资料来源：src/lib/utils/codeHighlight.ts:1-50\nconst EXT_OVERRIDE: Record = {\n\tpy: 'python',\n\tjs: 'javascript',\n\tts: 'typescript',\n\tjsx: 'jsx',\n\ttsx: 'tsx',\n\trb: 'ruby',\n\trs: 'rust',\n\tyml: 'yaml',\n\tmd: 'markdown',\n\tdockerfile: 'dockerfile',\n\tproto: 'proto',\n\tgraphql: 'graphql',\n\tgql: 'graphql',\n};\n```\n\n支持的语言标识符集合包含超过 50 种编程语言和配置格式，确保前端代码展示的准确性。\n\n## 部署架构\n\n### Docker 部署模式\n\n```mermaid\ngraph TB\n USER[用户] --> BROWSER[浏览器]\n BROWSER --> DOCKER[Docker 容器]\n \n subgraph DOCKER[Docker 容器]\n NGINX[反向代理]\n FASTAPI[FastAPI 后端]\n SVELTE[构建静态文件]\n end\n \n FASTAPI --> OLLAMA[(Ollama 服务)]\n FASTAPI --> DATA[数据卷 /app/backend/data]\n \n subgraph OLLAMA[(Ollama 服务)]\n MODEL1[模型 1]\n MODEL2[模型 2]\n MODEL_N[模型 N]\n end\n```\n\n### 离线模式支持\n\n系统支持完全离线运行，通过设置以下环境变量禁用所有网络请求：\n\n```bash\nexport HF_HUB_OFFLINE=1\n```\n\n资料来源：[README.md](https://github.com/open-webui/open-webui/blob/main/README.md)\n\n## 技术栈总结\n\n| 层级 | 技术选型 | 说明 |\n|-----|---------|------|\n| 前端框架 | SvelteKit | 现代化响应式框架 |\n| 后端框架 | FastAPI | 高性能 Python ASGI 框架 |\n| 数据库 | SQLite (默认) / PostgreSQL | 灵活的数据存储选项 |\n| 存储 | S3 / GCS / Azure Blob | 云端对象存储支持 |\n| LLM 运行时 | Ollama / OpenAI API | 多模型支持 |\n| 文档处理 | Tika / Docling / Mistral OCR | 多格式文档解析 |\n| WebSocket | 原生 FastAPI WebSocket | 实时双向通信 |\n\n资料来源：[README.md](https://github.com/open-webui/open-webui/blob/main/README.md), [backend/open_webui/env.py:1-50]()\n\n---\n\n\n\n## 后端路由与 API\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [认证与安全](#page-auth-security), [模型集成与支持](#page-model-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [backend/open_webui/routers/chats.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/chats.py)\n- [backend/open_webui/routers/auths.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/auths.py)\n- [backend/open_webui/routers/models.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/models.py)\n- [backend/open_webui/routers/ollama.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/ollama.py)\n- [backend/open_webui/routers/openai.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/openai.py)\n- [backend/open_webui/routers/retrieval.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/retrieval.py)\n- [backend/open_webui/routers/tasks.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/tasks.py)\n \n\n# 后端路由与 API\n\n## 1. 概述\n\nOpen WebUI 的后端采用 FastAPI 框架构建，提供了完整的 RESTful API 接口层。系统通过模块化的路由设计，将不同功能域的 API 逻辑分离到独立的路由器（Router）中，实现了代码的高内聚低耦合。\n\n### 1.1 架构设计原则\n\n后端 API 层遵循以下核心设计原则：\n\n| 设计原则 | 说明 |\n|---------|------|\n| **分层架构** | 路由层 → 服务层 → 数据访问层分离 |\n| **依赖注入** | 使用 FastAPI 的 Depends 机制管理依赖 |\n| **异步优先** | 全面采用 AsyncIO 异步编程模型 |\n| **权限控制** | 基于角色的访问控制（RBAC） |\n| **统一响应** | 标准化的响应格式和错误处理 |\n\n### 1.2 核心路由模块\n\n系统的主要路由模块位于 `backend/open_webui/routers/` 目录下：\n\n```mermaid\ngraph TD\n A[客户端请求] --> B[API 网关层]\n B --> C[认证路由 auths]\n B --> D[聊天路由 chats]\n B --> E[模型路由 models]\n B --> F[知识库路由 knowledge]\n B --> G[检索路由 retrieval]\n B --> H[任务路由 tasks]\n B --> I[外部集成 ollama/openai]\n \n C --> K[用户认证服务]\n D --> L[对话管理服务]\n E --> M[模型配置服务]\n F --> N[文档处理服务]\n G --> O[向量检索服务]\n H --> P[异步任务服务]\n```\n\n资料来源：[backend/open_webui/routers/](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/)\n\n---\n\n## 2. 认证与授权系统\n\n### 2.1 认证路由（auths）\n\n认证路由负责处理用户身份验证、会话管理和访问授权。\n\n资料来源：[backend/open_webui/routers/auths.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/auths.py)\n\n#### 2.1.1 主要 API 端点\n\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/auth/login` | POST | 用户登录 |\n| `/api/auth/logout` | POST | 用户登出 |\n| `/api/auth/user` | GET | 获取当前用户信息 |\n| `/api/auth/modelfiles` | GET | 获取用户自定义模型文件 |\n\n#### 2.1.2 认证流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant API as 认证 API\n participant DB as 数据库\n participant Session as 会话管理\n\n Client->>API: POST /api/auth/login\n API->>DB: 验证用户凭据\n DB-->>API: 用户信息\n API->>Session: 创建会话\n Session-->>API: 会话令牌\n API-->>Client: 返回认证令牌\n```\n\n### 2.2 访问控制机制\n\n系统通过 `AccessGrants` 模块实现细粒度的资源访问控制：\n\n```python\nif not (\n user.role == 'admin'\n or knowledge.user_id == user.id\n or await AccessGrants.has_access(\n user_id=user.id,\n resource_type='knowledge',\n resource_id=knowledge.id,\n permission='read',\n db=db,\n )\n):\n raise HTTPException(\n status_code=status.HTTP_400_BAD_REQUEST,\n detail=ERROR_MESSAGES.ACCESS_PROHIBITED,\n )\n```\n\n资料来源：[backend/open_webui/routers/knowledge.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)\n\n---\n\n## 3. 对话管理 API\n\n### 3.1 聊天路由（chats）\n\n聊天路由是系统的核心模块，负责处理所有与对话相关的功能，包括消息发送、对话历史管理和对话状态维护。\n\n资料来源：[backend/open_webui/routers/chats.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/chats.py)\n\n#### 3.1.1 核心功能\n\n| 功能 | 描述 |\n|------|------|\n| 创建对话 | 初始化新的聊天会话 |\n| 发送消息 | 向对话中添加用户消息和助手回复 |\n| 获取历史 | 检索指定对话的消息历史 |\n| 删除对话 | 删除整个对话及其关联数据 |\n| 分享对话 | 将对话导出为可分享格式 |\n\n#### 3.1.2 消息处理流程\n\n```mermaid\ngraph TD\n A[用户发送消息] --> B[消息验证]\n B --> C{工具调用检测}\n C -->|是| D[执行工具函数]\n C -->|否| E[模型推理]\n D --> F[返回工具结果]\n E --> G[生成回复]\n F --> G\n G --> H[保存消息]\n H --> I[流式返回]\n```\n\n### 3.2 消息处理工具函数\n\n系统提供了丰富的消息处理工具函数：\n\n| 函数名 | 功能 |\n|--------|------|\n| `get_message_list` | 获取消息列表 |\n| `add_or_update_system_message` | 添加/更新系统消息 |\n| `add_or_update_user_message` | 添加/更新用户消息 |\n| `get_last_user_message` | 获取最后用户消息 |\n| `get_last_assistant_message` | 获取最后助手消息 |\n| `replace_system_message_content` | 替换系统消息内容 |\n\n资料来源：[backend/open_webui/utils/chat.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/chat.py)\n\n---\n\n## 4. 模型管理 API\n\n### 4.1 模型路由（models）\n\n模型路由负责管理系统中的大语言模型配置，包括模型列表管理、配置更新和模型选择。\n\n资料来源：[backend/open_webui/routers/models.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/models.py)\n\n#### 4.1.1 配置参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `title` | string | 模型显示名称 |\n| `base_url` | string | 模型服务地址 |\n| `api_key` | string | API 密钥 |\n| `max_tokens` | int | 最大生成 token 数 |\n| `temperature` | float | 生成温度参数 |\n| `stream` | boolean | 是否启用流式输出 |\n\n### 4.2 外部模型集成\n\n系统支持多种外部模型服务的集成，通过统一的适配器接口实现。\n\n---\n\n## 5. 外部服务集成\n\n### 5.1 Ollama 集成\n\nOllama 路由提供了与本地 Ollama 服务通信的接口。\n\n资料来源：[backend/open_webui/routers/ollama.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/ollama.py)\n\n```mermaid\ngraph LR\n A[Open WebUI] -->|API 请求| B[Ollama 适配层]\n B --> C[Ollama 服务]\n C -->|模型响应| B\n B -->|标准化响应| A\n```\n\n#### 5.1.1 Ollama API 端点映射\n\n| Open WebUI 端点 | Ollama API |\n|----------------|-----------|\n| `/ollama/chat` | `/api/chat` |\n| `/ollama/models` | `/api/tags` |\n| `/ollama/generate` | `/api/generate` |\n| `/ollama/embeddings` | `/api/embeddings` |\n\n### 5.2 OpenAI 兼容 API\n\nOpenAI 路由实现了与 OpenAI API 兼容的接口，支持使用 OpenAI SDK 的应用无缝接入。\n\n资料来源：[backend/open_webui/routers/openai.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/openai.py)\n\n#### 5.2.1 支持的端点\n\n| 端点 | 描述 |\n|------|------|\n| `/openai/v1/chat/completions` | 聊天补全 |\n| `/openai/v1/completions` | 文本补全 |\n| `/openai/v1/embeddings` | 向量嵌入 |\n| `/openai/v1/models` | 模型列表 |\n\n---\n\n## 6. 知识库与检索系统\n\n### 6.1 知识库路由\n\n知识库路由负责文档上传、内容处理和知识库管理。\n\n资料来源：[backend/open_webui/routers/knowledge.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)\n\n#### 6.1.1 文件操作 API\n\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/{id}/files` | GET | 列出知识库文件 |\n| `/{id}/file/add` | POST | 添加文件到知识库 |\n| `/{id}/file/delete` | DELETE | 删除知识库文件 |\n| `/{id}/search` | POST | 搜索知识库内容 |\n\n#### 6.1.2 访问控制流程\n\n```mermaid\ngraph TD\n A[请求访问知识库] --> B{用户角色检查}\n B -->|管理员| C[允许访问]\n B -->|普通用户| D{是否为所有者}\n D -->|是| C\n D -->|否| E{检查访问权限}\n E -->|有读权限| C\n E -->|无权限| F[拒绝访问 400]\n```\n\n### 6.2 检索路由\n\n检索路由提供了向量检索和全文搜索功能。\n\n资料来源：[backend/open_webui/routers/retrieval.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/retrieval.py)\n\n#### 6.2.1 检索处理流程\n\n```mermaid\ngraph TD\n A[用户查询] --> B[查询预处理]\n B --> C[向量嵌入]\n C --> D[向量数据库检索]\n D --> E[结果重排序]\n E --> F[格式化输出]\n F --> G[返回检索结果]\n```\n\n---\n\n## 7. 异步任务系统\n\n### 7.1 任务路由\n\n任务路由管理系统中的异步任务，包括任务创建、状态查询和结果获取。\n\n资料来源：[backend/open_webui/routers/tasks.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/tasks.py)\n\n#### 7.1.1 任务类型\n\n| 任务类型 | 描述 |\n|---------|------|\n| `chat` | 聊天消息生成任务 |\n| `title` | 对话标题生成任务 |\n| `summarize` | 消息摘要任务 |\n| `rerank` | 检索结果重排序任务 |\n\n#### 7.1.2 任务状态流转\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending: 创建任务\n Pending --> Processing: 开始执行\n Processing --> Completed: 执行成功\n Processing --> Failed: 执行失败\n Completed --> [*]\n Failed --> [*]\n```\n\n### 7.2 任务处理配置\n\n系统通过配置文件管理任务处理参数：\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| `TASK_MODEL` | 任务处理模型 | auto |\n| `TASK_MODEL_EXTERNAL` | 外部任务模型 | - |\n\n资料来源：[backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)\n\n---\n\n## 8. 代码执行系统\n\n### 8.1 代码解释器配置\n\n系统支持在聊天中执行代码，提供强大的动态执行能力。\n\n资料来源：[backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)\n\n#### 8.1.1 配置参数\n\n| 配置项 | 类型 | 说明 |\n|--------|------|------|\n| `ENABLE_CODE_EXECUTION` | boolean | 启用代码执行 |\n| `CODE_EXECUTION_ENGINE` | string | 执行引擎 (pyodide) |\n| `CODE_EXECUTION_JUPYTER_URL` | string | Jupyter 服务地址 |\n| `CODE_EXECUTION_JUPYTER_AUTH` | string | Jupyter 认证信息 |\n\n#### 8.1.2 架构设计\n\n```mermaid\ngraph TD\n A[代码块检测] --> B{启用代码执行}\n B -->|是| C[隔离执行环境]\n C --> D[Pyodide/Jupyter]\n B -->|否| E[普通代码展示]\n D --> F[执行结果捕获]\n F --> G[格式化返回]\n```\n\n---\n\n## 9. 工具系统\n\n### 9.1 工具函数管理\n\n系统提供灵活的函数调用机制，支持自定义工具扩展。\n\n资料来源：[backend/open_webui/utils/tools.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/tools.py)\n\n| 函数 | 功能 |\n|------|------|\n| `get_tools` | 获取可用工具列表 |\n| `get_updated_tool_function` | 获取更新后的工具定义 |\n| `get_terminal_tools` | 获取终端级工具 |\n\n### 9.2 工具调用处理\n\n```mermaid\ngraph TD\n A[模型输出] --> B{检测工具调用}\n B -->|function_call| C[解析工具名和参数]\n C --> D[加载工具模块]\n D --> E[执行工具函数]\n E --> F[返回执行结果]\n F --> G[模型生成最终回复]\n```\n\n---\n\n## 10. 流水线处理\n\n### 10.1 管道过滤器\n\n系统支持在请求处理流程中插入自定义过滤器，实现功能的灵活扩展。\n\n资料来源：[backend/open_webui/routers/pipelines.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/pipelines.py)\n\n| 处理阶段 | 描述 |\n|---------|------|\n| `pipeline_inlet_filter` | 请求预处理过滤器 |\n| `pipeline_outlet_filter` | 响应后处理过滤器 |\n\n### 10.2 处理流程\n\n```mermaid\ngraph LR\n A[用户请求] --> B[输入过滤器]\n B --> C[核心业务处理]\n C --> D[输出过滤器]\n D --> E[返回响应]\n```\n\n---\n\n## 11. API 响应格式规范\n\n### 11.1 统一响应结构\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | string | 资源唯一标识符 |\n| `object` | string | 对象类型 |\n| `created` | int | 创建时间戳 |\n| `model` | string | 使用的模型 |\n| `choices` | array | 生成选项列表 |\n| `usage` | object | Token 使用统计 |\n\n### 11.2 错误响应\n\n| 状态码 | 说明 |\n|--------|------|\n| 400 | 请求参数错误 |\n| 401 | 认证失败 |\n| 403 | 权限不足 |\n| 404 | 资源不存在 |\n| 500 | 服务器内部错误 |\n\n---\n\n## 12. 总结\n\nOpen WebUI 的后端 API 系统采用模块化设计，通过清晰的路由划分实现了功能的有效分离。系统提供了完整的用户认证、对话管理、模型配置、知识库管理和异步任务处理能力，同时支持与 Ollama、OpenAI 等外部服务的高效集成。\n\n该架构的核心优势包括：\n\n- **可扩展性**：通过流水线过滤器支持自定义扩展\n- **安全性**：基于角色的访问控制和细粒度的资源权限管理\n- **性能**：全面采用异步编程模型，支持高并发处理\n- **兼容性**：提供 OpenAI 兼容接口，无缝对接现有生态系统\n\n---\n\n\n\n## 数据模型层\n\n### 相关页面\n\n相关主题：[后端路由与 API](#page-backend-routers)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [backend/open_webui/models/users.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/users.py)\n- [backend/open_webui/models/chats.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/chats.py)\n- [backend/open_webui/models/messages.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/messages.py)\n- [backend/open_webui/models/files.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/files.py)\n- [backend/open_webui/models/functions.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/functions.py)\n- [backend/open_webui/models/tools.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/tools.py)\n- [backend/open_webui/models/knowledge.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/knowledge.py)\n- [backend/open_webui/internal/db.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/internal/db.py)\n \n\n# 数据模型层\n\n## 概述\n\nOpen WebUI 的数据模型层是整个系统的核心基础设施，负责管理和持久化所有业务数据。该层采用了**分层架构设计**，将数据访问逻辑、业务模型定义和数据库交互分离到不同的模块中，以实现高内聚、低耦合的代码结构。\n\n数据模型层的主要职责包括：\n\n- **用户认证与授权**：管理用户账户信息、权限配置和会话状态\n- **对话历史管理**：存储和检索聊天记录，支持消息的增删改查操作\n- **文件与媒体处理**：管理上传文件、元数据和访问控制\n- **工具与函数集成**：维护可扩展的工具和函数定义\n- **知识库管理**：支持向量化的知识检索和文档管理\n\n资料来源：[backend/open_webui/internal/db.py:1-50]()\n\n## 架构设计\n\n### 整体架构图\n\n```mermaid\ngraph TB\n subgraph \"表现层 (API Routes)\"\n A[API 路由层]\n end\n \n subgraph \"服务层 (Services)\"\n B[业务逻辑服务]\n end\n \n subgraph \"数据模型层 (Models)\"\n C[用户模型
users.py]\n D[对话模型
chats.py]\n E[消息模型
messages.py]\n F[文件模型
files.py]\n G[函数模型
functions.py]\n H[工具模型
tools.py]\n I[知识模型
knowledge.py]\n end\n \n subgraph \"数据访问层 (Internal)\"\n J[数据库连接
db.py]\n K[数据仓库
Repositories]\n end\n \n subgraph \"存储层 (Storage)\"\n L[(SQLite/MySQL
PostgreSQL)]\n M[(文件存储
S3/本地)]\n end\n \n A --> B\n B --> C\n B --> D\n B --> E\n B --> F\n B --> G\n B --> H\n B --> I\n \n C --> J\n D --> J\n E --> J\n F --> J\n G --> J\n H --> J\n I --> J\n \n J --> K\n K --> L\n K --> M\n```\n\n### 模块职责划分\n\n| 模块文件 | 主要职责 | 核心数据结构 |\n|---------|---------|-------------|\n| `users.py` | 用户账户、认证、权限 | UserModel |\n| `chats.py` | 对话会话、聊天历史 | ChatModel |\n| `messages.py` | 单条消息、消息内容 | MessageModel |\n| `files.py` | 文件上传、元数据管理 | FileModel |\n| `functions.py` | 可调用函数定义 | FunctionModel |\n| `tools.py` | 外部工具集成 | ToolModel |\n| `knowledge.py` | 知识库、向量存储 | KnowledgeModel |\n| `db.py` | 数据库连接、查询构建 | Database Connection |\n\n资料来源：[backend/open_webui/internal/db.py:1-30]()\n\n## 核心数据模型详解\n\n### 1. 用户模型 (User Model)\n\n用户模型是系统的基础实体，包含了用户身份验证和授权所需的所有信息。\n\n```mermaid\nclassDiagram\n class UserModel {\n +str id\n +str email\n +str name\n +str password_hash\n +str role\n +datetime created_at\n +datetime updated_at\n +dict settings\n +dict preferences\n }\n \n class UserSettings {\n +str theme\n +str language\n +list allowed_models\n +bool consent_analytics\n }\n```\n\n**主要字段说明：**\n\n| 字段名 | 类型 | 说明 | 必填 |\n|-------|------|------|-----|\n| `id` | str | 唯一标识符 (UUID) | 是 |\n| `email` | str | 用户邮箱地址 | 是 |\n| `name` | str | 显示名称 | 是 |\n| `password_hash` | str | 密码哈希值 (bcrypt) | 是 |\n| `role` | str | 角色 (admin/user/guest) | 是 |\n| `created_at` | datetime | 创建时间戳 | 自动 |\n| `updated_at` | datetime | 更新时间戳 | 自动 |\n| `settings` | dict | 用户偏好设置 | 否 |\n\n资料来源：[backend/open_webui/models/users.py:1-100]()\n\n### 2. 对话模型 (Chat Model)\n\n对话模型采用扁平化的 JSON 结构存储聊天会话，包含完整的对话历史和元数据。\n\n```mermaid\ngraph LR\n A[ChatModel] --> B[\"chat: Dict\"]\n B --> C[\"history: Dict\"]\n C --> D[\"messages: Dict
message_id → message\"]\n C --> E[\"metadata: Dict\"]\n B --> F[\"share_id: str\"]\n B --> G[\"archived: bool\"]\n B --> H[\"pinned: bool\"]\n```\n\n**关键特性：**\n\n- **消息存储方式**：对话消息存储在 `chat.history.messages` 字典中，以 `message_id` 为键\n- **双轨存储**：支持从独立的 `chat_message` 表快速查询，同时保持向后兼容的 JSON blob 存储\n- **自动清理**：对消息内容进行特殊字符清理，防止数据库存储问题\n\n资料来源：[backend/open_webui/models/chats.py:1-50]()\n\n### 3. 消息模型 (Message Model)\n\n消息是对话的原子单位，每条消息包含发送者、内容、附件和时间戳等完整信息。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | str | 消息唯一标识 |\n| `chat_id` | str | 所属对话 ID |\n| `role` | str | 发送者角色 (user/assistant/system) |\n| `content` | str | 消息文本内容 |\n| `attachments` | list | 附件列表 |\n| `metadata` | dict | 额外元数据 |\n| `created_at` | datetime | 创建时间 |\n\n资料来源：[backend/open_webui/models/messages.py:1-80]()\n\n### 4. 文件模型 (File Model)\n\n文件模型管理用户上传的所有文件，包括图片、文档、音频等。\n\n```mermaid\nstateDiagram-v2\n [*] --> Uploaded: 用户上传\n Uploaded --> Processing: 开始处理\n Processing --> Ready: 处理完成\n Processing --> Failed: 处理失败\n Failed --> [*]\n Ready --> Deleted: 用户删除\n Ready --> [*]\n```\n\n**文件类型支持：**\n\n| 类型 | 说明 | 存储方式 |\n|------|------|---------|\n| `image` | 图片文件 | 对象存储 |\n| `document` | 文档 (PDF, DOCX等) | 对象存储 |\n| `audio` | 音频文件 | 对象存储 |\n| `video` | 视频文件 | 对象存储 |\n| `html` | HTML 内容 | 内联存储 |\n\n资料来源：[backend/open_webui/models/files.py:1-100]()\n\n### 5. 函数与工具模型\n\n函数和工具模型为系统提供了扩展能力，允许用户和开发者自定义功能。\n\n```mermaid\ngraph TD\n A[FunctionModel/ToolModel] --> B[\"id: str\"]\n A --> C[\"name: str\"]\n A --> D[\"description: str\"]\n A --> E[\"parameters: dict\"]\n A --> F[\"source_code: str\"]\n A --> G[\"enabled: bool\"]\n \n H[函数调用流程] --> I[解析参数]\n H --> J[执行函数]\n H --> K[返回结果]\n```\n\n资料来源：[backend/open_webui/models/functions.py:1-60]()\n\n### 6. 知识库模型 (Knowledge Model)\n\n知识库模型支持向量化的文档存储和语义检索。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | str | 知识库唯一标识 |\n| `name` | str | 知识库名称 |\n| `description` | str | 描述信息 |\n| `documents` | list | 文档列表 |\n| `embeddings` | list | 向量化数据 |\n| `created_by` | str | 创建者 ID |\n\n资料来源：[backend/open_webui/models/knowledge.py:1-80]()\n\n## 数据库交互层\n\n### 数据库连接管理\n\n`db.py` 模块负责建立和管理数据库连接，支持多种数据库后端：\n\n```python\n# 核心配置参数\nDB_HOST = os.environ.get('DB_HOST', 'localhost')\nDB_PORT = os.environ.get('DB_PORT', '5432')\nDB_NAME = os.environ.get('DB_NAME', 'openwebui')\nDB_USER = os.environ.get('DB_USER', 'postgres')\nDB_PASSWORD = os.environ.get('DB_PASSWORD', '')\n```\n\n**支持的数据库类型：**\n\n| 数据库 | 配置项 | 说明 |\n|-------|-------|------|\n| SQLite | 默认 | 轻量级开发环境 |\n| PostgreSQL | `DATABASE_URL` | 生产环境推荐 |\n| MySQL | `DATABASE_URL` | 兼容模式支持 |\n\n资料来源：[backend/open_webui/internal/db.py:30-80]()\n\n### 数据仓库模式\n\n系统采用 Repository 模式封装数据访问逻辑，提供统一的 CRUD 操作接口：\n\n```mermaid\ngraph TB\n A[Service Layer] --> B[Repository Interface]\n B --> C[UserRepository]\n B --> D[ChatRepository]\n B --> E[MessageRepository]\n B --> F[FileRepository]\n \n C --> G[(Database)]\n D --> G\n E --> G\n F --> G\n```\n\n### 数据清理与安全\n\n消息内容在存入数据库前会经过严格的安全处理：\n\n```python\ndef sanitize_text_for_db(text: str) -> str:\n \"\"\"移除可能导致数据库问题的特殊字符\"\"\"\n # 移除空字符和其他控制字符\n return text.replace('\\x00', '')\n```\n\n**安全措施包括：**\n\n- 移除空字符 (`\\x00`)\n- 转义 HTML 特殊字符\n- 验证字符串长度\n- 类型检查和类型转换\n\n资料来源：[backend/open_webui/models/chats.py:40-60]()\n\n## 数据流程与生命周期\n\n### 消息创建流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant API as API路由\n participant S as 服务层\n participant M as MessageModel\n participant D as 数据库\n \n U->>API: 发送消息\n API->>S: create_message()\n S->>M: 构建消息对象\n M->>D: sanitize_text_for_db()\n D-->>M: 清理后的文本\n M->>D: INSERT INTO messages\n D-->>M: 返回插入结果\n M-->>S: MessageModel\n S-->>API: 响应\n API-->>U: 返回消息\n```\n\n### 对话历史查询流程\n\n系统采用两级缓存策略优化查询性能：\n\n1. **优先路径**：从 `chat_message` 表直接查询（推荐）\n2. **回退路径**：从 `chat.chat.history.messages` JSON blob 读取（兼容旧数据）\n\n```mermaid\nflowchart TD\n A[get_messages_map] --> B{chat_message表存在?}\n B -->|是| C[快速查询
ChatMessages.get_messages_map_by_chat_id]\n B -->|否| D[查询Chat表]\n D --> E{Chat存在?}\n E -->|是| F[解析chat.history.messages]\n E -->|否| G[返回None]\n C --> H[返回消息映射]\n F --> H\n```\n\n资料来源：[backend/open_webui/models/chats.py:15-35]()\n\n## 配置与环境变量\n\n数据模型层的行为受以下环境变量控制：\n\n| 环境变量 | 默认值 | 说明 |\n|---------|-------|------|\n| `DATABASE_URL` | sqlite | 数据库连接字符串 |\n| `DB_HOST` | localhost | 数据库主机 |\n| `DB_PORT` | 5432 | 数据库端口 |\n| `DB_NAME` | openwebui | 数据库名称 |\n| `DB_USER` | postgres | 数据库用户 |\n| `DEVICE_TYPE` | cpu | 嵌入模型设备类型 |\n| `USE_CUDA_DOCKER` | false | 是否使用GPU加速 |\n\n资料来源：[backend/open_webui/env.py:1-60]()\n\n## 扩展与自定义\n\n### 添加新数据模型\n\n在 Open WebUI 中添加新的数据模型需要遵循以下步骤：\n\n1. 在 `backend/open_webui/models/` 目录创建新的模型文件\n2. 定义 Pydantic 模型类继承基础类\n3. 在 `db.py` 中注册新的数据库表\n4. 实现 CRUD 操作方法\n\n```python\n# 示例：新模型结构\nfrom pydantic import BaseModel\nfrom typing import Optional\nfrom datetime import datetime\n\nclass NewModel(BaseModel):\n id: str\n name: str\n description: Optional[str] = None\n created_at: datetime\n updated_at: datetime\n```\n\n### 数据迁移策略\n\n系统支持平滑的数据迁移，确保向后兼容性：\n\n- 新字段添加使用默认值\n- 旧数据结构在读取时自动转换\n- 迁移脚本支持批量更新历史数据\n\n## 最佳实践\n\n### 数据访问规范\n\n1. **始终使用模型方法**：通过模型层访问数据，不要直接操作数据库\n2. **处理空值情况**：使用 `Optional` 类型注解，明确空值处理逻辑\n3. **批量操作优化**：对于大量数据使用批量插入和查询\n4. **事务管理**：相关操作使用数据库事务保证一致性\n\n### 性能优化建议\n\n| 场景 | 优化方案 |\n|------|---------|\n| 频繁读取对话 | 使用 `get_messages_map_by_chat_id` 快速路径 |\n| 大量文件存储 | 配置对象存储而非数据库 |\n| 向量检索 | 使用专门的向量数据库后端 |\n| 复杂查询 | 添加适当的数据库索引 |\n\n## 相关文档\n\n- [API 路由层](../api/routes)\n- [服务层架构](../services)\n- [存储配置](../storage)\n- [安全机制](../security)\n\n---\n\n\n\n## 认证与安全\n\n### 相关页面\n\n相关主题：[后端路由与 API](#page-backend-routers), [数据模型层](#page-backend-models)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [backend/open_webui/utils/auth.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/auth.py)\n- [backend/open_webui/utils/oauth.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/oauth.py)\n- [backend/open_webui/routers/auths.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/auths.py)\n- [backend/open_webui/models/users.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/users.py)\n- [backend/open_webui/routers/scim.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/scim.py)\n- [src/lib/constants/permissions.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/constants/permissions.ts)\n- [backend/open_webui/utils/asgi_middleware.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/asgi_middleware.py)\n- [backend/open_webui/env.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/env.py)\n \n\n# 认证与安全\n\n## 概述\n\nOpen WebUI 的认证与安全系统是一套完整的多层防护机制，支持多种认证方式，包括本地账号认证、OAuth 2.0 单点登录、API Key 认证以及 SCIM 用户管理协议。该系统采用基于角色的访问控制（RBAC）模型，确保不同权限级别的用户只能访问其授权范围内的资源。安全架构的核心设计理念是将认证逻辑与业务逻辑分离，通过中间件统一处理身份验证和授权检查。\n\n整个认证体系构建在 FastAPI 框架之上，利用 Python 的异步特性实现高性能的请求处理。密码存储采用行业标准的加密算法，用户凭证在传输过程中全程使用 HTTPS 加密保护。系统还提供了细粒度的权限控制机制，支持对知识库、提示词、模型等资源进行独立的读写权限配置。\n\n## 认证方式\n\n### 本地账号认证\n\n本地账号认证是 Open WebUI 的基础认证方式，用户通过用户名和密码注册和登录系统。注册时系统会验证邮箱格式并确保用户名唯一性，密码则通过 bcrypt 算法进行加盐哈希存储，确保即使数据库泄露也无法直接还原用户密码。\n\n登录流程中，系统首先根据用户名查找用户记录，验证密码哈希是否匹配。认证成功后，系统生成 JWT（JSON Web Token）格式的访问令牌，令牌中包含用户 ID、角色和过期时间等信息。令牌的有效期默认为 24 小时，用户可以在此期间无需重新登录访问系统资源。\n\n```mermaid\nsequenceDiagram\n participant 用户\n participant 前端 as 前端应用\n participant API as 认证 API\n participant 数据库 as 用户数据库\n\n 用户->>前端: 输入用户名和密码\n 前端->>API: POST /auth/login\n API->>数据库: 查询用户信息\n 数据库-->>API: 用户记录\n API->>API: 验证密码哈希\n API->>API: 生成 JWT Token\n API-->>前端: 返回 Token 和用户信息\n 前端->>前端: 存储 Token 到本地\n 前端-->>用户: 登录成功\n```\n\n用户注册功能默认启用，但管理员可通过配置禁用注册或将系统设置为只读模式。在只读模式下，新用户注册将被阻止，但现有用户仍可正常登录使用系统。密码修改功能允许用户随时更新密码，系统会要求输入当前密码以确认身份。\n\n资料来源：[backend/open_webui/routers/auths.py:1-100](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/auths.py)\n资料来源：[backend/open_webui/models/users.py:1-150](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/users.py)\n\n### OAuth 2.0 单点登录\n\nOpen WebUI 支持通过 OAuth 2.0 协议与企业身份提供商集成，实现单点登录（SSO）。系统目前支持 OIDC（OpenID Connect）标准，能够与主流的身份服务如 Keycloak、Authentik、Okta、Auth0 等无缝对接。OAuth 认证流程遵循标准授权码模式，用户首先被重定向到身份提供商进行身份验证，验证成功后返回授权码，再由后端交换为访问令牌和用户信息。\n\nOAuth 配置通过环境变量进行管理，主要配置项包括提供商类型、客户端 ID、客户端密钥和授权端点 URL。系统会自动发现 OIDC 提供商的配置元数据，包括令牌颁发者地址、用户信息端点和 JWKS（JSON Web Key Set）用于验证令牌签名。\n\n```mermaid\ngraph TD\n A[用户访问 Open WebUI] --> B{是否已登录}\n B -->|否| C[点击 OAuth 登录]\n C --> D[重定向到身份提供商]\n D --> E[用户输入凭证]\n E --> F{身份验证成功}\n F -->|是| G[返回授权码]\n F -->|否| H[显示错误信息]\n G --> I[后端交换授权码]\n I --> J[获取访问令牌]\n J --> K[获取用户信息]\n K --> L[创建或更新本地用户]\n L --> M[生成 JWT 会话]\n M --> N[用户登录成功]\n B -->|是| O[直接访问受保护资源]\n```\n\n用户首次通过 OAuth 登录时，系统会自动创建本地用户记录，将 OAuth 提供商返回的用户信息映射到本地用户模型。后续登录时，系统会识别已有用户并更新其信息，实现用户数据的同步。管理员可以为不同用户分配不同的角色，或将 OAuth 用户自动映射到特定角色组。\n\n资料来源：[backend/open_webui/utils/oauth.py:1-200](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/oauth.py)\n\n### API Key 认证\n\n对于程序化访问场景，Open WebUI 提供了 API Key 认证方式，允许外部应用或服务使用 API Key 访问系统接口。API Key 通过自定义 HTTP 头传输，默认头名称为 `x-api-key`，可在配置中修改以适应不同的反向代理环境。\n\nAPI Key 的创建和管理完全由管理员控制，每个 API Key 可以关联到特定用户或配置为全局密钥。全局密钥绕过用户关联，适用于服务间通信或系统集成场景。API Key 采用一次性哈希存储，后端仅保存密钥的 SHA-256 摘要，用户创建后无法再次查看完整密钥，必须保存后妥善保管。\n\n当 API Key 通过中间件验证时，系统会将其映射到关联的用户身份，后续的权限检查逻辑与普通用户登录完全一致。这意味着 API Key 持有者受到与普通用户相同的 RBAC 约束，确保程序化访问不会绕过安全策略。\n\n资料来源：[backend/open_webui/utils/asgi_middleware.py:1-80](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/asgi_middleware.py)\n\n### SCIM 用户管理\n\nOpen WebUI 实现了 SCIM（System for Cross-domain Identity Management）2.0 协议，支持与企业身份管理系统（如 Okta、Azure AD、OneLogin）集成进行用户自动化配置和生命周期管理。SCIM 接口允许外部系统推送用户创建、更新和禁用操作，实现用户账号的集中管理。\n\n```mermaid\ngraph LR\n A[身份管理系统] -->|POST /Users| B[创建用户]\n A -->|PUT /Users/:id| C[更新用户]\n A -->|PATCH /Users/:id| D[修改用户属性]\n A -->|DELETE /Users/:id| E[禁用用户]\n A -->|GET /Users| F[查询用户列表]\n B --> G{验证数据}\n G -->|通过| H[创建本地用户]\n G -->|失败| I[返回错误]\n H --> J[分配默认角色]\n J --> K[返回用户信息]\n```\n\nSCIM 端点位于 `/scim/v2` 路径下，支持标准的 RESTful 操作。创建用户时，系统会验证请求体的 schema 合规性，提取用户名、邮箱、姓名和活跃状态等核心属性。成功创建的用户会被分配默认角色，并生成对应的本地账号。用户更新操作会同步修改本地用户记录，包括角色变更和状态切换。\n\n资料来源：[backend/open_webui/routers/scim.py:1-300](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/scim.py)\n\n## 令牌与会话管理\n\n### JWT 令牌机制\n\nOpen WebUI 使用 JWT（JSON Web Token）作为主要的会话令牌格式。JWT 包含三个部分：头部（Header）、载荷（Payload）和签名（Signature）。令牌在用户登录成功后生成，包含用户 ID、用户名、角色、权限范围和过期时间等声明。签名使用 HS256 算法，确保令牌内容不可被篡改。\n\n令牌的有效期通过配置管理，默认设置为 24 小时。系统在每个请求中验证令牌的签名和过期时间，过期令牌将被拒绝并返回 401 未授权响应。用户可以通过设置中的\"记住我\"功能延长令牌有效期，延长后的有效期可达 30 天。\n\n```json\n{\n \"id\": \"user-uuid\",\n \"name\": \"username\",\n \"email\": \"user@example.com\",\n \"role\": \"user\",\n \"exp\": 1699999999,\n \"iat\": 1699913599\n}\n```\n\n令牌刷新机制允许用户在令牌即将过期时获取新令牌，无需重新输入密码。刷新令牌通过独立的端点交换，系统会验证原令牌的有效性后颁发新令牌并使旧令牌失效。这种机制在保持安全性的同时提供了流畅的用户体验。\n\n资料来源：[backend/open_webui/utils/auth.py:50-150](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/auth.py)\n\n### Cookie 与 Header 认证\n\n系统支持两种令牌传输方式：通过 HTTP Cookie 或 Authorization Header。Cookie 方式适用于浏览器环境，令牌自动随请求发送并在浏览器关闭后清除。Header 方式则需要客户端手动在请求头中添加 `Authorization: Bearer `，适用于 API 客户端和程序化访问。\n\n```mermaid\ngraph TD\n A[收到 HTTP 请求] --> B{检查 Authorization 头}\n B -->|存在| C[提取 Bearer Token]\n B -->|不存在| D{检查 Cookie}\n D -->|存在| E[提取 token Cookie]\n D -->|不存在| F{检查 API Key 头}\n F -->|存在| G[验证 API Key]\n F -->|不存在| H[返回 401]\n C --> I[验证 JWT 签名]\n E --> I\n G --> J{API Key 有效}\n J -->|是| K[获取关联用户]\n J -->|否| H\n I --> L{JWT 有效}\n L -->|是| M[设置请求状态]\n L -->|否| H\n K --> M\n```\n\n中间件优先检查 Authorization 头，若不存在则回退到 Cookie，最后才检查 API Key。这种优先级设计确保了最佳的安全性：Bearer Token 提供了最细粒度的控制，而 Cookie 认证则为 Web 界面提供了便利。\n\n资料来源：[backend/open_webui/utils/asgi_middleware.py:20-100](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/asgi_middleware.py)\n\n## 基于角色的访问控制\n\n### 角色定义\n\nOpen WebUI 实现了三级角色体系，每种角色对应不同的权限级别：\n\n| 角色 | 描述 | 主要权限 |\n|------|------|----------|\n| admin | 管理员 | 全部功能、用户管理、系统配置、模型管理 |\n| user | 普通用户 | 聊天、创建知识库、使用提示词 |\n| pending | 待审核用户 | 仅登录，无功能权限 |\n\n管理员拥有系统的完全控制权，可以创建和删除用户、修改系统配置、管理 Ollama 模型和知识库。普通用户可以正常使用对话功能，创建个人知识库和提示词，但无法访问管理功能。待审核用户是注册后等待管理员审批的临时状态，此状态下用户只能登录无法使用任何功能。\n\n默认情况下，管理员需要在用户管理界面手动审核新注册用户。但系统也支持配置为自动批准模式，新用户注册后自动获得普通用户角色，立即可以使用系统全部基础功能。\n\n资料来源：[src/lib/constants/permissions.ts:1-100](https://github.com/open-webui/open-webui/blob/main/src/lib/constants/permissions.ts)\n资料来源：[backend/open_webui/models/users.py:50-120](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/users.py)\n\n### 资源权限授予\n\n除了基于角色的粗粒度控制，系统还支持对特定资源进行细粒度的权限授予。资源类型包括知识库（knowledge）、提示词（prompt）、文件（file）等，每种资源可以独立设置读（read）、写（write）和删除（delete）权限。\n\n```mermaid\ngraph TD\n A[用户请求访问资源] --> B[获取资源信息]\n B --> C{用户是管理员?}\n C -->|是| D[允许访问]\n C -->|否| E{用户是资源所有者?}\n E -->|是| D\n E -->|否| F[查询访问授权表]\n F --> G{存在匹配授权?}\n G -->|是| H{授权类型匹配请求?}\n H -->|是| D\n H -->|否| I[拒绝访问]\n G -->|否| I[拒绝访问]\n```\n\n访问授权表（Access Grants）存储用户与资源之间的权限关系。授权可以针对个人用户或用户组设置，支持灵活的权限继承和覆盖机制。管理员可以授予其他用户访问自己创建的知识库的权限，实现团队协作。\n\n资源级别的权限检查贯穿于各个路由处理函数。系统在处理请求前首先验证用户身份，然后在执行业务逻辑前检查用户是否具有相应资源的访问权限。若权限不足，请求将被拒绝并返回 403 Forbidden 响应。\n\n资料来源：[backend/open_webui/routers/knowledge.py:50-150](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)\n\n## 安全中间件\n\n### 请求认证中间件\n\nASGI 中间件是请求处理流程的第一道关卡，负责从 HTTP 请求中提取并验证认证凭证。该中间件实现了统一的认证逻辑，封装在 FastAPI 的请求处理管道中，对所有路由生效。\n\n```python\nasync def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:\n # 仅处理 HTTP 请求\n if scope['type'] != 'http':\n await self.app(scope, receive, send)\n return\n \n request = Request(scope)\n # 尝试多种认证方式\n token = self._extract_bearer_token(request)\n if not token:\n token = self._extract_cookie_token(request)\n if not token:\n token = self._extract_api_key(request)\n \n # 将认证结果存入请求状态\n request.state.token = token\n request.state.enable_api_keys = self._snapshot_config()\n```\n\n中间件按优先级依次尝试 Bearer Token、Cookie Token 和 API Key 三种认证方式。一旦找到有效凭证，中间件会将用户信息和权限快照存入 `request.state`，供后续处理函数使用。这种设计使得业务逻辑可以专注于权限检查，无需关心认证细节。\n\n中间件还会添加响应头 `X-Process-Time`，记录请求处理耗时，便于监控和性能分析。处理时间会被记录但不会影响正常响应，主要用于调试和运维目的。\n\n资料来源：[backend/open_webui/utils/asgi_middleware.py:1-150](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/asgi_middleware.py)\n\n### CSRF 保护\n\n系统实现了 CSRF（跨站请求伪造）保护机制，防止恶意网站诱导已登录用户发起非预期请求。CSRF 防护通过验证请求头中的自定义字段实现，敏感操作（如表单提交、状态变更）必须携带有效的 CSRF 令牌。\n\nWeb 界面在发起跨域请求前会自动获取并附加 CSRF 令牌，确保用户操作的合法性。API 客户端则需要在请求头中手动添加令牌，或使用 Cookie 认证方式（Cookie 请求会自动携带同源策略保护）。\n\n## 环境配置\n\n### 认证相关环境变量\n\nOpen WebUI 通过环境变量配置认证和安全相关的各项参数。这些变量在服务启动时读取，决定了系统的安全行为。\n\n| 环境变量 | 默认值 | 描述 |\n|----------|--------|------|\n| WEBUI_AUTH | True | 是否启用认证（False 为公开访问） |\n| ADMIN_USER_EMAIL | - | 管理员邮箱（首次启动时创建） |\n| ADMIN_USER_PASSWORD | - | 管理员密码 |\n| JWT_EXPIRY | 24h | JWT 令牌有效期 |\n| OIDC_CLIENT_ID | - | OAuth 客户端 ID |\n| OIDC_CLIENT_SECRET | - | OAuth 客户端密钥 |\n| OIDC_PROVIDER_URL | - | OIDC 提供商 URL |\n| CUSTOM_API_KEY_HEADER | x-api-key | API Key 传输头名称 |\n| SCIM_AUTH_HEADER | - | SCIM 认证头 |\n\n管理员邮箱和密码在首次启动时用于创建初始管理员账号。如果未设置，系统会在控制台输出随机生成的初始密码。生产环境中强烈建议设置强密码并妥善保管凭证。\n\n资料来源：[backend/open_webui/env.py:30-100](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/env.py)\n\n### OAuth 提供商配置\n\nOAuth 认证需要配置提供商的详细信息。以下是常见的 OAuth 提供商配置示例：\n\n```bash\n# Keycloak 配置示例\nOIDC_PROVIDER_URL=https://keycloak.example.com/realms/myrealm\nOIDC_CLIENT_ID=open-webui\nOIDC_CLIENT_SECRET=your-client-secret\n\n# Authentik 配置示例\nOIDC_PROVIDER_URL=https://authentik.example.com/application/oauth2/open-webui\nOIDC_CLIENT_ID=open-webui\nOIDC_CLIENT_SECRET=your-client-secret\n\n# 通用 OIDC 配置（系统自动发现元数据）\nOIDC_PROVIDER_URL=https://provider.example.com\nOIDC_CLIENT_ID=open-webui\nOIDC_CLIENT_SECRET=your-client-secret\n```\n\n配置完成后，管理员需要在 OAuth 提供商的应用注册中设置回调 URL，格式为 `{WEBUI_URL}/auth/oidc/callback`。用户点击登录页的 SSO 按钮后将自动跳转到提供商进行身份验证。\n\n资料来源：[backend/open_webui/utils/oauth.py:100-250](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/oauth.py)\n\n## 安全最佳实践\n\n### 部署建议\n\n在生产环境中部署 Open WebUI 时，应遵循以下安全最佳实践：\n\n- **启用 HTTPS**：所有生产部署必须使用 HTTPS，确保传输层加密。使用反向代理（如 Nginx、Caddy）终止 TLS 连接并转发 HTTP 请求到后端。\n- **配置强管理员密码**：首次部署时使用包含大小写字母、数字和特殊字符的强密码。定期更换密码，建议周期为 90 天。\n- **限制 API Key 访问**：API Key 适合机器对机器通信，应限制其访问范围，优先使用最小权限原则。\n- **启用审计日志**：配置日志记录所有认证事件和敏感操作，便于安全审计和异常检测。\n- **定期更新**：保持 Open WebUI 和所有依赖项为最新版本，及时应用安全补丁。\n\n### 常见安全威胁防护\n\n系统内置了针对常见 Web 安全威胁的防护机制：\n\n- **SQL 注入防护**：使用参数化查询处理所有数据库操作，阻止恶意 SQL 代码注入。\n- **XSS 防护**：前端对用户输入进行转义处理，防止跨站脚本执行。\n- **CSRF 防护**：敏感操作需要有效的 CSRF 令牌，防止跨站请求伪造。\n- **暴力破解防护**：登录失败后实施渐进式延迟，阻止自动化暴力猜测攻击。\n\n## 总结\n\nOpen WebUI 的认证与安全系统提供了全面而灵活的访问控制能力，支持从简单的单用户部署到复杂的企业级 SSO 集成。通过 JWT 令牌、OAuth 2.0、API Key 和 SCIM 协议的多重支持，系统可以适应各种使用场景和安全需求。基于角色的访问控制与细粒度资源权限的结合，确保了权限管理的精确性和灵活性。管理员应根据实际需求选择合适的认证方式，并遵循安全最佳实践进行部署和运维。\n\n---\n\n\n\n## 前端组件结构\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [前端路由页面](#page-frontend-routes)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/lib/components/chat/Chat.svelte](https://github.com/open-webui/open-webui/blob/main/src/lib/components/chat/Chat.svelte)\n- [src/lib/components/chat/Messages.svelte](https://github.com/open-webui/open-webui/blob/main/src/lib/components/chat/Messages.svelte)\n- [src/lib/components/workspace/Models.svelte](https://github.com/open-webui/open-webui/blob/main/src/lib/components/workspace/Models.svelte)\n- [src/lib/components/admin/Settings.svelte](https://github.com/open-webui/open-webui/blob/main/src/lib/components/admin/Settings.svelte)\n- [src/lib/stores/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/stores/index.ts)\n- [src/lib/i18n/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/i18n/index.ts)\n \n\n# 前端组件结构\n\n## 概述\n\nOpen WebUI 的前端采用现代化的 SvelteKit 框架构建，采用组件化架构设计。前端代码位于 `src/` 目录下，主要包含组件（components）、状态管理（stores）、工具函数（utils）、国际化（i18n）等核心模块。整个前端架构遵循高内聚低耦合的设计原则，通过 Svelte 的响应式系统和 Store 模式实现状态共享与组件通信。\n\n## 目录结构\n\n```\nsrc/\n├── lib/\n│ ├── components/ # UI 组件目录\n│ │ ├── chat/ # 聊天相关组件\n│ │ ├── workspace/ # 工作区组件\n│ │ ├── admin/ # 管理面板组件\n│ │ └── ...\n│ ├── stores/ # Svelte 状态存储\n│ ├── utils/ # 工具函数\n│ ├── i18n/ # 国际化模块\n│ └── constants.ts # 常量定义\n├── app.html # 应用主模板\n└── routes/ # 页面路由\n```\n\n## 核心组件架构\n\n### 聊天组件体系\n\n聊天模块是 Open WebUI 的核心功能之一，主要由以下组件构成：\n\n| 组件名称 | 文件路径 | 功能描述 |\n|---------|---------|---------|\n| Chat.svelte | src/lib/components/chat/ | 聊天主容器组件，处理用户输入和消息流 |\n| Messages.svelte | src/lib/components/chat/ | 消息展示组件，负责渲染对话内容 |\n| Collapsible | - | 可折叠容器，用于渲染思考过程和代码解释器 |\n\n#### 消息处理流程\n\n```mermaid\ngraph TD\n A[用户输入] --> B[Chat.svelte]\n B --> C[验证输入]\n C --> D[发送API请求]\n D --> E[流式响应]\n E --> F[Messages.svelte]\n F --> G[内容处理sanitizeResponseContent]\n G --> H[渲染消息]\n H --> I[显示完成状态]\n \n J[代码块] --> K[Collapsible组件]\n K --> L[代码解释器执行]\n L --> M[展示执行结果]\n```\n\n聊天组件通过 Store 模式实现与全局状态的同步，支持流式输出和多模态交互。\n\n### 工作区组件\n\nModels.svelte 是工作区中的重要组件，负责模型管理和配置界面：\n\n```mermaid\ngraph LR\n A[模型列表] --> B[模型选择器]\n B --> C[配置面板]\n C --> D[参数调整]\n D --> E[模型切换]\n E --> A\n```\n\n工作区组件与后端 API 通过统一的接口层进行通信，支持模型的动态加载和配置管理。\n\n### 管理面板组件\n\n管理面板通过 Settings.svelte 组件实现用户设置和系统配置功能：\n\n| 配置类别 | 功能模块 |\n|---------|---------|\n| 用户设置 | 主题切换、语言选择、音频配置 |\n| 系统设置 | API 配置、数据库连接、存储后端 |\n| 安全设置 | RBAC 权限管理、访问控制 |\n\n## 状态管理\n\n### Store 架构\n\nOpen WebUI 使用 Svelte 的 writable store 模式实现全局状态管理。核心状态存储定义在 `src/lib/stores/index.ts` 中：\n\n```typescript\n// 关键状态定义示例\nexport const settings: Writable = writable({});\nexport const chatRequestQueues: Writable> = writable({});\nexport const showSidebar = writable(false);\nexport const showSettings = writable(false);\n```\n\n#### 状态分类表\n\n| 状态类型 | 变量名 | 用途 |\n|---------|-------|------|\n| 用户界面 | showSidebar, showSettings | 控制面板显示/隐藏 |\n| 聊天状态 | chatRequestQueues | 管理请求队列 |\n| 全局配置 | settings | 存储用户偏好设置 |\n| 临时状态 | temporaryChatEnabled | 临时会话标记 |\n\n### 响应式数据流\n\n```mermaid\ngraph LR\n A[用户操作] --> B[Store 更新]\n B --> C[响应式订阅]\n C --> D[组件重渲染]\n D --> E[UI 更新]\n```\n\n## 国际化支持\n\n### i18n 模块\n\n国际化系统位于 `src/lib/i18n/` 目录，支持多语言切换功能：\n\n- 语言检测与自动切换\n- 实时翻译文本替换\n- 聊天历史上下文保留\n\n国际化配置通过后端 `backend/open_webui/config.py` 中的配置项管理：\n\n```python\nVOICE_MODE_PROMPT_TEMPLATE = PersistentConfig(...)\nENABLE_VOICE_MODE_PROMPT = PersistentConfig(...)\n```\n\n## 工具函数库\n\n### 核心工具模块\n\n`src/lib/utils/index.ts` 提供了丰富的前端工具函数：\n\n| 函数名称 | 功能描述 |\n|---------|---------|\n| sanitizeResponseContent | 清理响应内容，移除特殊标记 |\n| processResponseContent | 处理中文内容显示 |\n| extractSentences | 提取音频用句子 |\n| extractParagraphsForAudio | 提取音频用段落 |\n| extractCodeBlocks | 提取并处理代码块 |\n\n#### 内容处理流程\n\n```mermaid\ngraph TD\n A[原始内容] --> B[移除特殊标记]\n B --> C[中文处理processChineseContent]\n C --> D[代码块提取]\n D --> E[清理敏感字符]\n E --> F[最终输出]\n```\n\n### 响应内容清理\n\n系统通过 `sanitizeResponseContent` 函数处理模型输出：\n\n```typescript\nexport const sanitizeResponseContent = (content: string) => {\n return content\n .replace(/<\\|[a-z]*$/, '')\n .replace(/<\\|[a-z]+\\|$/, '')\n .replace(/<$/, '')\n .replaceAll('<', '<')\n .replaceAll('>', '>')\n .replaceAll(/<\\|[a-z]+\\|>/g, ' ')\n .trim();\n};\n```\n\n## 常量与配置\n\n### 前端常量定义\n\n`src/lib/constants.ts` 定义了应用级别的常量：\n\n```typescript\nexport const APP_NAME = 'Open WebUI';\nexport const WEBUI_API_BASE_URL = `${WEBUI_BASE_URL}/api/v1`;\nexport const REQUIRED_OLLAMA_VERSION = '0.1.16';\n```\n\n#### 支持的文件类型\n\n| 类型分类 | 文件格式 |\n|---------|---------|\n| 文档 | PDF, EPUB, DOCX, Markdown |\n| 代码 | Python, JavaScript, CSS, XML |\n| 音频 | MPEG, WAV |\n| 其他 | CSV, HTML, Plain Text |\n\n### API 端点常量\n\n| 常量名称 | 用途 |\n|---------|------|\n| OLLAMA_API_BASE_URL | Ollama 模型 API |\n| OPENAI_API_BASE_URL | OpenAI 兼容 API |\n| AUDIO_API_BASE_URL | 音频处理 API |\n| IMAGES_API_BASE_URL | 图像生成 API |\n| RETRIEVAL_API_BASE_URL | 检索增强 API |\n\n## 数据流转架构\n\n### 消息流转\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant C as Chat.svelte\n participant S as Stores\n participant M as Messages.svelte\n participant API as Backend API\n \n U->>C: 发送消息\n C->>API: POST /api/v1/chat\n API-->>C: 流式响应\n C->>S: 更新状态\n S->>M: 触发响应式更新\n M-->>U: 渲染消息内容\n```\n\n### 状态同步机制\n\n组件间通过 Svelte 的响应式系统实现高效状态同步，无需手动订阅和取消订阅。\n\n## 组件通信模式\n\n### 父子组件通信\n\n- Props 传递：父组件向子组件传递数据和回调函数\n- 事件分发：子组件通过 `createEventDispatcher` 触发事件\n\n### 跨组件通信\n\n- Store 共享：多个组件订阅同一 Store 实现状态共享\n- Context API：深层嵌套组件间的数据传递\n\n## 样式与主题\n\n### 主题系统\n\n`src/app.html` 中定义了主题切换的基础样式：\n\n```css\nhtml.dark #splash-screen {\n background: #000;\n}\n\nhtml.her #splash-screen {\n background: #983724;\n}\n```\n\n### 加载屏幕\n\n应用启动时显示统一的加载界面，包含 Logo、进度条等元素，通过 CSS 控制显示与隐藏。\n\n## 技术栈总结\n\n| 层级 | 技术选型 | 说明 |\n|-----|---------|------|\n| 框架 | SvelteKit | 现代化的 Svelte 框架 |\n| 状态管理 | Svelte Stores | 轻量级响应式状态管理 |\n| 路由 | SvelteKit Routes | 基于文件的路由系统 |\n| 构建工具 | Vite | 快速开发与构建 |\n| 样式 | CSS + Custom Properties | 原生 CSS 变量支持主题 |\n| 国际化 | 自定义 i18n 模块 | 多语言支持 |\n\n本页面详细介绍了 Open WebUI 前端组件的组织结构、核心组件功能、状态管理机制以及数据流转方式，为开发者理解和扩展前端功能提供了系统性参考。\n\n---\n\n\n\n## 前端路由页面\n\n### 相关页面\n\n相关主题：[前端组件结构](#page-frontend-structure), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/routes/(app)/+page.svelte](https://github.com/open-webui/open-webui/blob/main/src/routes/(app)/+page.svelte) *(未在当前上下文中提供)*\n- [src/routes/(app)/+layout.svelte](https://github.com/open-webui/open-webui/blob/main/src/routes/(app)/+layout.svelte) *(未在当前上下文中提供)*\n- [src/routes/(app)/admin/+page.svelte](https://github.com/open-webui/open-webui/blob/main/src/routes/(app)/admin/+page.svelte) *(未在当前上下文中提供)*\n- [src/routes/(app)/workspace/+page.svelte](https://github.com/open-webui/open-webui/blob/main/src/routes/(app)/workspace/+page.svelte) *(未在当前上下文中提供)*\n- [src/routes/(app)/c/[id]/+page.svelte](https://github.com/open-webui/open-webui/blob/main/src/routes/(app)/c/[id]/+page.svelte) *(未在当前上下文中提供)*\n- [src/lib/constants.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)\n- [src/lib/utils/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/utils/index.ts)\n- [src/lib/apis/terminal/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/apis/terminal/index.ts)\n- [backend/open_webui/main.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/main.py)\n- [backend/open_webui/routers/knowledge.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)\n- [backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)\n \n\n# 前端路由页面\n\n## 概述\n\nOpen WebUI 的前端采用 **SvelteKit** 作为核心框架，通过文件路由系统（File-based Routing）组织页面结构。路由系统遵循 SvelteKit 的约定式路由规范，使用 `(app)` 路由组来封装应用的主要功能页面。\n\n前端路由页面的主要职责包括：\n\n- 提供用户交互的主界面（聊天、对话管理）\n- 实现管理员控制台\n- 支持工作区功能\n- 处理动态路由参数（如对话 ID）\n\n## 路由架构\n\n### 路由目录结构\n\n```\nsrc/routes/\n├── (app)/\n│ ├── +layout.svelte # 应用布局组件\n│ ├── +page.svelte # 首页/主聊天页面\n│ ├── admin/\n│ │ └── +page.svelte # 管理后台页面\n│ ├── workspace/\n│ │ └── +page.svelte # 工作区页面\n│ └── c/\n│ └── [id]/\n│ └── +page.svelte # 动态对话详情页\n```\n\n### 路由与后端 API 的映射关系\n\n| 前端路由 | 后端 API 前缀 | 功能描述 |\n|----------|---------------|----------|\n| `(app)/+page.svelte` | `/api/v1/chats` | 聊天列表与主界面 |\n| `(app)/admin/+page.svelte` | `/api/v1/*` | 系统管理与配置 |\n| `(app)/workspace/+page.svelte` | `/api/v1/knowledge` | 知识库与 RAG 工作区 |\n| `(app)/c/[id]/+page.svelte` | `/api/v1/chats/{id}` | 特定对话详情与消息 |\n\n## 核心组件说明\n\n### 布局组件 (`+layout.svelte`)\n\n`(app)/+layout.svelte` 作为全局布局，包裹所有 `(app)` 路由组下的页面。主要功能包括：\n\n- 初始化全局状态管理\n- 配置应用级导航栏\n- 加载用户会话信息\n- 设置主题与语言偏好\n\n### 主页面 (`+page.svelte`)\n\n`(app)/+page.svelte` 是用户首次访问时的默认页面，提供：\n\n- 对话列表展示\n- 新建对话入口\n- 模型选择器\n- 聊天消息输入框\n\n### 管理员页面\n\n`(app)/admin/+page.svelte` 提供系统管理功能：\n\n- 用户管理 (RBAC)\n- 模型配置\n- 系统设置\n- 日志与审计\n\n资料来源：[backend/open_webui/main.py:1-50]()\n\n### 工作区页面\n\n`(app)/workspace/+page.svelte` 面向知识管理场景：\n\n- 知识库文件上传与管理\n- RAG 配置\n- 文档处理状态监控\n\n资料来源：[backend/open_webui/routers/knowledge.py:1-50]()\n\n### 动态对话页面\n\n`(app)/c/[id]/+page.svelte` 处理动态路由参数 `[id]`，该页面用于：\n\n- 加载特定对话的消息历史\n- 渲染对话流内容\n- 处理代码解释器等特殊消息类型\n\n资料来源：[src/lib/utils/index.ts:1-80]()\n\n## API 路由集成\n\n### 后端 FastAPI 路由注册\n\nOpen WebUI 后端使用 FastAPI 的.include_router()方法注册所有 API 路由：\n\n```python\napp.include_router(chats.router, prefix='/api/v1/chats', tags=['chats'])\napp.include_router(knowledge.router, prefix='/api/v1/knowledge', tags=['knowledge'])\napp.include_router(models.router, prefix='/api/v1/models', tags=['models'])\napp.include_router(files.router, prefix='/api/v1/files', tags=['files'])\n```\n\n资料来源：[backend/open_webui/main.py:50-80]()\n\n### 前端 API 端点常量\n\n前端通过 `src/lib/constants.ts` 定义 API 基础 URL：\n\n| 常量名 | 值 | 用途 |\n|--------|-----|------|\n| `WEBUI_API_BASE_URL` | `/api/v1` | 主 API 端点 |\n| `AUDIO_API_BASE_URL` | `/api/v1/audio` | 音频处理 |\n| `IMAGES_API_BASE_URL` | `/api/v1/images` | 图像处理 |\n| `RETRIEVAL_API_BASE_URL` | `/api/v1/retrieval` | RAG 检索 |\n\n资料来源：[src/lib/constants.ts:1-20]()\n\n## 状态管理与数据流\n\n```mermaid\ngraph TD\n A[用户交互] --> B[SvelteKit 路由]\n B --> C{页面组件}\n \n C --> D[加载对话数据]\n C --> E[管理知识库]\n C --> F[管理员操作]\n \n D --> G[调用 /api/v1/chats]\n E --> H[调用 /api/v1/knowledge]\n F --> I[调用 /api/v1/users, /api/v1/configs]\n \n G --> J[后端 Chat 路由处理器]\n H --> K[后端 Knowledge 路由处理器]\n I --> L[后端 Admin 路由处理器]\n \n J --> M[(SQLite/PostgreSQL)]\n K --> N[(向量数据库)]\n L --> M\n```\n\n## 消息内容处理\n\n前端路由页面使用 `sanitizeResponseContent` 和 `processResponseContent` 函数处理 AI 响应：\n\n```typescript\nexport const sanitizeResponseContent = (content: string) => {\n return content\n .replace(/<\\|[a-z]*$/, '')\n .replace(/<\\|[a-z]+\\|$/, '')\n .replace(/<$/, '')\n .replaceAll('<', '<')\n .replaceAll('>', '>')\n .replaceAll(/<\\|[a-z]+\\|>/g, ' ')\n .trim();\n};\n```\n\n资料来源：[src/lib/utils/index.ts:50-70]()\n\n### 中文内容特殊处理\n\n针对中文内容，框架进行了特殊处理以解决 Markdown/LaTeX 格式问题：\n\n```typescript\nfunction processChineseContent(content: string): string {\n if (!/[\\u4e00-\\u9fa5]/.test(content)) return content;\n // 中文内容处理逻辑\n}\n```\n\n资料来源：[src/lib/utils/index.ts:75-90]()\n\n## 文件 API 与终端集成\n\n前端通过 `src/lib/apis/terminal/index.ts` 提供文件操作能力：\n\n| 函数 | 功能 |\n|------|------|\n| `listFiles` | 列出目录中的文件 |\n| `readFile` | 读取文件内容 |\n| `downloadFileBlob` | 下载文件为 Blob |\n\n资料来源：[src/lib/apis/terminal/index.ts:1-60]()\n\n## 代码解释器集成\n\n路由页面支持代码解释器功能，通过后端中间件处理 `code_interpreter` 类型消息：\n\n```python\nelif item_type == 'open_webui:code_interpreter':\n # 代码解释器消息处理\n code = item.get('code', '').strip()\n lang = item.get('lang', 'python')\n status = item.get('status', 'in_progress')\n```\n\n资料来源：[backend/open_webui/utils/middleware.py:1-50]()\n\n### 代码执行引擎配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `ENABLE_CODE_EXECUTION` | True | 是否启用代码执行 |\n| `CODE_EXECUTION_ENGINE` | pyodide | 执行引擎 (pyodide/jupyter) |\n| `CODE_EXECUTION_JUPYTER_URL` | - | Jupyter 服务地址 |\n| `CODE_EXECUTION_JUPYTER_AUTH` | - | Jupyter 认证信息 |\n\n资料来源：[backend/open_webui/config.py:1-50]()\n\n## 访问控制与权限\n\n路由页面通过后端 RBAC 系统实现访问控制：\n\n```python\nif not (\n user.role == 'admin'\n or knowledge.user_id == user.id\n or await AccessGrants.has_access(...)\n):\n raise HTTPException(status_code=400, detail=ERROR_MESSAGES.ACCESS_PROHIBITED)\n```\n\n资料来源：[backend/open_webui/routers/knowledge.py:50-80]()\n\n## 相关页面\n\n- [后端 API 路由](backend/open_webui/main.py)\n- [前端工具函数](src/lib/utils/index.ts)\n- [应用常量定义](src/lib/constants.ts)\n- [知识库路由](backend/open_webui/routers/knowledge.py)\n- [终端 API](src/lib/apis/terminal/index.ts)\n\n---\n\n\n\n## 模型集成与支持\n\n### 相关页面\n\n相关主题：[检索增强生成 (RAG)](#page-retrieval-rag), [工具与函数系统](#page-tools-functions)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [backend/open_webui/main.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/main.py)\n- [backend/open_webui/routers/models.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/models.py)\n- [backend/open_webui/routers/ollama.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/ollama.py)\n- [backend/open_webui/routers/openai.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/openai.py)\n- [backend/open_webui/utils/models.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/models.py)\n- [backend/open_webui/models/models.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/models/models.py)\n- [backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)\n- [src/lib/constants.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)\n- [src/lib/components/chat/ModelSelector.svelte](https://github.com/open-webui/open-webui/blob/main/src/lib/components/chat/ModelSelector.svelte)\n- [src/lib/components/workspace/Models.svelte](https://github.com/open-webui/open-webui/blob/main/src/lib/components/workspace/Models.svelte)\n \n\n# 模型集成与支持\n\n## 概述\n\nOpen WebUI 的模型集成与支持系统是整个平台的核心功能模块，负责管理与接入多种大语言模型（LLM）提供方。该系统通过统一的 API 网关架构，将 Ollama、OpenAI 兼容 API 等多种模型服务进行抽象封装，为用户提供无缝的模型切换与交互体验。\n\n系统支持多模型并发对话、模型热度管理、角色权限控制等功能，并提供完整的模型生命周期管理，包括模型的发现、拉取、配置与删除操作。资料来源：[backend/open_webui/main.py:48]()\n\n```mermaid\ngraph TD\n A[用户界面] --> B[前端 ModelSelector]\n B --> C[API 网关层]\n C --> D[Ollama 路由器]\n C --> E[OpenAI 路由器]\n C --> F[Models 路由器]\n D --> G[Ollama 服务]\n E --> H[OpenAI 兼容服务]\n F --> I[模型数据库]\n G --> I\n H --> I\n```\n\n## 架构设计\n\n### API 端点结构\n\nOpen WebUI 采用 FastAPI 框架构建后端服务，通过路由器（Router）模式组织 API 端点。模型相关的 API 端点分布在多个路由器中，形成统一的接口体系。\n\n| 路由器 | 前缀路径 | 标签 | 功能描述 |\n|--------|----------|------|----------|\n| models | `/api/v1/models` | models | 模型 CRUD 操作 |\n| ollama | `/api/v1/ollama` | ollama | Ollama 专属 API |\n| openai | `/api/v1/openai` | openai | OpenAI 兼容 API |\n| functions | `/api/v1/functions` | functions | 函数调用管理 |\n\n资料来源：[backend/open_webui/main.py:48-54]()\n\n### 服务地址配置\n\n前端通过 `src/lib/constants.ts` 集中管理所有 API 服务地址，支持开发环境与生产环境的动态切换。\n\n```typescript\nexport const WEBUI_HOSTNAME = browser ? (dev ? `${location.hostname}:8080` : ``) : '';\nexport const WEBUI_BASE_URL = browser ? (dev ? `http://${WEBUI_HOSTNAME}` : ``) : ``;\nexport const WEBUI_API_BASE_URL = `${WEBUI_BASE_URL}/api/v1`;\nexport const OLLAMA_API_BASE_URL = `${WEBUI_BASE_URL}/ollama`;\nexport const OPENAI_API_BASE_URL = `${WEBUI_BASE_URL}/openai`;\n```\n\n资料来源：[src/lib/constants.ts:4-11]()\n\n## 支持的模型类型\n\n### Ollama 模型\n\nOllama 是 Open WebUI 的核心本地模型运行引擎，支持在本地部署和运行各类开源大语言模型。系统通过 Ollama API 进行模型管理，支持超过 1000 种开源模型。\n\n支持的模型类型包括：\n\n- **对话模型**：Llama 2/3、Mistral、Qwen 等\n- **嵌入模型**：用于向量检索和语义搜索\n- **多模态模型**：支持图像理解和分析的模型\n\n### OpenAI 兼容模型\n\nOpen WebUI 通过 OpenAI 兼容层支持接入任何符合 OpenAI API 规范的服务提供方，包括：\n\n- OpenAI 官方 API（GPT-4、GPT-3.5-turbo）\n- Azure OpenAI Service\n- 自定义 OpenAI 兼容 API 服务器\n- 云端模型服务（如 Groq、Perplexity 等）\n\n资料来源：[src/lib/apis/openai/index.ts:1-10]()\n\n## 前端模型选择组件\n\n### ModelSelector 组件\n\n`ModelSelector.svelte` 是聊天界面中的模型选择器组件，提供直观的模型切换交互界面。该组件支持以下功能：\n\n- 模型搜索与过滤\n- 模型热度排序\n- 快捷键切换模型\n- 模型图标与描述显示\n\n```mermaid\ngraph LR\n A[用户点击选择器] --> B[展开模型列表]\n B --> C[搜索/过滤模型]\n C --> D[选择目标模型]\n D --> E[更新会话上下文]\n E --> F[发送请求至后端]\n```\n\n资料来源：[src/lib/components/chat/ModelSelector.svelte]()\n\n### Workspace Models 组件\n\n`Models.svelte` 是工作区中的模型管理界面，提供更全面的模型管理功能，包括：\n\n- 模型列表展示与排序\n- 模型添加与配置\n- 模型删除与禁用\n- 模型使用统计\n\n资料来源：[src/lib/components/workspace/Models.svelte]()\n\n## 模型管理 API\n\n### 获取模型列表\n\n```\nGET /api/v1/models\n```\n\n返回系统中所有已配置的模型列表，包括模型的元数据、状态和配置信息。\n\n### 获取模型详情\n\n```\nGET /api/v1/models/{model_id}\n```\n\n获取指定模型的详细信息，包括：\n\n- 模型 ID 和名称\n- 模型类型和提供者\n- 上下文长度\n- 支持的功能（函数调用、视觉等）\n\n### 创建模型配置\n\n```\nPOST /api/v1/models\n```\n\n创建新的模型配置，支持配置模型参数和连接信息。\n\n### 更新模型配置\n\n```\nPUT /api/v1/models/{model_id}\n```\n\n更新现有模型的配置参数。\n\n### 删除模型\n\n```\nDELETE /api/v1/models/{model_id}\n```\n\n从系统中移除指定的模型配置。\n\n资料来源：[backend/open_webui/main.py:48]()\n\n## 配置选项\n\n### 环境变量配置\n\n系统通过环境变量和配置文件管理模型相关的设置。主要配置项包括：\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| `OLLAMA_API_BASE_URL` | Ollama API 地址 | `/ollama` |\n| `OPENAI_API_BASE_URL` | OpenAI API 地址 | `/openai` |\n| `OPENAI_API_KEY` | OpenAI API 密钥 | - |\n| `ENABLE_OPENAI_API` | 启用 OpenAI API | True |\n| `DEFAULT_MODEL` | 默认模型 | - |\n\n资料来源：[backend/open_webui/config.py]()\n\n### 运行时配置\n\n系统支持通过管理员界面动态调整模型配置，包括：\n\n- 模型调用参数（温度、最大 token 等）\n- API 超时设置\n- 重试策略配置\n- 代理设置\n\n## 多模型对话支持\n\nOpen WebUI 支持在单一对话中使用多个模型，通过并行调用不同模型获取响应，实现更优的回答质量。\n\n### 多模型对话流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant F as 前端\n participant B as 后端\n participant M1 as 模型A\n participant M2 as 模型B\n \n U->>F: 发送消息\n F->>B: 转发请求\n B->>M1: 并发请求模型A\n B->>M2: 并发请求模型B\n M1-->>B: 返回响应A\n M2-->>B: 返回响应B\n B-->>F: 合并响应\n F-->>U: 展示结果\n```\n\n### 模型选择策略\n\n系统支持多种模型选择策略：\n\n1. **自动选择**：根据请求类型自动选择最合适的模型\n2. **手动选择**：用户显式指定使用的模型\n3. **智能路由**：基于模型能力与请求特征的动态路由\n\n资料来源：[src/lib/components/chat/ModelSelector.svelte]()\n\n## 角色权限控制\n\nOpen WebUI 实现基于角色的访问控制（RBAC），模型访问权限与用户角色挂钩：\n\n| 角色 | 权限级别 | 可用功能 |\n|------|----------|----------|\n| 管理员 | 完全权限 | 所有模型操作 |\n| 普通用户 | 受限权限 | 使用已授权模型 |\n| 访客 | 最小权限 | 仅使用公开模型 |\n\n资料来源：[README.md]()\n\n## 最佳实践\n\n### 模型选择建议\n\n1. **性能优先场景**：选择量化模型或较小的模型以降低延迟\n2. **质量优先场景**：使用较大的基础模型或 GPT-4 系列\n3. **成本敏感场景**：优先使用本地 Ollama 模型\n4. **多模态场景**：选择支持视觉的模型（如 Llava）\n\n### 安全配置\n\n- 生产环境务必配置 API 密钥\n- 启用模型访问审计日志\n- 定期轮换 API 密钥\n- 限制敏感模型的访问权限\n\n## 相关文档\n\n- [Ollama 官方文档](https://github.com/ollama/ollama)\n- [OpenAI API 文档](https://platform.openai.com/docs/api-reference)\n- [Open WebUI 安装指南](./installation.md)\n- [管理员配置手册](./admin-guide.md)\n\n---\n\n\n\n## 检索增强生成 (RAG)\n\n### 相关页面\n\n相关主题：[模型集成与支持](#page-model-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [backend/open_webui/retrieval/vector/factory.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/retrieval/vector/factory.py)\n- [backend/open_webui/retrieval/loaders/main.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/retrieval/loaders/main.py)\n- [backend/open_webui/retrieval/web/main.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/retrieval/web/main.py)\n- [backend/open_webui/routers/knowledge.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/knowledge.py)\n- [backend/open_webui/routers/retrieval.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/routers/retrieval.py)\n \n\n# 检索增强生成 (RAG)\n\n## 概述\n\n检索增强生成（Retrieval-Augmented Generation，简称 RAG）是一种将信息检索与语言模型生成相结合的技术架构。在 Open WebUI 项目中，RAG 模块负责从外部知识库、文档集合或网络资源中检索相关内容，并将检索结果注入到大语言模型（LLM）的上下文窗口中，从而提升模型回答的准确性、时效性和可信度。\n\nOpen WebUI 的 RAG 系统支持多种文档格式、多种向量存储后端以及多种网络搜索提供者，形成了完整的**文档处理 → 向量化 → 存储 → 检索 → 上下文注入**链路。\n\n## 核心架构\n\nRAG 系统在整体上分为三大子模块：\n\n1. **文档加载与处理（Loaders）**：负责从各类文件格式中提取文本内容\n2. **向量存储与检索（Vector Stores）**：负责文本的向量化、存储和相似度检索\n3. **网络搜索（Web Retrieval）**：支持通过外部搜索引擎获取实时信息\n\n```mermaid\ngraph TD\n A[用户查询] --> B[检索模块]\n B --> C{检索类型}\n C -->|知识库检索| D[向量存储检索]\n C -->|网络搜索| E[Web Search Providers]\n \n D --> F[文档加载器]\n F --> G[文本分块]\n G --> H[向量化]\n H --> I[向量数据库]\n I --> J[相似度检索]\n J --> K[上下文构建]\n \n E --> L[搜索结果处理]\n L --> K\n \n K --> M[LLM 生成响应]\n```\n\n## 文档加载与处理\n\n### 支持的文件格式\n\n文档加载模块支持以下文件类型（资料来源：[src/lib/constants.ts](src/lib/constants.ts)）：\n\n| 文件类型 | MIME 类型 |\n|---------|-----------|\n| PDF | `application/pdf` |\n| EPUB | `application/epub+zip` |\n| Word 文档 | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |\n| 纯文本 | `text/plain` |\n| CSV | `text/csv` |\n| XML | `text/xml` |\n| HTML | `text/html` |\n| Markdown | `text/markdown` |\n| Python 代码 | `text/x-python` |\n| CSS | `text/css` |\n| JavaScript | `application/x-javascript` |\n| 音频 | `audio/mpeg`, `audio/wav` |\n\n### 加载器实现\n\n文档加载器的核心实现在 `backend/open_webui/retrieval/loaders/` 目录下。加载器采用统一的接口设计，主要包括：\n\n- **PDF 处理**：支持多种 PDF 解析后端，包括 Tika、DOCLING、文档智能（Document Intelligence）、Mistral OCR、PaddleOCR VL、MinerU 等\n- **图片 OCR**：通过 PaddleOCR VL 等引擎从图片中提取文字（资料来源：[backend/open_webui/retrieval/loaders/paddleocr_vl.py](backend/open_webui/retrieval/loaders/paddleocr_vl.py)）\n\n```mermaid\ngraph LR\n A[上传文件] --> B{文件类型判断}\n B -->|PDF| C[PDF Loader]\n B -->|图片| D[OCR Engine]\n B -->|文本| E[Text Loader]\n \n C --> F[文本提取]\n D --> G[OCR 识别]\n E --> H[直接读取]\n \n F --> I[Document 对象]\n G --> I\n H --> I\n \n I --> J[分块处理]\n J --> K[元数据附加]\n K --> L[输出片段列表]\n```\n\n### 配置参数\n\n文档处理支持以下关键配置（资料来源：[backend/open_webui/retrieval/utils.py](backend/open_webui/retrieval/utils.py)）：\n\n| 参数名 | 说明 |\n|-------|------|\n| `EXTERNAL_DOCUMENT_LOADER_URL` | 外部文档加载器服务地址 |\n| `TIKA_SERVER_URL` | Apache Tika 服务器地址 |\n| `DOCLING_SERVER_URL` | DOCLING 服务地址 |\n| `DOCLING_API_KEY` | DOCLING API 密钥 |\n| `PDF_EXTRACT_IMAGES` | 是否从 PDF 提取图片 |\n| `PDF_LOADER_MODE` | PDF 加载模式 |\n| `DOCUMENT_INTELLIGENCE_ENDPOINT` | Azure 文档智能端点 |\n| `MISTRAL_OCR_API_BASE_URL` | Mistral OCR API 地址 |\n| `PADDLEOCR_VL_BASE_URL` | PaddleOCR VL 服务地址 |\n| `MINERU_API_URL` | MinerU API 地址 |\n\n## 向量存储与检索\n\n### 向量存储后端\n\nOpen WebUI 支持多种向量数据库作为存储后端，通过工厂模式（Factory Pattern）进行统一管理（资料来源：[backend/open_webui/retrieval/vector/factory.py](backend/open_webui/retrieval/vector/factory.py)）：\n\n| 向量存储 | 说明 |\n|---------|------|\n| Chroma | 本地向量数据库 |\n| FAISS | Facebook AI 相似度搜索 |\n| Qdrant | 高性能向量数据库 |\n| Milvus | 分布式向量数据库 |\n| Weaviate | 云原生向量搜索引擎 |\n| Pinecone | 云端向量数据库 |\n| Elasticsearch | 混合搜索能力 |\n| Chroma Legacy | 向后兼容模式 |\n\n### 检索流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant A as API 路由\n participant R as 检索路由器\n participant V as 向量存储\n participant L as LLM\n \n U->>A: 发送查询请求\n A->>R: 转发查询\n R->>V: 执行相似度搜索\n V-->>R: 返回 Top-K 相关片段\n R->>L: 构建提示词上下文\n L-->>U: 生成增强响应\n```\n\n### 检索 API\n\n检索功能通过 RESTful API 暴露，主要端点包括（资料来源：[backend/open_webui/routers/retrieval.py](backend/open-webui/routers/retrieval.py)）：\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/api/v1/retrieval/search` | POST | 执行知识库检索 |\n| `/api/v1/retrieval/process` | POST | 处理并索引文档 |\n| `/api/v1/retrieval/config` | GET | 获取检索配置 |\n\n## 网络搜索\n\n### 支持的搜索提供者\n\nOpen WebUI 集成了超过 15 种网络搜索提供者，可在 RAG 流程中注入实时网络信息（资料来源：[README.md](README.md)）：\n\n| 提供者 | 说明 |\n|-------|------|\n| SearXNG | 开源自托管元搜索引擎 |\n| Google PSE | Google Programmable Search Engine |\n| Brave Search | Brave 浏览器搜索 API |\n| Kagi | 高质量搜索服务 |\n| Mojeek | 独立搜索索引 |\n| Tavily | AI 优化的搜索 API |\n| Perplexity | AI 搜索服务 |\n| DuckDuckGo | 隐私导向搜索 |\n| Bing | Microsoft 搜索 API |\n| Jina | AI 驱动的搜索与摘要 |\n| Exa | 语义搜索 API |\n| Azure AI Search | Azure 云搜索服务 |\n| Ollama Cloud | Ollama 云端服务 |\n\n### 搜索结果处理\n\n搜索结果经过标准化处理后返回统一的 `SearchResult` 数据结构（资料来源：[backend/open_webui/retrieval/web/ydc.py](backend/open_webui/retrieval/web/ydc.py)）：\n\n```python\n@dataclass\nclass SearchResult:\n link: str # 结果链接\n title: str # 结果标题\n snippet: str # 摘要内容\n```\n\n对于不同的搜索 API，Open WebUI 进行了结果格式统一，包括：\n- 标题提取与清理\n- 摘要/片段（Snippet）的合并构建\n- URL 解析与规范化\n- 评分与排序\n\n## 知识库管理\n\n### 知识库 API\n\n知识库管理功能提供了完整的 CRUD 操作（资料来源：[backend/open_webui/routers/knowledge.py](backend/open-webui/routers/knowledge.py)）：\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/api/v1/knowledge` | GET | 列出所有知识库 |\n| `/api/v1/knowledge` | POST | 创建新知识库 |\n| `/api/v1/knowledge/{id}` | GET | 获取知识库详情 |\n| `/api/v1/knowledge/{id}` | PUT | 更新知识库配置 |\n| `/api/v1/knowledge/{id}` | DELETE | 删除知识库 |\n| `/api/v1/knowledge/{id}/file` | POST | 上传文件到知识库 |\n| `/api/v1/knowledge/{id}/file/{file_id}` | DELETE | 从知识库删除文件 |\n\n### 知识库数据模型\n\n```\nKnowledge {\n id: string # 唯一标识符\n name: string # 知识库名称\n description: string # 描述信息\n user_id: string # 所有者 ID\n created_at: timestamp # 创建时间\n updated_at: timestamp # 更新时间\n settings: {\n embeddings: object # 嵌入模型配置\n chunk_size: int # 分块大小\n chunk_overlap: int # 分块重叠\n }\n}\n```\n\n## RAG 与 LLM 集成\n\n### 上下文注入流程\n\nRAG 检索结果通过以下方式注入到 LLM 对话中：\n\n```mermaid\ngraph LR\n A[用户消息] --> B[检索查询生成]\n B --> C[并行执行]\n C --> D[向量检索]\n C --> E[网络搜索]\n D --> F[结果合并]\n E --> F\n F --> G[上下文构建]\n G --> H[提示词组装]\n H --> I[LLM 生成]\n I --> J[响应输出]\n```\n\n### 提示词模板\n\nRAG 系统使用专门的提示词模板来引导模型正确利用检索到的上下文：\n\n- **默认检索模板**：通用问答场景\n- **中文内容处理**：针对中文文档的特殊格式化处理（资料来源：[src/lib/utils/index.ts](src/lib/utils/index.ts)）\n- **引用标注**：在回答中标注信息来源\n\n## 配置管理\n\n### 环境变量配置\n\nRAG 系统的核心配置通过环境变量管理：\n\n| 变量名 | 默认值 | 说明 |\n|-------|-------|------|\n| `ENABLE_RAG_WEB` | `True` | 启用网络搜索 RAG |\n| `RAG_TOP_K` | `5` | 检索返回的 Top-K 结果数 |\n| `RAG_EMBEDDING_MODEL` | - | 嵌入模型选择 |\n| `RAG_VECTOR_DB` | `chroma` | 向量数据库选择 |\n| `WEB_SEARCH_API_KEY` | - | 搜索 API 密钥 |\n| `SEARXNG_QUERY_URL` | - | SearXNG 实例地址 |\n\n## 使用场景\n\n1. **私有知识问答**：上传内部文档创建私有知识库\n2. **实时信息补充**：通过网络搜索获取最新资讯\n3. **多模态文档理解**：处理 PDF、图片混合文档\n4. **跨语言检索**：支持多语言文档的统一检索\n\n## 最佳实践\n\n- **分块策略**：根据文档类型选择合适的分块大小，代码类文档建议较小分块\n- **向量模型选择**：根据文档语言选择对应语言的嵌入模型\n- **混合检索**：结合向量检索与关键词检索以平衡精确度与召回率\n- **定期更新**：知识库内容变更后需重新索引\n\n---\n\n\n\n## 工具与函数系统\n\n### 相关页面\n\n相关主题：[模型集成与支持](#page-model-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [backend/open_webui/main.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/main.py)\n- [backend/open_webui/config.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/config.py)\n- [src/lib/utils/index.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/utils/index.ts)\n- [backend/open_webui/utils/middleware.py](https://github.com/open-webui/open-webui/blob/main/backend/open_webui/utils/middleware.py)\n- [src/lib/constants.ts](https://github.com/open-webui/open-webui/blob/main/src/lib/constants.ts)\n \n\n# 工具与函数系统\n\n## 概述\n\nOpen WebUI 的工具与函数系统是平台的核心扩展机制之一，允许用户通过自定义工具和函数来增强 AI 助手的交互能力。该系统支持在对话过程中动态调用外部工具、执行代码、访问外部数据源，从而实现更丰富的智能助手体验。\n\n系统通过 API 路由层统一管理工具的注册、调用和生命周期维护，支持多种工具类型，包括内置工具、用户自定义工具以及通过函数定义的工具。\n\n## 系统架构\n\n### 整体架构流程\n\n```mermaid\ngraph TD\n A[用户请求] --> B[API 路由层
routers/tools.py]\n B --> C[工具注册表
tools/__init__.py]\n C --> D{工具类型}\n D --> E[内置工具
builtin.py]\n D --> F[用户自定义函数
models/functions.py]\n D --> G[外部工具]\n E --> H[工具执行引擎]\n F --> H\n G --> H\n H --> I[结果返回]\n I --> J[前端展示
Tools.svelte]\n```\n\n### 组件层级\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| API 层 | routers/tools.py | HTTP 接口、请求验证、响应格式化 |\n| 核心层 | tools/__init__.py | 工具注册表、调度逻辑、生命周期管理 |\n| 内置工具层 | tools/builtin.py | 系统内置工具实现 |\n| 数据模型层 | models/functions.py | 函数数据结构、序列化/反序列化 |\n| 前端层 | Tools.svelte | 工具管理界面、用户交互 |\n| 中间件层 | utils/middleware.py | 工具输出渲染、内容处理 |\n\n## 工具注册与路由\n\n### API 路由配置\n\n工具系统通过 FastAPI 路由模块挂载到主应用，所有工具相关的 HTTP 接口均以 `/api/v1/tools` 为前缀。\n\n```python\napp.include_router(tools.router, prefix='/api/v1/tools', tags=['tools'])\n```\n资料来源：[backend/open_webui/main.py]()\n\n### 路由端点\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/` | GET | 获取工具列表 |\n| `/{tool_id}` | GET | 获取特定工具详情 |\n| `/` | POST | 注册新工具 |\n| `/{tool_id}` | PUT | 更新工具配置 |\n| `/{tool_id}` | DELETE | 删除工具 |\n\n## 函数数据模型\n\n### 数据结构定义\n\n函数（Function）是工具系统的核心数据结构，用于描述可调用的工具逻辑。\n\n```python\nclass Function:\n id: str # 唯一标识符\n name: str # 函数名称\n description: str # 函数描述\n parameters: dict # 参数定义（JSON Schema）\n return_type: str # 返回值类型\n is_enabled: bool # 是否启用\n created_at: datetime # 创建时间\n updated_at: datetime # 更新时间\n```\n\n### 参数定义规范\n\n函数参数采用 JSON Schema 格式定义，支持以下类型：\n\n| 类型 | 描述 | 示例 |\n|------|------|------|\n| string | 字符串类型 | `\"type\": \"string\"` |\n| integer | 整数类型 | `\"type\": \"integer\"` |\n| number | 数字类型 | `\"type\": \"number\"` |\n| boolean | 布尔类型 | `\"type\": \"boolean\"` |\n| array | 数组类型 | `\"type\": \"array\", \"items\": {...}` |\n| object | 对象类型 | `\"type\": \"object\", \"properties\": {...}` |\n\n## 工具执行流程\n\n### 执行时序\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant A as API路由\n participant T as 工具注册表\n participant E as 执行引擎\n participant R as 结果渲染器\n\n U->>A: 调用工具请求\n A->>T: 查询工具定义\n T-->>A: 返回工具元数据\n A->>E: 提交执行任务\n E->>E: 执行工具逻辑\n E-->>A: 返回执行结果\n A->>R: 渲染结果内容\n R-->>A: 格式化输出\n A-->>U: 返回响应\n```\n\n### 内置工具类型\n\n系统预置多种内置工具，覆盖常见的扩展场景：\n\n| 工具类别 | 功能描述 |\n|----------|----------|\n| 搜索工具 | 集成 SearXNG、Google PSE、Brave Search 等搜索引擎 |\n| 知识库工具 | 支持知识库检索、文档问答 |\n| 计算工具 | 数学计算、公式求解 |\n| 代码执行 | 代码解释器执行 Python 代码 |\n| 图像生成 | 集成 DALL-E、Stable Diffusion 等图像生成服务 |\n\n## 前端集成\n\n### 工具管理界面\n\n前端工具管理组件位于 `src/lib/components/workspace/Tools.svelte`，提供以下功能：\n\n- **工具列表视图**：展示所有已注册工具，支持按名称、类型筛选\n- **工具详情面板**：查看工具描述、参数说明、使用示例\n- **工具调试控制台**：测试工具调用、查看执行结果\n- **工具创建向导**：引导用户创建自定义工具\n\n### 响应内容处理\n\n前端通过 `sanitizeResponseContent` 函数处理工具执行后的响应内容，确保内容安全展示：\n\n```typescript\nexport const sanitizeResponseContent = (content: string) => {\n\treturn content\n\t\t.replace(/<\\|[a-z]*$/, '')\n\t\t.replace(/<\\|[a-z]+\\|$/, '')\n\t\t.replace(/<$/, '')\n\t\t.replaceAll('<', '<')\n\t\t.replaceAll('>', '>')\n\t\t.replaceAll(/<\\|[a-z]+\\|>/g, ' ')\n\t\t.trim();\n};\n```\n资料来源：[src/lib/utils/index.ts]()\n\n## 中间件渲染\n\n### 工具输出渲染机制\n\n系统中间件负责将工具执行结果渲染为可展示的 HTML 格式，支持代码解释器等特殊工具类型：\n\n```python\nelif item_type == 'open_webui:code_interpreter':\n # 代码解释器需要检查/修改先前的累积内容\n # 去除尾部未闭合的代码块\n content = '\\n'.join(parts)\n content_stripped, original_whitespace = split_content_and_whitespace(content)\n if is_opening_code_block(content_stripped):\n content = content_stripped.rstrip('`').rstrip() + original_whitespace\n else:\n content = content_stripped + original_whitespace\n```\n资料来源：[backend/open_webui/utils/middleware.py]()\n\n### 渲染输出格式\n\n| 工具类型 | 渲染格式 | 说明 |\n|----------|----------|------|\n| 通用工具 | `` | 折叠面板展示 |\n| 代码解释器 | `` | 带执行状态 |\n| 思考过程 | `` | 显示思考耗时 |\n\n## 配置管理\n\n### 环境变量配置\n\n工具系统支持通过环境变量进行全局配置：\n\n| 变量名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `TOOLS_ENABLED` | bool | true | 启用/禁用工具系统 |\n| `TOOLS_LIMIT` | int | 10 | 单次对话最大工具调用数 |\n| `CODE_INTERPRETER_ENABLED` | bool | true | 启用代码解释器 |\n\n### 配置持久化\n\n工具配置通过 `PersistentConfig` 类实现持久化存储：\n\n```python\nTOOLS_ENABLED = PersistentConfig(\n 'TOOLS_ENABLED',\n 'tools.enabled',\n os.environ.get('TOOLS_ENABLED', 'True'),\n)\n```\n资料来源：[backend/open_webui/config.py]()\n\n## 安全机制\n\n### 权限控制\n\n工具系统集成基于角色的访问控制（RBAC）机制：\n\n- **管理员**：可创建、编辑、删除所有工具\n- **普通用户**：仅可使用已启用的工具\n- **访客**：无法使用工具功能\n\n### 代码执行沙箱\n\n代码解释器工具使用 RestrictedPython 库限制可执行的代码范围：\n\n```\nRestrictedPython==8.1\n```\n资料来源：[backend/requirements-min.txt]()\n\n## API 常量定义\n\n### 前端 API 端点配置\n\n| 常量名 | 值 | 用途 |\n|--------|-----|------|\n| `RETRIEVAL_API_BASE_URL` | `/api/v1/retrieval` | 检索工具 API |\n| `WEBUI_API_BASE_URL` | `/api/v1` | 通用 API 基础地址 |\n\n资料来源：[src/lib/constants.ts]()\n\n## 扩展开发指南\n\n### 创建自定义工具步骤\n\n1. **定义工具元数据**：在 `models/functions.py` 中添加函数定义\n2. **实现工具逻辑**：在 `tools/` 目录下创建工具实现文件\n3. **注册工具**：在 `tools/__init__.py` 中注册工具\n4. **挂载路由**：确保路由在 `routers/tools.py` 中可用\n5. **前端集成**：在 `Tools.svelte` 中添加工具管理界面\n\n### 工具接口规范\n\n所有自定义工具需遵循统一接口规范：\n\n```python\nclass BaseTool:\n name: str # 工具名称（唯一）\n description: str # 工具描述\n parameters: dict # JSON Schema 参数定义\n \n async def execute(self, **kwargs) -> dict:\n \"\"\"执行工具逻辑\"\"\"\n raise NotImplementedError\n```\n\n## 总结\n\nOpen WebUI 的工具与函数系统为平台提供了强大的扩展能力，通过标准化的 API 路由、数据模型和前端组件，实现了工具的注册、调用、管理全流程支持。系统架构清晰，安全机制完善，支持从内置工具到用户自定义工具的多种场景，是构建智能助手生态的重要基础设施。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：open-webui/open-webui\n\n摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:701547123 | https://github.com/open-webui/open-webui | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:701547123 | https://github.com/open-webui/open-webui | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:701547123 | https://github.com/open-webui/open-webui | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:701547123 | https://github.com/open-webui/open-webui | no_demo; severity=medium\n\n## 5. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:701547123 | https://github.com/open-webui/open-webui | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:701547123 | https://github.com/open-webui/open-webui | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：open-webui/open-webui\n\n摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:701547123 | https://github.com/open-webui/open-webui | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:701547123 | https://github.com/open-webui/open-webui | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:701547123 | https://github.com/open-webui/open-webui | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:701547123 | https://github.com/open-webui/open-webui | no_demo; severity=medium\n\n## 5. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:701547123 | https://github.com/open-webui/open-webui | issue_or_pr_quality=unknown\n\n## 6. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:701547123 | https://github.com/open-webui/open-webui | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# open-webui - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 open-webui 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: User-friendly AI Interface (Supports Ollama, OpenAI API, ...) 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 暂无明确的运行时能力线索。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. page-backend-routers：后端路由与 API。围绕“后端路由与 API”模拟一次用户任务，不展示安装或运行结果。\n4. page-backend-models：数据模型层。围绕“数据模型层”模拟一次用户任务，不展示安装或运行结果。\n5. page-auth-security：认证与安全。围绕“认证与安全”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-backend-routers\n输入：用户提供的“后端路由与 API”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-backend-models\n输入：用户提供的“数据模型层”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-auth-security\n输入：用户提供的“认证与安全”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-backend-routers：Step 3 必须围绕“后端路由与 API”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-backend-models：Step 4 必须围绕“数据模型层”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-auth-security：Step 5 必须围绕“认证与安全”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/open-webui/open-webui\n- https://github.com/open-webui/open-webui#readme\n- README.md\n- backend/open_webui/__init__.py\n- backend/open_webui/constants.py\n- backend/open_webui/main.py\n- backend/open_webui/config.py\n- backend/open_webui/socket/main.py\n- src/app.html\n- svelte.config.js\n- backend/open_webui/routers/chats.py\n- backend/open_webui/routers/auths.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 open-webui 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：open-webui/open-webui\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install open-webui\n```\n\n来源：https://github.com/open-webui/open-webui#readme\n\n## 来源\n\n- repo: https://github.com/open-webui/open-webui\n- docs: https://github.com/open-webui/open-webui#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_e2f0e782f2844612b65d669f75051cd6"
}