Dify 插件开发实验（07）：私有模型网关接入——如何让 Dify 用上私有模型网关？

1. 业务场景

先讲一个我们实际遇到的场景。

企业有内部模型网关：OpenAI 兼容协议，统一管理模型密钥与配额，所有对外的大模型调用都必须经过它——合规要审计、成本要管控、数据不出企业边界。客服工单 SaaS 的智能问答、工单摘要、Agent 对话，全都必须走公司网关，不能直连外部模型。但问题来了：Dify 控制台的模型列表里，根本没有「企业网关」这个供应商。

我们第一次接这类需求时，第一反应也是「Dify 不是支持自定义模型吗，配一下不就行了」。真正动手才发现——「模型」在 Dify 里不是填个 API 地址就能用，而是一个完整的供应商插件：要声明供应商、声明模型、实现调用逻辑，还要过凭证校验——控制台里能选到公司模型，背后是一整套 model provider 插件机制。

这不是个例。任何有私有模型/统一网关的企业都是这个模式：金融行业要审计模型调用、政企要求数据不出域、集团统一采购模型配额——「控制台里能选到公司的模型」，是模型接入的第一诉求。

2. 场景痛点

这个流程的痛点，在接入企业网关时体现得最直接：

• 合规与审计过不去：应用直连外部模型，调用记录、数据流向都不受控，审计时根本说不清。
• 密钥管理分散：每个应用各配各的模型密钥，换一次密钥要改遍所有应用，泄露了也无从追溯。
• 控制台选不到公司模型：Dify 内置供应商列表里没有企业网关，团队只能绕开 Dify 单独接模型，能力割裂。
• 配额与成本不可控：没有网关层统一管控，谁的调用都直接打到模型厂商，预算超了才知道。

本质上，企业要的不是「某个模型」，而是「受控的模型入口」——统一网关、统一密钥、统一审计，Dify 必须能消费这个入口。

3. 方案：为什么是模型插件

选模型插件，我们实际对比过：

• 模型插件 = 供应商扩展：Dify 的 model provider 插件机制，让自定义供应商（含旗下模型）直接出现在控制台模型列表；
• 凭证在控制台配置：网关 base_url + api_key 作为 provider 凭证在控制台录入，不写死在代码，密钥统一管理；
• OpenAI 兼容协议复用生态：网关暴露 /v1/models + /v1/chat/completions，插件按兼容协议实现即可，无需私有协议适配。

这篇文章我们就用它把企业私有网关接进 Dify：开发一个 model provider 插件 dify106_07_gateway_provider，让控制台出现「企业网关」供应商及旗下模型 enterprise-gpt，并用本地 mock 网关（OpenAI 兼容）验证「凭证校验 → 模型列表 → LLM 调用（含流式）」全链路。

4. 整体架构

链路很清晰：控制台声明供应商 → 配置凭证（保存即校验）→ 模型列表可见 → LLM 节点/Agent 调用走插件 → OpenAI 兼容协议打到网关。关键设计是凭证校验前置——配置页保存时调 /v1/models 验证，错的密钥当场报错，不拖到运行时。

5. 模块设计

5.1 manifest 声明模型插件

注意 plugins: models: 而非 tools：

plugins:

  models:

    - provider/gateway.yaml

5.2 供应商声明（provider/gateway.yaml）

supported_model_types + predefined-model + 凭证 schema：

provider: gateway

supported_model_types:

  - llm

configurate_methods:

  - predefined-model

provider_credential_schema:

  credential_form_schemas:

    - variable: base_url

      type: text-input

      required: true

      placeholder:

        zh_Hans: http://host.docker.internal:8005

    - variable: api_key

      type: secret-input

      required: true

models:

  llm:

    predefined:

      - "models/llm/llm.yaml"

extra:

  python:

    provider_source: provider/gateway.py

    model_sources:

      - "models/llm/llm.py"

5.3 模型声明（models/llm/llm.yaml）

features 决定 Agent 能否使用该模型（工单场景必须支持函数调用）：

model: enterprise-gpt

model_type: llm

features:

  - agent-thought

  - tool-call

model_properties:

  mode: chat

  context_size: 8192

parameter_rules:

  - name: temperature

    use_template: temperature

  - name: max_tokens

    use_template: max_tokens

5.4 LLM 实现（models/llm/llm.py）

LargeLanguageModel 子类实现四抽象 _invoke / validate_credentials / get_num_tokens / _invoke_error_mapping。_invoke 把 PromptMessage 转成 OpenAI messages 调 /chat/completions；流式逐行解析 SSE（data: 前缀、[DONE] 终止、delta.content 非空才 yield）；validate_credentials 调 /v1/models 验证 base_url/api_key——配置页「保存」即时报错。

6. 运行验证

环境：Dify 1.16.1（Docker Compose），mock 网关 tmp/mock_gateway.py（127.0.0.1:8005，Bearer mock-secret-106）。Agent 形态经等价验证（106-03 已挂工具，替换模型场景等价；未单独跑 agent+企业网关组合）。

7. 实战坑

8. 实验文档及源码获取

• 实验文档：DIFY-106-07：模型插件接入私有网关.md
• 验证应用 DSL：dify106_07_验证应用.yml
• 插件安装包：dify106_07_gateway_provider.signed.difypkg
• 源码目录：dify-106/dsl | dify-106/plugins

文章聚焦核心配置与采坑点，完整分步操作与模型接入全链路验证记录见实验文档原文。