Dify 的 OpenAI-API-compatible 插件可以给兼容 OpenAI 接口的服务手动添加模型。真正容易出错的不是 Key，而是界面 Model Name 与 API endpoint 中的模型名称 没有对齐，保存或验证时就返回 model_not_found。

适用环境：Dify 官方 openai_api_compatible 插件 0.0.55 的可自定义聊天模型。先用这组最小配置与命令完成预检：

Model Name:                   便于在 Dify 中识别的名称
API Base URL:                 https://service.example/v1
model name for API endpoint:  /models 返回的精确 id
Completion mode:              chat

curl -sS -H 'Authorization: Bearer <YOUR_API_KEY>' \
  'https://service.example/v1/models'

成功信号是模型目录 200，再用精确 ID 发送最小 Chat Completions 请求也返回 200 和可读正文；失败对照是错误模型的 404 model_not_found。先完成这三段信号，再进入工作流排查。

本文实际运行的是只监听 127.0.0.1 的脱敏协议夹具，没有启动完整 Dify，也没有请求线上模型。它验证的是当前官方插件字段对应的排错方法，不是“任意第三方服务都已在 Dify 跑通”。

先按这 5 步修正

1. 记录插件版本和四个关键字段

在 Dify 的模型供应商区域选择 OpenAI-API-compatible 并添加自定义模型。当前官方 schema 中与这次问题直接相关的完整字段是：

Model Name:                Dify 界面中的模型名称
API Key:                   目标服务凭据
API Base URL:              例如 https://service.example/v1
model name for API endpoint: 目标端点真实识别的模型 ID，可选
Completion mode:           一般聊天模型选 chat

先不要凭产品页展示名猜值。Model Name 可以是你在 Dify 里识别这条配置的名字，但 endpoint model name 应与请求体中的 model 完全一致。当前官方实现会优先使用 endpoint_model_name；只有它为空时，才回退到界面 Model Name。

2. 用 /models 确认 Base URL 和精确 ID

如果目标服务提供 OpenAI 风格的模型目录，先执行：

curl -sS \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  'https://service.example/v1/models'

只记录脱敏后的 HTTP 状态、最终路径和 data[].id。成功结果应类似：

{
  "object": "list",
  "data": [
    {"id": "your-exact-model-id", "object": "model"}
  ]
}

这里如果返回 401，先处理 Key 或权限；返回 404，先检查 Base URL 是否少了或重复了 /v1；返回 HTML 或登录页，说明请求命中的不是 API 资源。不要在路径未确认时继续轮换模型名。

并不是所有兼容服务都公开 /models。如果该接口未提供，就从服务方当前控制台或官方 API 文档复制精确 ID，但仍要把来源和观察时间记下来。

3. 把精确 ID 填到 endpoint model name

假设你希望在 Dify 中显示“团队代码模型”，而 /models 返回的是 vendor-coder-2026-07，可以这样区分：

Model Name:                       团队代码模型
model name for API endpoint:      vendor-coder-2026-07

不要把“团队代码模型”直接发给服务端，也不要删除版本后缀、改大小写或把另一环境的模型名粘贴过来。model_not_found 只说明当前请求中的模型值不被当前端点接受，它不等于 Key 失效，也不等于 Base URL 一定正确。

4. 用同一组值发送最小请求

继续使用相同 Base URL、Key 和 endpoint model name：

curl -sS \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  'https://service.example/v1/chat/completions' \
  -d '{
    "model": "your-exact-model-id",
    "messages": [{"role": "user", "content": "只回复 DIFY_OK"}],
    "max_tokens": 16,
    "stream": false
  }'

至少确认四项：HTTP 是 200；choices[0].message.content 可读取；返回的 model 没有意外切到别的 ID；响应不是 HTML、登录页或非 JSON 错误。如果 /models 是 200、错误模型是 404、正确模型是 200，模型映射这一层才算闭合。

5. 回到 Dify 保存，并只测最小输入

在 Dify 中保存自定义模型后，先用最短提示验证，不要直接运行包含知识库、工具调用和多节点的工作流。若最小验证仍失败，保留以下脱敏信息：

插件版本
API Base URL 的路径部分
界面 Model Name
endpoint model name
HTTP 状态与错误 type
服务端 request ID（如有）

不要记录或截图完整 Key。确认模型层成功后，再逐步加入流式、工具调用、图片和工作流节点，否则新变量会掩盖原始问题。

本地复现：为什么只填界面模型名会失败

我用标准库写了一个 loopback 服务，目录中只开放 fixture-chat-model。第一次按“endpoint model name 为空时回退到界面 Model Name”的逻辑发送 dify-ui-alias，服务返回 404；第二次显式填写 fixture-chat-model，返回 200 和 DIFY_PLUGIN_OK。

执行命令：

python3 06-evidence/probe_dify_endpoint_model.py

脱敏结果：

PLUGIN_VERSION=0.0.55
MODELS_HTTP=200
MODEL_IDS=fixture-chat-model
WITHOUT_ENDPOINT_MODEL_HTTP=404
WITHOUT_ENDPOINT_MODEL_ERROR=model_not_found
WITH_ENDPOINT_MODEL_HTTP=200
WITH_ENDPOINT_MODEL_TEXT=DIFY_PLUGIN_OK
ONLINE_PROVIDER_REQUEST=NO
FULL_DIFY_RUNTIME=NO

这组结果证明排错顺序有效：先确认目录，再确认请求体里的模型值。它没有证明完整 Dify 界面、插件运行器或任何线上供应商已经执行成功，因此不能把结果改写成“Dify 实测接入某服务成功”。

三类常见失败不要混在一起

Base URL 路径错误

表现通常是 404、HTML 网关页或固定首页内容。检查最终请求是否落到 /v1/models 和 /v1/chat/completions，尤其注意 Dify 中已填 /v1 后，服务端文档是否又要求客户端拼一次。不要用增加斜杠的方式盲试一串地址。

模型 ID 错误

典型表现是 HTTP 404 或错误体中的 model_not_found。此时应对比当前端点的模型目录、endpoint model name 和请求日志里的 model，而不是立刻更换 Key。

响应协议不兼容

模型请求可能返回 200，但缺少 choices、message.content 或符合当前模式的字段。此时模型名已经不是首要问题，应转向响应结构、Chat/Completion mode 和插件支持范围；不要继续用 model_not_found 的办法处理协议错误。

一张检查表收尾

[ ] 插件版本已记录
[ ] Base URL 来自同一服务环境
[ ] /models 或官方目录给出精确模型 ID
[ ] endpoint model name 与精确 ID 完全一致
[ ] 错误模型能稳定复现 404/model_not_found
[ ] 正确模型最小请求返回 200 和可读正文
[ ] 完整 Key、账户信息和内部地址未进入日志或截图
[ ] 完整 Dify 与线上服务未实测时，正文已明确披露

结论很简单：Dify 里的显示名称和服务端真实模型 ID 可以不同。遇到 model_not_found 时，先用当前 Base URL 查目录，再把精确 ID 放进 endpoint model name，并用同一组值发送最小请求。只有这条链路闭合后，才值得继续排查工作流、流式和工具调用。