Dify + Custom Model API
Configure, Verify, and Keep a RollbackDify + 自定义模型 API：配置、验证并保留回滚路径
Adding a custom provider creates a new credential and data boundary. Configure placeholders first, test every required capability and keep the previous provider available.
添加自定义供应商会创建新的凭证与数据边界。先配置占位符，测试每项必需能力，并保持旧供应商可用。
TL;DR
Do not share provider keys or logs across unrelated workspaces.
Test models, chat, streams, tools, schemas and errors.
Keep provider, model, request ID, usage and failure evidence.
Canary one app and retain the previous provider configuration.
不要在无关 Workspace 间共享供应商密钥或日志。
测试模型、Chat、流、工具、结构定义与错误。
保留供应商、模型、请求 ID、用量与故障证据。
灰度一个应用，并保留旧供应商配置。
Custom provider setup flow自定义供应商设置流程
Register an approved base URL, scoped key and model alias in the provider configuration. Verify the endpoint's actual routes and capabilities before exposing it to an app.
在供应商配置中登记经过批准的基础地址、受限密钥和模型别名。向应用开放前，应先验证端点的实际路由与能力。
Start with the provider contract, not the display name. Confirm the exact path Dify will call, authentication header, model identifier, request and response fields, timeout behavior and error format. “OpenAI compatible” often covers basic chat completion but not necessarily streaming, tool calling, vision, JSON schema, embeddings or token accounting.
配置应从供应商契约出发，而不是只看显示名称。需要确认 Dify 实际调用的路径、认证请求头、模型标识、请求与响应字段、超时行为和错误格式。“兼容 OpenAI”通常只表示基础聊天补全可用，并不必然支持流式输出、工具调用、视觉输入、JSON Schema、Embedding 或 Token 核算。
Use a stable internal alias for the application and keep the physical provider model behind it. This lets operators change endpoints or model versions without editing every workflow. Record the alias-to-endpoint mapping, provider configuration version and owner so an incident can be traced to the exact configuration that served a request.
应用侧应使用稳定的内部别名，把真实供应商模型隐藏在别名之后。这样运营人员更换端点或模型版本时，无需逐个修改工作流。还要记录别名与端点的映射、供应商配置版本和负责人，确保事故发生时能够定位实际处理请求的准确配置。
Promote through a test workspace, canary selected applications and watch native errors, usage and output quality. Roll back configuration without rewriting prompts. Keep production and test credentials separate, and verify that a workflow exported from one workspace cannot silently inherit a higher-privilege provider record in another.
先在测试工作区验证，再对选定应用进行灰度，并持续观察原生错误、用量和输出质量；回滚配置不应要求重写提示词。生产与测试凭证必须分离，还要确认从一个工作区导出的工作流不会在另一个环境中悄悄继承权限更高的供应商配置。
Configuration fields to govern需要治理的配置字段
| Field字段 | Best fit最适合 | Verify before choosing选择前验证 |
|---|---|---|
| Base URL基础地址（Base URL） | Approved HTTPS compatible endpoint.批准的 HTTPS 兼容端点。 | Validate operator, host, region and data terms.验证运营者、主机地址、区域与数据条款。 |
| API keyAPI 密钥 | Tenant-scoped least-privilege credential.租户受限最小权限凭证。 | Store in secrets, rotate and audit access.存入上游密钥、轮换并审计访问。 |
| Model alias模型别名 | Stable app-facing workload name.面向应用的稳定工作负载名称。 | Map to a versioned model and verified capabilities.映射到版本化模型与已验证能力。 |
| Retries and timeout重试与超时 | Bounded execution policy.有界执行策略。 | Give one layer ownership and preserve idempotency.由一层负责并保留幂等。 |
Capability verification能力验证
Check model listing and each required inference path.
Test streams, tools, JSON schema, errors and usage.
Confirm keys, configs, logs and budgets remain tenant-scoped.
Version the provider config and test one-click rollback.
检查模型列表与每条必需推理路径。
测试流、工具、JSON 结构定义、错误与用量。
确认密钥、配置、日志与预算保持租户受限。
版本化供应商配置并测试一键回滚。
Promote one application at a time逐个应用推进上线
A provider can pass a simple playground prompt and still break a production Dify application. Build the test set from actual workflow nodes: system prompts, conversation history, structured variables, knowledge context, file inputs, streaming, tool calls and downstream parsers. Compare both the raw provider response and the final workflow output.
供应商即使通过了简单的 Playground 提示词，也可能破坏生产环境中的 Dify 应用。测试集应来自真实工作流节点，包括系统提示词、对话历史、结构化变量、知识库上下文、文件输入、流式输出、工具调用和下游解析器。既要比较供应商原始响应，也要比较最终工作流输出。
- Run provider contract tests outside production.
- Compare target and previous providers on representative app workflows.
- Canary one tenant and monitor errors, routes and accepted outputs.
- Exercise rollback and credential revocation.
- 在生产环境之外运行供应商契约测试。
- 使用具有代表性的应用工作流比较目标供应商与原供应商。
- 先灰度一个租户，监控错误、路由与被接受的输出。
- 演练配置回滚和凭证吊销。
Define acceptance thresholds before the canary. Track transport errors, first-token and total latency, schema-valid output, tool-call argument validity, token usage and task-level quality. A lower error rate is not enough if the new route drops citations, changes JSON field types or produces much longer responses that break cost assumptions.
灰度前应先定义验收阈值，至少跟踪传输错误、首 Token 延迟、总延迟、结构有效率、工具调用参数有效率、Token 用量和任务级质量。即使新路由错误率更低，如果它丢失引用、改变 JSON 字段类型，或生成明显更长的响应并打破成本假设，也不能视为通过。
Rollback must restore the full previous provider record, not only the model name. Test base URL, credential reference, capability flags, context limits, timeout, retry policy and output adapter as one versioned unit. Revoke the rejected credential after rollback so stale workers cannot continue sending traffic to the failed route.
回滚必须恢复完整的旧供应商记录，而不只是恢复模型名称。基础地址、凭证引用、能力标记、上下文限制、超时、重试策略和输出适配器应作为一个版本化单元共同回滚。回滚完成后要吊销被弃用的凭证，避免陈旧 Worker 继续向失败路由发送流量。
Treat provider configuration as code把供应商配置视为代码
Dify applications reference a stable alias. A tenant-scoped provider record holds the approved endpoint and secret. Capability tests gate promotion, telemetry preserves native evidence and configuration versions make rollback immediate.
Dify 应用引用稳定别名；租户范围内的供应商记录保存已批准的端点和凭证；能力测试控制配置晋级，遥测保留原生证据，配置版本则让回滚能够立即执行。
Store non-secret configuration in version control or a governed configuration registry. Review changes to endpoint, model mapping, context limits and capability flags like code. Secrets remain in a vault and are referenced by identifier. The deployed record should include a checksum or version so the request trace can prove which configuration was active.
非敏感配置应进入版本控制或受治理的配置注册表。端点、模型映射、上下文限制和能力标记的变更都要像代码一样经过审查；密钥继续保存在密钥库中，只通过标识符引用。部署记录还应包含校验值或版本，使请求调用链能够证明当时实际启用的是哪份配置。
Separate discovery from promotion. A provider administrator may create and test a candidate record, but production activation should require an approval or automated quality gate. This prevents a convenient dashboard edit from bypassing tenant policy, data residency or application-level regression checks.
发现与上线应当分离。供应商管理员可以创建并测试候选配置，但生产启用必须经过审批或自动质量门禁。这样可以防止一次方便的后台编辑绕过租户策略、数据驻留要求或应用级回归检查。
Production rule: never mark a capability supported until its production path has passed a contract test.
生产规则：生产路径通过契约测试前，绝不能把某项能力标记为已支持。
Add QVeris for external APIs and tools用 QVeris 接入外部 API 与工具
The custom model API supplies inference. QVeris supplies external APIs, tools, services and live data through Discover → Inspect → Call. Keep their provider records, secrets and evidence separate.
自定义模型 API 提供推理；QVeris 通过“发现 → 检查 → 调用”提供外部 API、工具、服务和实时数据。两类供应商记录、上游密钥与证据应彼此分离。
This matters when a Dify workflow moves from generating text to completing a real task. A model route may be allowed to summarize a request, while the following capability call needs a separate permission to query a filing, fetch live market data, parse a document or update an external system. Inspecting the capability before execution exposes required arguments, schema, cost, latency and permission requirements.
当 Dify 工作流从生成文本转向完成真实任务时，这种分离非常重要。模型路由可以被允许总结请求，但后续能力调用仍需要独立权限，才能查询监管申报文件、获取实时市场数据、解析文档或更新外部系统。执行前检查能力，可以提前了解必填参数、输出结构、成本、延迟和权限要求。
Join the two layers with a workflow trace rather than one shared secret. Record the Dify application and model attempt, then attach the QVeris search, capability and execution identifiers to the same trace. Operators can reconstruct the complete workflow while still rotating, revoking and budgeting inference and external actions independently.
两层应通过工作流调用链关联，而不是共用同一份密钥。先记录 Dify 应用和模型尝试，再把 QVeris 的搜索、能力与执行标识附加到同一调用链。这样运营人员既能还原完整工作流，也能分别轮换、吊销和控制推理与外部动作的预算。
Start with the provider contract Dify actually loads从 Dify 实际加载的供应商契约开始
Dify's current plugin system separates provider metadata, credential fields, model-type code, invocation, token counting, and error mapping. A custom model is not only a URL field: package the contract, validate credentials with a lightweight call, and test both streaming and non-streaming paths.
当前 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- Implement validate_credentials and map auth, rate-limit, timeout, and provider errors.
- Return normalized text, finish reason, usage, and native request identifiers.
- Remote-debug the plugin, package it, and promote one Dify application before workspace-wide rollout.
- 实现 validate_credentials，并映射认证、限流、超时和供应商错误。
- 返回标准化文本、Finish Reason、用量与原生请求 Identifier。
- 远程调试并打包 Plugin，先推广一个 Dify Application，再扩到整个 Workspace。
Verified implementation reference: Dify custom model integration.
实施参考已根据官方资料核验：Dify custom model integration。
FAQ
Use the provider contract Dify supports and verify the current integration documentation.
Prefer scoped credentials and explicit isolation unless your governance permits sharing.
Restore the previous provider config and revoke the target credential if needed.
使用 Dify 当前支持的供应商契约，并验证最新集成文档。
除非治理允许，否则优先使用受限凭证与显式隔离。
恢复旧供应商配置，并在需要时撤销目标凭证。