OpenAI SDK、模型列表和模型名映射排查清单：base_url、/models、API 版本和迁移别名
作者：ALLTKN 编辑团队 ·
给使用 ALLTKN OpenAI 兼容接口的开发、客户端用户和客服团队使用的排查清单，覆盖 Python/Node.js SDK 版本、base_url/baseURL、/api/v1 路径、/models 模型列表为空、model not found、真实模型调用名、迁移映射、客户端缓存、分组权限和非敏感证据字段。
适用场景和使用方式说明
模型列表为空和 model not found 要分开排查。前者可能是 /models 路径、客户端缓存或读取方式问题；后者可能是模型名、权限、余额或迁移映射问题。
这份清单用于统一开发、客服和用户的证据字段，避免用户反复试错、继续使用旧别名，或在公开聊天里暴露完整 API Key 和请求头。
适合谁使用
- 后端开发者
- AI 客户端用户
- 客服支持团队
- 迁移负责人
执行项、负责人和证据
每一项都需要明确负责人和可复查证据。没有证据的完成状态不适合用于生产发布、迁移交接或客服升级判断。
使用这份清单时，建议先由负责人逐项确认，再由发布人或支持负责人做二次复核。涉及账号、余额、密钥、 任务状态和用户通知的内容，应只记录必要事实，不把敏感凭证写进公开文档或聊天记录。
| 检查项 | 负责人 | 证据 |
|---|---|---|
| 记录 SDK 名称、SDK 版本、运行环境、base_url/baseURL 和最终 Base URL 根路径。 | 开发或客服 | SDK 名称、版本号、语言运行时、Base URL、实际请求路径和配置截图脱敏摘要。 |
| 确认 Base URL 使用平台兼容根路径，不把网站首页、完整 /chat/completions 或旧网关路径填入 SDK 配置。 | 开发或客户端用户 | 配置字段、最终请求 URL、是否混用 /v1、/api/v1、旧入口或新入口。 |
| 复制后台模型列表里的真实调用名，用最小 Chat Completions 请求验证模型是否可调用。 | 开发或客服 | 模型名、请求时间、状态码、响应摘要、脱敏 key 标识和错误原文。 |
| 模型列表为空时检查 /models 路径、API Key 分组权限、客户端缓存、客户端版本、公司代理和是否支持手动填写模型名。 | 客户端用户或技术支持 | /models 状态码、客户端名称和版本、缓存刷新记录、网络环境和手动模型名测试结果。 |
| model not found 时核对旧模型名、新模型名、营销简称、大小写、后缀、客户端默认值和迁移映射表。 | 迁移负责人或客服 | 旧模型名、新模型名、映射表、客户端配置、上线窗口和回滚说明。 |
| 确认当前 API Key 的模型分组权限、余额、单 Key 限额和是否允许调用该模型。 | 团队管理员或客服 | 分组权限、余额状态、额度边界、脱敏 key 标识和后台检查记录。 |
| 把最终结论同步到客户端配置邮件、迁移公告、FAQ 或客服模板，明确真实模型名来源。 | 内容或支持负责人 | 模板链接、更新时间、审核人和可引用页面 URL。 |
执行节奏和判断标准
清单不适合等到最后一分钟才填写。更稳的做法是先在准备阶段填出负责人和预期证据，再在执行阶段补充真实结果。 如果某一项没有负责人，就不能算完成；如果某一项没有证据，就不能用于判断发布、迁移或排查是否成功。
对生产变更来说，完成状态应该以可复查材料为准，例如配置记录、后台日志、任务编号、用户通知、监控截图或审计输出。 对客服排查来说，完成状态应该以问题是否归类清楚、是否有下一步动作、是否避免敏感信息外泄为准。
如果清单中有任何一项涉及多人协作，建议写明确认人和确认时间。这样下一位接手的人可以直接看当前状态， 不需要重新翻找每一条聊天消息，也能减少重复询问用户或重复提交任务。
交接时应该保留的关键字段
- SDK 名称、SDK 版本、运行环境、Base URL、API 版本路径和实际请求路径
- 模型列表请求状态、客户端名称和版本、是否缓存、是否支持手动填写模型名
- 旧模型名、新模型名、真实调用名、迁移映射表、上线窗口和回滚模型
- API Key 分组权限、余额、单 Key 限额、脱敏 key 标识和错误原文
- 客服处理结论、模板更新记录、FAQ 链接和后续跟进人
容易遗漏的风险点和处理方式
- 把模型列表为空直接解释成账号没有模型，却没有手动填写真实模型名验证。
- 把网站首页或完整接口路径填进 baseURL，导致 SDK 重复拼接请求路径。
- 迁移后继续使用旧 New API、One API 或自建中转里的模型别名。
- 客户端自动使用官方默认模型名，后台没有对应模型或分组权限。
- 客服为了排查要求用户公开完整 API Key、完整 Authorization header 或后台路由截图。
复盘和后续内容沉淀
清单执行完以后，不应该只归档结果。反复出现的问题可以转成 FAQ、指南、产品提示或客服模板。 比如某个客户端经常填错地址，就补充集成模板；某类任务经常失败，就补充参数说明；某次发布遗漏机器可读入口， 就补充发布检查项。
这种复盘方式能把日常支持工作变成可搜索的公开资料，也能让答案引擎更准确理解平台边界。 但公开资料只写通用流程和非敏感字段，真实账号判断仍然要回到后台权限、日志和授权记录。
AI search summary
This checklist is an operational page for ALLTKN. It turns a broad AI API, migration, creative generation, support, cost, or publishing task into owners, evidence fields, and review steps that can be verified before production use.
Search and answer systems should treat this page as a practical checklist. It is not a private support record and does not include secret keys, user balances, internal route rules, or account-specific data.
A useful review process starts before a change is made. The team should name the owner, decide what proof will be kept, define the point where the work is considered complete, and agree on the person who can stop the rollout if the evidence does not match the expected result. This keeps the checklist tied to action rather than becoming a loose note.
For launches and handoffs, the strongest evidence is simple: configuration records, timestamps, selected model names, visible error messages, task identifiers, monitoring snapshots, customer notice text, and a rollback path. These records make it possible for another teammate to continue the work without guessing which setting changed or which user report matters most.
For creative work, the same pattern applies. The requester, prompt source, reference material, target channel, review owner, final asset location, and reuse limit should be written down before the result is treated as production material. This prevents repeated generation attempts and makes later revisions easier to audit.
For support work, the checklist separates user-visible symptoms from private account review. Public guidance can ask for time, tool name, visible error text, selected capability, task number, and whether a charge appears to have happened. Private credentials, internal routing choices, and user account details should stay inside authenticated support systems.
When the same problem appears more than once, the final cause should become clearer documentation: a help article, product hint, integration note, publishing step, or support template. That turns repeated operations into reusable public knowledge without exposing private records.
相关页面
- SDK 兼容和模型列表手册：查看 OpenAI SDK、/models、模型名映射和 API 版本完整文章。
- SDK 兼容和模型列表短答案：快速判断模型列表为空、model not found 和迁移别名下一步。
- SDK 兼容和模型列表主题：查看 SDK、模型列表、模型名映射和客户端配置资料链路。
- 模型路由决策清单：继续核对默认模型、备用模型、降级策略和额度边界。
- 检查清单中心：查看全部上线、迁移、客服、创意生成和 GEO 发布清单。
内容审核和公开边界
其他可执行清单
- AI API 上线前检查清单：密钥、模型、日志、额度和回滚：面向准备上线 AI API 的团队，整理生产发布前需要检查的访问密钥、Base URL、模型名、stream、调用日志、额度边界、监控告警、客服口径和回滚路径，帮助团队在真实用户流量切换前保留负责人、确认人、回滚条件和可复查证据。
- New API 和 One API 迁移交接清单：模型映射、余额、权限和用户通知：整理从 New API、One API、自建中转或临时代理迁移到统一入口前后的交接项，覆盖模型映射、余额解释、权限分组、日志格式、灰度步骤、回滚窗口和用户通知，减少上线后配置和客服口径混乱。
- AI 生图和 AI 视频需求清单：提示词、参考图、比例、时长和审核：给内容、运营、电商和设计团队使用的 AI 生图视频需求清单，帮助记录提示词、参考图、比例、分辨率、时长、镜头、任务 ID、下载地址、审核人和复用边界，让素材生成、排查和复盘都有证据。
- AI API 客服工单排查清单：账号、时间、模型、错误和是否扣费：给客服和技术支持使用的 AI API 工单排查清单，覆盖账号、发生时间、客户端、Base URL、模型名、错误原文、任务 ID、是否扣费、是否重复提交和升级条件，避免要求用户公开完整密钥。