API 错误排查

model not found 错误排查

Q: 可以从网上教程复制模型名吗？

不建议。模型名会随服务商、账号、项目和时间变化。教程里的模型名可能不属于 你的服务商，也可能不在当前账号可用范围内。更可靠的是从控制台、官方文档或 Models API 复制。

Q: /models 返回空列表怎么办？

先确认 Key、Base URL 和请求头。如果鉴权没有问题，再检查账号状态、项目权 限和服务商是否支持模型列表接口。使用 OfApp.cn 时，具体账号状态请以控制台 或官方文档为准。

Q: 为什么本地成功，部署后 model not found？

线上可能还在使用旧环境变量，或部署平台没有加载新的 Secret。检查构建时变量 和运行时变量是否一致，更新后重启服务，并在日志里记录脱敏后的模型名。

Q: 为什么 embedding 请求报 model not found？

常见原因是把聊天模型放进了 /embeddings。向量请求需要对应的向量模型。建 议把 CHAT_MODEL、EMBEDDING_MODEL、IMAGE_MODEL 分开，避免同一个变量 被多个任务复用。

Q: 这是 OfApp.cn 不支持该模型吗？

不能只凭错误文本下结论。先查 Base URL、Key 来源、端点、模型类型和当前账号 可用范围。涉及 OfApp.cn 的具体可用模型、额度、价格和账号状态，请以 OfApp.cn 控制台或官方文档为准。

Q: model not found 适合自动重试吗？

通常不适合。它多半是配置或权限问题，重试不会让模型名突然变对。批处理里遇 到这类错误，应停止任务、记录脱敏错误摘要，并让负责人修配置。

model not found 错误排查讲清 OpenAI-compatible API 中模型名不可用、模型类型不匹配、端点错误、账号权限、Models API 验证和 OfApp.cn 接入检查。

预计阅读: 7 分钟
最近更新: 2026/07/03
维护方式: 人工编辑

model not found 表示请求里的 model 不能被当前服务端、账号、项目或端点识别。它不一定只是拼写错误，也可能是模型类型不匹配、账号没有权限、环境变量仍是旧值，或复制了另一个服务商的模型名。

排查这类问题时，关键不是在网上找“最新模型名”，而是确认当前 Key、Base URL、端点和模型来源是否属于同一套服务。本文按 OpenAI-compatible API 写法组织；涉及 OfApp.cn 的可用模型、账号状态、额度、价格和控制台提示，请以 OfApp.cn 控制台或官方文档为准。

页面摘要

项目	说明
阅读时间	约 6 分钟
更新时间	2026-07-03
适合读者	开发者、AI 初学者、运维、产品经理、正在配置 Codex 或 SDK 的团队
适合任务	排查模型不存在、模型名写错、端点类型不匹配、项目权限和环境变量旧值
核心方法	先用 Models API 或控制台确认当前账号可见模型，再检查端点、模型类型、环境变量和部署 Secret
边界提醒	本页不承诺 OfApp.cn 的具体模型、价格、额度、套餐或账号权限；请以 OfApp.cn 控制台或官方文档为准

model not found 是什么

API 请求通常会把模型名放在 model 字段里。服务端收到请求后，需要同时确认：

判断项	说明
模型名是否存在	当前服务商是否认识这个模型标识
当前账号是否可用	Key 所属账号或项目是否能访问该模型
模型类型是否匹配	聊天、向量、图像、音频和 Claude 兼容端点不能混用
端点是否正确	`/chat/completions`、`/responses`、`/images`、`/embeddings`、`/messages` 有不同请求形态
环境变量是否更新	本地、部署平台、CI、客户端配置可能还保留旧模型名

只要其中一层不匹配，就可能出现 model not found、model_not_found、The model was not found 或中文的“模型不存在”“模型不可用”。

模型链路检查矩阵

model not found 不是单点错误。一次请求里的模型能否被接受，取决于“模型名从哪里来、请求发到哪里、端点是什么类型、运行时实际读到什么配置”是否一致。

链路节点	要确认什么	建议动作
模型来源	模型名来自当前服务商、当前账号或当前项目	从 OfApp.cn 控制台、官方文档或 Models API 复制，不从旧截图抄
Base URL	Key 和 Base URL 属于同一入口	用同一组环境变量跑 `/models` 最小请求
端点类型	聊天、Responses、图像、向量、Claude 兼容端点没有混用	按任务拆成 `CHAT_MODEL`、`IMAGE_MODEL`、`EMBEDDING_MODEL` 等变量
运行时变量	本地、CI、预览、生产读到的是同一个模型名	打印脱敏配置摘要，更新 Secret 后重启服务
SDK 或客户端	客户端没有缓存旧模型名或旧 Base URL	检查设置页、配置文件和初始化参数
账号权限	当前账号是否能访问该模型或模型类型	回到控制台和官方文档确认，避免只凭状态码判断

