agentic_huge_data_base / wiki
页面 Onyx · 6.4 大模型提供方访问控制·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 6.4

6.4 · 大模型提供方访问控制（Access Control for LLM Providers）

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目Onyx 章节6.4 状态全文译文 模块测试、发布与运维、界面与交互、接口与服务契约、模型调用与提供方适配
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节Access Control for LLM Providers 上一章6.3 下一章7
源码线索
  • backend/alembic/versions/f0db5f1c6370_optional_llm_provider_name.py
  • backend/ee/onyx/server/seeding.py
  • backend/ee/onyx/server/tenants/provisioning.py
  • backend/onyx/db/llm.py
  • backend/onyx/llm/factory.py
  • backend/onyx/llm/utils.py
  • backend/onyx/llm/well_known_providers/auto_update_service.py
  • backend/onyx/server/manage/image_generation/models.py
  • backend/onyx/server/manage/llm/api.py
  • backend/onyx/server/manage/llm/models.py
模块标签
  • 测试、发布与运维
  • 界面与交互
  • 接口与服务契约
  • 模型调用与提供方适配
  • 系统架构

章节正文

大模型提供方访问控制

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/6.4-access-control-for-llm-providers

大语言模型（LLM）提供商的访问控制

相关源文件

以下文件为本维基页面的生成提供了上下文：

  • backend/alembic/versions/f0db5f1c6370_optional_llm_provider_name.py
  • backend/ee/onyx/server/seeding.py
  • backend/ee/onyx/server/tenants/provisioning.py
  • backend/onyx/db/llm.py
  • backend/onyx/llm/factory.py
  • backend/onyx/llm/utils.py
  • backend/onyx/llm/well_known_providers/auto_update_service.py
  • backend/onyx/server/manage/image_generation/models.py
  • backend/onyx/server/manage/llm/api.py
  • backend/onyx/server/manage/llm/models.py
  • backend/tests/external_dependency_unit/llm/test_llm_provider.py
  • backend/tests/external_dependency_unit/llm/test_llm_provider_auto_mode.py
  • backend/tests/external_dependency_unit/llm/test_llm_provider_default_model_protection.py
  • backend/tests/integration/tests/llm_provider/test_llm_provider.py
  • backend/tests/unit/onyx/llm/test_model_map.py
  • backend/tests/unit/onyx/llm/test_token_limit_lookups.py
  • web/src/app/craft/components/BuildLLMPopover.tsx
  • web/src/app/css/line-item.css
  • web/src/components/llm/LLMSelector.tsx
  • web/src/hooks/useMultiModelChat.ts
  • web/src/refresh-components/SimplePopover.tsx
  • web/src/refresh-components/buttons/AttachmentButton.tsx
  • web/src/refresh-components/buttons/LineItem.tsx
  • web/src/refresh-components/popovers/ActionsPopover/ActionLineItem.tsx
  • web/src/refresh-components/popovers/ActionsPopover/SwitchList.tsx
  • web/src/refresh-components/popovers/ActionsPopover/index.tsx
  • web/src/refresh-components/popovers/FilePickerPopover.tsx
  • web/src/refresh-components/popovers/LLMPopover.tsx
  • web/src/refresh-components/popovers/ModelListContent.tsx
  • web/src/refresh-components/popovers/ModelSelector.tsx

本文档说明了 Onyx 中大语言模型（LLM）提供商访问控制的技术实现。访问权限通过全局可见性标志、用户组成员身份（企业版）以及特定 Persona（角色）限制的组合方式进行管理。

提供商访问逻辑概述

对大语言模型（LLM）提供商的访问并非简单的二元开关。系统会根据用户的角色、所属的组以及请求所使用的特定 Persona（助手）来评估访问权限。

判断用户能否使用特定大语言模型（LLM）提供商的核心逻辑实现在 can_user_access_llm_provider 函数中 backend/onyx/db/llm.py:101-147。

访问决策矩阵

以下逻辑按顺序应用：

  1. Persona 限制：当设置了 Persona 限制时，该限制始终生效，不受 is_public 标志影响。如果某个提供商被限制为仅特定 Persona 可用，则用户必须使用这些白名单中的 Persona 才能访问该提供商 backend/onyx/db/llm.py:136-138。
  2. 公共访问：如果提供商标记为 is_public，则所有用户均可访问（前提是通过 Persona 检查）backend/onyx/db/llm.py:140-141。
  3. 组访问：如果不是公共访问，则用户必须是管理员（可绕过组检查）或属于已被授予该提供商访问权限的 UserGroup backend/onyx/db/llm.py:143-144。
  4. 仅限管理员：如果未配置任何组或 Persona，且不是公共访问，则该提供商实际上"锁定"为仅管理员可用 backend/onyx/db/llm.py:146-147。

来源：backend/onyx/db/llm.py:101-147，backend/onyx/server/manage/llm/models.py:93-105

