故障排查
从下游到上游逐层定位问题，比反复修改模型名称或 Key 更有效。
客户端 -> Access Key / 配置 API -> 模型资源 / 调度 -> 上游 / 凭证 -> 模型厂商推荐流程
- 记录 HTTP 状态和错误码。
- 用同一个 Key 调用
/v1/models。 - 检查配置 API 是否启用、模型是否允许、RPM 是否超限。
- 单独测试对应上游，并核对模型资源健康状态。
按状态码排查
| 状态 / 现象 | 常见原因 | 下一步 |
|---|---|---|
| 400 | 请求格式、协议或参数不兼容 | 用最小请求重试，移除厂商专有字段 |
| 401 | Key 缺失、错误、禁用或已删除 | 确认使用 Lumoswitch Access Key |
| 403 | 模型范围、项目权限或上游权限不足 | 检查 Key 限制和厂商账户权限 |
| 404 / 模型不存在 | Base URL 错误或对外模型名称不匹配 | 调用 /models 并复制返回的模型 ID |
| 429 | Key RPM 或上游限流 | 检查 Key 限制和上游账户 |
| 5xx | 无可用资源、上游错误或平台异常 | 检查候选资源和上游连接 |
| 超时 | 上游延迟、网络或重试链过长 | 单测上游并检查各阶段耗时 |
| 流式中断 | 客户端 SSE、代理缓冲或上游中断 | 先验证非流式，再检查代理配置 |
/models 成功但调用失败
模型可见只说明 Key 和模型范围基本有效。继续检查：
- 配置是否包含健康且可路由的模型资源。
- 请求协议是否与配置输出一致。
- 上游凭证是否有实际调用权限和余额。
- AI 智能调度或故障转移是否找到了候选资源。
模型或上游状态陈旧
当厂商权限、Key 或模型列表变化后，重新执行上游连接测试和模型检测。不要仅依赖旧的健康状态。
安全地提交支持信息
可提供：时间范围、HTTP 状态、错误码、Key 前缀、对外模型名称和脱敏后的配置摘要。
不要提供：完整 Access Key、上游厂商 Key、账号密码、完整 prompt 或包含个人数据的响应正文。