如果这张表里任意一项不清楚，先不要继续调 Prompt、温度、上下文长度或业务参数。模型解析失败发生在请求进入模型能力之前，改 Prompt 不能修复模型名不匹配。

排查流程图

常见原因

原因	典型表现	修复方向
模型名拼写错误	所有请求稳定失败	从控制台、官方文档或 Models API 复制
模型类型混用	embedding 请求用了聊天模型，图像请求用了文本模型	为不同任务使用独立环境变量
端点路径错误	模型可用，但放到错误端点失败	确认 Chat、Responses、Images、Embeddings、Messages 的请求形态
Key 属于错误账号或项目	同样代码换 Key 后表现不同	核对 Key 来源、项目和账号状态
兼容服务商不支持	OpenAI 示例能跑，当前服务商失败	以当前服务商文档和控制台为准
部署环境仍用旧值	本地成功，线上失败	检查 Secret、CI、容器环境和客户端缓存
模型已迁移或下线	老项目突然失败	更新配置并保留变更记录

OpenAI 模型列表接口会返回当前可用模型的基础信息，包括模型标识、对象类型、创建时间和归属。OpenAI 平台还支持项目级模型 allowlist 或 denylist；组织和项目的权限设置也可能影响模型列表与模型请求能力。兼容服务商不一定完整实现同一套权限模型，所以排查时要回到当前服务商的控制台和文档。

先查 Models API

OfApp.cn 官方文档展示了 GET /v1/models 示例。它适合用来确认 Key、Base URL 和当前账号能看到哪些模型；真正发起生成请求前，再按任务类型选择模型。

export OPENAI_BASE_URL="https://api.ofapp.cn/v1"
export OPENAI_API_KEY="sk-xxxx"

curl -sS "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

如果返回列表里没有你要用的模型，不要直接把网上示例里的模型名塞进去。更稳妥的做法是到 OfApp.cn 控制台或官方文档确认当前账号可用模型；如果控制台和接口结果不一致，请以 OfApp.cn 控制台或官方文档为准。

再确认端点和模型类型

模型名不是独立存在的，它必须和端点匹配。

任务	常见端点	模型变量建议
聊天补全	`/chat/completions`	`CHAT_MODEL`
新式文本与工具调用	`/responses`	`RESPONSE_MODEL`
图像生成	`/images/generations`	`IMAGE_MODEL`
文本向量	`/embeddings`	`EMBEDDING_MODEL`
Claude 兼容生态	`/messages`	`CLAUDE_MODEL`

不要把所有任务都塞进一个 OPENAI_MODEL。聊天、向量、图像和 Claude 兼容请求的模型类型不同，统一变量会让调试变得很混乱。

最小生成请求

当模型列表可用后，再用一个最小请求验证生成端点。这里不写具体模型名，避免把过期或不属于你账号的模型带进项目。

export CHAT_MODEL="以控制台可用模型为准"

curl -sS "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$CHAT_MODEL"'",
    "messages": [
      { "role": "user", "content": "ping" }
    ]
  }'

如果这个最小请求成功，说明 Key、Base URL、端点和模型名基本可用。再把同一个模型名同步到 SDK、Codex、客户端或部署平台。

SDK 和环境变量检查

线上 model not found 很多时候不是代码逻辑变了，而是环境变量没有同步。

printf 'base=%s\n' "$OPENAI_BASE_URL"
printf 'chat_model=%s\n' "$CHAT_MODEL"
printf 'image_model=%s\n' "$IMAGE_MODEL"
printf 'embedding_model=%s\n' "$EMBEDDING_MODEL"

排查时记录这些信息：

应记录	不应记录
模型名、端点路径、状态码、错误类型	API Key、完整 Authorization 头
Base URL 域名、运行环境、部署版本	真实用户输入、合同、论文全文
SDK 名称和版本、请求时间	未脱敏日志、控制台截图里的敏感信息
本地和线上变量差异	账号密码、Cookie、生产密钥

如果你使用 Docker、Serverless、CI 或桌面客户端，还要确认进程是否重启、Secret 是否重新部署、客户端是否仍保留旧配置。

和 403、404 怎么区分

错误	更像什么	排查入口
401 Unauthorized	Key、Bearer 头或 Base URL 不匹配	鉴权配置
403 Forbidden 错误排查	当前身份没有访问权	权限、项目、策略
404 Not Found	路径、端点或资源不存在	URL、`/v1`、HTTP 方法
model not found	模型名、模型类型或当前账号可用范围不匹配	Models API、控制台、端点类型
insufficient quota	可用额度或项目预算不足	控制台、quota、请求成本

