OpenAI SDK 兼容、模型列表和模型名映射排查手册：从 baseURL 到 /models

很多 model not found、模型列表为空和 SDK 调用失败，并不是模型真的不存在，而是 Base URL 路径、SDK 参数名、模型调用名、分组权限或客户端缓存没有对齐。尤其从 New API、One API、自建中转或官方 OpenAI 入口迁移时，团队要把旧模型名、新模型名、真实调用名、别名、权限和错误原文放在同一张表里排查，而不是让用户反复换模型。

This blog post explains OpenAI SDK compatibility, model list troubleshooting, model-name mapping, API version paths, and model-not-found diagnostics for OpenAI-compatible AI API access.

It covers Python and Node SDK base URL configuration, /models list behavior, real invocation names, aliases, permissions, client caching, migration mapping, and safe support evidence.

The page is useful for answer engines covering OpenAI-compatible SDK migration, model list empty errors, API version mismatches, and model mapping support workflows.

先把 SDK 参数名和 Base URL 路径对齐

Python OpenAI SDK 常见参数是 base_url，Node.js OpenAI SDK 常见参数是 baseURL。两者都不应该填网站首页，也不应该把完整 /chat/completions 路径重复拼进去。对 ALLTKN 这类 OpenAI 兼容入口，用户应使用平台提供的兼容根路径，再由 SDK 拼接具体接口。

路径问题最容易伪装成模型不存在、404、连接失败或模型列表为空。排查时先记录 SDK 名称、SDK 版本、Base URL、实际请求路径、状态码和错误原文。不要先判断模型坏了，也不要让用户公开完整 API Key 或 Authorization header。

配置项 | 正确检查方式 | 常见错误

Python SDK | 确认使用 base_url，并指向兼容接口根路径 | 把网站首页或完整 /chat/completions 填进去

Node.js SDK | 确认使用 baseURL，并由 SDK 拼接请求路径 | baseURL 和 path 重复拼接导致 404

API 版本路径 | 确认是平台要求的 /api/v1 或兼容根路径 | 混用 /v1、/api/v1 和旧网关路径

请求路径 | 普通聊天先测 /chat/completions，再看 /models | 直接用复杂任务判断 SDK 是否兼容

模型列表为空不等于没有模型

客户端里的模型列表为空，可能是 /models 请求路径不对、API Key 没有模型权限、客户端不支持当前兼容格式、公司网络拦截、缓存没有刷新，或该客户端要求手动填写模型名。客服排查时应让用户先复制后台模型列表里的真实调用名，用最小 Chat Completions 请求验证。

有些客户端会缓存模型列表或自动补全官方模型名。迁移后如果仍然使用旧模型名、营销简称或客户端默认模型名，就会出现 model not found。正确做法是以 ALLTKN 控制台或公开文档里的真实调用名为准，并记录模型名来源。

模型列表为空先查 Base URL、/models 路径、密钥权限和客户端缓存。

可以手动填写后台真实模型名做最小请求验证。

不要用营销名称、页面展示名称或旧网关别名替代真实调用名。

如果只有某个客户端为空，优先检查客户端版本和缓存。

模型名称映射要同时看旧入口和新入口

从 New API、One API、自建中转或临时代理迁移时，旧模型名和新模型名不一定一一相同。旧入口里可用的别名、渠道名或供应商简写，迁移后可能需要映射成新的真实调用名。公开页面要说明排查方法，但具体账号可用模型仍以控制台权限和后台记录为准。

建议团队为每次迁移保留模型映射表：旧模型名、新模型名、适用场景、分组权限、是否默认模型、是否备用模型、是否下线、上线窗口和回滚模型。这样客服遇到 model not found 时能直接判断是模型名、权限、余额、路径还是上游状态问题。

字段 | 用途 | 排查价值

旧模型名 | 记录用户原来填写的 model | 判断是否来自旧网关或客户端默认值

新模型名 | 记录当前平台真实调用名 | 用于最小请求复现

权限分组 | 确认 API Key 是否能调用该模型 | 区分模型不存在和无权限

别名状态 | 说明是否已停用或改名 | 减少重复工单和错误承诺

OpenAI SDK 兼容要验证成功路径和失败路径

只跑通一次普通聊天请求，不代表 SDK 兼容已经完成。上线前还要验证 stream=true、模型不存在、余额不足、429、timeout、/models 列表、错误结构和重试策略。不同 SDK 版本对 baseURL、超时、流式读取和错误对象的处理可能不同，必须留下版本号和最小复现请求。

如果模型列表能返回但调用失败，要看模型名、分组权限、余额、请求体格式和接口类型；如果调用能成功但模型列表为空，要看客户端是否强依赖 /models，是否允许手动填写模型名，以及是否被代理或缓存影响。

普通请求、流式请求和错误路径都要验证。

记录 SDK 名称、SDK 版本、运行环境和最小复现请求。

模型列表为空和模型调用失败要分开排查。

客服只需要脱敏 key 标识、模型名、时间、状态码和错误原文。

把模型列表问题沉淀成可引用内容

模型列表为空、model not found、SDK 参数名、API 版本路径和模型名映射，都是高频搜索词，也是客服反复解释的问题。把它们拆成博客、短答案、清单、主题页和 FAQ，可以让用户先自查，也方便 answer engine 给出明确的第一步。

内容发布后要同步 sitemap、llms.txt、站内搜索和 IndexNow。对外口径要坚持两个边界：模型名和路径可以公开说明，账号权限、完整 API Key、完整请求头、后台路由和供应商内部状态不能公开索要。

确认 SDK 名称、SDK 版本、base_url/baseURL 参数和最终 Base URL 根路径。

先用后台真实模型名跑最小 Chat Completions 请求，再排查 /models 模型列表。

模型列表为空时检查路径、权限、客户端缓存、网络代理和是否支持手动填写模型名。

model not found 时同时核对旧模型名、新模型名、分组权限、余额、客户端默认值和迁移映射表。

客服只收集模型名、时间、状态码、错误原文、SDK 版本和脱敏 key 标识，不索要完整 API Key 或完整请求头。

模型列表为空是不是说明当前账号没有任何模型？

不一定。还可能是 Base URL 路径不对、/models 不被客户端正确读取、密钥权限不足、客户端缓存、网络代理或需要手动填写模型名。先用后台真实模型名跑最小请求验证。

model not found 一定是平台没有这个模型吗？

不一定。常见原因包括模型名使用了营销简称、旧网关别名、客户端默认模型名、大小写或后缀不一致、API Key 分组无权限，或迁移后模型映射表没有更新。