# 🧩 模块说明：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）。
  - 通过根目录 `embeddings.py` 模块的 `get_embeddings()` 函数获取向量化模型（默认使用 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. `load_from_chroma.py` （从 Chroma 加载向量库）

加载已持久化的 Chroma 向量数据库，用于后续检索。

- ✅ 掌握点：
  - 通过根目录 `embeddings.py` 模块的 `get_embeddings()` 函数加载向量化模型。
  - 使用 `Chroma(persist_directory="...")` 从磁盘加载已保存的向量库。
  - 无需重新向量化，实现"离线索引"快速启动。
  - 获取 `db.as_retriever()` 作为后续 RAG 流程的输入。

- 依赖前提：
  - 必须存在 `chroma_db_war_and_peace_bge_small_en_v1.5` 目录。

---

### 4. `reranker.py` （引入精排序器）

在召回结果上应用 Reranker 模型，提升上下文相关性。

- ✅ 掌握点：
  - 通过根目录 `embeddings.py` 模块的 `get_embeddings()` 函数加载向量化模型。
  - 使用 `BAAI/bge-reranker-base` Cross-Encoder 对检索结果进行重排序。
  - 通过 `ContextualCompressionRetriever` 和 `CrossEncoderReranker` 实现检索增强。
  - 理解`k`与`top_n`的作用
  - 保留 Top-6 最相关文档，过滤语义噪声。

- 依赖前提：
  - 必须存在 `chroma_db_war_and_peace_bge_small_en_v1.5` 目录。

---

### 5. `rag_as_tool.py` （RAG 工具化封装）

将 RAG 链封装为 LangChain `@tool`，供 Agent 调用。

- ✅ 掌握点：
  - 通过根目录 `embeddings.py` 模块的 `get_embeddings()` 函数加载向量化模型。
  - 在启动时一次性构建 RAG 链（避免每次调用重复加载模型/数据库）。
  - 使用 `@tool` 装饰器注册 `search_war_and_peace(query)` 函数。
  - 支持与其他工具（如 `get_weather`）并列使用。

- 依赖前提：
  - 必须存在 `chroma_db_war_and_peace_bge_small_en_v1.5` 目录。

---

### 6. `memory_rag_agent.py` （终极集成 Agent）

首次融合 LangChain 六大核心模块，构建带记忆、能自主决策的智能体。

- ✅ 掌握点：
  - 通过根目录 `embeddings.py` 模块的 `get_embeddings()` 函数加载向量化模型。
  - 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 脚本中的模型名。


---

### 💡 **建议**：

直接运行 `memory_rag_agent.py` 体验完整 Agent 能力；若想自定义知识库，可替换 `war_and_peace.txt` 并重新运行 build_index.py（记得先删除旧数据库目录）。