agentic_huge_data_base / wiki
页面 Onyx · 6.2 模型选择层级·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 6.2

6.2 · 模型选择层级（Model Selection Hierarchy）

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

项目Onyx 章节6.2 状态全文译文 模块模型调用与提供方适配、系统架构、测试、发布与运维、接口与服务契约
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节Model Selection Hierarchy 上一章6.1 下一章6.3
源码线索
  • 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.2-model-selection-hierarchy

模型选择层级

相关源文件

本章引用的主要源码文件：

  • 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）的优先级系统。该选择层级允许用户在多个层级上覆盖模型设置，同时保持合理的默认值。这套逻辑确保专用助手使用其优化后的模型，同时允许高级用户尝试不同的后端。

选择层级总览

Onyx 通过一个五级优先级系统来解析当前活跃的 LLM 模型，按优先级从高到低依次评估。解析逻辑主要在前端的 useLlmManager 钩子和后端的 get_llm_for_persona 工厂中实现。

  1. 用户手动覆盖：通过聊天输入界面显式选择的模型。
  2. 聊天会话覆盖：锁定到特定现有聊天会话的模型选择。
  3. 助手（Persona）覆盖：在助手配置中定义的模型。
  4. 用户偏好：用户在其个人资料中设置的个人默认模型。
  5. 系统默认：全局默认提供商的默认模型。

模型选择逻辑流程

Onyx · 选择层级总览 · 图 1
Onyx · 选择层级总览 · 图 1

来源： backend/onyx/llm/factory.py:131-154, backend/onyx/llm/factory.py:156-194, web/src/lib/hooks.ts:542-636

优先级层级详情

层级 1：用户手动覆盖

最高优先级是用户在当前聊天会话界面中显式选择的模型。这由 ModelSelector 组件处理。

  • 实现方式：由前端状态中的 userHasManuallyOverriddenLLM 布尔标志管理。
  • 行为：当用户从下拉菜单中选择模型时，此标志变为 true，所选模型在当前交互期间持续生效，直到助手被更改。

来源： web/src/lib/hooks.ts:564-565, backend/onyx/llm/factory.py:146-148

层级 2：聊天会话覆盖

如果用户返回到现有对话，Onyx 会尝试使用该特定会话之前活跃的模型。

  • 数据模型：存储在 ChatSession 数据库实体中。
  • 字段：current_alternate_model。
  • 上下文：这确保了消息线程内的一致性，防止同一历史记录中消息之间出现意外行为变化。

来源： web/src/lib/hooks.ts:606-609, backend/onyx/llm/factory.py:131-141

层级 3：助手（Persona）覆盖

管理员可以为助手（Persona）配置特定模型，使其更适合其任务（例如，"创意写作助手"使用 Claude 3.5 Opus，而"代码助手"使用 GPT-4o）。

  • 逻辑：如果 Persona 对象设置了 default_model_configuration_id，它会指向一个与 LLMProvider 关联的 ModelConfiguration 条目。
  • 解析：后端的 _resolve_provider_and_model 函数会获取与此 ID 关联的提供商和模型名称。

助手模型解析

Onyx · 层级 3：助手（Persona）覆盖 · 图 2
Onyx · 层级 3：助手（Persona）覆盖 · 图 2

来源： backend/onyx/onyx/llm/factory.py:87-129, backend/onyx/db/llm.py:165-179

层级 4：用户偏好

用户可以在其账户设置中定义自己的默认模型。如果助手没有特定的模型要求，则会使用此设置。

  • 实现方式：存储在 User 模型的 preferences JSON 字段中，键为 default_model。

来源： web/src/lib/hooks.ts:618-619

层级 5：系统默认

最终的降级方案是系统管理员配置的全局默认 LLM 提供商。

  • 配置：通过 fetch_default_llm_model 函数设置，该函数查询数据库中被标记为默认的提供商。
  • 默认模型：使用与该提供商关联的主要模型配置。

来源： backend/onyx/db/llm.py:25-26, backend/onyx/llm/factory.py:197-205

技术实现

LLM 工厂与多 LLM 包装器

后端使用 LitellmLLM（一个围绕 LiteLLM 的包装器）来与各种提供商交互。选择层级最终会生成一个由 llm_from_provider 产生的 LLM 接口实例。

代码实体映射

Onyx · LLM 工厂与多 LLM 包装器 · 图 3
Onyx · LLM 工厂与多 LLM 包装器 · 图 3

来源： backend/onyx/llm/factory.py:131-194, backend/onyx/llm/multi_llm.py:95-106, backend/onyx/llm/models.py:112-116

能力与推理努力度

选择模型时，Onyx 还会解析特定能力，例如支持"思考"的模型（如 OpenAI o1、Claude 3.7）的推理努力度。

  • 推理级别：AUTO、OFF、LOW、MEDIUM、HIGH。
  • 提供商映射：
  • OpenAI：通过 OPENAI_REASONING_EFFORT 直接映射到 reasoning_effort。
  • Anthropic：通过 ANTHROPIC_REASONING_EFFORT_BUDGET 映射到 budget_tokens。
  • 自适应推理：较新的模型（如 Claude 4.7）使用 ANTHROPIC_ADAPTIVE_REASONING_EFFORT 映射到 output_config.effort。

来源： backend/onyx/llm/models.py:13-56, backend/onyx/llm/multi_llm.py:77-92

在 LiteLLM 包装器中的实现

LitellmLLM 类处理消息和工具配置的最终转换。它使用 _strip_tool_content_from_messages 来确保在工具调用被禁用或当前请求不支持时，与 Bedrock 等提供商兼容。

来源： backend/onyx/llm/multi_llm.py:136-182, backend/onyx/llm/multi_llm.py:22-26