模型请求失败
模型请求失败不是页面动作失败。它可能源于缺失配置、错误的 base URL、鉴权拒绝、CORS、网关超时或服务商限流。先确定请求发到了哪里，再排查响应。
快速判断
| 症状 | 可能原因 |
|---|---|
NOT_CONFIGURED | 没有完整的模型配置 |
| 网络错误 / CORS | 浏览器直连跨域端点，或同源路由未代理 |
401 / 403 | 网关鉴权或上游密钥错误 |
429 | 服务商限流，或网关重试耗尽 |
502 / 504 | 上游不可用或超时 |
| 流式中断 | 代理缓冲、连接超时、取消信号 |
| 页面无响应但无错误 | 请求未挂载、会话被销毁或 UI 未渲染 |
配置检查
确认：
- 生产浏览器使用同源相对路径，例如
/api/llm/v1； - 模型名是网关允许的固定别名；
- 浏览器没有服务商密钥；
- 网关有
authorize，不是匿名开放； - 上游地址只来自服务端；
- 超时与重试预算没有被两层重复放大。
MODEL_BASE_URL_MISSING、MODEL_NAME_MISSING、MODEL_API_KEY_MISSING 与 LIMITS_INVALID 应显示为配置诊断，不要显示成一条模糊的“模型失败”。
网关检查
用请求 id 在审计中查：
- 状态码与上游状态码；
- 尝试次数、是否可重试、是否重试耗尽；
- 是否配置了模型白名单；
- 请求大小与超时；
- 是否有人把 prompt / 密钥写进日志。
不要为了本地调试关闭鉴权后忘记恢复，也不要把上游错误正文原样返回给浏览器。
客户端处理
- 401/403：重新认证或修配置，不自动重试；
- 408/429/5xx：遵守可重试标记与退避；
- 已开始流式输出后失败：不要重放整个请求，展示可恢复状态；
retryExhausted：不要继续在浏览器层叠加循环；- 页面动作已执行但模型失败：保留工具结果，重连后从当前状态继续。
安全边界
模型密钥只存在服务端。VITE_* 或等价前端变量会进入构建产物，不是秘密存储。日志中不得记录 Authorization、完整提示词或回复正文，除非应用明确选择并且符合隐私要求。