Dify + 自定义模型 API：配置、验证并保留回滚路径
添加自定义供应商会创建新的凭证与数据边界。先配置占位符，测试每项必需能力，并保持旧供应商可用。
速览
不要在无关 Workspace 间共享供应商密钥或日志。
测试模型、Chat、流、工具、结构定义与错误。
保留供应商、模型、请求 ID、用量与故障证据。
灰度一个应用，并保留旧供应商配置。
自定义供应商设置流程
在供应商配置中登记经过批准的基础地址、受限密钥和模型别名。向应用开放前，应先验证端点的实际路由与能力。
配置应从供应商契约出发，而不是只看显示名称。需要确认 Dify 实际调用的路径、认证请求头、模型标识、请求与响应字段、超时行为和错误格式。“兼容 OpenAI”通常只表示基础聊天补全可用，并不必然支持流式输出、工具调用、视觉输入、JSON Schema、Embedding 或 Token 核算。
应用侧应使用稳定的内部别名，把真实供应商模型隐藏在别名之后。这样运营人员更换端点或模型版本时，无需逐个修改工作流。还要记录别名与端点的映射、供应商配置版本和负责人，确保事故发生时能够定位实际处理请求的准确配置。
先在测试工作区验证，再对选定应用进行灰度，并持续观察原生错误、用量和输出质量；回滚配置不应要求重写提示词。生产与测试凭证必须分离，还要确认从一个工作区导出的工作流不会在另一个环境中悄悄继承权限更高的供应商配置。
需要治理的配置字段
| 字段 | 最适合 | 选择前验证 |
|---|---|---|
| 基础地址（Base URL） | 批准的 HTTPS 兼容端点。 | 验证运营者、主机地址、区域与数据条款。 |
| API 密钥 | 租户受限最小权限凭证。 | 存入上游密钥、轮换并审计访问。 |
| 模型别名 | 面向应用的稳定工作负载名称。 | 映射到版本化模型与已验证能力。 |
| 重试与超时 | 有界执行策略。 | 由一层负责并保留幂等。 |
能力验证
检查模型列表与每条必需推理路径。
测试流、工具、JSON 结构定义、错误与用量。
确认密钥、配置、日志与预算保持租户受限。
版本化供应商配置并测试一键回滚。
逐个应用推进上线
供应商即使通过了简单的 Playground 提示词，也可能破坏生产环境中的 Dify 应用。测试集应来自真实工作流节点，包括系统提示词、对话历史、结构化变量、知识库上下文、文件输入、流式输出、工具调用和下游解析器。既要比较供应商原始响应，也要比较最终工作流输出。
- 在生产环境之外运行供应商契约测试。
- 使用具有代表性的应用工作流比较目标供应商与原供应商。
- 先灰度一个租户，监控错误、路由与被接受的输出。
- 演练配置回滚和凭证吊销。
灰度前应先定义验收阈值，至少跟踪传输错误、首 Token 延迟、总延迟、结构有效率、工具调用参数有效率、Token 用量和任务级质量。即使新路由错误率更低，如果它丢失引用、改变 JSON 字段类型，或生成明显更长的响应并打破成本假设，也不能视为通过。
回滚必须恢复完整的旧供应商记录，而不只是恢复模型名称。基础地址、凭证引用、能力标记、上下文限制、超时、重试策略和输出适配器应作为一个版本化单元共同回滚。回滚完成后要吊销被弃用的凭证，避免陈旧 Worker 继续向失败路由发送流量。
把供应商配置视为代码
Dify 应用引用稳定别名；租户范围内的供应商记录保存已批准的端点和凭证；能力测试控制配置晋级，遥测保留原生证据，配置版本则让回滚能够立即执行。
非敏感配置应进入版本控制或受治理的配置注册表。端点、模型映射、上下文限制和能力标记的变更都要像代码一样经过审查；密钥继续保存在密钥库中，只通过标识符引用。部署记录还应包含校验值或版本，使请求调用链能够证明当时实际启用的是哪份配置。
发现与上线应当分离。供应商管理员可以创建并测试候选配置，但生产启用必须经过审批或自动质量门禁。这样可以防止一次方便的后台编辑绕过租户策略、数据驻留要求或应用级回归检查。
生产规则：生产路径通过契约测试前，绝不能把某项能力标记为已支持。
用 QVeris 接入外部 API 与工具
自定义模型 API 提供推理；QVeris 通过“发现 → 检查 → 调用”提供外部 API、工具、服务和实时数据。两类供应商记录、上游密钥与证据应彼此分离。
当 Dify 工作流从生成文本转向完成真实任务时，这种分离非常重要。模型路由可以被允许总结请求，但后续能力调用仍需要独立权限，才能查询监管申报文件、获取实时市场数据、解析文档或更新外部系统。执行前检查能力，可以提前了解必填参数、输出结构、成本、延迟和权限要求。
两层应通过工作流调用链关联，而不是共用同一份密钥。先记录 Dify 应用和模型尝试，再把 QVeris 的搜索、能力与执行标识附加到同一调用链。这样运营人员既能还原完整工作流，也能分别轮换、吊销和控制推理与外部动作的预算。
从 Dify 实际加载的供应商契约开始
当前 Dify Plugin 系统把供应商 Metadata、凭证字段、模型类型代码、调用、Token 计算与错误映射分开。Custom 模型不只是一个 URL 字段：应封装完整契约，用轻量调用验证凭证，并同时测试流式与非流式路径。
provider: company_gateway
label:
en_US: Company LLM Gateway
zh_Hans: 企业 LLM 网关
supported_model_types:
- llm
configurate_methods:
- customizable-model
provider_credential_schema:
credential_form_schemas:
- variable: server_url
type: text-input
required: true
- variable: api_key
type: secret-input
required: true
extra:
python:
provider_source: provider/company_gateway.py
model_sources:
- models/llm/llm.py- 实现 validate_credentials，并映射认证、限流、超时和供应商错误。
- 返回标准化文本、Finish Reason、用量与原生请求 Identifier。
- 远程调试并打包 Plugin，先推广一个 Dify Application，再扩到整个 Workspace。
实施参考已根据官方资料核验：Dify custom model integration。
FAQ
使用 Dify 当前支持的供应商契约，并验证最新集成文档。
除非治理允许，否则优先使用受限凭证与显式隔离。
恢复旧供应商配置，并在需要时撤销目标凭证。