阶段学习任务单：LLM 应用开发与 RAG
这个阶段的目标是让你能把大模型接入真实应用，而不是只会在聊天框里提问。你需要掌握 API 调用、提示词、文档处理、向量检索、答案引用、评估和工程化部署。
本阶段必须完成的任务
| 任务 | 产出物 | 通过标准 |
|---|---|---|
| 跑通 LLM API 调用 | 一个最小调用脚本 | 能处理 key、请求、响应、异常和重试 |
| 完成文档处理 | 一份切分与清洗记录 | 能说明 chunk 大小、重叠、元数据和来源 |
| 建立向量检索 | 一个最小检索 Demo | 能从问题检索到相关文档片段 |
| 完成 RAG 问答 | 一个课程问答原型 | 回答包含来源引用，并能说明检索依据 |
| 完成 RAG 评估 | 一份测试集与评估表 | 能记录命中率、答案质量、引用质量和失败样本 |
推荐学习顺序
先跑通模型 API，再处理文档和 embedding，然后建立向量检索，最后把检索结果和生成模型连接起来。不要一开始 就引入复杂框架，先用最小代码理解 RAG 的输入输出边界。
RAG 的关键不是“接了向量数据库”，而是能解释为什么这段文档被检索出来、答案是否真的由来源支持、哪些问题检索不到、哪些答案可能幻觉。
和 AI 学习助手项目的关系
本阶段对应 AI 学习助手的 v0.8 课程问答助手。它应该能读取课程 Markdown，建立索引，回答学习者问题，并给出引用来源。这个版本是贯穿项目从“学习记录工具”升级为“AI 助手”的关键节点。
建议最小功能包括：导入课程文档、按标题和正文切分、保存元数据、检索相关片段、生成回答、展示引用路径、记录问题和答案。标准版本再加入评估集、失败样本分析和配置化参数。
常见卡点
常见问题包括文档切分太碎或太大、metadata 丢失、embedding 模型和语言不匹配、检索命中但答案不用来源、答案看似正确但引用不支持、上下文太长导致成本和延迟过高。排查时要把检索结果和生成答案分开看。
轻松版 / 标准版 / 挑战版任务
| 难度 | 你要完成什么 | 适合谁 |
|---|---|---|
| 轻松版 | 完成 5 个带来源回答 | 第一遍学习、时间少或刚入门的学习者 |
| 标准版 | 完成 10 个评估问题和 citation_ok 检查 | 希望把本阶段放进作品集的学习者 |
| 挑战版 | 比较 chunk、top-k 或 rerank 策略的失败类型 | 已有基础、想做更强项目证据的学习者 |
本阶段徽章与 Boss 战
| 类型 | 内容 |
|---|---|
| Boss 战 | 引用幻觉龙 |
| 可解锁徽章 | RAG 引用警察、检索考古学家 |
| 最小通关口号 | 先跑通、再解释、再记录失败 |
| 证据保存建议 | 把截图、日志、失败样本或评估表保存到 reports/、evals/ 或 logs/ |
完成轻松版就可以继续前进；完成标准版才建议写进作品集；挑战版只在你有余力时再做。
阶段作品集交付物
如果你想把本阶段成果沉淀到作品集，建议至少保留下面这些文件或等价材料。
| 交付物 | 说明 |
|---|---|
chunks.jsonl | 文档切块结果，包含 text、source、section、page、content_type 等字段 |
retrieval_logs.jsonl | 每次 query 的 top-k、score、source 和命中文本摘要 |
eval_questions.csv | 固定评估问题、标准答案、应命中文档和关键引用 |
failure_cases.md | 检索失败、生成失败、引用失败、metadata 失败等样本 |
rag_config.md | chunk_size、overlap、top-k、rerank、prompt_version 等配置记录 |
README.md | 运行命令、示例输入输出、评估结果和改进计划 |
这些文件不一定一开始就很完整，但它们会让你的 RAG 项目从“能回答”变成“能解释、能评估、能复盘”。
阶段通关问题
学完后，你应该能回答这些问题：RAG 解决了大模型的什么限制，chunk 大小会影响什么，embedding 和关键词检索有什么区别，为什么答案必须有引用，如何判断一次 RAG 失败是检索问题还是生成问题。
完成状态 Checklist
- 我能独立完成一次 LLM API 调用，并处理异常和重试。
- 我能说明文档切分、embedding、向量检索和生成回答之间的关系。
- 我能查看检索到的原文片段，而不是只看最终答案。
- 我已经完成一个带来源引用的 RAG 问答原型。
- 我有一组固定评估问题，并记录了检索失败、引用失败或生成失败样本。