对应第一个月计划第 2 周第 6 天在 LangChain 与 LlamaIndex 中选一个框架重写 Day 12。本文默认选择 LangChain。建议投入45 小时。当天交付功能等价的框架版 RAG、基线对比和行为差异报告。一、今天完成后要达到什么程度你应当能够将原生实现映射到Document、Splitter、VectorStore、Retriever、Prompt 与 Runnable。使用 LangChain 组装检索和生成但仍能解释每一步输入输出。保留 Day 12 的 metadata、引用、拒答和权限边界。用相同测试集验证框架版与原生版功能等价。识别框架默认行为、版本变化和抽象泄漏。判断框架何时减少样板代码、何时增加调试成本。二、必须掌握的知识点1. 组件映射自定义文档记录 → Document 手写分块 → TextSplitter Chroma 入库 → VectorStore 检索函数 → Retriever Prompt 字符串 → PromptTemplate 顺序编排 → Runnable Chain框架只是封装。若无法说明每个组件的数据结构和副作用就还没有真正掌握它。2. DocumentDocument通常包含page_content正文metadata来源、页码、标题、版本、权限和稳定 ID。不能因为框架方便而丢失 Day 09 建立的可追溯信息。3. Splitter今天主要复用已有 chunks避免同时改变分块和编排。若重新分块必须记录参数并与 Day 09 基线对照。4. VectorStore 与 RetrieverVectorStore 管理写入和相似度查询。Retriever 提供统一检索接口并可配置 K、阈值或过滤。“统一接口”不意味着不同后端的分数语义完全相同。5. Prompt 与 RunnableRunnable 可表达query → retriever → format_context → prompt → model → parser关键业务状态仍应在应用层显式处理不要把权限与拒答隐藏在不可观察的 chain 中。6. 版本与可观测性锁定依赖版本记录关键组件配置为检索结果和 Prompt 组装保留可调试日志不依赖已弃用的旧教程 API升级后运行完整回归测试。三、一步步完成今天的任务第 0 步冻结 Day 12 基线约 20 分钟记录依赖版本8 条测试结果RecallK、引用通过率、拒答状态P50 或平均延迟核心代码行数。今天的目标是“框架迁移”不是顺便改变检索策略。第 1 步创建项目约 20 分钟mkdirlangchain-rag-labcdlangchain-rag-lab uv init uvaddlangchain langchain-openai langchain-chroma python-dotenv pydantictouchapp.py ingest.py rag_chain.py evaluate.py comparison.md .env.example依赖包会随版本拆分安装后以当前官方文档和实际导入路径为准不照抄过时示例。第 2 步把 chunks 转成 Document约 30 分钟读取 Day 09 的chunks.jsonlDocument(page_contentchunk[text],metadatachunk[metadata]|{chunk_id:chunk[chunk_id]},)检查所有必需 metadata 字段均未丢失。第 3 步构建或读取 Chroma约 35 分钟明确两种模式首次运行写入已有 chunks后续运行读取持久化 collection。避免每次启动都重复入库。记录 collection、Embedding 模型和索引版本。第 4 步创建 Retriever约 25 分钟使用as_retriever配置k可选 score thresholdmetadata 过滤条件。先打印实际返回的 Document确认来源、页码和 ID 完整再接生成链。第 5 步实现上下文格式化约 30 分钟不要直接连接所有page_content。格式化函数仍需去重分配稳定引用编号控制预算建立编号到 metadata 的映射清晰分隔不可信文档内容。第 6 步组装 Runnable Chain约 40 分钟链路应保持可观察输入问题 → 受权限约束的 Retriever → 格式化上下文 → PromptTemplate → Chat Model → 结构化解析 → 引用校验空检索应在调用模型前返回no_result不要为了链式写法牺牲明确状态。第 7 步复用 Day 12 测试集约 40 分钟对每条测试比较最终状态检索到的 chunk IDs回答关键事实引用来源延迟与 Token是否发生异常或隐式重试。出现差异时先检查框架默认 K、过滤、Prompt 和解析行为。第 8 步比较代码与维护成本约 25 分钟在comparison.md记录维度原生版 / LangChain 版 核心代码行数 配置透明度 调试难度 替换后端难度 引用与拒答实现 依赖与升级风险“代码量减半”是原计划的挑战目标不应通过删除校验、安全和测试来实现。第 9 步做一次故障定位约 25 分钟主动制造一个问题例如错误 collection、缺失模型配置或无效结构化输出确认能定位到具体组件而不是只得到模糊的 chain 异常。第 10 步复盘与口头验收约 20 分钟回答Document 与 Day 09 chunk 如何对应VectorStore 和 Retriever 的职责有何不同为什么仍需要自定义上下文格式化哪些状态不适合隐藏在 Chain 内框架默认值为什么可能导致回归什么时候不值得引入框架四、当天验收清单框架版可完成 Day 12 同等问答流程。metadata、引用、拒答和权限边界未丢失。已使用 Day 12 同一测试集完成回归。已记录依赖版本和关键默认参数。已比较质量、延迟、Token 和核心代码量。已写出行为差异及其原因。能脱离框架 API 解释完整 RAG 链路。完成后Day 13 即为通过Day 14 将用固定测试集复盘第二周并沉淀调参 Checklist。