故障排查
先区分同步推理链路和异步记账链路：
客户端 -> 公网入口 -> Lumoswitch Access Key -> 模型组 -> 渠道
Lumoswitch usage records -> Lumoswitch Worker -> 用量记录与账本推荐流程
- 记录 HTTP 状态、Lumoswitch Runtime request ID、对外模型名称和 Key 前缀。
- 使用同一个 Key 向独立推理 Base URL 调用
GET /v1/models。 - 检查配置、部署组、Virtual Key 和预算是否均为就绪状态。
- 从 Lumoswitch 控制台分别测试每个候选上游。
- 如有账单差异，对比 Lumoswitch usage records、Worker 导入窗口和隔离记录。
按状态排查
| 状态 / 现象 | 常见原因 | 下一步 |
|---|---|---|
| 400 | 所选客户端格式的请求或参数无效 | 在配置已启用的公开路径发送最小请求 |
| 401 | Virtual Key 缺失、错误、阻断或删除 | 确认使用最新的 Lumoswitch Access Key |
| 403 | 模型范围或渠道权限不足 | 检查 Key 模型白名单和渠道账户 |
| 404 / 模型不存在 | Base URL、路径或对外模型名称错误 | 从配置中复制推理地址和模型名称 |
| 429 | Lumoswitch Runtime Key 预算/速率限额或渠道限流 | 先检查运行时限额，再检查渠道配额 |
| 5xx | 无可用部署或渠道错误 | 检查候选就绪状态和上游连接 |
| 用量延迟 | Worker 重叠窗口或 Spend API 临时错误 | 检查 Worker；导入具备幂等与重试能力 |
URL 与路径检查
- OpenAI-compatible Base URL 以
/v1结尾，不要重复追加。 - 公网仅允许协议与兼容性中列出的统一 OpenAI、Anthropic Messages 与 Gemini generateContent 路径。
- Lumoswitch 控制 API 不是推理备用入口，客户端 Base URL 不得指向它。
仅提交时间范围、状态、request ID、Key 前缀、对外模型名称和脱敏配置摘要。不要提供完整 Access Key、上游 Key、密码、Prompt 或个人数据。