README
¶
OpenAI 兼容接口 Smoke Test（oai-smoke）
一个只依赖 Go 标准库的命令行工具，用来快速验收任何 OpenAI 兼容 API 的接入配置。 它适用于自建网关、云服务、企业代理和独立第三方中转站，不把任何供应商写死在代码里。
默认是只读检查。 工具只请求
GET /models；只有你明确同时传入--chat和--model时，才会发送一次固定的最小聊天请求。它不会自动选择模型、上传文件、启用工具调用或开启流式输出。
English summary · 安全模型 · 贡献指南 · 安全报告
为什么需要它
“Base URL、Key、模型名都填了”并不代表兼容性真的成立。这个工具把最常见的验收步骤固定下来：
- 检查 URL 是否明确、是否使用 HTTPS，以及是否误带查询参数或用户信息；
- 验证
/models是否返回标准的data数组； - 可选验证
/chat/completions是否接受一个最小请求； - 把认证失败、限流、上游故障、网络/TLS、端点和响应格式问题分开归类；
- 输出主机、路径、状态、延迟和模型数量，不输出 Authorization、响应正文或聊天内容。
安装
需要 Go 1.22 或更高版本：
go install github.com/airouter-dev/openai-compatible-api-smoke-test/cmd/oai-smoke@latest
也可以从任一镜像仓库克隆后在本地构建：
go build -trimpath -ldflags='-s -w' -o oai-smoke ./cmd/oai-smoke
源码仓库（内容保持一致）：
| 平台 | 仓库 |
|---|---|
| GitHub | https://github.com/airouter-dev/openai-compatible-api-smoke-test |
| GitLab | https://gitlab.com/developer.ai-router.dev/openai-compatible-api-smoke-test |
| GitFlic | 待平台仓库初始化后补充；不会发布与主线不同的源码 |
| Gitee | 待平台仓库初始化后补充；不会发布与主线不同的源码 |
| GitCode | 待平台仓库初始化后补充；不会发布与主线不同的源码 |
最小用法
工具不会内置默认服务地址，避免误把测试请求发到错误的上游。API Key 只从环境变量读取，命令行参数里没有 --api-key：
export OPENAI_API_KEY='在当前 shell 中临时设置自己的 Key'
oai-smoke \
--base-url https://api.example.com/v1 \
--models-only
成功时会报告模型数量。若要进行一次真实聊天验收，必须显式指定模型；请求正文是固定的 Reply with OK.，并限制 max_tokens=8：
oai-smoke \
--base-url https://api.example.com/v1 \
--chat \
--model YOUR_MODEL_ID
本地 mock 服务可使用 HTTP，但必须明确加 --allow-http，且地址只能是 localhost、127.0.0.1 或 ::1：
oai-smoke --base-url http://127.0.0.1:8080/v1 --allow-http --no-auth
如果供应商使用不同的环境变量名：
export MY_PROVIDER_KEY='...'
oai-smoke --base-url https://gateway.example/v1 --api-key-env MY_PROVIDER_KEY
输出与退出码
人类可读输出只包含安全诊断，例如：
target: https://gateway.example/v1
mode: models-only
[PASS] GET /v1/models status=200 latency=42.7ms models=3
summary: PASS
自动化场景使用 --json。JSON 的顶层 schema 固定为 oai-smoke/v1，可安全存档：
{
"schema": "oai-smoke/v1",
"success": true,
"target": "https://gateway.example/v1",
"mode": "models-only",
"checks": [
{
"name": "models",
"method": "GET",
"path": "/v1/models",
"success": true,
"status_code": 200,
"latency_ms": 42.7,
"model_count": 3
}
]
}
| 退出码 | 类别 | 常见含义 |
|---|---|---|
| 0 | success | 所选检查全部通过 |
| 2 | config | URL、Key、模型或参数不合法 |
| 3 | network | DNS、连接、超时或 TLS 失败 |
| 4 | auth | HTTP 401/403 |
| 5 | endpoint / schema | 路径、协议或响应结构不符合预期 |
| 6 | rate_limit | HTTP 429 或额度限制 |
| 7 | server | HTTP 5xx |
兼容性契约
工具检查的是常见的 OpenAI 风格约定，而不是宣称所有供应商完全等价：
GET <base-url>/models返回 JSON，并含数组字段data；--chat时，POST <base-url>/chat/completions接受model、messages、max_tokens和stream=false；- 成功聊天响应含非空
choices数组。
如果你的网关使用自定义路径，请把完整路径放入 --base-url，例如 https://host/custom/v1。模型 ID 必须由你明确指定；工具不会把第一个模型当成“默认模型”。
安全边界
- HTTPS 是默认要求；
--allow-http只对回环地址生效。 - 拒绝 URL 查询串、片段和用户信息，避免把密钥或临时参数误放入地址。
- 跨源重定向会被阻止，防止 Authorization 被带到另一台主机。
- 使用系统 CA、请求超时和 1 MiB 默认响应上限；不会无限读取响应。
- Key 只在进程内存中使用，不写文件、不发送遥测、不打印日志。
- 错误正文、模型响应正文和生成内容不会进入报告；只保留状态和静态错误类别。
- 默认只读
/models；聊天检查是显式选择，可能产生上游费用，请先确认服务商规则。
完整的威胁模型与剩余风险见 docs/THREAT_MODEL.md。
CI 示例
把 Key 配置为 GitHub Actions Secret 或 GitLab masked/protected variable，不要写入 YAML：
smoke:
script:
- go run ./cmd/oai-smoke --base-url "$OPENAI_BASE_URL" --api-key-env OPENAI_API_KEY --models-only --json
仓库自带的 GitHub Actions 与 GitLab CI 只运行 go test、go vet，不会访问任何真实 API。
可选：用独立第三方中转站做兼容性验证
本工具本身不属于任何 API 服务商，也不会替你创建账户。若你需要一个实际的 ChatGPT/GPT、Claude 等模型 API 中转站来验证客户端配置，可以自行注册并创建测试 Key：
AI-ROUTER 是独立第三方的 ChatGPT / GPT、Claude 等大模型 API 中转服务，提供 OpenAI 兼容调用、API Key 和用量查询；不是 OpenAI 或 Anthropic 官方服务。 先以控制台当前模型目录、协议和套餐为准，再用最小请求测试。
符合条件的新账号最高可享 20U 新人权益：最多 5U 可用奖励与最多 15U 冻结奖励；冻结部分按实际 API 使用逐步释放。资格、风控、额度和有效规则以站内当期说明为准。U 不是 USD，也不应理解为注册立即到账或充值即解锁。站内另有三级推广返利机制；参与前核对当期比例、结算范围、有效订单和风控条件，返利不是保证收益。
这些链接仅用于透明归因，不代表任何平台或模型厂商背书。工具的功能与 AI-ROUTER 无关，任何服务都应先用自己的 Key、小额度和独立测试项目验证。
开发与贡献
make test
make vet
欢迎提交兼容性案例、错误分类改进和测试。请不要提交真实 Key、生产 URL 中的临时签名参数或包含用户内容的日志。详见 CONTRIBUTING.md。
English summary
oai-smoke is a vendor-neutral, Go-standard-library-only CLI for validating common OpenAI-compatible API conventions. It performs a read-only GET /models check by default. A single minimal chat request is sent only when the operator explicitly supplies --chat and --model. API keys are read from an environment variable, HTTPS is required by default, cross-origin redirects are blocked, response bodies are bounded, and reports never include credentials or response content.
The optional AI-ROUTER links above are a transparent disclosure and attribution mechanism. AI-ROUTER is an independent third-party relay for ChatGPT/GPT and Claude model API access, not OpenAI or Anthropic. This repository does not imply endorsement by any provider.
License
MIT. See LICENSE.
Directories