13.4 · 模型配置与访问（Model Configuration and Access）

多模型对话工作台与知识应用入口 · 本章是 Open WebUI DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Open WebUI 章节13.4 状态全文译文模块工具、记忆与模型调用、界面与交互、检索、召回与知识系统、接口与服务契约

项目要点页2.5 参考项目项目章节目录Open WebUI DeepWiki 原始章节Model Configuration and Access 上一章13.3 下一章13.5

源码线索

backend/open_webui/models/models.py
backend/open_webui/routers/models.py
backend/open_webui/routers/prompts.py
backend/open_webui/routers/tools.py
src/lib/apis/knowledge/index.ts
src/lib/apis/models/index.ts
src/lib/components/admin/Settings/Evaluations/ArenaModelModal.svelte
src/lib/components/admin/Settings/Evaluations/Model.svelte
src/lib/components/chat/Settings/Advanced/AdvancedParams.svelte
src/lib/components/chat/Settings/General.svelte

模块标签

工具、记忆与模型调用
界面与交互
检索、召回与知识系统
接口与服务契约
可观测性与治理

中文译文

模型配置与访问（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/13.4-model-configuration-and-access

翻译时间：2026-06-09T16:11:20.305Z

翻译模型：deepseek-chat

原文字符数：13772

项目：Open WebUI (open-webui)

---

模型配置与访问

配置存储架构

Open WebUI 使用双层配置系统管理模型设置：全局配置和按用户访问控制。

PersistentConfig 模式

模型配置设置通过 PersistentConfig 系统管理，该系统优先使用数据库存储的值而非环境变量。这使得管理员可以通过管理界面在运行时修改设置。

标题：PersistentConfig 数据流

graph TB
    EnvVars["环境变量<br/>(DEFAULT_MODELS 等)"]
    DBConfig["数据库配置表<br/>config.data JSON"]
    Redis["Redis 缓存<br/>config:* 键"]

    PersistentConfig["PersistentConfig&lt;T&gt;<br/>env_name, config_path"]
    EnvValue["env_value: T"]
    DBValue["config_value: T"]
    FinalValue["value: T<br/>(DB > Env 优先级)"]

    AppConfig["AppConfig 单例<br/>request.app.state.config"]

    EnvVars --> EnvValue
    DBConfig --> DBValue

    EnvValue --> FinalValue
    DBValue --> FinalValue
    FinalValue --> PersistentConfig

    PersistentConfig --> AppConfig
    AppConfig -->|写入| DBConfig
    AppConfig -->|写入| Redis
    AppConfig -->|读取| Redis

    AdminUI["管理设置界面<br/>Settings Modal"] -->|更新| AppConfig
    APIEndpoints["API 端点<br/>/models, /chat"] -->|读取| AppConfig

全局模型配置设置

以下设置存储在 AppConfig 中，并在重启后持续生效：

设置项	配置路径	用途
`DEFAULT_MODELS`	`ui.default_models`	向新用户展示的模型
`DEFAULT_PINNED_MODELS`	`ui.default_pinned_models`	在选择界面中固定的模型
`MODEL_ORDER_LIST`	`ui.model_order_list`	自定义模型显示顺序
`ENABLE_BASE_MODELS_CACHE`	`models.enable_base_models_cache`	启动时缓存模型列表

来源：backend/open_webui/config.py，src/lib/components/admin/Settings/General.svelte

模型访问控制系统

模型访问在多个层级上受到控制：全局绕过标志、按用户访问列表，以及存储在模型定义中的细粒度 access_grants。

访问授权架构

现代访问控制系统使用 AccessGrant 对象来定义特定用户或组的权限。

标题：访问控制实体关系

classDiagram
    class AccessGrant {
        +string id
        +string principal_type ("user" | "group")
        +string principal_id
        +string permission ("read" | "write")
    }

    class ModelModel {
        +string id
        +string user_id
        +AccessGrant[] access_grants
        +ModelMeta meta
        +ModelParams params
    }

    class ModelMeta {
        +dict capabilities
        +string[] toolIds
        +string[] filterIds
        +Knowledge[] knowledge
    }

    ModelModel "1" *-- "many" AccessGrant
    ModelModel "1" *-- "1" ModelMeta

