6.1 · 提供方与模型架构（Provider and Model Architecture）

提供方与模型架构（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/langgenius/dify/6.1-provider-and-model-architecture

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

翻译模型：deepseek-chat

原文字符数：16499

项目：Dify (dify)

--- 好的，作为一名资深技术文档翻译专家，我将严格遵循您的要求，对这份 DeepWiki 技术文档进行全文翻译和润色。

---

提供商与模型架构

相关源文件

本维基页面基于以下文件生成：

• api/core/agent/output_parser/cot_output_parser.py
• api/core/app/app_config/easy_ui_based_app/model_config/converter.py
• api/core/app/llm/model_access.py
• api/core/entities/model_entities.py
• api/core/entities/provider_configuration.py
• api/core/hosting_configuration.py
• api/core/model_manager.py
• api/core/provider_manager.py
• api/core/schemas/resolver.py
• api/services/enterprise/enterprise_service.py
• api/services/entities/model_provider_entities.py
• api/services/model_load_balancing_service.py
• api/services/model_provider_service.py
• api/tests/integration_tests/model_runtime/__mock/plugin_model.py
• api/tests/test_containers_integration_tests/services/test_api_based_extension_service.py
• api/tests/test_containers_integration_tests/services/test_model_load_balancing_service.py
• api/tests/test_containers_integration_tests/services/test_model_provider_service.py
• api/tests/unit_tests/core/entities/test_entities_provider_configuration.py
• api/tests/unit_tests/core/test_model_manager.py
• api/tests/unit_tests/core/test_provider_configuration.py
• api/tests/unit_tests/core/test_provider_manager.py
• api/tests/unit_tests/models/test_provider_models.py
• api/tests/unit_tests/services/test_model_load_balancing_service.py

目的与范围

本文档描述了 Dify 中的提供商与模型管理系统，该系统负责处理与 100 多个大语言模型（LLM）提供商（如 OpenAI、Anthropic 等）及其模型的集成。内容涵盖：

• 提供商、模型和凭证的数据库模型
• 运行时架构（ModelManager、ProviderManager、ProviderConfiguration）
• 凭证管理与解析
• 负载均衡配置
• 模型实例的创建与校验

关于这些提供商在执行过程中如何被调用的信息，请参阅模型调用管线。关于配额扣除和信用额度追踪，请参阅配额管理与信用池。

架构总览：

该系统由三个主要层级组成：

1. 数据库层：api/models/provider.py 中的 SQLAlchemy 模型 api/models/provider.py:1-372
2. 管理层：用于配置组装的 ProviderManager 和 ModelManager 类 api/core/provider_manager.py:64-79, api/core/model_manager.py:35-56
3. 运行时层：ModelInstance 的创建和凭证解析 api/core/model_manager.py:35-56

---

核心数据库模式

提供商与模型架构由多个相互关联的数据库表组成，用于管理提供商配置、模型设置、凭证和租户偏好。

实体关系图

