很多人第一次遇到这个问题时，都会下意识怀疑 API Key 坏了：同一个 Key，Cursor 里能正常补全代码，换到 Chatbox 就提示model_not_found；Cherry Studio 里模型列表能看到，真正聊天时却报invalid_api_key；Dify 的 RAG 应用前一天还正常，今天接入向量引擎后开始context_length_exceeded；还有一些 OpenAI 兼容接口在浏览器插件里可用，放进桌面客户端就变成timeout或rate_limit。
这类问题最麻烦的地方，不是它真的复杂到无从下手，而是它表面上太像“模型不可用”。于是很多人反复换 Key、换模型、换客户端，最后把排障变成玄学。实际上，AI API 的请求链路通常有四层：客户端工具、OpenAI 兼容接口、供应商或 API 中转站、真实模型服务。如果中间再加上企业统一接入层、模型路由、日志审计、成本控制、向量引擎和 RAG 检索上下文，model_not_found就不再只是“模型名不存在”这么简单。
本文不写基础入门配置，而是围绕一个典型场景展开：同一个 API Key，为什么 Cursor 能用，但 Chatbox 报model_not_found？我们会把 Base URL、模型别名、模型路由、OpenAI 兼容接口参数差异、API Key 权限、timeout、rate_limit、context_length_exceeded、向量引擎上下文预算这些因素放在同一张排障地图里。目标不是记住某个工具的某个按钮，而是建立一套可以迁移到 Cursor、Chatbox、Cherry Studio、Dify 和企业统一接入平台的判断方法。
一、先把问题从“Key 坏了”改写成“请求被谁解释了”
当你在 Cursor、Chatbox、Cherry Studio 中填入同一个 API Key 时，你以为三者发出的请求是一样的。实际上，它们可能在以下位置发生差异：
- Base URL 是否自动补
/v1 - 模型名是手动填写，还是从
/v1/models拉取 - 是否把展示名映射成真实模型 ID
- 是否默认启用 stream
- 是否附带 OpenAI 官方特有参数
- 是否把 max_tokens、temperature、tools、response_format 传给兼容接口
- 超时时间是 30 秒、60 秒还是更短
- 错误响应是否被客户端二次包装
- 是否读取系统代理、环境变量或本地缓存
因此，同一个 API Key 在 Cursor 可用，并不能证明这个 Key 在所有工具里都可用；它只能证明“Cursor 当前构造的请求，在它选择的模型和路由下可用”。Chatbox 报model_not_found，也不能直接证明供应商没有这个模型；它只能说明“Chatbox 当前请求中的 model 字段，被接收方解释为不可用”。
排障的第一步，是把一句模糊描述改写成可验证命题：
Cursor 使用 API Key A、Base URL B、模型名 C、参数集合 D，调用成功。
Chatbox 使用同一个 API Key A，但 Base URL、模型名或参数集合可能不同，调用失败并返回
model_not_found。
这一步看似啰嗦，却能避免最常见的误判：把 API Key 当成唯一变量。AI API 接入排错里，Key 只是身份凭证，真正决定请求走向的还有 Base URL、模型 ID、供应商路由、组织权限、模型别名、请求路径和参数兼容性。
二、Base URL：尾部/v1是小字符，也是大分叉
OpenAI 兼容接口最常见的路径形态是：
https://example.com/v1/chat/completions
https://example.com/v1/chat/completions
很多客户端会让你填写 Base URL，但“Base URL 到底应该填到哪里”并不统一。有些工具希望你填：
https://api.example.com
然后它自己拼接 `/v1/chat/completions`。另一些工具希望你填： ```text https://api.example.com/v1然后它只拼接/chat/completions。如果你填错，就会出现两种典型情况：
https://api.example.com/chat/completions
https://api.example.com/v1/v1/chat/completions
前者少了/v1，后者重复了/v1。这两种情况都可能被网关返回为 404、model_not_found、Not Found，甚至被客户端包装成“模型不可用”。这就是为什么 Cursor 能用而 Chatbox 不能用：不是 Key 不同，而是路径拼接规则不同。
以技术配置备忘为例，如果某个 OpenAI 兼容接口文档写的是：
Base URL: https://api.vectorengine.cn/v1
Chat API: https://api.vectorengine.cn/v1/chat/completions
那你就要看客户端配置项的说明。如果配置项叫 OpenAI API Base URL，且示例已经包含/v1，通常应填https://api.vectorengine.cn/v1。如果配置项叫 API Host 或 Endpoint，并且工具会自动拼/v1，就可能只填根域名。判断标准不是猜，而是用最小请求确认最终访问路径。
推荐先做一个最小 curl 请求：
curl https://api.vectorengine.cn/v1/chat/completions
-H “Authorization: Bearer $API_KEY”
-H “Content-Type: application/json”
-d ‘{
“model”: “your-real-model-id”,
“messages”: [
{“role”: “user”, “content”: “ping”}
]
}’
如果这个请求成功，再回到 Cursor、Chatbox、Cherry Studio 对照它们实际填写的 Base URL。排障顺序应该是：先确认接口本身可用，再排查客户端如何拼接路径。反过来做，会被客户端 UI 牵着走。
三、模型别名：展示名、真实 ID 与路由名不是一回事
model_not_found的第二个高频原因，是把“你看到的模型名”当成了“API 接收的模型 ID”。
很多工具会显示较友好的模型名，例如：
GPT-4.1
DeepSeek V3
Claude Sonnet
Qwen Max
但 API 请求里的 model 字段可能要求：
{
“model”: “gpt-4.1”
}
或者：
{
“model”: “deepseek-chat”
}
在 API 中转站或企业统一接入层里，还可能出现第三种名字：路由别名。例如团队希望所有客户端都只填：
team-coder team-chat team-rag-long然后由网关在后台路由到不同供应商和模型。此时team-coder不是真实模型 ID，而是企业模型路由表中的别名。Cursor 里能用，是因为 Cursor 填的是team-coder；Chatbox 报错，可能是因为它自动从/v1/models拉到了真实模型名，用户又手动改成了展示名；Cherry Studio 报错，可能是因为供应商配置里模型 ID 写成了中文备注。
模型名至少有四层：
| 层级 | 示例 | 作用 |
|---|---|---|
| 展示名 | GPT-4.1 / DeepSeek V3 | 给人看 |
| 真实模型 ID | gpt-4.1 / deepseek-chat | 给 API 看 |
| 路由别名 | team-coder / rag-long | 给企业网关看 |
| 客户端缓存名 | 最近使用模型 | 给工具本地配置看 |
排查model_not_found时，关键不是问“这个模型有没有”，而是问“当前请求里的model字段到底是什么”。如果客户端能导出日志、打开开发者日志或查看请求记录，要优先看请求体。如果看不到，就用同一个 model 字段在 curl 中复现。
很多兼容接口支持/v1/models，但并不代表它返回的模型列表适合所有客户端。有些接口返回的是供应商真实模型，有些返回的是路由别名，有些为了兼容只返回少量默认模型。如果客户端强依赖模型列表，而你的网关没有实现完整/v1/models，就可能出现“列表为空、手动填写可用”或“列表可见、调用失败”的错觉。
四、Cursor 能用，不代表 Chatbox 的请求一样
Cursor 的使用场景偏代码编辑器，它的模型调用可能带有更复杂的上下文、代码片段、工具约定，也可能在某些模式下使用内置模型或独立配置。Chatbox 更像通用聊天客户端，常见配置项是 API Key、API Host、模型名、是否流式输出。Cherry Studio 则更强调多供应商管理、模型列表和知识库体验。
这三类工具的差异会带来几个排障点。
第一，模型字段来源不同。Cursor 里你可能在某个配置文件或设置页里写了模型 ID；Chatbox 可能从供应商配置里选择模型；Cherry Studio 可能有“添加模型”和“选择默认模型”两个层级。看似选择了同一个模型，实际请求体未必一致。
第二，Base URL 处理不同。有的工具会自动补/v1，有的不会；有的会将 OpenAI 类型供应商固定拼接/chat/completions，有的支持自定义完整路径。重复/v1和漏/v1都可能被误判成模型问题。
第三，参数默认值不同。Cursor 可能在代码补全中使用较短请求，Chatbox 可能带上长历史对话，Cherry Studio 可能开启知识库检索。于是同一个模型在 Cursor 成功，在 Chatbox 或 Cherry Studio 中触发context_length_exceeded，根因不是模型名，而是上下文长度。
第四，错误展示不同。供应商返回的原始错误可能是：
{"error":{"message":"The model xxx does not exist or you do not have access to it.","type":"invalid_request_error","code":"model_not_found"}}客户端可能只展示model_not_found，也可能翻译成“模型不存在”，还可能把 HTTP 404、401、429、504 都显示为一个笼统弹窗。排障时要尽量拿到原始响应，而不是只看 UI 上的一行红字。
五、invalid_api_key：Key 错了只是其中一种解释
invalid_api_key看起来比model_not_found更直接，但它也不总是“复制错了 Key”。在 OpenAI 兼容接口和 API 中转站里，API Key 往往同时承担身份、权限、余额、项目、组织、路由策略等含义。常见原因包括：
- Key 前后多了空格或换行
- 把 OpenAI 官方 Key 填到了第三方 Base URL
- 把中转站 Key 填到了 OpenAI 官方 Base URL
- Key 属于另一个项目或组织
- Key 没有目标模型权限
- Key 被企业网关限制了来源 IP、客户端或并发数
- Key 已被轮换，但客户端仍在使用旧缓存
- 代理或环境变量覆盖了客户端里的配置
这里有一个非常实用的判断方法：把 API Key 和 Base URL 当成一对，而不是两个独立字段。很多用户只确认 Key 对不对，却没有确认它应该发往哪个网关。OpenAI 官方 Key、某个 API 中转站的 Key、企业统一接入平台发放的虚拟 Key，可能长得都像sk-...，但它们的验证端完全不同。Key A 对 Base URL A 有效，不代表对 Base URL B 有效。
如果你在 Cursor 中使用企业发放的虚拟 Key，Base URL 指向企业网关；到了 Chatbox 却把 Base URL 改成 OpenAI 官方地址，就可能报invalid_api_key。反过来，把官方 Key 发到企业网关，也会失败。此时不是 Key 本身错，而是 Key 与验证入口不匹配。
团队实践里可以把这些信息记在一个配置表里：Key 名称、所属环境、Base URL、允许模型、用途、负责人、过期时间、日志位置。我的个人资料出处和接口接入备忘里也会顺手把相关入口记成一行，例如 https://178.nz/dn 这种方式只作为配置来源记录，避免团队成员在聊天记录里反复翻旧链接。
六、timeout：有时不是服务挂了，而是请求太重或流式处理不兼容
timeout通常被理解为网络问题，但在 AI API 场景里，它至少有五类原因。
第一类是网络连通性问题。客户端所在机器无法访问 Base URL，代理未生效，DNS 解析慢，TLS 握手失败，或企业网络拦截了请求。
第二类是供应商响应慢。大模型首 token 延迟较高，尤其是长上下文、复杂推理、RAG 大片段输入、多工具调用时，服务端可能还在处理，但客户端已经超时。
第三类是流式响应不兼容。某些 OpenAI 兼容接口对stream: true支持不完整，curl 非流式能成功，Chatbox 流式聊天却卡住。此时可以临时关闭 stream，确认是否为 SSE 处理问题。
第四类是客户端超时阈值过短。有些桌面工具默认 30 秒超时，长文本总结、代码分析或 RAG 检索后的回答很容易超过。Cursor 某些请求短而快，Chatbox 带着完整历史对话就慢很多。
第五类是网关队列或限流。企业统一接入层为了成本控制和并发保护，可能会排队请求。客户端看到的是timeout，日志里看到的却是排队过久或上游超时。
排查时建议用三步法：
1. 同一 Base URL，同一 Key，同一模型，用最短 prompt 测试。 2. 关闭 stream，再测试。 3. 增加输入长度，观察超时是否随 token 增加而出现。如果短 prompt 成功、长 prompt 失败，就不要继续怀疑 Key。此时应关注上下文、模型能力、网关超时、客户端超时和 RAG 检索片段数量。
七、rate_limit：限流不只看供应商，也看企业网关策略
rate_limit的直观含义是请求过多，但它也有很多层。真实模型供应商可能按 RPM、TPM、并发数、账户余额、模型等级限流；API 中转站可能按用户套餐、虚拟 Key、团队额度限流；企业统一接入层还可能按部门、项目、应用、场景、时间段做限制。
同一个 API Key 在 Cursor 能用，在 Chatbox 报rate_limit，可能是因为 Cursor 发的是短请求，而 Chatbox 带着历史对话和知识库上下文，单次消耗 token 更高；也可能是 Chatbox 开启了自动标题生成、自动总结、翻译等附加请求，表面上你只问了一次，实际发了多次 AI API 调用。
如果接入了向量引擎和 RAG，还要注意 embedding 请求与 chat 请求可能共用同一个 Key 或同一个额度池。一次知识库问答可能包含：
1. 对用户问题做 embedding 2. 向向量引擎检索相似片段 3. 拼接 RAG 检索上下文 4. 调用 chat completions 5. 可能再生成标题、摘要或追问建议用户以为只调用了一次聊天模型，日志里可能已经产生了多次 API 调用。此时rate_limit不是偶然，而是链路设计造成的额度放大。企业环境里最好把 embedding、chat、rerank、总结等用途分开统计，必要时使用不同虚拟 Key 或不同路由策略。
八、context_length_exceeded：RAG 接入后最容易被误判的错误
context_length_exceeded是很多 RAG 项目进入生产前一定会遇到的问题。它的根因很简单：最终送进聊天 API 的 tokens 超过了模型上下文窗口。但在多客户端场景里，它常常被误判成模型不可用。
假设你在 Cherry Studio 里接入知识库，向量引擎检索出 12 个片段，每个片段 800 字；客户端又带上 20 轮历史对话；系统提示词里还有角色设定、回答格式、引用规则；最后选择的模型上下文窗口只有 8K。此时即使模型 ID 正确、API Key 正确、Base URL 正确，也会失败。
RAG 检索上下文进入聊天 API 后，模型选择就不再只是“哪个模型回答质量好”，而是要同时考虑上下文预算：
总预算 = 模型上下文窗口 - 系统提示词 - 历史对话 - 用户问题 - RAG 检索上下文 - 工具调用参数 - 预留输出 tokens很多人只关注检索召回率，觉得片段越多越稳。但对聊天模型来说，检索片段越多，越容易挤占回答空间，也越容易触发context_length_exceeded。如果客户端没有清晰展示 token 预算，用户会以为“同一个模型昨天能用今天不能用”。其实昨天没有检索知识库，今天带上了大量上下文。
解决思路包括：
- 减少 top_k
- 控制单个 chunk 长度
- 对检索结果做 rerank
- 对历史对话做摘要或截断
- 给输出预留 tokens
- 为 RAG 场景选择更长上下文模型
- 将 embedding 模型和 chat 模型分开配置
- 在企业网关中为 RAG 设置单独模型路由
如果是 Dify 这类工作流平台，还要检查知识库召回、上下文模板、变量拼接、LLM 节点模型、最大 token 设置是否一致。很多时候不是 Dify 错了，而是上游兼容接口只支持某些参数，或者路由别名指向了一个上下文窗口较短的模型。
九、OpenAI 兼容不等于参数完全一致
“OpenAI 兼容接口”这几个字容易给人一种错觉：只要路径和 JSON 格式像 OpenAI，就所有客户端都能无差别使用。现实中，兼容往往分层级。
有的接口只兼容/v1/chat/completions，不支持/v1/responses。有的接口支持基础 messages，但不支持 tools。还有的接口支持 stream，但事件格式与客户端预期略有差异。常见差异包括：
response_format不支持或只支持部分模式tools/tool_choice格式不完整stream_options被拒绝max_tokens与max_completion_tokens名称差异- 多模态消息格式不兼容
- system role 被某些模型弱化或改写
/v1/models返回格式不完整- 错误码不是 OpenAI 标准结构
这就是为什么排障时要从最小请求开始。先只发：
{"model":"your-model","messages":[{"role":"user","content":"ping"}]}成功后再逐步加参数：stream、temperature、max_tokens、tools、response_format、RAG 上下文。这样你能知道是哪一个参数触发了失败。如果一开始就让客户端带着完整配置请求，错误码可能会误导你。
对于 Chatbox、Cherry Studio 这类工具，如果某个供应商兼容层比较薄，建议优先关闭高级参数，只保留模型、消息、温度和最大输出。等基础聊天稳定后，再启用流式输出、知识库、工具调用、多模态等能力。
十、供应商路由：model_not_found可能来自路由表，而不是模型库
在企业统一接入和 API 中转站里，模型路由通常是核心能力。用户在客户端填一个模型名，网关根据策略转发到不同供应商。路由规则可能包含：
- 按模型别名路由
- 按 Key 权限路由
- 按部门或项目路由
- 按成本优先路由
- 按可用性 fallback
- 按上下文长度路由
- 按地区或合规要求路由
- 按日志审计策略路由
当路由表没有配置某个别名时，网关可能返回model_not_found。这时真实供应商可能有模型，但企业网关不认识你填的别名。反过来，网关认识别名，但当前 API Key 没有访问权限，也可能返回类似错误。
建议把模型路由表设计成可审计的结构：
| 客户端模型名 | 网关别名 | 上游供应商 | 真实模型 ID | 上下文 | 权限范围 |
|---|---|---|---|---|---|
| coder-fast | team-coder | Vendor A | model-a-code | 32K | dev |
| chat-general | team-chat | Vendor B | model-b-chat | 16K | all |
| rag-long | team-rag-long | Vendor C | model-c-long | 128K | knowledge |
| cheap-summary | team-summary | Vendor A | model-a-small | 8K | ops |
这样当 Chatbox 报model_not_found时，你可以直接检查：客户端发来的model是否在路由表中；该 Key 是否允许访问这个别名；该别名当前是否启用；上游真实模型 ID 是否变更；fallback 是否配置了同等上下文能力。
没有模型路由表的团队，排障基本靠猜。有了路由表、日志审计和请求 ID，排障会变成查证据。
十一、向量引擎与聊天 API：不要把 embedding 模型当成 chat 模型
向量引擎接入后，还有一个隐蔽坑：embedding 模型、rerank 模型和 chat 模型的名字被混在一起。很多工具的模型配置页会同时出现“嵌入模型”和“聊天模型”，但用户只记得自己填了一个模型名。结果可能是：
embedding 模型被填进 chat completions chat 模型被填进 embedding 接口 rerank 模型被当作聊天模型调用这些错误可能表现为model_not_found，也可能表现为参数不兼容。因为 embedding API 通常需要 input 字段，chat API 需要 messages 字段；模型能力也不同。即使模型名存在，如果调用了错误接口，也会失败。
在 RAG 系统里应明确拆分三类配置：
Embedding：负责把问题和文档片段向量化 Vector Engine：负责相似度检索和过滤 Chat Model：负责阅读 RAG 检索上下文并回答如果使用 Dify、Cherry Studio 或自建知识库，建议为每一类配置写清楚 Base URL、API Key、模型 ID、最大输入、超时、重试策略。不要把“AI API 配好了”当成一个整体完成项。RAG 的稳定性来自每一段接口都可单独验证。
十二、用最小可复现请求建立排障基线
跨工具排障最怕“同时改很多东西”。正确做法是建立一个基线请求。这个请求应该满足：
- 不带历史对话
- 不带 RAG 上下文
- 不带 tools
- 不带 response_format
- 不启用复杂参数
- 只用一个确定模型
- 明确 Base URL
- 明确 API Key
- 明确是否 stream
示例：
curlhttps://api.vectorengine.cn/v1/chat/completions\-H"Authorization: Bearer sk-your-key"\-H"Content-Type: application/json"\-d'{ "model": "team-chat", "messages": [ {"role": "user", "content": "请只回复 ok"} ], "stream": false }'如果基线失败，看原始错误：
invalid_api_key：检查 Key 与 Base URL 是否匹配，Key 是否有效，是否有权限。model_not_found：检查 model 字段是否为真实 ID 或网关别名，路由表是否存在。rate_limit：检查额度、并发、RPM、TPM、虚拟 Key 策略。timeout：检查网络、服务端延迟、网关超时、模型冷启动。context_length_exceeded：基线一般不会出现，若出现说明系统默认注入了大量上下文或模型路由错误。
如果基线成功，再迁移到客户端。迁移时只改一个变量：先填同样的 Base URL 和 Key，再填同样的模型名，再关闭知识库和长历史，再测试非流式，再逐步打开流式、RAG、工具调用。这样可以明确是哪一步引入错误。
十三、Cursor、Chatbox、Cherry Studio 的排查清单
针对 Cursor，重点看：
- 当前使用的是哪个模型配置
- 是否使用了内置模型还是自定义 OpenAI 兼容接口
- Base URL 是否被自动拼接
- 代码上下文是否过长
- 是否有代理或环境变量影响请求
- 编辑器插件或版本是否缓存了旧配置
针对 Chatbox，重点看：
- API Host 是否需要包含
/v1 - 模型是否为手动填写的真实 model ID
- 是否启用了 stream
- 是否带了完整历史对话
- 是否自动生成标题造成额外请求
- 错误详情里有没有原始 HTTP 状态码
针对 Cherry Studio，重点看：
- 供应商类型是否选对
- Base URL 与模型列表配置是否一致
- 模型 ID 是否是 API 接收的 ID
- 知识库是否引入过长 RAG 检索上下文
- embedding 模型与 chat 模型是否混用
- 默认模型和当前会话模型是否一致
如果这三者用的是同一个 API 中转站或企业统一接入层，还要去网关日志里查请求 ID。客户端只能看到结果，网关日志才能告诉你请求被路由到哪里、用了哪个上游模型、消耗了多少 tokens、是否被限流、是否触发成本控制策略。
十四、企业统一接入：把“能用”升级成“可治理”
个人使用 AI API 时，只要能聊起来就算成功。企业场景不同，成功标准至少包括：
- API Key 不直接分发给所有人
- Base URL 统一，供应商可在后台切换
- 模型路由可审计
- 日志可追踪请求来源
- 成本可按团队、项目、模型拆分
- rate_limit 策略可配置
- 高风险模型或高成本模型有权限控制
- RAG 和向量引擎调用可单独统计
- 错误码能回溯到原始响应
这也是为什么很多团队会在 OpenAI 兼容接口前面加一层企业网关。Cursor、Chatbox、Cherry Studio、Dify 都只接入企业统一 Base URL，客户端填写统一的虚拟 API Key 和模型别名。真正的供应商 Key、模型 ID、fallback 策略、日志审计、成本控制都留在服务端。
这种做法的好处是客户端配置简单，模型切换不需要每个人改设置。缺点是网关本身必须维护好路由表和错误透明度。如果网关把所有上游错误都包装成model_not_found，排障会更难。因此企业网关应尽量保留原始错误码、上游供应商、路由别名、请求 ID 和 token 统计。
十五、一张从错误码反推原因的排障表
可以把常见错误整理成这样：
| 错误 | 优先检查 | 常见根因 |
|---|---|---|
invalid_api_key | Key 与 Base URL 是否匹配 | Key 发错入口、权限不足、缓存旧 Key |
model_not_found | 请求体 model 字段 | 模型别名错误、路由表缺失、无模型权限 |
timeout | 请求耗时和 stream | 网络问题、上下文过长、上游慢、客户端超时短 |
rate_limit | 额度和并发 | RPM/TPM 超限、虚拟 Key 限流、RAG 多次调用 |
context_length_exceeded | 总 token 预算 | 历史对话过长、检索片段过多、模型上下文太短 |
这张表不是为了替代日志，而是为了让排障有先后顺序。遇到错误时先不要换客户端，也不要马上换 Key。先固定 Base URL、API Key、model、messages，拿到最小请求的结果，再逐步恢复真实场景。
十六、一个完整排障案例
假设团队使用统一 AI API 网关，给研发同学发放一个虚拟 API Key。Cursor 里配置：
Base URL: https://api.vectorengine.cn/v1 Model: team-coder使用正常。某位同学把同样 Key 填到 Chatbox，模型名填成“GPT-4.1”，结果报model_not_found。排查过程如下：
第一步，用 curl 调用team-coder，成功。说明 Key、Base URL、网关和路由别名至少在最小聊天场景可用。
第二步，用 curl 调用GPT-4.1，失败并返回model_not_found。说明 Chatbox 里填的不是网关认识的模型 ID，而是展示名。
第三步，查看网关路由表，发现只开放了team-coder、team-chat、team-rag-long三个别名，没有开放真实上游模型名。于是把 Chatbox 模型名改成team-chat，基础聊天成功。
第四步，开启 Chatbox 历史对话和知识库后，又出现context_length_exceeded。查看请求日志，发现 RAG 检索上下文过长，top_k 为 20，每个 chunk 约 1000 字。把 top_k 降到 6，并改用team-rag-long路由，问题消失。
第五步，Cherry Studio 中 embedding 失败。继续查配置，发现 embedding 模型也填了team-chat。改为专门的 embedding 路由别名后恢复。
这个案例说明，最初的model_not_found只是入口问题，后续还会暴露上下文预算和模型用途拆分问题。真正可靠的排障不是“修一个报错”，而是把整条链路整理清楚。
十七、给团队的一套配置命名建议
为了减少跨工具误解，建议不要让用户直接填写上游真实模型名，而是用场景化别名：
team-chat team-coder team-rag-long team-summary team-embed team-rerank这些名字不绑定具体供应商，便于后台切换。命名时要避免过度营销化，也不要把模型版本写死在客户端。比如gpt-x-latest这类名字在版本升级后容易混乱，而team-rag-long更能表达用途。
同时建议在文档里明确：
聊天模型：用于 /v1/chat/completions 嵌入模型：用于 /v1/embeddings 重排模型：用于 rerank 接口 长上下文模型：用于 RAG 检索上下文较长的问答 代码模型：用于 Cursor 等代码场景当用户在 Chatbox 或 Cherry Studio 中新增模型时，只需要照表填写，不必理解所有上游供应商细节。企业网关则通过日志审计和成本控制保证后端可治理。
十八、结论：不要只盯着错误码，要盯着请求链路
同一个 API Key，Cursor 能用但 Chatbox 报model_not_found，最常见原因不是 Key 神秘失效，而是请求链路发生了变化。Base URL 可能拼错，/v1可能重复或缺失，模型展示名可能被当成真实 ID，企业模型路由表可能没有对应别名，客户端可能附带了不兼容参数，RAG 检索上下文可能把模型上下文窗口挤爆。
OpenAI 兼容接口的价值，是让不同工具以相似方式接入 AI API；但“兼容”不等于所有路径、参数、模型名和错误处理完全一致。越是多端工具、多供应商、多模型路由、多向量引擎的场景，越需要用最小可复现请求建立基线，再逐层恢复真实配置。
最后可以记住一句排障口诀：
先验 Key 与 Base URL，再验 model 字段； 先跑最小请求，再回客户端； 先看原始错误，再看 UI 文案； RAG 先算上下文预算，再谈模型质量； 企业接入先建路由表，再分发配置。当你把invalid_api_key、model_not_found、timeout、rate_limit、context_length_exceeded都放回请求链路里，它们就不再是零散报错，而是定位系统边界的信号。Cursor、Chatbox、Cherry Studio、Dify、向量引擎和企业 API 网关都可以共存，前提是每一层都知道自己该接收什么、转发什么、记录什么，以及在失败时把证据留下来。
但客户端可能要求你填https://api.vectorengine.cn/v1，也可能要求只填根域名。如果漏掉/v1或变成/v1/v1，就可能被包装成model_not_found或普通 404。
第二步检查模型名。你在界面里看到的“GPT-4.1”“DeepSeek V3”可能只是展示名，API 需要的是真实模型 ID；企业统一接入或 API 中转站还可能要求填写路由别名，例如team-chat、team-coder、team-rag-long。Cursor 能用，可能是因为它填的是路由别名；Chatbox 报错，可能是因为你填了展示名。
第三步用最小请求验证：
curlhttps://api.vectorengine.cn/v1/chat/completions\-H"Authorization: Bearer sk-your-key"\-H"Content-Type: application/json"\-d'{ "model": "team-chat", "messages": [{"role": "user", "content": "ping"}], "stream": false }'如果这里返回invalid_api_key，优先检查 Key 和 Base URL 是否属于同一个平台。如果返回model_not_found，检查模型 ID、模型别名和模型路由表。如果最小请求成功，再回到客户端逐项恢复 stream、历史对话、知识库、tools 等功能。
timeout不一定是服务挂了，可能是长上下文、流式响应不兼容、客户端超时时间太短或上游排队。rate_limit也不只看供应商额度，企业网关、虚拟 Key、RAG 多次调用都会触发限制。
接入向量引擎后，还要特别注意context_length_exceeded。RAG 检索上下文、历史对话、系统提示词和预留输出 tokens 都会占用模型窗口。检索片段越多，不代表回答越稳，反而可能把聊天 API 挤爆。Dify、Cherry Studio 或自建知识库里，应把 embedding 模型、chat 模型、rerank 模型分开配置。
团队场景建议统一 Base URL、统一模型别名、统一日志审计和成本控制。客户端只填企业网关发放的虚拟 API Key 和模型别名，真实供应商 Key、模型路由、fallback 策略放在后端维护。我的配置备忘里也会把资料入口单独记录，例如 https://178.nz/dn，避免把 Key、模型名和接口说明散落在聊天记录里。
排障口诀很简单：
先验 API Key 与 Base URL； 再看 model 字段； 先跑最小 curl； 再回 Cursor、Chatbox、Cherry Studio； RAG 场景先算上下文预算。把model_not_found放回请求链路里看，它就不再是玄学错误，而是模型别名、供应商路由、OpenAI 兼容接口参数差异或上下文预算问题的定位信号。