访问控制逻辑

AccessControl.svelte 组件管理将传统访问控制列表转换为新授权系统的逻辑 src/lib/components/workspace/common/AccessControl.svelte:17-27。

公开访问：通过 principal_type 为 user、principal_id 为 *、permission 为 read 的授权表示 src/lib/components/workspace/common/AccessControl.svelte:157-161。
去重：通过 dedupeAccessGrants 基于类型、ID 和权限的组合键对授权进行去重 src/lib/components/workspace/common/AccessControl.svelte:46-61。

来源：src/lib/components/workspace/common/AccessControl.svelte:17-61，backend/open_webui/models/models.py:100-116

模型访问控制流程

当用户请求模型列表时，后端通过 get_models 路由器执行访问检查 backend/open_webui/routers/models.py:90-161。

标题：模型访问验证流程

graph TD
    UserRequest[("用户请求：GET /models/list")] --> GetVerifiedUser["get_verified_user(request)"]
    GetVerifiedUser --> GetUserGroups["Groups.get_groups_by_member_id(user.id)"]
    GetUserGroups --> SearchModels["Models.search_models(...)"]
    SearchModels --> FilterModelsByAccess["遍历模型"]

    subgraph "每个模型的访问检查"
        ModelLoop["模型实体"]
        IsAdmin["user.role == 'admin' AND BYPASS_ADMIN_ACCESS_CONTROL"]
        IsOwner["user.id == model.user_id"]
        HasWriteAccess["AccessGrants.get_accessible_resource_ids(...)"]

        ModelLoop --> IsAdmin
        ModelLoop --> IsOwner
        ModelLoop --> HasWriteAccess

        IsAdmin -- 或 --> ModelAccessible["模型可访问"]
        IsOwner -- 或 --> ModelAccessible
        HasWriteAccess -- 或 --> ModelAccessible
    end

    FilterModelsByAccess --> ModelLoop
    ModelAccessible --> ReturnModel["向响应添加 write_access 标志"]
    ReturnModel --> ModelAccessListResponse["ModelAccessListResponse"]

通过 get_verified_user 获取已验证用户 backend/open_webui/routers/models.py:98。
使用 Groups.get_groups_by_member_id 获取用户的组成员身份 backend/open_webui/routers/models.py:119。
Models.search_models 检索记录，如果 BYPASS_ADMIN_ACCESS_CONTROL 为 false，则应用用户特定过滤器 backend/open_webui/routers/models.py:122-128。
系统使用 AccessGrants.get_accessible_resource_ids 批量获取可写 ID backend/open_webui/routers/models.py:132-139。
最终的 ModelAccessResponse 包含基于所有权、管理员状态或显式授权的 write_access 布尔值 backend/open_webui/routers/models.py:143-156。

来源：backend/open_webui/routers/models.py:90-161，backend/open_webui/models/models.py:246-280

工作区模型配置

ModelEditor.svelte 组件是配置特定模型实例的主要界面。它允许管理员和模型所有者定义系统提示、参数覆盖和能力标志 src/lib/components/workspace/Models/ModelEditor.svelte:1-32。

关键配置字段

字段	代码实体	描述
系统提示	`info.params.system`	模型的全局系统指令 `src/lib/components/workspace/Models/ModelEditor.svelte:231`。
停止序列	`info.params.stop`	触发生成终止的令牌 `src/lib/components/workspace/Models/ModelEditor.svelte:232-236`。
能力	`info.meta.capabilities`	`vision`、`citations` 等标志 `src/lib/components/workspace/Models/ModelEditor.svelte:139`。
访问授权	`info.access_grants`	模型的细粒度权限 `src/lib/components/workspace/Models/ModelEditor.svelte:138`。
知识库	`info.meta.knowledge`	关联的知识库/文件 `src/lib/components/workspace/Models/ModelEditor.svelte:147-153`。

来源：src/lib/components/workspace/Models/ModelEditor.svelte:109-247，backend/open_webui/models/models.py:31-62

