agentic_huge_data_base / wiki
页面 Onyx · 6 大模型提供方管理·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 6

6 · 大模型提供方管理（LLM Provider Management）

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

项目Onyx 章节6 状态全文译文 模块接口与服务契约、模型调用与提供方适配、系统架构、测试、发布与运维
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节LLM Provider Management 上一章5.4 下一章6.1
源码线索
  • backend/alembic/versions/f0db5f1c6370_optional_llm_provider_name.py
  • backend/ee/onyx/server/seeding.py
  • backend/ee/onyx/server/tenants/provisioning.py
  • backend/onyx/configs/model_configs.py
  • backend/onyx/db/llm.py
  • backend/onyx/llm/constants.py
  • backend/onyx/llm/factory.py
  • backend/onyx/llm/models.py
  • backend/onyx/llm/multi_llm.py
  • backend/onyx/llm/utils.py
模块标签
  • 接口与服务契约
  • 模型调用与提供方适配
  • 系统架构
  • 测试、发布与运维
  • 界面与交互

章节正文

大模型提供方管理

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/6-llm-provider-management

大语言模型（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/configs/model_configs.py
  • backend/onyx/db/llm.py
  • backend/onyx/llm/constants.py
  • backend/onyx/llm/factory.py
  • backend/onyx/llm/models.py
  • backend/onyx/llm/multi_llm.py
  • backend/onyx/llm/utils.py
  • backend/onyx/llm/well_known_providers/auto_update_service.py
  • backend/onyx/llm/well_known_providers/constants.py
  • backend/onyx/llm/well_known_providers/llm_provider_options.py
  • backend/onyx/server/manage/image_generation/models.py
  • backend/onyx/server/manage/llm/api.py
  • backend/onyx/server/manage/llm/models.py
  • backend/onyx/server/manage/llm/utils.py
  • backend/tests/external_dependency_unit/llm/test_llm_provider.py
  • backend/tests/external_dependency_unit/llm/test_llm_provider_api_base.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/integration/tests/llm_provider/test_llm_provider_persona_access.py
  • backend/tests/unit/onyx/db/test_llm_sync.py
  • backend/tests/unit/onyx/llm/test_model_map.py
  • backend/tests/unit/onyx/llm/test_multi_llm.py
  • backend/tests/unit/onyx/llm/test_token_limit_lookups.py
  • backend/tests/unit/onyx/server/manage/llm/test_fetch_models_api.py
  • backend/tests/unit/onyx/server/manage/llm/test_llm_provider_utils.py
  • web/src/sections/modals/languageModels/VertexAIModal.tsx
  • web/src/sections/modals/languageModels/shared.tsx

本文档描述了在 Onyx 中配置和管理多个大语言模型（LLM）提供商的系统。该系统使管理员能够配置 OpenAI、Anthropic、AWS Bedrock、Google Vertex AI、Ollama 和 OpenRouter 等提供商，每个提供商都有自己的认证方式、模型列表和能力。系统还根据用户偏好、助手配置和会话状态，在运行时决定使用哪个大语言模型。

关于聊天会话中大语言模型的使用方式，请参见聊天与会话系统。关于配置具有特定大语言模型偏好的助手，请参见AI 助手与角色（Persona）。

架构总览

大语言模型提供商管理系统将管理配置与运行时大语言模型选择连接起来。管理员通过管理界面配置提供商，系统将凭证和模型配置存储在 PostgreSQL 中。在运行时，前端的 useLlmManager 钩子和后端的 get_llm_for_persona 工厂根据覆盖层级决定使用哪个提供商和模型。

大语言模型提供商管理架构

Onyx · 架构总览 · 图 1
Onyx · 架构总览 · 图 1

来源：backend/onyx/server/manage/llm/api.py:112-113, backend/onyx/llm/factory.py:131-136, backend/onyx/db/llm.py:101-106, backend/onyx/llm/multi_llm.py:26-26

数据库模式

大语言模型提供商系统使用数据库模型来存储配置和访问控制信息。

表名关键列用途
LLMProviderid, name, provider, api_key, api_base, api_version, is_public, custom_config存储提供商级别的配置，包括凭证和元数据。backend/onyx/db/models.py:13-13
ModelConfigurationid, llm_provider_id, name, is_visible, max_input_tokens, supports_image_input存储每个提供商下每个模型的设置。backend/onyx/db/models.py:16-16
LLMProvider__UserGroupllm_provider_id, user_group_id将提供商映射到用户组，用于访问控制。backend/onyx/db/llm.py:41-43
LLMProvider__Personallm_provider_id, persona_id限制哪些助手可以使用特定提供商。backend/onyx/db/llm.py:63-67

custom_config 字段存储提供商特定的配置，例如 Bedrock 的 AWS 区域或 Vertex AI 的凭证。敏感密钥（如 api_key）在通过 API 返回时会使用 _mask_string 进行掩码处理。backend/onyx/server/manage/llm/api.py:116-121

