6.3 · 模型能力与要求（Model Capabilities and Requirements）

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

项目Onyx 章节6.3 状态全文译文模块模型调用与提供方适配、文档对象与元数据、测试、发布与运维、接口与服务契约

项目要点页2.5 参考项目项目章节目录Onyx DeepWiki 原始章节Model Capabilities and Requirements 上一章6.2 下一章6.4

源码线索

backend/alembic/versions/7bd55f264e1b_add_display_name_to_model_configuration.py
backend/onyx/configs/model_configs.py
backend/onyx/llm/constants.py
backend/onyx/llm/model_metadata_enrichments.json
backend/onyx/llm/model_name_parser.py
backend/onyx/llm/models.py
backend/onyx/llm/multi_llm.py
backend/onyx/llm/well_known_providers/constants.py
backend/onyx/llm/well_known_providers/llm_provider_options.py
backend/onyx/llm/well_known_providers/recommended-models.json

模块标签

模型调用与提供方适配
文档对象与元数据
测试、发布与运维
接口与服务契约
界面与交互

章节正文

模型能力与要求

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/6.3-model-capabilities-and-requirements

模型能力与要求

目的与范围

本文档记录了集成到 Onyx 中的大语言模型（LLM）的模型特定功能、工具和技术要求。它详细说明了系统如何从动态提供商（Bedrock、Ollama、OpenRouter、Bifrost、LM Studio）获取模型列表，如何追踪工具调用、视觉和推理等能力，以及如何管理不同架构下的上下文窗口要求。

动态模型发现

Onyx 提供了工具函数，可以直接从提供商 API 获取可用模型。这使得系统能够用最新的模型列表填充管理界面，而无需为每个变体手动输入。

发现工具与数据流

下图展示了后端如何从外部提供商获取模型元数据，并将其与内部数据库同步。

模型发现与同步流程

Onyx · 发现工具与数据流 · 图 1

工具函数	提供商	实现细节
`fetch_bedrock_models`	AWS Bedrock	使用 `boto3` 客户端调用 `list_foundation_models`。通过 `is_valid_bedrock_model` 进行过滤。`backend/onyx/server/manage/llm/api.py:346-410`
`fetch_ollama_models`	Ollama	向 Ollama `/api/tags` 端点发送 `GET` 请求。`backend/onyx/server/manage/llm/api.py:270-305`
`fetch_openrouter_models`	OpenRouter	向 `https://openrouter.ai/api/v1/models` 发送 `GET` 请求。`backend/onyx/server/manage/llm/api.py:199-231`
`fetch_bifrost_models`	Bifrost	向 Bifrost `/v1/models` 端点发送 `GET` 请求。`backend/onyx/server/manage/llm/api.py:553-585`
`fetch_lm_studio_models`	LM Studio	向本地 LM Studio `/v1/models` 端点发送 `GET` 请求。`backend/onyx/server/manage/llm/api.py:488-518`

来源： backend/onyx/server/manage/llm/api.py:151-164、backend/onyx/server/manage/llm/utils.py:21-30、backend/onyx/llm/well_known_providers/llm_provider_options.py:38-56

模型能力追踪

Onyx 会追踪特定能力，以确定模型在聊天和搜索管线中的使用方式。这些能力存储在 ModelConfiguration 表中。

能力定义

能力	代码实体/字段	描述
推理	`supports_reasoning`	标识提供"思考"或"思维链"块的模型（例如 OpenAI o1、DeepSeek-R1）。`backend/onyx/server/manage/llm/models.py:32-56`
视觉	`supports_image_input`	指示模型是否可以处理 `UserMessage` 中的 `image_url` 内容部分。`backend/onyx/llm/models.py:73-78`
工具调用	`supports_function_calling`	模型是否可以生成用于工具执行的结构化 JSON。`backend/onyx/tools/utils.py:16-27`
上下文窗口	`max_input_tokens`	组合提示和历史的 Token 最大数量。`backend/onyx/llm/well_known_providers/constants.py:208-233`

推理与思考模式

对于支持扩展思考的模型，Onyx 会管理 ReasoningEffort 级别。根据底层提供商的 API 要求，映射方式会有所不同。

推理努力映射

Onyx · 推理与思考模式 · 图 2