能力标志与特性

模型可以配置特定能力，这些能力会改变 UI 与模型的交互方式。这些能力通过 Capabilities.svelte 组件管理，并存储在 ModelMeta 中。

能力标志

标志	影响
`vision`	启用图像上传和多模态处理。
`citations`	表示模型为 RAG 提供来源引用。
`tools`	启用函数调用能力。

来源：src/lib/components/workspace/Models/ModelEditor.svelte:139，src/lib/components/workspace/Models/Capabilities.svelte

高级参数

AdvancedParams.svelte 组件允许用户和管理员覆盖模型的各类生成参数。这些参数直接影响模型的输出行为 src/lib/components/chat/Settings/Advanced/AdvancedParams.svelte:15-48。

标题：高级参数层级

graph TD
    ModelEditor["ModelEditor.svelte"] --> AdvancedParams["AdvancedParams.svelte"]
    GeneralSettings["General.svelte (用户设置)"] --> AdvancedParams

    AdvancedParams --> StreamResponse["stream_response"]
    AdvancedParams --> StreamDelta["stream_delta_chunk_size"]
    AdvancedParams --> FuncCall["function_calling: 'native' | null"]
    AdvancedParams --> ReasonTags["reasoning_tags: bool | string[]"]
    AdvancedParams --> Sampling["采样：temp, top_p, top_k, min_p"]
    AdvancedParams --> Penalties["惩罚：freq, presence, repeat"]
    AdvancedParams --> Resource["资源：num_ctx, num_gpu, num_thread"]

关键参数及其效果：

stream_response：控制实时响应生成 src/lib/components/chat/Settings/Advanced/AdvancedParams.svelte:72-88。
stream_delta_chunk_size：定义文本传输的块大小 src/lib/components/chat/Settings/Advanced/AdvancedParams.svelte:110-119。
function_calling：确定工具调用的方式，可以是 'native' 或 'default' src/lib/components/chat/Settings/Advanced/AdvancedParams.svelte:165-174。
reasoning_tags：自定义模型推理的开始/结束标签（例如 <thought>）src/lib/components/chat/Settings/Advanced/AdvancedParams.svelte:194-215。
num_ctx：设置上下文窗口大小 src/lib/components/chat/Settings/General.svelte:94。

这些参数在发送给提供方之前，会从全局默认值、模型特定覆盖值和用户会话设置中合并 src/lib/components/chat/Settings/General.svelte:70-108。

来源：src/lib/components/chat/Settings/Advanced/AdvancedParams.svelte:15-48，src/lib/components/chat/Settings/General.svelte:42-68，src/lib/components/workspace/Models/ModelEditor.svelte:89-91

知识库集成

模型可以与特定知识库关联。Knowledge.svelte 组件管理模型文件的选择和上传 src/lib/components/workspace/Models/Knowledge.svelte:1-15。

选择：用户可以从工作区选择现有知识库 src/lib/components/workspace/Models/Knowledge.svelte:194-213。
上传：文件可以直接上传到模型，通过 uploadFile 触发自动内容提取 src/lib/components/workspace/Models/Knowledge.svelte:27-97。
存储：知识关联存储在 info.meta.knowledge 中 src/lib/components/workspace/Models/ModelEditor.svelte:148。

来源：src/lib/components/workspace/Models/Knowledge.svelte:27-132，src/lib/components/workspace/Models/ModelEditor.svelte:147-153

访问授权管理 API

模型访问可以通过 updateModelAccessGrants 函数以编程方式更新，该函数与 /models/model/access/update 端点交互 src/lib/apis/models/index.ts:290-322。

export const updateModelAccessGrants = async (
	token: string,
	id: string,
	name: string,
	accessGrants: any[]
) => {
    // 向 ${WEBUI_API_BASE_URL}/models/model/access/update 发送 POST 请求
};

这在 ModelEditor 中应用来自 AccessControlModal 的更改时使用 src/lib/components/workspace/Models/ModelEditor.svelte:31。

来源：src/lib/apis/models/index.ts:290-322，src/lib/components/workspace/Models/ModelEditor.svelte:31