常见问题 FAQ
大约 3 分钟
第二十章：常见问题解答
20.1 配置问题
20.1.1 启动后报 401/403
常见原因：
- API Key 没有注入到运行环境（本地终端导出了变量，但 IDE 启动没带上）
- Key 写错、过期、被禁用
- 使用了不匹配的 Base URL/区域
建议排查顺序：
- 确认运行进程是否真的拿到环境变量
- 只保留一个供应商配置，先跑通最小示例
- 再逐步开启多模型、多 profile
20.1.2 提示“找不到模型”或“模型不可用”
常见原因：
- 模型名写错（大小写/版本）
- 账户没有该模型权限
- 某些模型只在特定区域/套餐可用
做法：
- 把模型名做成配置项，支持快速切换
- 在日志中记录最终生效的 model（不要记录 key）
20.2 性能问题
20.2.1 响应很慢、经常超时
优先级最高的优化：
- 缩短 prompt：只带必要上下文
- 对长输出启用流式（第十一章）
- 增加超时控制与降级（第十二章）
- 对重复请求加缓存（第十五章）
20.2.2 频繁 429 限流
常见原因：
- 并发过高
- 重试策略不当（立即重试导致雪崩）
- 配额不足
建议：
- 加并发闸门（Semaphore）与指数退避（第十二章、第十五章）
- 区分“用户限流”和“供应商限流”，避免相互影响
20.3 兼容性问题
20.3.1 Spring AI 升级后 API 变动
建议：
- 版本升级前先读变更说明与迁移指南
- 把模型调用封装在 Facade 层，减少 API 变动影响面（第十二章）
- 写好单测覆盖关键逻辑（第十六章）
20.4 最佳实践
- 用“工具调用 + 参数校验”替代“让模型自己编造数据”（第十章）
- 让系统可观测：日志/指标/追踪（第十二章）
- 让配置可运营：多环境、灰度、回滚（第十三章）
- 让系统可治理：鉴权、限流、配额与审计（第十四章、第十五章） 点击这里👇🏻获取：100万QPS短链系统、复杂的商城微服务系统、智能翻译助手AI Agent、SaaS点餐系统、刷题吧小程序、商城系统、秒杀系统、AI项目、代码生成神器、苏三demo项目、智能天气播报AI Agent、智能代码审查AI Agent等 10 个项目的：项目源代码、开发教程和技术答疑
