首页 / 文章 / 《实用笔记》：我从零开始构建了16个RAG系统——实际情况究竟如何

rag agents llm architecture typescript python

《实用笔记》：我从零开始构建了16个RAG系统——实际情况究竟如何

《实用笔记》操作指南：我从零开始构建了16个RAG系统——实际情况是：适用于采用该模式的团队的合同、检查清单以及可直接插入的代码模块。

4118 词

本指南将从头开始构建从原材料到可运行系统的完整流程，内容来自《我从零搭建了16个RAG系统——哪些方法真正有效》。重点在于可操作的步骤、明确的检查点，以及可直接放入代码库的代码，无需猜测其用途。在概览阶段，应在修改代码之前明确输入参数、各步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏的状态。需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。

RAG诞生的三大问题

在处理RAG的三个问题阶段时，首先写下相关约定：所需的输入、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。相比庞大的脚本，应优先选择小型且可测试的单元。当某个步骤失败时，故障应指向单一的责任模块，而非复杂的流程链。在调整提示词之前，先使用固定的问题集来衡量召回率。仅仅更换提示词很难解决检索效果不佳的问题。

Without RAG:
  User: "What's our refund policy?"
  LLM:  "I believe you offer a 14-day return..." (guessing)

With RAG:
  User: "What's our refund policy?"
  → Step 1: Search internal docs → Finds: "Refunds within 30 days..."
  → Step 2: LLM reads the doc and answers accurately
  LLM:  "Your refund policy allows returns within 30 days..."

16种RAG模式（按实际影响程度排序）

在完成“16种RAG模式”这一阶段时，首先需写下相关契约：所需的输入参数、成功标志，以及部分失败时的处理方式。这样的清单能确保后续的代码修改始终符合约定。将这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功判定标准，杜绝默许部分完成的情况。在调整提示词之前，先使用固定的问题集来测试召回率。仅仅更换提示词往往无法解决检索效果不佳的问题。

第一层级：必须掌握

在完成第一阶段的“必须掌握”内容时，首先写下合同条款：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免从演示环境过渡到共享环境时出现意外费用。在调整提示词之前，先用固定的问题集测试召回率。仅仅更换提示词很难改善较差的检索效果。

几乎被所有生产环境中的RAG系统采用

在几乎每个阶段进行开发时，首先写下合同规范：所需的输入参数、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中管理，这样操作人员无需查看整个系统结构即可进行审计。在调整提示词之前，先使用固定的问题集来测试召回率。仅仅更换提示词很难解决检索效果不佳的问题。

1. 标准 RAG — 基础框架

在处理1标准RAG阶段时，首先写下相关约定：所需输入、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误消息处理都是产品本身的一部分，而非后续需要优化的内容。在调整提示词之前，先使用固定的问题集来衡量召回率。仅仅更换提示词很难解决检索效果不佳的问题。

# The core loop in ~10 lines
query_embedding = embed(user_query)
relevant_docs = vector_store.search(query_embedding, top_k=5)
context = "\n".join(relevant_docs)
prompt = f"Answer using this context:\n{context}\n\nQuestion: {user_query}"
answer = llm.generate(prompt)

2. 混合式RAG——最大的质量提升点

在处理“2 Hybrid RAG The stage”时，首先需明确相关约定：所需的输入参数、成功标志，以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合预期。相比冗长的脚本，应优先选择小型且可测试的单元。当某个步骤出现故障时，故障原因应能指向单一责任模块，而非复杂的流程链。在调整提示词之前，先使用固定的问题集来测试召回率。仅仅更换提示词往往无法解决检索效果不佳的问题。

User: "React useState hook"
→ Semantic search finds: "state management in React components"
→ BM25 finds: docs with exact string "useState"
→ Hybrid (RRF fusion): gets the best of both

3. 上下文检索 RAG —— 用于真实对话

在处理3个上下文检索RAG阶段时，首先写下相关契约：所需输入、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。将这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，杜绝无声的半完成状态。在调整提示词之前，先使用固定的问题集来衡量召回率。仅仅更换提示词很难改善较差的检索效果。

User turn 1: "Tell me about the Premium plan"
User turn 2: "How much does it cost?"

Before search, rewrite → "How much does the Premium plan cost?"
Now retrieve → finds the pricing document ✓

第二层级：竞争优势

在处理TIER 2 COMPETITIVE EDGE阶段时，首先写下相关契约：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免从演示环境过渡到共享环境时出现意外费用。在调整提示词之前，先用固定的问题集测试召回率。仅仅更换提示词很难改善较差的检索效果。

