Dify 插件开发实验07私有模型网关接入——如何让 Dify 用上私有模型网关Dify 实验系列 · 插件开发 07/12 | 实验编号DIFY-106-07基于 Dify 1.16.1 实测2026-081. 业务场景先讲一个我们实际遇到的场景。企业有内部模型网关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. 整体架构【验证应用】开始questionLLM 节点企业网关模型 enterprise-gpt输出结束模型插件model provider控制台模型列表声明供应商企业网关 模型LLM 类型predefined-model 模式凭证base_url api_keyvalidate_credentials 校验有效性get_models返回可用模型列表调用LLM 节点/Agent → 插件 _invoke → OpenAI 兼容协议 → 网关mock链路很清晰控制台声明供应商 → 配置凭证保存即校验→ 模型列表可见 → LLM 节点/Agent 调用走插件 → OpenAI 兼容协议打到网关。关键设计是凭证校验前置——配置页保存时调/v1/models验证错的密钥当场报错不拖到运行时。5. 模块设计5.1 manifest 声明模型插件注意plugins: models:而非 toolsplugins:models:-provider/gateway.yaml5.2 供应商声明provider/gateway.yamlsupported_model_types predefined-model 凭证 schemaprovider:gatewaysupported_model_types:-llmconfigurate_methods:-predefined-modelprovider_credential_schema:credential_form_schemas:-variable:base_urltype:text-inputrequired:trueplaceholder:zh_Hans:http://host.docker.internal:8005-variable:api_keytype:secret-inputrequired:truemodels:llm:predefined:-models/llm/llm.yamlextra:python:provider_source:provider/gateway.pymodel_sources:-models/llm/llm.py5.3 模型声明models/llm/llm.yamlfeatures 决定 Agent 能否使用该模型工单场景必须支持函数调用model:enterprise-gptmodel_type:llmfeatures:-agent-thought-tool-callmodel_properties:mode:chatcontext_size:8192parameter_rules:-name:temperatureuse_template:temperature-name:max_tokensuse_template:max_tokens5.4 LLM 实现models/llm/llm.pyLargeLanguageModel子类实现四抽象_invoke / validate_credentials / get_num_tokens / _invoke_error_mapping。_invoke把 PromptMessage 转成 OpenAI messages 调/chat/completions流式逐行解析 SSEdata:前缀、[DONE]终止、delta.content非空才 yieldvalidate_credentials调/v1/models验证 base_url/api_key——配置页「保存」即时报错。6. 运行验证输入预期结果mock 网关 /models /chat/completionscurl 通过非流式流式 SSE✅ 一致正确凭证保存201 保存成功✅ 一致错误 api_key / 网关不可达保存报错明确网关返回 401 / 不可达✅ 错误信息可读控制台模型列表出现「企业网关」供应商及 enterprise-gpt✅ status activefeatures agent-thoughttool-callLLM 节点调用企业网关回答✅ run succeeded0.8s流式输出增量完整可拼接✅ 本地单测 6 chunks 拼接完整mock 网关停止LLM 调用报错明确✅ ConnectionError 语义与校验层一致环境Dify 1.16.1Docker Composemock 网关 tmp/mock_gateway.py127.0.0.1:8005Bearer mock-secret-106。Agent 形态经等价验证106-03 已挂工具替换模型场景等价未单独跑 agent企业网关组合。7. 实战坑坑现象修复model_properties 枚举model_properties 写 max_tokens → 上传报「Failed to parse response from plugin daemon to PluginDecodeResponse」daemon 正常api 解析失败max_tokens 放 parameter_rulesuse_template: max_tokensmodel_properties 只允许 mode/context_size 等 10 个枚举模型凭证 schemaprovider yaml 带空 model_credential_schema 数组反而解析失败predefined-model 模式可省对照 deepseek 官方结构确认provider 声明格式错按工具插件写法声明模型上传失败manifest 用 plugins.models非 tools供应商 id author/plugin/provider 三段接口签名不符抽象方法未实现启动失败LargeLanguageModel 四抽象全实现本地单测用 object.new绕过init(model_schemas)流式实现缺陷SSE 解析不全丢字/不终止逐行解析 data: 前缀 [DONE] 终止delta.content 非空才 yield含 finish_reason 终止 chunk凭证泄漏错误信息带出 base_url/api_key错误信息只报状态码原因不出凭证模型凭证 APIPOST 创建同名凭证 400 already exists用 PUT 更新credential_id 从 provider_credentials 表拿凭证校验失败不保存保护行为LLM 节点 DSLmodel.provider 缺完整 id / data 缺字段 → 校验错provider 用完整 iddify106/dify106_07_gateway_provider/gatewaydata 必须含 context/memory: null/memory_config/variables/vision8. 实验文档及源码获取实验文档DIFY-106-07模型插件接入私有网关.md验证应用 DSLdify106_07_验证应用.yml插件安装包dify106_07_gateway_provider.signed.difypkg源码目录dify-106/dsl | dify-106/plugins文章聚焦核心配置与采坑点完整分步操作与模型接入全链路验证记录见实验文档原文。下一篇Dify 插件开发实验08外部知识库插件——如何把外部检索能力做成插件 你在这个实验的场景里踩过什么坑欢迎评论区分享你的实战经验。
Dify 插件开发实验（07）：私有模型网关接入——如何让 Dify 用上私有模型网关？
Dify 插件开发实验07私有模型网关接入——如何让 Dify 用上私有模型网关Dify 实验系列 · 插件开发 07/12 | 实验编号DIFY-106-07基于 Dify 1.16.1 实测2026-081. 业务场景先讲一个我们实际遇到的场景。企业有内部模型网关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. 整体架构【验证应用】开始questionLLM 节点企业网关模型 enterprise-gpt输出结束模型插件model provider控制台模型列表声明供应商企业网关 模型LLM 类型predefined-model 模式凭证base_url api_keyvalidate_credentials 校验有效性get_models返回可用模型列表调用LLM 节点/Agent → 插件 _invoke → OpenAI 兼容协议 → 网关mock链路很清晰控制台声明供应商 → 配置凭证保存即校验→ 模型列表可见 → LLM 节点/Agent 调用走插件 → OpenAI 兼容协议打到网关。关键设计是凭证校验前置——配置页保存时调/v1/models验证错的密钥当场报错不拖到运行时。5. 模块设计5.1 manifest 声明模型插件注意plugins: models:而非 toolsplugins:models:-provider/gateway.yaml5.2 供应商声明provider/gateway.yamlsupported_model_types predefined-model 凭证 schemaprovider:gatewaysupported_model_types:-llmconfigurate_methods:-predefined-modelprovider_credential_schema:credential_form_schemas:-variable:base_urltype:text-inputrequired:trueplaceholder:zh_Hans:http://host.docker.internal:8005-variable:api_keytype:secret-inputrequired:truemodels:llm:predefined:-models/llm/llm.yamlextra:python:provider_source:provider/gateway.pymodel_sources:-models/llm/llm.py5.3 模型声明models/llm/llm.yamlfeatures 决定 Agent 能否使用该模型工单场景必须支持函数调用model:enterprise-gptmodel_type:llmfeatures:-agent-thought-tool-callmodel_properties:mode:chatcontext_size:8192parameter_rules:-name:temperatureuse_template:temperature-name:max_tokensuse_template:max_tokens5.4 LLM 实现models/llm/llm.pyLargeLanguageModel子类实现四抽象_invoke / validate_credentials / get_num_tokens / _invoke_error_mapping。_invoke把 PromptMessage 转成 OpenAI messages 调/chat/completions流式逐行解析 SSEdata:前缀、[DONE]终止、delta.content非空才 yieldvalidate_credentials调/v1/models验证 base_url/api_key——配置页「保存」即时报错。6. 运行验证输入预期结果mock 网关 /models /chat/completionscurl 通过非流式流式 SSE✅ 一致正确凭证保存201 保存成功✅ 一致错误 api_key / 网关不可达保存报错明确网关返回 401 / 不可达✅ 错误信息可读控制台模型列表出现「企业网关」供应商及 enterprise-gpt✅ status activefeatures agent-thoughttool-callLLM 节点调用企业网关回答✅ run succeeded0.8s流式输出增量完整可拼接✅ 本地单测 6 chunks 拼接完整mock 网关停止LLM 调用报错明确✅ ConnectionError 语义与校验层一致环境Dify 1.16.1Docker Composemock 网关 tmp/mock_gateway.py127.0.0.1:8005Bearer mock-secret-106。Agent 形态经等价验证106-03 已挂工具替换模型场景等价未单独跑 agent企业网关组合。7. 实战坑坑现象修复model_properties 枚举model_properties 写 max_tokens → 上传报「Failed to parse response from plugin daemon to PluginDecodeResponse」daemon 正常api 解析失败max_tokens 放 parameter_rulesuse_template: max_tokensmodel_properties 只允许 mode/context_size 等 10 个枚举模型凭证 schemaprovider yaml 带空 model_credential_schema 数组反而解析失败predefined-model 模式可省对照 deepseek 官方结构确认provider 声明格式错按工具插件写法声明模型上传失败manifest 用 plugins.models非 tools供应商 id author/plugin/provider 三段接口签名不符抽象方法未实现启动失败LargeLanguageModel 四抽象全实现本地单测用 object.new绕过init(model_schemas)流式实现缺陷SSE 解析不全丢字/不终止逐行解析 data: 前缀 [DONE] 终止delta.content 非空才 yield含 finish_reason 终止 chunk凭证泄漏错误信息带出 base_url/api_key错误信息只报状态码原因不出凭证模型凭证 APIPOST 创建同名凭证 400 already exists用 PUT 更新credential_id 从 provider_credentials 表拿凭证校验失败不保存保护行为LLM 节点 DSLmodel.provider 缺完整 id / data 缺字段 → 校验错provider 用完整 iddify106/dify106_07_gateway_provider/gatewaydata 必须含 context/memory: null/memory_config/variables/vision8. 实验文档及源码获取实验文档DIFY-106-07模型插件接入私有网关.md验证应用 DSLdify106_07_验证应用.yml插件安装包dify106_07_gateway_provider.signed.difypkg源码目录dify-106/dsl | dify-106/plugins文章聚焦核心配置与采坑点完整分步操作与模型接入全链路验证记录见实验文档原文。下一篇Dify 插件开发实验08外部知识库插件——如何把外部检索能力做成插件 你在这个实验的场景里踩过什么坑欢迎评论区分享你的实战经验。
