坑
七大常见坑
Pitfalls
下面这些是新手接大模型时高频踩的坑，提前知道能少走弯路。
坑 1：API Key 无效或过期
报 401 / unauthorized。先确认 Key 复制对了、有没有多余空格、环境变量真的传进去了、账号有没有欠费。百炼新用户免费额度用完也会报错。
坑 2：流式输出前端处理
后端返回 Flux<String>，前端不能用普通 axios 直接收，得用 EventSource 或 fetch 的流式读取。Content-Type 必须是 text/event-stream。
坑 3：Function Calling 参数不匹配
AI 传的参数名/类型跟你 Java 方法对不上，调用就失败。@ToolParam 的描述要写清楚，参数类型用简单类型（String/Long），别上来就用复杂对象。
坑 4：RAG 检索不到相关文档
见第六章：切分太大太小、Embedding 模型不匹配、文档本身是乱码。先拿问题去向量库手动搜一下，看召回对不对。
坑 5：Token 超限
文档太长或历史太多，报 context length exceeded。截断 + 只取最相关片段。
坑 6：模型幻觉
AI 一本正经地编。RAG 能缓解（给它依据），但不能完全消除。关键业务一定要让它基于工具/文档回答，并且做输出校验。
坑 7：Prompt 注入攻击
用户输入里藏"忽略之前指令"。系统指令和用户输入要隔离，敏感信息别进 Prompt，输出要审核。
补一个坑：流式输出与 SSE
用 stream() 返回 Flux<String> 时，接口的 produces 必须设成 text/event-stream，前端用 EventSource 接，逐字显示。别用普通 POST 等完整返回，那就失去打字机效果了。