优秀系统与卓越系统的区别

在处理“什么造就优秀系统”这一阶段时，首先需列出相关规范：所需的输入参数、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合要求。应将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中管理，这样操作人员无需查看整个系统结构即可进行审计。在调整提示词之前，需先使用固定的问题集来测试系统的召回率。仅仅更换提示词往往无法解决检索效果不佳的问题。

4. 智能代理型RAG——2025–2026年的最热门趋势

在处理4个代理式RAG阶段时，首先写下相关契约：所需输入、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的组成部分，而非后续需要优化的内容。在调整提示词之前，先使用固定的问题集来衡量召回率。仅仅更换提示词很难解决检索效果不佳的问题。

User: "What was NVDA's stock return last quarter vs its historical average?"

Agentic RAG decides:
  → Use web_search tool for current stock data
  → Use calculator tool for return calculation
  → Use document_retrieval tool for historical reports
  → Synthesize all three into one answer

5. 自主式RAG——在容错率为零时的选择

在完成5个Self-RAG For When阶段时，首先写下相关规范：所需输入、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。建议采用小型、可测试的单元，而非冗长的脚本。当某个步骤失败时，故障应指向单一责任模块，而非复杂的流程链。在调整提示词之前，先使用固定的问题集来衡量召回率。仅仅更换提示词很难解决检索效果不佳的问题。

6. HyDE RAG — 词汇桥接

在处理6个HyDE RAG阶段时，首先写下契约：所需的输入、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。将这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，杜绝无声的半完成状态。在调整提示词之前，先使用固定的问题集来衡量召回率。仅仅更换提示词很难改善较差的检索效果。

User: "Why do things fall down?"
→ LLM generates hypothesis: "Objects fall due to gravitational force..."
→ Search with the hypothesis (technical vocabulary)
→ Find the actual document about gravitational acceleration
→ Answer using the real document

TIER 3: 高影响力专家

在完成 TIER 3 HIGH-IMPACT SPECIALISTS 阶段时，首先写下相关契约：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免从演示环境过渡到共享环境时出现意外账单。在调整提示词之前，先用固定的问题集测试召回率。仅仅更换提示词很难改善较差的检索效果。

在其领域中被广泛使用

在处理那些广泛应用的阶段时，首先写下合同条款：所需的输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能标志应集中于一个地方，这样操作人员无需查看整个系统结构即可进行审计。在调整提示词之前，先使用固定的问题集来衡量召回率。仅仅更换提示词很难解决检索效果不佳的问题。

7. 图结构RAG——用于关系推理

在处理7个Graph RAG阶段时，首先写下相关规范：所需输入、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误消息处理都是产品功能的一部分，而非后续需要补充的内容。缓存稳定的系统指令和工具结构。重复发送相同的开头信息是导致资源浪费的常见原因。

Text: "Dr. Chen collaborated with Dr. Patel on a 2022 study funded by NIH."

Graph nodes: Dr. Chen, Dr. Patel, 2022 study, NIH
Graph edges: COLLABORATED_WITH, FUNDED_BYQuery: "Who funded Dr. Chen's work?" → traverse: Chen → study → NIH

8. 内存增强型RAG——你的机器人会记住你

在完成“8种内存增强型RAG阶段”的工作时，首先写下相关规范：所需输入、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。优先选择小型、可测试的单元，而非冗长的脚本。当某个步骤失败时，故障应指向单一责任模块，而非复杂的流程链。在调整提示词之前，先使用固定的问题集来测试召回率。仅仅更换提示词很难解决检索效果不佳的问题。

user_profile = memory.get_user_facts(user_id)
recent_context = memory.get_recent_conversations(user_id, k=3)
answer = rag_with_context(query, user_profile, recent_context)
memory.update(user_id, query, answer)

9. 模块化RAG——无需重写即可更换任意部分

在处理9个模块化的RAG交换阶段时，首先需写下相关契约：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。将这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，杜绝无声的半完成状态。在调整提示词之前，先使用固定的问题集来测试召回率。仅仅更换提示词很难改善较差的检索效果。

Standard RAG:   [fixed retriever] → [fixed reranker] → [fixed LLM]

Modular RAG:    [pluggable retriever] → [pluggable reranker] → [pluggable LLM]
                     ↑ swap anytime         ↑ swap anytime        ↑ swap anytime

10. 领域专用RAG——专为您的行业打造

在完成10个领域特定RAG构建阶段时，首先需明确相关规范：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在系统从演示环境过渡到共享环境时出现意外费用。在调整提示词之前，先使用固定的问题集测试召回率。仅仅更换提示词往往无法改善较差的检索效果。在完成10个领域特定RAG构建阶段时，首先需明确相关规范：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误处理措施都是产品本身的一部分，而非后续需要补充的内容。

