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

模型选择层级（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/onyx-dot-app/onyx/6.2-model-selection-hierarchy

翻译时间：2026-05-27T08:44:47.999Z

翻译模型：deepseek-chat

原文字符数：11407

项目：Onyx (onyx)

---

模型选择层级

相关源文件

以下文件被用作生成此维基页面的上下文：

• 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. 系统默认：全局默认提供商的默认模型。

模型选择逻辑流程

graph TD
    Request["用户请求（聊天/查询）"]

    CheckUserOverride{"用户手动<br/>覆盖已设置？"}
    CheckSession{"聊天会话<br/>current_alternate_model？"}
    CheckAssistant{"Persona<br/>default_model_configuration_id？"}
    CheckUserPref{"用户偏好<br/>default_model？"}
    CheckSystemDefault{"系统默认<br/>提供商已配置？"}

    UseUserOverride["使用手动覆盖<br/>（本地状态）"]
    UseSession["使用聊天会话模型<br/>（数据库：ChatSession）"]
    UseAssistant["使用助手模型<br/>（数据库：Persona）"]
    UseUserPref["使用用户偏好<br/>（数据库：User）"]
    UseSystemDefault["使用系统默认<br/>（数据库：LLMProvider）"]
    Fail["请求失败<br/>（未找到模型）"]

    Request --> CheckUserOverride
    CheckUserOverride -->|是| UseUserOverride
    CheckUserOverride -->|否| CheckSession

    CheckSession -->|是| UseSession
    CheckSession -->|否| CheckAssistant

    CheckAssistant -->|是| UseAssistant
    CheckAssistant -->|否| CheckUserPref

    CheckUserPref -->|是| UseUserPref
    CheckUserPref -->|否| CheckSystemDefault

    CheckSystemDefault -->|是| UseSystemDefault
    CheckSystemDefault -->|否| Fail

来源： 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 关联的提供商和模型名称。

助手模型解析

graph LR
    subgraph "Persona 配置"
        P_MCID["default_model_configuration_id"]
    end

    subgraph "LLM 覆盖（会话/手动）"
        O_Prov["model_provider"]
        O_Vers["model_version"]
    end

    CheckOverride{"覆盖<br/>存在？"}
    FetchMC["fetch_model_configuration_by_id"]
    FetchProv["fetch_existing_llm_provider"]

    Result["最终结果（LLMProvider, model_name）"]

    P_MCID --> CheckOverride
    O_Prov --> CheckOverride

    CheckOverride -->|是| FetchProv
    CheckOverride -->|否| FetchMC

    FetchProv --> Result
    FetchMC --> Result

来源： 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 接口实例。

代码实体映射

graph TD
    subgraph "自然语言空间"
        UserMsg["用户消息"]
        AssistantSel["助手选择"]
    end

    subgraph "代码实体空间（backend/onyx/llm/）"
        Factory["factory.py: get_llm_for_persona"]
        MultiLLM["multi_llm.py: LitellmLLM"]
        Interfaces["interfaces.py: LLMConfig"]
        Models["models.py: AssistantMessage"]
    end

    subgraph "数据空间（PostgreSQL）"
        DB_Persona["Persona 表"]
        DB_MC["ModelConfiguration 表"]
        DB_Provider["LLMProvider 表"]
    end

    UserMsg --> Factory
    AssistantSel --> DB_Persona
    DB_Persona --> DB_MC
    DB_MC --> DB_Provider
    DB_Provider --> Factory
    Factory --> MultiLLM
    MultiLLM --> Models

来源： 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