6.1 · 提供方配置（Provider Configuration）

提供方配置

提供者配置

相关源文件

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

• 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）提供者。这包括配置 API 密钥、端点、模型偏好以及提供者特定的参数，使 Onyx 能够与 OpenAI、Anthropic、Azure、Bedrock 和 Ollama 等外部 AI 服务进行交互。

该系统使用基于 LiteLLM 构建的统一抽象层，为应用程序提供一致的接口，同时处理各种后端实现的细微差别，包括推理模型和多模态输入。

配置架构

提供者集成栈

来源： backend/onyx/llm/factory.py:21-22，backend/onyx/llm/interfaces.py:18-19，backend/onyx/llm/multi_llm.py:26-26，backend/onyx/llm/utils.py:25-27

核心配置系统

LLMConfig 与数据模型

配置通过 Pydantic 模型进行 API 交互封装，并通过 SQLAlchemy 模型进行持久化。LLMProvider 模型表示与服务的连接，而 ModelConfiguration 表示该服务中的特定模型。

关键 LLM 配置字段

来源： backend/onyx/server/manage/llm/models.py:93-105，backend/onyx/server/manage/llm/api.py:107-111，backend/onyx/db/models.py:13-16

LLM 抽象接口

Onyx 中的所有 LLM 实现都继承自 LLM 抽象基类，确保系统其余部分具有一致的契约。

关键接口方法：onyx.llm.interfaces

• invoke()：执行同步请求。它接受一个 LanguageModelInput（消息列表）并返回一个 ModelResponse。backend/onyx/llm/interfaces.py:43-54
• stream()：返回一个 Iterator[ModelResponseStream]，用于实时 Token 生成。backend/onyx/llm/interfaces.py:56-67

支持的 LLM 提供者

Onyx 支持广泛的提供者，通过 LlmProviderNames 枚举分为"知名"和"动态"类型。backend/onyx/llm/constants.py:11-30

动态模型获取

对于 Bedrock、Ollama 和 OpenRouter 等提供者，Onyx 可以从提供者的 API 动态获取可用模型。

模型获取流程

来源： backend/onyx/server/manage/llm/api.py:70-94，backend/onyx/server/manage/llm/utils.py:98-103

提供者特定配置

实现细节

LLM 工厂逻辑

get_llm_for_persona 函数根据覆盖层级确定要实例化的提供者。

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

推理与能力

Onyx 处理高级模型特性：

• 推理力度：通过 ReasoningEffort 枚举（LOW、MEDIUM、HIGH）管理。backend/onyx/llm/models.py:13-28
• 视觉支持：通过 infer_vision_support 基于模型命名和提供者元数据推断。backend/onyx/server/manage/llm/utils.py:100-100
• Token 限制：通过 get_max_input_tokens 或提供者特定工具（如 get_bedrock_token_limit）查找。backend/onyx/llm/utils.py:51-51，backend/onyx/llm/constants.py:208-230

管理与安全

敏感配置掩码

API 确保敏感密钥永远不会以明文形式返回。_mask_string 函数用星号替换密钥的中间部分。backend/onyx/server/manage/llm/api.py:116-121

访问控制

提供者访问通过 can_user_access_llm_provider 管理。backend/onyx/db/llm.py:101-147

1. is_public：如果为 true，所有用户都可以访问。
2. 用户组：如果为私有，用户必须属于白名单组（管理员绕过）。
3. 角色限制：提供者可以限制为特定的助手（角色）。

多租户保护

在多租户环境中，Onyx 会阻止更改现有提供者的 api_base 或 custom_config，除非同时更改 api_key，以防止恶意重定向有效凭证。backend/tests/external_dependency_unit/llm/test_llm_provider_api_base.py:84-118

来源： backend/onyx/db/llm.py:101-147，backend/onyx/server/manage/llm/api.py:123-156