11. 改进型RAG——三种来源，一个答案

改进型RAG的三个阶段若被视为可度量的结构，则效果最佳。在扩大范围之前，需收集一份理想的文本记录、一个失败案例以及回滚说明。优先选择小型且可测试的单元，而非庞大的脚本。当某一步骤失败时，故障应指向单一责任主体，而非复杂的流程链。将分块策略与检索策略分开。当质量指标发生变化时，修改其中一项不应迫使重新编写另一项。

Query: "Tell me about the Mars Exploration Program"

→ SQL: "Mars: 1.52 AU from sun, 687-day orbit"
→ Graph: Mars → explored_by → Curiosity Rover, Perseverance
→ Text: "Mars is the fourth planet... known as the Red Planet..."→ Fused Answer: Combines all three for comprehensive, expert-level response

12. 递归/多步骤RAG——用于复杂问题

将12个递归多步骤RAG阶段视为可度量的整体，效果最佳。在扩大范围之前，先记录一份理想的输出样本、一个失败案例以及回滚说明。把这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，绝不允许出现无声的、不完整的处理结果。将分块策略与检索策略分开。当质量指标发生变化时，修改其中一项不应强制要求重新编写另一项。

Round 1: Retrieve about transistors → learn about miniaturization
Round 2: Retrieve about integrated circuits → learn about computing power
Round 3: Retrieve about GPUs → learn about parallel processing
Round 4: Retrieve about deep learning → learn about compute requirements
Round 5: Synthesize the full chain into a coherent answer

第4层：专业应用场景

将TIER 4 SPECIALIZED USE阶段视为可测量的界面来处理效果最佳。在扩大范围之前，先记录一份优秀的测试案例、一个故障实例以及回滚说明。在功能结果旁同时记录执行时间以及令牌或查询成本。提前了解成本情况，就能避免在系统从演示环境过渡到共享环境时出现意外账单。应将分块策略与检索策略分开，当质量指标发生变化时，修改其中一项无需强制重写另一项。

在需要时不可或缺

在需要处理舞台级工作时，将其视为可测量的表面最为有效。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。将配置与应用程序代码分开。环境文件、密钥存储和功能标志应集中存放于一处，这样操作人员无需查看整个架构即可进行审计。将分块策略与检索策略分开。当质量指标发生变化时，修改其中一项不应迫使重新编写另一项。

13. ODQA RAG — 无所不能的回答

将13个ODQA RAG回答阶段视为可度量的对象时，其效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。同时记录正常流程和恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的一部分，而非后续需要补充的内容。应将分块策略与检索策略分开，当质量指标发生变化时，修改其中一项不应强制要求重新编写另一项。

14. 多模态RAG——文本、图像与音频的结合

将14多模态RAG文本阶段视为可度量的对象来处理效果最佳。在扩大范围之前，先记录一份理想的处理结果、一个失败案例以及回滚说明。优先选择小型且可测试的单元，而非庞大的脚本。当某个步骤出现故障时，故障应指向单一责任主体，而非复杂的流程链。将分块策略与检索策略分开。当质量指标发生变化时，修改其中一项不应迫使重新编写另一项。

User (text): "Show me the anatomy of the heart"
→ Retrieves both: text descriptions AND anatomical diagrams
→ Response includes both text explanation and relevant image

15. 流式RAG——实时知识

将15流式RAG实时处理阶段视为可度量的对象使用效果最佳。在扩大范围之前，先记录一份优秀的处理结果、一个失败案例以及回滚说明。把这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，绝不允许出现无声无息的半完成状态。应将分块策略与检索策略分开。当质量指标发生变化时，修改其中一项不应强制要求重新编写另一项。

Time 9:00 AM: "What's happening with NVDA?"
→ Retrieves this morning's earnings report

Time 11:30 AM (after news breaks): "What's happening with NVDA?"
→ Retrieves the breaking news from 11:15 AM

16. 联邦式RAG——以隐私为先，多源整合

将16个联邦RAG隐私优先阶段视为可度量的对象来使用效果最佳。在扩大应用范围之前，需记录一份理想的处理结果、一个故障案例以及回滚说明。在功能结果旁还需标注处理时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。应将分块策略与检索策略分开处理，当质量指标发生变化时，修改其中一项不应迫使重新编写另一项。将16个联邦RAG隐私优先阶段视为可度量的对象来使用效果最佳。在扩大应用范围之前，需记录一份理想的处理结果、一个故障案例以及回滚说明。需同时记录正常处理流程和异常恢复流程。重试机制、人工审核环节以及错误消息处理都是产品本身的组成部分，而非后续需要补充的功能。

