𝗧𝗿𝗼𝘂𝗯𝗹𝗲𝘀𝗵𝗼𝗼𝘁𝗶𝗻𝗴 𝗢𝗽𝗲𝗻𝗔𝗜 𝗕𝗮𝘀𝗲 𝗨𝗥𝗟𝘀
更换模型本应轻而易举。你只需更改端点（endpoint）并保留原有的 SDK。
在实际项目中，第一次运行往往会失败。你会看到类似 401、404 或 429 的错误。
在归咎于 SDK 之前，请先使用这份检查清单。
检查 /v1 前缀 大多数网关需要在 URL 中包含 /v1 后缀。如果你只使用域名，SDK 可能会调用错误的路径。请从供应商文档中复制准确的格式。
验证你的 API 密钥 混用密钥会导致失败。请检查以下常见错误： • 在中继 URL（relay URL）上使用 OpenAI 密钥。 • 在 OpenAI URL 上使用中继密钥。 • 使用已禁用项目的密钥。 • 密钥开头或结尾包含空格。 如果你看到 401 错误，请打印密钥的首尾字符，并将其与控制台（dashboard）中的密钥进行对比。切勿记录完整的密钥。
确保模型名称完全匹配 不要猜测模型名称。网关名称会发生变化。错误的名称会导致 404 或
model_not_found错误。请直接从当前模型列表中复制模型 ID。先运行一个极小的请求 在调试整个应用程序之前，先进行一次小规模测试。使用简单的 "ping" 消息和较低的
max_tokens。如果测试成功，说明你的 URL、密钥和模型都是正常的。问题出在你的应用逻辑中，例如流式传输（streaming）或工具调用（tool calling）。理解错误代码 • 401 表示密钥或账户问题。 • 429 表示速率限制（rate limit）或余额问题。 如果你看到 429，请检查你的账单页面。避免使用过于密集的重试循环，这会让问题变得更糟。
检查状态页面 如果你的代码昨天还能运行，今天却失败了，不要急着重写集成代码。请先检查供应商的状态页面。上游故障通常是根本原因。
使用 curl 命令 在你的项目文档中保留一个简单的 curl 命令。
当应用崩溃时，先运行 curl 命令。 如果 curl 失败，问题出在账户、网关或网络。 如果 curl 成功，问题出在你的应用代码。