技术实现

数据模型

访问控制依赖于 PostgreSQL 数据库中的多个关系表：

  • LLMProvider：包含 is_public 标志的主实体 backend/onyx/db/models.py:13。
  • LLMProvider__UserGroup：将提供商与特定用户组关联的连接表 backend/onyx/db/llm.py:15。
  • LLMProvider__Persona：将提供商与特定 Persona 关联的连接表 backend/onyx/db/llm.py:14。
关键代码实体
实体位置角色
can_user_access_llm_providerbackend/onyx/db/llm.py访问验证的核心布尔逻辑。
get_llm_for_personabackend/onyx/llm/factory.py编排大语言模型（LLM）实例化，同时通过 can_user_access_llm_provider 检查用户/Persona 权限。
LLMProviderDescriptorbackend/onyx/server/manage/llm/models.py面向非管理员用户的提供商"安全"视图，隐藏敏感凭证。
useLLMProvidersweb/src/hooks/useLanguageModels.ts前端钩子，根据 personaId 获取过滤后的提供商列表。
fetch_user_group_idsbackend/onyx/db/llm.py检索特定用户组成员身份的工具函数。

来源：backend/onyx/db/llm.py:79-98，backend/onyx/db/llm.py:101-147，backend/onyx/llm/factory.py:131-194，backend/onyx/server/manage/llm/models.py:59-91，web/src/refresh-components/popovers/ActionsPopover/index.tsx:33-33

自然语言到代码实体的映射

以下图表将高级访问概念桥接到具体的代码实现。

提供商请求流程

此图展示了聊天请求在调用大语言模型（LLM）之前如何验证提供商访问权限。

Onyx · 提供商请求流程 · 图 1
Onyx · 提供商请求流程 · 图 1

来源：backend/onyx/llm/factory.py:131-194，backend/onyx/db/llm.py:101-147，backend/onyx/llm/factory.py:189-194

访问控制逻辑层次

此图展示了 can_user_access_llm_provider 的内部逻辑。

Onyx · 访问控制逻辑层次 · 图 2
Onyx · 访问控制逻辑层次 · 图 2

来源：backend/onyx/db/llm.py:101-147，backend/onyx/server/manage/llm/models.py:93-106

前端和 API 过滤

应用程序使用特定的钩子和组件来确保用户只能看到他们被授权使用的模型。

useLLMProviders 钩子

useLLMProviders 钩子用于 ActionsPopover 等组件，以过滤特定助手的可用提供商 web/src/refresh-components/popovers/ActionsPopover/index.tsx:175-177。

管理员与用户数据模型
  1. 管理员 UI：管理员与 LLMProviderView 交互。这包括完整配置、未掩码或掩码的 api_key 以及详细的组/Persona 分配 backend/onyx/server/manage/llm/models.py:122-170。
  2. 标准用户 UI：用户接收 LLMProviderDescriptor，其中仅包含显示名称和模型配置，省略了所有敏感配置和凭证 ID backend/onyx/server/manage/llm/models.py:59-91。
模型选择 UI

LLMSelector 和 LLMPopover 组件负责处理和选择授权模型。LLMSelector 按提供商实例对选项进行分组，以便同一提供商类型的多个配置（例如两个不同的 OpenAI 密钥）显示为不同的组 web/src/components/llm/LLMSelector.tsx:117-146。

来源：backend/onyx/server/manage/llm/models.py:59-91，backend/onyx/server/manage/llm/models.py:122-170，web/src/components/llm/LLMSelector.tsx:117-146，web/src/refresh-components/popovers/LLMPopover.tsx:140-157

校验与安全

API 密钥解析与掩码

编辑现有提供商时，API 密钥在 UI 中会被掩码处理 backend/onyx/server/manage/llm/api.py:116-120。_resolve_api_key 函数确保如果用户未修改掩码值，则会从数据库中检索原始的未掩码密钥，用于模型获取或验证请求 backend/onyx/server/manage/llm/api.py:123-156。

模型配置校验

通过 LLMProviderUpsertRequest 更新提供商时，系统会校验请求的模型配置。这包括解析模型名称以确定其能力，例如是否支持图像或推理 backend/onyx/server/manage/llm/models.py:107-120，backend/tests/integration/tests/llm_provider/test_llm_provider.py:44-78。

Persona 与组管理

管理员可以使用 update_group_llm_provider_relationships__no_commit 和 update_llm_provider_persona_relationships__no_commit 将提供商限制到特定组或 Persona。这些函数会在事务内替换现有限制，以确保原子性更新 backend/onyx/db/llm.py:35-77。

来源：backend/onyx/server/manage/llm/api.py:123-156，backend/onyx/db/llm.py:35-77，backend/onyx/server/manage/llm/models.py:107-120，backend/tests/integration/tests/llm_provider/test_llm_provider.py:44-78