Central Query: "What's the survival rate for treatment X?"

→ Hospital A retriever: returns relevant anonymized snippets
→ Hospital B retriever: returns relevant anonymized snippets
→ Hospital C retriever: returns relevant anonymized snippets
→ Central LLM synthesizes — never saw raw patient recordsResult: HIPAA/GDPR compliant, collaborative AI

实用路线图：每月应完成的工作

在制定“实用路线图”时，需先明确每个阶段的输入内容、负责人员以及代码修改的终止标准。操作人员应能够从已知的检查点重新执行相应步骤，而无需猜测隐藏状态。相比冗长的脚本，更应采用小型且可测试的单元。当某一步骤失败时，故障原因应能指向单一责任模块，而非复杂的流程链。必须引用实际作为答案依据的段落；没有引用的话，操作人员就无法区分是虚假信息还是索引缺失导致的错误。

Month 1:  Standard RAG           ← Get something working
Month 2:  + Hybrid RAG            ← Biggest retrieval quality win
Month 3:  + Contextual Retrieval  ← Multi-turn conversations work now
Month 4:  + Self-RAG              ← Stop hallucinations
Month 5:  + Agentic capabilities  ← Tools beyond just search

This covers 80-90% of production RAG needs.

RAG类型的组合应用：实际案例

在“组合型RAG类型实际应用阶段”，在修改代码之前需明确输入内容、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，定义成功判定标准，并拒绝默许的半完成状态。需注明真正作为答案依据的段落。若没有引用，操作人员就无法区分幻觉内容与索引缺失的问题。

快速参考：选择您的RAG

快速参考：在修改代码之前，请先选择对应阶段，明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在流程从演示环境转向共享环境时出现意外费用。需注明实际作为答案依据的段落内容；没有引用的话，操作人员就无法区分是幻觉结果还是索引缺失导致的错误。快速参考：在修改代码之前，请先选择对应阶段，明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。需同时记录正常流程和异常恢复流程的细节。重试机制、人工审核环节以及错误处理方式都是产品的一部分，而非后续需要补充的内容。

。

5分钟快速入门

在完成“5分钟快速入门”阶段时，首先写下相关契约：所需的输入参数、成功标志以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。建议采用小型、可测试的单元而非庞大的脚本。当某个步骤失败时，故障应指向单一责任点，而非复杂的流程链。在调整提示词之前，先使用固定的问题集来衡量召回率。仅仅更换提示词很难解决检索效果不佳的问题。

# Clone the repo
git clone https://github.com/Manjunadh86/RAG-Materials.git
cd RAG-Materials

# Install dependencies
pip install -r requirements.txt# Set your OpenAI API key
export OPENAI_API_KEY="sk-your-key-here"# Run your first RAG system
cd 01-Standard-RAG
python hands_on.py

下一步是什么

在“下一步计划”阶段，首先写下相关契约：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改始终符合约定。将此阶段视为输入与验证后输出之间的契约。为相关成果命名，明确成功判定标准，杜绝无声的半完成状态。在调整提示词之前，先使用固定的问题集来测试召回率。仅仅更换提示词往往无法解决检索效果不佳的问题。

操作检查清单

若将“操作检查清单”阶段视为可测量的对象，其效果会更好。在扩大范围之前，先记录一份最佳示例、一个失败案例以及回滚说明。应将配置信息与应用程序代码分开。环境文件、密钥存储和功能开关应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。

将分块策略与检索策略分开。当质量指标发生变化时，修改其中一项不应强制重新编写另一项。

在预算允许的情况下，使用测试数据而非真实的付费 API，在持续集成过程中添加用于检测关键路径的冒烟测试。

同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及死信处理都是产品的一部分，而非后续需要补充的功能。

将分块策略与检索策略分开。当质量指标发生变化时，修改其中一项不应强制重新编写另一项。

在推广该技术栈之前，先冻结版本，为关键路径生成标准操作记录，并确认回滚步骤。共享环境需要设置速率限制、进行租户检查，同时明确密钥轮换的负责人。与其追求华丽的临时演示，不如注重扎实的可靠性。

关于 ba5dd76016c2 的批量处理说明：不要将提供者密钥放入代码仓库，为每个会话设置令牌上限，并将转录内容存储在评估测试用例的旁边，以便后续更换模型时仍能保持可比性。

全部文章发送简报