Appearance
FAQ：那些反复被问的问题
1. 本节产出
20 个高频问题的直答：每个问题给出结论、理由、以及「什么情况下结论会变」。
2. 前置依赖
无。
3. 为什么需要 FAQ
有些问题没有唯一正确答案，但每次都要重新讨论一遍很浪费。这里给出课程的建议答案 + 判断依据，你可以不同意，但要知道分歧点在哪。
4. 核心原理
每个回答遵循结构：结论 → 理由 → 例外。
5. 问题清单
5.1 选型类
Q1：RAG 还是微调？ 结论：默认 RAG，微调是最后选项。 理由：知识频繁变 → 微调要重训；需要溯源 → 微调不支持；微调的一次性成本与更新成本都被低估。 例外：要改变模型的表达风格/输出格式，且 prompt 和 few-shot 都试过无效时，才考虑微调。详见 02-02。
Q2：向量库选哪个？ 结论：默认 PGVector。 理由：运维成本最低、元数据过滤用 SQL 表达力最强、事务保证灌库原子性。性能在百万级以下不是瓶颈。 例外：片段数接近千万、已有 ES 且需要强关键词检索、有专职运维。详见 02-06。
Q3：用 Spring AI 还是 AgentScope？ 结论：默认 Spring AI + 自研循环。 理由：单 Agent 场景占绝大多数；可靠性才是难点且框架不管；与 Spring 生态一致。 例外：真的需要多 Agent 协作或分布式 Agent。详见 03-02。
Q4：SSE 还是 WebSocket？ 结论：默认 SSE。 理由：单向足够、HTTP 穿透性好、浏览器自动重连、实现极简。 例外：需要客户端在生成过程中反向控制服务端（打断、追加条件）。详见 01-04、01-05。
Q5：要不要上多 Agent？ 结论：默认不要。 理由：成本超线性增长，质量边际递减。实测 5 Agent 的成本是单 Agent 的 5.7 倍，质量提升 0.1 分。 例外：需要权限隔离（查数据的不能写数据）、或需要对抗性校验。详见 03-04。
5.2 参数类
Q6：temperature 设多少？ 结论：抽取/分类/结构化 0~0.2；对话 0.5~0.7；创意 0.8~1.0。 理由：temperature 影响采样分布，越高越倾向长尾，结构化任务会偏离 Schema。 例外：需要多样性输出（比如生成多个候选）。详见 01-01。
Q7：similarityThreshold 设多少？ 结论：没有通用值，起点 0.6，必须实测标定。 理由：不同 Embedding 模型的相似度分布不同，某模型的 0.68 可能相当于另一模型的 0.85。 例外：无。这个值必须标。详见 02-08。
Q8：chunk 切多大？ 结论：制度文档 500~800 Token，FAQ 200~400，技术文档 600~1000。 理由：要保证片段自身语义完整。太小切断语义，太大引入噪声。 例外：用评测集实测，不同文档类型差异大。详见 02-04。
Q9：topK 设多少？ 结论：粗排 20 → 精排取 5。 理由：大 K 保证召回，精排保证精度。直接 topK=5 会漏，直接 topK=20 会引入噪声。 例外：成本极度敏感时可减到 3。详见 02-10。
Q10：maxIterations 设多少？ 结论：预期轮次的 1.5~2 倍（预期 8 就设 12~15）。 理由：上限是兜底，不是让它真跑那么多次。设 50 等于没有上限。 例外：无。且必须同时设 Token 预算。详见 03-10。
5.3 工程类
Q11：工具调用不生效怎么排查？ 结论：按「最简工具 → 真实工具 → 调描述」三步排查。 理由：90% 的根因是模型不支持或描述含糊，不是框架配置。 例外：无。详见 01-07。
Q12：测试要不要打真实模型？ 结论：单元测试绝不用真实模型；冒烟测试每天一次、最多 5 个用例。 理由：单测用真实模型会导致 CI 成本失控、不稳定，最终 CI 被关掉。 例外：无。详见 01-11。
Q13：工具返回值应该返回什么？ 结论：精简的、人能读懂的文本，不含整个对象。 理由：返回值会进上下文，每一字节都花钱。 例外：无。且失败时要返回「可行动」的文本（NOT_FOUND / ERROR + 建议）。详见 03-03。
Q14：Agent 的写操作能自动重试吗？ 结论：绝对不能。 理由：工具可能已执行成功只是响应丢失，重试等于重复业务。 例外：下游支持幂等键，且用同一个 key 重试。详见 03-08。
Q15：tenantId 能作为工具参数吗？ 结论：不能，必须从上下文注入。 理由：模型可以根据对话内容传别的租户 ID，这是直接越权。 例外：无。详见 03-11。
5.4 效果类
Q16：RAG 效果不好，第一步该做什么？ 结论：检查离线段（解析质量、切分完整性、元数据），不要先调模型或向量库。 理由：实测中只换解析器就能让召回率从 61% 到 84%；换向量库通常提升不到 5%。 例外：离线段已确认无问题时，再加混合检索与 Rerank。详见 02-01。
Q17：代码审查 Agent 报了一堆误报怎么办？ 结论：精确率优先，设置信度阈值、只报有依据的问题、行号由代码解析。 理由：误报的代价是工具被弃用，漏报的代价只是一个 bug。 例外：无。详见 03-15。
Q18：评测集要多大规模？ 结论：50 条能看趋势，100 条能做决策；其中 20%~30% 必须是「无答案」样本。 理由：全是可答样本会导致拒答机制从未被验证。 例外：无。详见 02-17。
Q19：怎么证明 AI 提效了？ 结论：测基线 → 上线后对比任务时长；主要指标是采纳率，不是调用次数。 理由：调用次数不反映价值，还会诱导为数字而使用。 例外：无。基线必须在上线前测。详见 04-08。
Q20：成本突然涨了怎么查？ 结论：先看单日异常检测（是否 3 倍日均），再看按租户/场景的 Top10。 理由：突增通常是死循环或滥用，月度预算发现时钱已花完。 例外：无。详见 04-07。
6. 跑起来
Ctrl+F 搜关键词。每个答案都指向详细章节。
| 检查项 | 通过标准 |
|---|---|
| 有结论 | 每个问题给出明确建议，不含糊 |
| 有例外 | 说明什么情况下结论会变 |
| 指向正文 | 标注详细章节 |
7. 生产避坑
- FAQ 的答案是有上下文的建议，不是教条。每个答案都写了「例外」，遇到与你的场景不符时，回到正文中看推导过程，不要直接套用结论。
- 参数类答案（Q7/Q8/Q10）必须实测标定，不能直接用这里的数值。这里给的是起点和判断方法，实际取值取决于你的数据和模型。