Anthropic 自适应思考： 较新的模型（例如 Claude 4.7）使用 adaptive 思考类型，会拒绝 temperature 等采样参数。backend/onyx/llm/multi_llm.py:77-92
OpenAI 努力： 默认将 ReasoningEffort.AUTO 映射为 medium。backend/onyx/llm/models.py:32-38

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

工具调用与消息格式化

Onyx 使用标准化的消息结构（LanguageModelInput），该结构会被转换为提供商特定的格式。某些提供商有严格的要求，这些要求在 multi_llm.py 中处理。

Bedrock 工具配置要求

AWS Bedrock 的 Converse API 要求，如果历史记录中的任何消息包含 toolUse 或 toolResult 块，则必须定义 toolConfig。

实现： _strip_tool_content_from_messages 将结构化的工具调用和结果转换为消息历史记录中的纯文本字符串（例如 [Tool Call] name=...），以避免在工具未激活时出现"必须定义 toolConfig 字段"的错误。backend/onyx/llm/multi_llm.py:136-181

消息规范化

LiteLLM 期望消息是字典格式。Onyx 使用 _prompt_to_dicts 序列化 Pydantic 消息模型，并使用 _normalize_content 规范化内容块（文本与块列表）。backend/onyx/llm/multi_llm.py:107-133

来源： backend/onyx/llm/multi_llm.py:107-181、backend/onyx/llm/models.py:81-127

模型元数据与显示名称

Onyx 维护了丰富的元数据集，为晦涩的模型 ID 提供人性化的友好名称，特别是对于动态提供商。

显示名称生成

Bedrock： 去除区域前缀（例如 us.、eu.）和版本后缀（例如 :0），并对 Claude 或 Llama 等系列应用正确的大小写格式。backend/onyx/server/manage/llm/utils.py:113-173
Ollama： 将基础名称与标签拆分，并应用 OLLAMA_MODEL_NAME_MAPPINGS 中的映射。backend/onyx/server/manage/llm/utils.py:176-208

视觉支持推断

当 API 元数据缺失时，Onyx 会根据模型 ID 模式推断视觉支持。

Bedrock 视觉模型： 包括 anthropic.claude-3、amazon.nova-pro 等。backend/onyx/server/manage/llm/utils.py:44-52
Bifrost 视觉系列： 包括 openai/gpt-4o、google/gemini 和 qwen/qwen2.5-vl。backend/onyx/server/manage/llm/utils.py:56-71

来源： backend/onyx/server/manage/llm/utils.py:40-71、backend/onyx/server/manage/llm/utils.py:113-208、backend/onyx/llm/constants.py:165-200

安全与配置限制

为防止管理员将 API 请求重定向到攻击者控制的服务器以窃取 API 密钥等漏洞，Onyx 实施了严格的更新规则。

多租户保护

在 MULTI_TENANT 模式下，除非在同一请求中也更改了 api_key，否则禁止更改 LLM 提供商的 api_base 或 custom_config。

逻辑： 系统会比较传入的 api_base 与现有的 api_base。如果两者不同且 api_key_changed 为 false，则会抛出 OnyxErrorCode.VALIDATION_ERROR。backend/tests/external_dependency_unit/llm/test_llm_provider_api_base.py:84-118

来源： backend/tests/external_dependency_unit/llm/test_llm_provider_api_base.py:84-118、backend/onyx/llm/well_known_providers/constants.py:21-24

技术要求总结

功能	要求	实现
流式传输	模型必须支持服务器发送事件（SSE）。	通过 `multi_llm.py` 中的 `ModelResponseStream` 处理。`backend/onyx/llm/multi_llm.py:24-24`
工具调用	模型必须标记为 `supports_function_calling`。	逻辑在 `explicit_tool_calling_supported` 中。`backend/onyx/tools/utils.py:16-27`
上下文窗口	必须配置 `max_input_tokens`。	`get_max_input_tokens` 中的逻辑使用 `BEDROCK_MODEL_TOKEN_LIMITS` 或 LiteLLM 默认值。`backend/onyx/llm/constants.py:208-233`
推理	模型必须位于 `_ANTHROPIC_ADAPTIVE_THINKING_MODELS` 或 OAI 的等效列表中。	通过 `ReasoningEffort` 枚举和提供商特定映射进行控制。`backend/onyx/llm/multi_llm.py:79-79`

来源： backend/onyx/llm/multi_llm.py:23-25、backend/onyx/tools/utils.py:16-27、backend/onyx/llm/constants.py:208-233、backend/onyx/llm/models.py:13-28