2025.11.6

07_rag_advanced/README.md

@@ -0,0 +1,110 @@
+# 🧩 模块说明：RAG 进阶 - 从基础到智能 Agent
+
+> 📌 核心知识点：持久化向量库（Chroma）｜精排序（Reranker）｜RAG 工具化｜Agent 集成｜记忆型对话｜六大模块融合
+
+---
+
+### 1. war_and_peace.txt （知识库源文件）
+
+托尔斯泰经典小说《战争与和平》的纯文本版本（约3.2MB），作为本篇 RAG 系统的私有知识库。
+
+- 说明：
+  - 文件需放置在项目根目录。
+  - 若缺失，可从 [Project Gutenberg #2600](https://www.gutenberg.org/ebooks/2600.txt.utf-8) 下载并重命名为 `war_and_peace.txt`。
+  - 所有后续 RAG 功能均基于此文档构建。
+
+---
+
+### 2. build_index.py （构建 Chroma 向量数据库）
+
+将 `war_and_peace.txt` 加载、分块、向量化，并存入 Chroma 持久化向量数据库。
+
+- ✅ 掌握点：
+  - 使用 RecursiveCharacterTextSplitter 分割长文本（chunk_size=500, overlap=75）。
+  - 调用 HuggingFaceEmbeddings（模型：BAAI/bge-small-en-v1.5）生成语义向量。
+  - 通过 Chroma(persist_directory=...) 创建可持久化、支持增删改的向量库。
+  - 自动分批插入（每批 ≤5000 条），规避 Chroma 单次写入上限限制。
+
+- 注意事项：
+  - 该脚本仅需运行一次，成功后会生成目录 chroma_db_war_and_peace_bge_small_en_v1.5。
+  - 首次运行需下载 Embedding 模型（约2分钟）+ 向量化全文（约3分钟），总耗时较长。
+  - ✅ 项目已附带预建好的 chroma_db_war_and_peace_bge_small_en_v1.5 文件夹，推荐直接使用，无需重复运行此脚本。
+  - 如需重建，请先手动删除该目录再执行。
+
+---
+
+### 3. `01_load_from_chroma.py` （从 Chroma 加载向量库）
+
+加载已持久化的 Chroma 向量数据库，用于后续检索。
+
+- ✅ 掌握点：
+  - 使用 `Chroma(persist_directory="...")` 从磁盘加载已保存的向量库。
+  - 无需重新向量化，实现“离线索引”快速启动。
+  - 获取 `db.as_retriever()` 作为后续 RAG 流程的输入。
+
+- 依赖前提：
+  - 必须存在 `chroma_db_war_and_peace_bge_small_en_v1.5` 目录。
+
+---
+
+### 4. `02_reranker.py` （引入精排序器）
+
+在召回结果上应用 Reranker 模型，提升上下文相关性。
+
+- ✅ 掌握点：
+  - 使用 `BAAI/bge-reranker-base` Cross-Encoder 对检索结果进行重排序。
+  - 通过 `ContextualCompressionRetriever` 封装为统一检索器。
+  - 仅保留 Top-2 最相关文档，过滤语义噪声。
+
+- 依赖前提：
+  - 必须存在 `chroma_db_war_and_peace_bge_small_en_v1.5` 目录。
+
+---
+
+### 5. `03_rag_as_tool.py` （RAG 工具化封装）
+
+将 RAG 链封装为 LangChain `@tool`，供 Agent 调用。
+
+- ✅ 掌握点：
+  - 在启动时一次性构建 RAG 链（避免每次调用重复加载模型/数据库）。
+  - 使用 `@tool` 装饰器注册 `search_war_and_peace(query)` 函数。
+  - 支持与其他工具（如 `get_weather`）并列使用。
+
+- 依赖前提：
+  - 必须存在 `chroma_db_war_and_peace_bge_small_en_v1.5` 目录。
+
+---
+
+### 6. `04_memory_rag_agent.py` （终极集成 Agent）
+
+首次融合 LangChain 六大核心模块，构建带记忆、能自主决策的智能体。
+
+- ✅ 掌握点：
+  - LLM：ChatOpenAI 作为推理引擎。
+  - Prompt：含 MessagesPlaceholder("history") 的系统提示。
+  - Chain：LCEL 构建的 RAG 链 + AgentExecutor。
+  - Memory：RunnableWithMessageHistory 实现跨轮次上下文记忆。
+  - Agents：create_tool_calling_agent 驱动 ReAct 循环。
+  - RAG：以 search_war_and_peace 工具形式注入私有知识能力。
+
+- 效果：
+  - Agent 可结合历史（如“他”指皮埃尔）精准调用 RAG，同时支持查天气等外部工具。
+
+- 依赖前提：
+  - 必须存在 `chroma_db_war_and_peace_bge_small_en_v1.5` 目录。
+
+---
+
+### 🔔 全局注意事项
+
+- 所有 `.py` 文件（除 `build_index.py` 外）均依赖 `chroma_db_war_and_peace_bge_small_en_v1.5` 目录。
+- 推荐直接使用已提供的向量数据库文件夹，跳过 `build_index.py` 的长时间构建过程。
+- 若自行运行 `build_index.py`，请确保 `war_and_peace.txt` 已就位。
+- 如需更换 Embedding 模型（如升级至 `bge-m3`），需同步更新 `build_index.py` 和 RAG 脚本中的模型名。
+
+
+---
+
+### 💡 **建议**：
+
+直接运行 04_memory_rag_agent.py 体验完整 Agent 能力；若想自定义知识库，可替换 war_and_peace.txt 并重新运行 build_index.py（记得先删除旧数据库目录）。