接 OpenAI-compatible API 时，最容易被误判的问题是 404。
很多人看到 404 会以为服务不可用，或者 SDK 版本坏了。实际更常见的原因是 Base URL、路径前缀、模型名和接口类型没有对上。
这篇只做一件事：把 404 的排查顺序讲清楚。
第一项：确认 /v1 有没有写对
OpenAI SDK 通常会在你提供的 base_url 后面继续拼接接口路径。如果兼容网关要求的入口是：
https://api.wappkit.com/v1
那你就应该把完整的 /v1 一起写进去。
如果只写根域名：
https://api.wappkit.com
SDK 可能会请求到错误路径。错误表现可能是 404，也可能是看起来像认证失败。
最小测试代码可以这样写：
from openai import OpenAI
client = OpenAI(
api_key="your_gateway_key",
base_url="https://api.wappkit.com/v1",
)
result = client.chat.completions.create(
model="gpt-5.5",
messages=[{"role": "user", "content": "return one short sentence"}],
)
print(result.choices[0].message.content)
先跑通这段，再接你的业务代码。
第二项：模型名是不是当前可用名称
model not found 也经常被包装成 404。
不要凭印象写模型名。比如你想用 gpt-5.5，就去模型列表复制当前暴露的名称。版本号、短横线、大小写、别名都可能导致请求失败。
如果你正在迁移旧项目，尤其要检查代码里有没有多个地方写死模型名。最容易漏的是：
.env- Docker Compose
- CI 配置
- 前端示例代码
- 后台默认参数
- 测试脚本
只改一处不够，所有入口都要统一。
第三项：接口类型是否匹配
有些模型只适合 chat completions，有些接口可能要求不同的请求格式。你用 chat SDK 调一个不支持该接口类型的模型，也可能得到不清晰的错误。
排查时先不要用复杂请求。关掉 stream、工具调用、JSON mode、长上下文，先发一条普通 chat 请求。普通请求通了，再逐项打开其他能力。
第四项：环境变量有没有被覆盖
很多项目不是代码写错，而是运行时读到的环境变量不是你以为的值。
建议启动时打印非敏感配置：
import os
print("base_url =", os.getenv("AI_API_BASE_URL"))
print("model =", os.getenv("AI_MODEL"))
不要打印 API Key。只确认 Base URL 和模型名就够了。
如果你用的是 Cursor、Cline、Docker、云函数或 PM2，记得这些运行环境可能不会自动读取你当前终端里的变量。
第五项：看状态页和请求日志
如果昨天能跑，今天突然 404，先别急着改代码。
看两件事：
- 状态页是否有模型维护或上游波动。
- 请求日志里实际请求的模型名和路径是什么。
Wappkit 的接入说明可以先看 docs，模型名称以 model list 为准。如果你能在日志里看到请求路径、模型名和错误信息，排查会快很多。
一个简单排查顺序
遇到 404 时，可以按这个顺序走：
- Base URL 是否包含正确的
/v1。 - API Key 是否属于当前网关。
- 模型名是否从当前模型列表复制。
- 接口类型是否匹配。
- 环境变量是否被运行环境覆盖。
- 状态页和请求日志是否显示异常。
这六步比盲目换 SDK 更有效。
小结
OpenAI-compatible Base URL 的 404，大部分不是神秘故障。
它通常来自路径前缀、模型名、接口类型或运行环境配置不一致。把最小请求跑通，再逐步接回业务代码，问题会清楚很多。
Top comments (0)