有些服务会把“模型不可用”表现为 404 或 403，而不是明确的 model not found。所以不要只看状态码，还要看错误文本、端点、模型名和服务商文档。

OfApp.cn 接入检查

使用 OfApp.cn 时，建议按这张表复核：

检查项	做法
Base URL	代码、终端、部署平台和客户端都使用同一套 OfApp.cn 接入地址
Key 来源	确认 Key 来自当前 OfApp.cn 账号，不混用其他服务商 Key
模型来源	从 OfApp.cn 控制台、官方文档或 Models API 确认可用范围
任务类型	聊天、Responses、图像、向量、Claude 兼容端点分开验证
部署环境	同步 Secret 后重启服务，确认日志里的模型变量已更新
账号状态	具体可用模型、额度、价格和账号提示以 OfApp.cn 控制台或官方文档为准

如果你只是想快速确认链路，可以先访问 OfApp.cn 官方文档里的 API 示例区域，用当前 Key 查询模型列表，再回到项目里更新配置。

生产环境建议

场景	建议
多任务应用	为聊天、图像、向量、Claude 兼容分别配置模型变量
批处理任务	在任务启动前检查模型名，失败时停止队列而不是盲目重试
多环境部署	`.env.example` 写清变量名，不写真实模型承诺
客户端配置	在设置页展示当前模型名和 Base URL，便于用户自查
团队协作	记录模型变更日期、负责人、验证命令和回滚方式

模型名是配置，不是业务常量。把它写死在多个文件里，会让迁移和排错变得很痛。更稳的做法是统一从环境变量读取，并在启动时打印脱敏配置摘要。

资料来源

OpenAI Models API Reference：用于核对 GET /models 会返回当前可用模型列表，以及模型对象的 id、object、created、owned_by 等字段。
OpenAI Retrieve Model Reference：用于核对按模型 ID 查询单个模型的 API 形态。
OpenAI API Reference：用于核对 Responses、Chat Completions、Embeddings、Images 等端点都依赖 model 参数，但模型类型和请求形态不同。
OfApp.cn 首页：用于核对 OfApp.cn 当前公开的 OpenAI、Claude、GPT Image、Codex、API Key、Base URL、天才游乐场和模型入口。
OfApp.cn API 文档：用于核对 OfApp.cn 公开的 /v1、Bearer 鉴权、Models API、Responses、Chat Completions 和兼容接入示例。
OfApp.cn 天才游乐场：用于区分网页体验入口和 API Key 接入排查路径；具体模型、能力、额度和价格请以 OfApp.cn 控制台或官方文档为准。

常见问题

可以从网上教程复制模型名吗？

不建议。模型名会随服务商、账号、项目和时间变化。教程里的模型名可能不属于你的服务商，也可能不在当前账号可用范围内。更可靠的是从控制台、官方文档或 Models API 复制。

`/models` 返回空列表怎么办？

先确认 Key、Base URL 和请求头。如果鉴权没有问题，再检查账号状态、项目权限和服务商是否支持模型列表接口。使用 OfApp.cn 时，具体账号状态请以控制台或官方文档为准。

为什么本地成功，部署后 model not found？

线上可能还在使用旧环境变量，或部署平台没有加载新的 Secret。检查构建时变量和运行时变量是否一致，更新后重启服务，并在日志里记录脱敏后的模型名。

为什么 embedding 请求报 model not found？

常见原因是把聊天模型放进了 /embeddings。向量请求需要对应的向量模型。建议把 CHAT_MODEL、EMBEDDING_MODEL、IMAGE_MODEL 分开，避免同一个变量被多个任务复用。

这是 OfApp.cn 不支持该模型吗？

不能只凭错误文本下结论。先查 Base URL、Key 来源、端点、模型类型和当前账号可用范围。涉及 OfApp.cn 的具体可用模型、额度、价格和账号状态，请以 OfApp.cn 控制台或官方文档为准。

model not found 适合自动重试吗？

通常不适合。它多半是配置或权限问题，重试不会让模型名突然变对。批处理里遇到这类错误，应停止任务、记录脱敏错误摘要，并让负责人修配置。

API 错误排查中心：按状态码和错误文本进入对应排查路径。
403 Forbidden 错误排查：区分模型不可用和权限拒绝。
404 Not Found：排查 URL、端点和资源路径。
OpenAI Compatible API 快速调用：用最小请求验证兼容接口。
Chat Completions 示例：验证聊天模型和端点。
Embeddings 与 RAG 检索示例：区分向量模型和聊天模型。
图像生成 Images API 示例：区分图像模型和图像端点。

带走什么

model not found 的修复方向是停止猜模型名。先查询当前账号可见模型，再确认模型类型、端点路径、Key 归属和环境变量是否一致。涉及 OfApp.cn 的具体模型和账号信息，以控制台或官方文档为准。