提供商配置

详情请参见提供商配置。

Onyx 通过统一接口支持多个大语言模型提供商。管理员可以配置知名提供商（OpenAI、Anthropic、Azure、Bedrock、Vertex AI、Ollama、OpenRouter）或通用的 LiteLLM 兼容提供商。

  • 凭证：API 密钥和基础 URL 会安全存储。_resolve_api_key 通过比较标准化后的基础 URL 来处理模型获取请求中的密钥解掩码。backend/onyx/server/manage/llm/api.py:123-150
  • 模型列表：管理员通过 ModelConfigurationUpsertRequest 选择提供商中哪些模型应对用户可见。backend/onyx/server/manage/llm/models.py:172-178
  • 自定义配置：基于 JSON 的配置，用于满足提供商特定需求（例如 LM_STUDIO_API_KEY_CONFIG_KEY 或 VERTEX_PROJECT_KWARG）。backend/onyx/llm/multi_llm.py:46-55

来源：backend/onyx/server/manage/llm/api.py:123-156, backend/onyx/server/manage/llm/models.py:107-114, backend/onyx/llm/factory.py:26-28, backend/onyx/llm/multi_llm.py:46-52

模型选择层级

详情请参见模型选择层级。

当用户与 Onyx 交互时，系统根据 get_llm_for_persona 中定义的优先级确定要使用的具体模型：

  1. 大语言模型覆盖：通过 LLMOverride 在聊天界面中显式选择（包括提供商、模型版本和温度参数）。backend/onyx/llm/factory.py:146-148
  2. 角色覆盖：专门链接到 AI 助手的模型配置（persona.default_model_configuration_id）。backend/onyx/llm/factory.py:112-115
  3. 系统默认：管理员通过 get_default_llm 配置的全局默认值。backend/onyx/llm/factory.py:151-155

来源：backend/onyx/llm/factory.py:131-168, backend/onyx/db/llm.py:25-26, backend/onyx/llm/override_models.py:23-23

模型能力与要求

详情请参见模型能力与要求。

Onyx 会动态检测和验证模型特性，以确保与系统操作的兼容性：

  • 动态发现：诸如 fetch_available_well_known_llms 和提供商特定的获取器（例如 fetch_llm_recommendations_from_github）等工具会查询提供商定义。backend/onyx/server/manage/llm/api.py:55-57, backend/onyx/server/manage/llm/api.py:64-66
  • 特性支持：系统会跟踪 supports_image_input（视觉能力）、supports_reasoning 和工具调用能力。使用 infer_vision_support 和 model_is_reasoning_model 对模型进行分类。backend/onyx/server/manage/llm/utils.py:100-102, backend/onyx/llm/multi_llm.py:32-32
  • Token 限制：通过 max_input_tokens 管理上下文窗口。系统使用 get_max_input_tokens_from_llm_provider 来确定特定模型/提供商组合的有效限制。backend/onyx/llm/factory.py:24-24, backend/onyx/llm/utils.py:17-18

来源：backend/onyx/server/manage/llm/api.py:55-60, backend/onyx/server/manage/llm/utils.py:97-112, backend/onyx/llm/factory.py:63-70, backend/onyx/llm/utils.py:16-18

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

详情请参见大语言模型提供商的访问控制。

对大语言模型提供商的访问由 can_user_access_llm_provider 中的可见性和权限规则控制：

  • 公开与私有：标记为 is_public 的提供商对所有用户可用，除非受角色限制。backend/onyx/db/llm.py:140-141
  • 组限制：提供商可以限制为仅特定 UserGroups 可用。用户必须是允许组中的成员才能访问该提供商。backend/onyx/db/llm.py:143-144
  • 角色过滤：管理员可以限制特定助手（角色）仅使用可用大语言模型提供商的子集。如果提供商有受限的角色，则只有这些角色可以使用它。backend/onyx/db/llm.py:137-138
  • 管理员绕过：管理员（角色 UserRole.ADMIN）可以绕过用户组限制，但仍需遵守角色级别的白名单。backend/onyx/db/llm.py:144-144

来源：backend/onyx/db/llm.py:101-148, backend/onyx/db/llm.py:35-55, backend/onyx/server/manage/llm/api.py:18-20

错误处理与分类

系统使用 litellm_exception_to_error_msg 将原始提供商错误映射为用户友好的消息和分类错误代码（例如 AUTH_ERROR、RATE_LIMIT_ERROR、CONTEXT_WINDOW_EXCEEDED）。它会处理嵌套异常，并允许使用 LITELLM_CUSTOM_ERROR_MESSAGE_MAPPINGS 中定义的自定义错误消息映射。backend/onyx/llm/utils.py:134-172

来源：backend/onyx/llm/utils.py:134-200, backend/onyx/configs/app_configs.py:12-12