erDiagram
    "Provider" ||--o| "ProviderCredential" : "credential_id"
    "Provider" {
        uuid "id" PK
        uuid "tenant_id"
        string "provider_name"
        string "provider_type"
        boolean "is_valid"
        datetime "last_used"
        uuid "credential_id" FK
        string "quota_type"
        bigint "quota_limit"
        bigint "quota_used"
    }

    "ProviderModel" ||--o| "ProviderModelCredential" : "credential_id"
    "ProviderModel" {
        uuid "id" PK
        uuid "tenant_id"
        string "provider_name"
        string "model_name"
        string "model_type"
        uuid "credential_id" FK
        boolean "is_valid"
    }

    "ProviderCredential" {
        uuid "id" PK
        uuid "tenant_id"
        string "provider_name"
        string "credential_name"
        text "encrypted_config"
    }

    "ProviderModelCredential" {
        uuid "id" PK
        uuid "tenant_id"
        string "provider_name"
        string "model_name"
        string "model_type"
        string "credential_name"
        text "encrypted_config"
    }

    "ProviderModelSetting" {
        uuid "id" PK
        uuid "tenant_id"
        string "provider_name"
        string "model_name"
        string "model_type"
        boolean "enabled"
        boolean "load_balancing_enabled"
    }

    "LoadBalancingModelConfig" {
        uuid "id" PK
        uuid "tenant_id"
        string "provider_name"
        string "model_name"
        string "model_type"
        string "name"
        text "encrypted_config"
        uuid "credential_id" FK
        string "credential_source_type"
        boolean "enabled"
    }

    "TenantDefaultModel" {
        uuid "id" PK
        uuid "tenant_id"
        string "provider_name"
        string "model_name"
        string "model_type"
    }

    "TenantPreferredModelProvider" {
        uuid "id" PK
        uuid "tenant_id"
        string "provider_name"
        string "preferred_provider_type"
    }

    "Provider" ||--o{ "ProviderModel" : "provider_name"
    "ProviderModelSetting" ||--o{ "LoadBalancingModelConfig" : "model configuration"
    "Provider" ||--o| "TenantPreferredModelProvider" : "tenant preference"

来源： api/models/provider.py:49-372

---

提供商类型与配额系统

提供商类型

系统支持两种在 ProviderType 枚举中定义的提供商类型：

类型	描述	使用场景
SYSTEM	具有系统级配置的预定义提供商	由 Dify 管理的内置提供商
CUSTOM	用户配置的提供商	自定义 API 端点、自托管模型

来源： api/models/provider.py:19-28

配额类型

对于托管（云）环境，系统通过 ProviderQuotaType 追踪三种配额类型 api/core/entities/provider_entities.py:18-34：

配额类型	描述	追踪方式
PAID	为托管提供商购买的配额	从 quota_used 中扣除，受 quota_limit 限制
FREE	第三方提供商提供的免费额度	不在 Dify 配额系统中追踪
TRIAL	托管提供商的试用配额	有时间或使用量限制的试用信用额度

托管配置： 在云模式下，HostingConfiguration 会使用环境变量为 Azure OpenAI 和 Anthropic 等提供商初始化这些配额 api/core/hosting_configuration.py:52-66。

---

提供方与 ProviderModel 层级

提供方模型

Provider 表代表一个已配置的提供商实例。关键字段如下：

# api/models/provider.py:49-127
class Provider(TypeBase):
    __tablename__ = "providers"

    id: Mapped[str]                    # UUID 主键
    tenant_id: Mapped[str]              # 工作空间隔离
    provider_name: Mapped[str]          # 例如 "openai"
    provider_type: Mapped[str]          # "custom" 或 "system"
    is_valid: Mapped[bool]              # 凭证校验状态
    credential_id: Mapped[str | None]   # 外键，关联 ProviderCredential

    # 配额字段
    quota_type: Mapped[str | None]      # "paid"、"free" 或 "trial"
    quota_limit: Mapped[int | None]     # 最大配额
    quota_used: Mapped[int | None]      # 当前使用量

来源： api/models/provider.py:49-127

ProviderModel 模型

ProviderModel 表代表提供商内的单个模型：

# api/models/provider.py:129-177
class ProviderModel(TypeBase):
    __tablename__ = "provider_models"

    id: Mapped[str]                  # UUID 主键
    tenant_id: Mapped[str]            # 工作空间隔离
    provider_name: Mapped[str]        # 父级提供商
    model_name: Mapped[str]           # 例如 "gpt-4"
    model_type: Mapped[str]           # "llm"、"text-embedding" 等
    credential_id: Mapped[str | None] # 外键，关联 ProviderModelCredential

来源： api/models/provider.py:129-177

---

凭证管理架构

系统实现了一个两级凭证层级：提供商级凭证和模型级凭证，两者均以加密方式存储。

凭证层级

graph TB
    subgraph "凭证存储"
        "PC"["`ProviderCredential
        (提供商级)`"]
        "PMC"["`ProviderModelCredential
        (模型级)`"]
    end

    subgraph "实体引用"
        "Provider"["Provider<br/>credential_id"]
        "ProviderModel"["ProviderModel<br/>credential_id"]
        "LBConfig"["`LoadBalancingModelConfig
        credential_id
        credential_source_type`"]
    end

    subgraph "凭证访问模式"
        "Access"["凭证访问"]
        "CheckModel"{"存在模型级<br/>凭证？"}
        "CheckProvider"{"存在提供商级<br/>凭证？"}
        "UsePMC"["使用 ProviderModelCredential"]
        "UsePC"["使用 ProviderCredential"]
        "NoCredential"["无凭证<br/>（系统默认）"]

        "Access" --> "CheckModel"
        "CheckModel" -->|是| "UsePMC"
        "CheckModel" -->|否| "CheckProvider"
        "CheckProvider" -->|是| "UsePC"
        "CheckProvider" -->|否| "NoCredential"
    end

    "Provider" --> "PC"
    "ProviderModel" --> "PMC"
    "LBConfig" --> "PC"
    "LBConfig" --> "PMC"

    "PMC" -.-> "UsePMC"
    "PC" -.-> "UsePC"

ProviderCredential 和 ProviderModelCredential

ProviderCredential 为每个提供商存储多个命名的凭证 api/models/provider.py:315-338。ProviderModelCredential 存储特定于模型的凭证，允许每个模型使用不同的 API 密钥 api/models/provider.py:341-372。两者都使用 encrypted_config 来存储敏感数据。

---

负载均衡架构

负载均衡系统为每个模型启用多个凭证配置，以实现高可用性和速率限制分发。

负载均衡组件

graph TB
    subgraph "配置表"
        "PMS"["`ProviderModelSetting
        load_balancing_enabled: bool`"]
        "LBC1"["`LoadBalancingModelConfig #1
        name: '__inherit__'
        credential_id: null
        credential_source_type: 'provider'`"]
        "LBC2"["`LoadBalancingModelConfig #2
        name: 'API Key 2'
        encrypted_config: {...}
        credential_source_type: 'custom'`"]
    end

    subgraph "运行时选择"
        "Request"["模型调用"]
        "CheckLB"{"已启用负载均衡？"}
        "SingleConfig"["使用提供商默认<br/>凭证"]
        "LoadLBConfigs"["加载所有已启用<br/>的负载均衡配置"]
        "SelectConfig"["LBModelManager 选择"]
        "Execute"["使用所选凭证<br/>执行"]

        "Request" --> "CheckLB"
        "CheckLB" -->|否| "SingleConfig"
        "CheckLB" -->|是| "LoadLBConfigs"
        "LoadLBConfigs" --> "SelectConfig"
        "SelectConfig" --> "Execute"
        "SingleConfig" --> "Execute"
    end

LBModelManager： 当启用负载均衡时，ModelInstance 会初始化一个 LBModelManager api/core/model_manager.py:105-114。该管理器负责在调用期间从 load_balancing_configs 列表中选择凭证 api/core/model_manager.py:51-56。

来源： api/models/provider.py:284-312, api/core/model_manager.py:83-116, api/services/model_load_balancing_service.py:45-167

---

运行时架构

ModelManager 和 ProviderManager

运行时层使用两个关键的管理器类来访问配置：

类	位置	用途
ProviderManager	api/core/provider_manager.py	管理租户范围内的提供商配置组装和缓存 api/core/provider_manager.py:64-79。
ProviderConfiguration	api/core/entities/provider_configuration.py	用于管理凭证的增删改查（CRUD）、负载均衡和模型启用的实体 api/core/entities/provider_configuration.py:57-72。
ModelInstance	api/core/model_manager.py	在运行时代表一个特定模型，持有其解析后的凭证和负载均衡管理器 api/core/model_manager.py:35-56。

凭证解析

ProviderConfiguration 类根据提供商类型解析凭证：

# api/core/entities/provider_configuration.py:115-150
def get_current_credentials(self, model_type: ModelType, model: str) -> dict[str, Any] | None:
    if self.using_provider_type == ProviderType.SYSTEM:
        # 从系统范围的托管配置中解析
        return self.system_configuration.credentials.copy()
    else:
        # 从自定义的模型级或提供商级配置中解析
        # ...

来源： api/core/entities/provider_configuration.py:115-170

桥梁：自然语言到代码实体空间的映射

graph LR
    subgraph "自然语言概念"
        "P_Cfg"["提供商配置"]
        "M_Inst"["模型实例"]
        "LB_Set"["负载均衡设置"]
    end

    subgraph "代码实体空间"
        "PM_Class"["ProviderManager (api/core/provider_manager.py)"]
        "PC_Class"["ProviderConfiguration (api/core/entities/provider_configuration.py)"]
        "MI_Class"["ModelInstance (api/core/model_manager.py)"]
        "MLBS_Class"["ModelLoadBalancingService (api/services/model_load_balancing_service.py)"]
    end

    "P_Cfg" --> "PM_Class"
    "PM_Class" -- "构建" --> "PC_Class"
    "M_Inst" --> "MI_Class"
    "LB_Set" --> "MLBS_Class"
    "MI_Class" -- "使用" --> "PC_Class"

来源： api/core/provider_manager.py:64-100, api/core/entities/provider_configuration.py:57-72, api/core/model_manager.py:35-56, api/services/model_load_balancing_service.py:45-58

---

模型参数与提供商服务

系统提供专用服务来处理高级提供商操作和模型模式解析。

ModelProviderService

ModelProviderService 作为控制台 API 的主要接口，用于获取提供商列表和模型配置 api/services/model_provider_service.py:24-32。它通过清理 CustomModelConfiguration 对象，确保敏感凭证不会在列表视图中暴露 api/services/model_provider_service.py:78-95。

ModelLoadBalancingService

该服务管理负载均衡配置的生命周期，包括为特定模型启用/禁用负载均衡，以及管理代表默认提供商/模型凭证的 __inherit__ 配置 api/services/model_load_balancing_service.py:50-91, api/services/model_load_balancing_service.py:147-168。

桥梁：请求流到代码实体的映射

graph TD
    "Client"["控制台客户端"]
    "API"["ModelProviderService (api/services/model_provider_service.py)"]
    "PM"["ProviderManager (api/core/provider_manager.py)"]
    "MLBS"["ModelLoadBalancingService (api/services/model_load_balancing_service.py)"]
    "DB_PMS"["ProviderModelSetting (api/models/provider.py)"]
    "DB_LBMC"["LoadBalancingModelConfig (api/models/provider.py)"]

    "Client" -- "GET /providers" --> "API"
    "API" -- "get_configurations" --> "PM"
    "Client" -- "POST /load-balancing" --> "MLBS"
    "MLBS" -- "update" --> "DB_PMS"
    "MLBS" -- "create/update" --> "DB_LBMC"

来源： api/services/model_provider_service.py:56-68, api/services/model_load_balancing_service.py:50-70, api/models/provider.py:257-282, api/models/provider.py:284-312