2025.11.2

.github/workflows/ci.yml

@@ -23,12 +23,13 @@ jobs:
       uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
-    
+
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -r requirements.txt
+        # 使用--use-deprecated=legacy-resolver来更好地处理依赖冲突
-        pip install pytest
+        pip install -r requirements.txt --use-deprecated=legacy-resolver
+        pip install pytest faiss-cpu
     
     - name: Run basic checks
       run: |

06_rag_basics/01_load_and_split.py

@@ -0,0 +1,82 @@
+import os
+from langchain_community.document_loaders import TextLoader # 加载
+from langchain_text_splitters import RecursiveCharacterTextSplitter # 分割
+
+
+# 创建一个演示txt文件
+knowledge_base_content = """
+### 模块 01 — Agent 入门 & 环境搭建
+
+- **目标**：理解 Agent 概念，完成环境配置与首次调用。
+- **内容**：环境依赖｜API Key 配置｜最小可运行 Agent
+
+### 模块 02 — LLM 基础调用
+
+- **目标**：掌握模型调用逻辑，初步构建智能体能力。
+- **内容**：LLM了解与调用｜Prompt编写与逻辑构思｜多轮对话记忆｜独立搭建一个智能体
+
+### 模块 03 — Function Calling 与工具调用
+
+- **目标**：实现 LLM 调用外部函数，赋予模型“执行力”。
+- **内容**：Function calling原理｜工具函数封装｜API接入实践｜多轮调用流程｜Agent能力扩展
+
+### 模块 04 — LangChain 基础篇
+
+- **目标**：认识Langchain六大模块，学会用Langchain构建智能体。
+- **内容**：LLM 调用｜Prompt 设计｜Chain 构建｜Memory 记忆｜实战练习
+
+### 模块 05 — LangChain 进阶篇
+
+- **目标**：掌握Langchain Agents的核心机制，构建能调用工具、持续思考、具备记忆的智能体。
+- **内容**：Function Calling｜@tool 工具封装｜ReAct 循环｜Agent 构建｜SQL Agent｜记忆+流式｜开发优化
+
+"""
+
+
+with open('knowledge_base.txt','w',encoding='utf8') as f:
+    f.write(knowledge_base_content)
+
+# 1.加载
+# TextLoader 读取.txt文件，并将其转换为Document对象
+loader = TextLoader('knowledge_base.txt',encoding='utf8')
+docs = loader.load()
+print(f'{docs}已加载完成!')
+
+# 2.分割
+text_splitter = RecursiveCharacterTextSplitter(
+    # 本节重点
+    chunk_size=250, # 设定的chunk块大小(字符数),
+    chunk_overlap=40 # 设定的重叠大小(字符数)
+) # 创建分割器的配置模板
+splits = text_splitter.split_documents(docs) # 实际执行切割
+
+print(f'分块结果:{len(splits)}')
+
+for i,doc in enumerate(splits):
+    print(f'片段{i+1}(长度:{len(doc.page_content)})')
+    print(doc.page_content)
+    print('-'*100+'\n')
+
+
+# 观察：
+# 我们的文本被分割成了四块，没有一块的长度超过250.
+# 所以没有用到overlap(重叠)，这是最好的结果
+
+# 删除txt文件
+os.remove('knowledge_base.txt')
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

06_rag_basics/02_embedding.py

@@ -0,0 +1,19 @@
+from langchain_huggingface import HuggingFaceEmbeddings
+
+# 第一次运行可能时间较久
+print('---正在首次加载本地嵌入模型(bge-small-zh-v1.5)...---')
+
+# 理论：有embedding的向量模型
+embeddings_model = HuggingFaceEmbeddings(
+    model_name="BAAI/bge-small-zh-v1.5" # 一个中英双语开源模型
+)
+print('嵌入模型载入完毕')
+
+# 演示：将文本转换为向量
+text = "模块05的目标是什么"
+query_embedding = embeddings_model.embed_query(text)
+
+# 验证：向量存在，而且有具体数值
+print(f'文本:{text}')
+print(f'向量(前五维):{query_embedding[:5]}')
+print(f'向量维度:{len(query_embedding)}')

06_rag_basics/03_build_index.py

@@ -0,0 +1,77 @@
+# 仅负责: 切片 -> 向量化 -> 构建索引 -> 保存到磁盘
+# 运行一次即可，无需每次检索都运行
+
+import os
+from langchain_community.document_loaders import TextLoader
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+from langchain_huggingface import HuggingFaceEmbeddings
+from langchain_community.vectorstores import FAISS
+
+# 准备知识库内容
+knowledge_base_content = """
+### 模块 01 — Agent 入门 & 环境搭建
+
+- **目标**：理解 Agent 概念，完成环境配置与首次调用。
+- **内容**：环境依赖｜API Key 配置｜最小可运行 Agent
+
+### 模块 02 — LLM 基础调用
+
+- **目标**：掌握模型调用逻辑，初步构建智能体能力。
+- **内容**：LLM了解与调用｜Prompt编写与逻辑构思｜多轮对话记忆｜独立搭建一个智能体
+
+### 模块 03 — Function Calling 与工具调用
+
+- **目标**：实现 LLM 调用外部函数，赋予模型“执行力”。
+- **内容**：Function calling原理｜工具函数封装｜API接入实践｜多轮调用流程｜Agent能力扩展
+
+### 模块 04 — LangChain 基础篇
+
+- **目标**：认识Langchain六大模块，学会用Langchain构建智能体。
+- **内容**：LLM 调用｜Prompt 设计｜Chain 构建｜Memory 记忆｜实战练习
+
+### 模块 05 — LangChain 进阶篇
+
+- **目标**：掌握Langchain Agents的核心机制，构建能调用工具、持续思考、具备记忆的智能体。
+- **内容**：Function Calling｜@tool 工具封装｜ReAct 循环｜Agent 构建｜SQL Agent｜记忆+流式｜开发优化
+
+"""
+
+with open("knowledge_base.txt",'w',encoding='utf8') as f:
+    f.write(knowledge_base_content)
+
+
+# 1. 加载并切分文档 (Load&Split)
+loader = TextLoader("knowledge_base.txt",encoding='utf8')
+docs = loader.load()
+text_splitter = RecursiveCharacterTextSplitter(chunk_size=250,chunk_overlap=40) # 载入切分器模板
+splits = text_splitter.split_documents(docs) # 运行切分器
+print(f'p1完成，文档已切分成{len(splits)}个片段\n')
+
+# 2. 向量化(Embedding)
+embeddings_model = HuggingFaceEmbeddings(model_name="BAAI/bge-small-zh-v1.5") # 载入向量化模型
+print(f'p2完成，Embedding模型已准备\n') #
+
+# 3. 存储(Store)
+db = FAISS.from_documents(splits,embeddings_model) # 将分割块与向量化的模型传递给FAISS，FAISS会使用它们并完成最终向量数据库的构建。
+
+db.save_local("faiss_index")
+print(f'p3完成，向量数据库{db}已构建')
+
+# 清理临时文件
+os.remove("knowledge_base.txt")
+
+print('---所有阶段已经完成!---')
+
+
+
+
+
+
+
+
+
+
+
+
+
+

06_rag_basics/04_rag_chain_full.py

@@ -0,0 +1,124 @@
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+api_key = os.getenv("OPENAI_API_KEY")
+
+from langchain_community.document_loaders import TextLoader
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+from langchain_huggingface import HuggingFaceEmbeddings
+from langchain_community.vectorstores import FAISS
+from langchain_openai import ChatOpenAI
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.output_parsers import StrOutputParser
+from langchain_core.runnables import RunnablePassthrough
+
+# --- 模块A (离线操作) ---
+# 1. 加载&分割 2. 向量化 3. 存储
+KNOWLEDGE_BASE_CONTENT = """
+### 模块 01 - Agent 入门 & 环境搭建
+- **目标**: 理解 Agent 概念, 完成环境配置与首次调用。
+- **内容**: 环境依赖 | API Key 配置 | 最小可运行 Agent
+
+### 模块 02 - LLM 基础调用
+- **目标**: 掌握模型调用逻辑, 初步构建智能体能力。
+- **内容**: LLM 了解与调用 | Prompt 编写与逻辑构思 | 多轮对话记忆 | 独立构建一个智能体
+
+### 模块 03 - Function Calling 与工具调用
+- **目标**: 实现 LLM 调用外部函数, 赋予模型“执行力”。
+- **内容**: Function calling 原理 | 工具函数封装 | API 接入实践 | 多轮调用流程 | Agent 能力扩展
+
+### 模块 04 - LangChain 基础篇
+- **目标**: 认识 LangChain 六大模块, 学会用 LangChain 构建智能体。
+- **内容**: LLM 调用 | Prompt 设计 | Chain 构建 | Memory 记忆 | 实战练习
+
+### 模块 05 - LangChain 进阶篇
+- **目标**: 掌握 LangChain Agents 的核心机制, 构建能调用工具、持续思考、具备记忆的智能体。
+- **内容**: Function Calling | @tool 工具封装 | ReAct 循环 | Agent 构建 | SQL Agent | 记忆+流式 | 开发优化
+"""
+with open("knowledge_base.txt", "w", encoding="utf-8") as f:
+    f.write(KNOWLEDGE_BASE_CONTENT)
+
+loader = TextLoader('knowledge_base.txt',encoding='utf8')
+docs = loader.load()
+text_splitter = RecursiveCharacterTextSplitter(chunk_size=250,chunk_overlap=40)
+splits = text_splitter.split_documents(docs)
+embedding_model = HuggingFaceEmbeddings(model_name="BAAI/bge-small-zh-v1.5")
+db = FAISS.from_documents(splits,embedding_model)
+print('---模块A(Indexing)完成---\n')
+
+
+
+# --- 模块B (在线运行:Online R-A-G Flow) ---
+print('--- 模块B R-A-G正在构建---\n')
+
+# 1. R (Retrieval - 检索)
+retrieve = db.as_retriever(search_kwarg={"k":1}) # 只返回最相关的1个
+
+# 2. A (Augmented - 增强)
+system = """
+请你扮演一个 Ai Agent 教学助手。
+请你只根据下面提供的“上下文”来回答问题。
+如果上下文中没有提到，请回答“对不起，我不知道”。
+
+[上下文]:
+{context}
+
+[问题]:
+{question}
+"""
+prompt = ChatPromptTemplate.from_messages([
+    ('system',system),
+    ('human','{question}')
+])
+
+# 3. G (Generation - 生成)
+llm = ChatOpenAI(
+    model="deepseek-chat",
+    api_key=api_key,
+    base_url="https://api.deepseek.com"
+)
+
+# 4. 辅助函数：将检索到的Doc原始文档对象格式化为字符串，让llm能读懂
+def format_docs(docs):
+    return "\n".join(doc.page_content for doc in docs)
+
+# 5. 组装 RAG 链条(LCEL)
+rag_chain = (
+    {"context":retrieve | format_docs,"question":RunnablePassthrough()}
+    | prompt
+    | llm
+    | StrOutputParser()
+)
+
+# --- 运行 RAG 链 ---
+
+question = '模块05的目标是什么？'
+response = rag_chain.invoke(question)
+print(f'提问:{question}')
+print(f'回答:{response}\n')
+
+question = 'Langchain进阶篇讲了什么？'
+response = rag_chain.invoke(question)
+print(f'提问:{question}')
+print(f'回答:{response}\n')
+
+question = '今天天气怎么样？'  # 知识库中没有
+response = rag_chain.invoke(question)
+print(f'提问:{question}')
+print(f'回答:{response}\n')
+
+# 清理临时文件
+os.remove("knowledge_base.txt")
+
+
+
+
+
+
+
+
+
+
+
+

06_rag_basics/README.md

@@ -0,0 +1,51 @@
+## 🧩 模块说明：RAG 基础 - 构建专属知识库
+
+📌 **核心知识点**：  
+RAG 概念｜文本加载与分块 (Load & Split)｜向量化 (Embedding)｜向量存储 (FAISS)｜LCEL RAG 链
+
+---
+
+### 1. `01_load_and_split.py`（文本加载与分块）
+加载本地 `.txt` 文档，并使用 `RecursiveCharacterTextSplitter` 将其智能分割成“知识卡片”。
+
+✅ **掌握点**：
+- 使用 `TextLoader` 将文件加载为 `Document` 对象。
+- **RAG 核心**：深入理解 `chunk_size` (分块大小) 和 `chunk_overlap` (重叠) 的调优策略。
+- `RecursiveCharacterTextSplitter` 如何按 `["\n\n", "\n", " "]` 优先级智能分割。
+
+---
+
+### 2. `02_embedding.py`（文本向量化）
+演示如何加载本地 Embedding 模型，并将任意文本（知识卡片）转换为“语义向量”。
+
+✅ **掌握点**：
+- 使用 `HuggingFaceEmbeddings` 加载开源本地模型（如 `BAAI/bge-small-zh-v1.5`）。
+- 理解 Embedding（向量化）是 RAG 的“语义标签”，用于实现“语义搜索”。
+- 如何调用 `embed_query` 将文本转换为向量（一串数字）。
+
+---
+
+### 3. `03_build_index.py`（构建并存储索引）
+整合“加载”、“分块”和“向量化”三个步骤，构建 FAISS 向量索引库，并将其**持久化**保存到本地磁盘。
+
+✅ **掌握点**：
+- 什么是 FAISS（轻量级、高性能的向量索引库）。
+- 如何使用 `FAISS.from_documents` 一键完成“批量向量化+构建索引”。
+- 如何使用 `db.save_local` 将索引保存到磁盘，实现**“离线索引”**。
+
+---
+
+### 4. `04_rag_chain_full.py`（LCEL 完整 RAG 链）
+使用 LCEL（LangChain 表达式语言）“手动组装”一个完整的 RAG 流程，实现“检索-增强-生成”的闭环。
+
+✅ **掌握点**：
+- R (Retrieval): `db.as_retriever()` 如何作为检索器。
+- A (Augmented): `ChatPromptTemplate` 如何接收 `{context}` 和 `{question}`。
+- G (Generation): LLM 如何根据上下文（Context）回答问题。
+- **LCEL 核心**：使用 `{"context": ..., "question": RunnablePassthrough()}` 并行组装数据流。
+- 使用 `format_docs` 函数将 `List[Document]` 适配为 `str` 字符串。
+
+---
+
+💡 **建议**：
+跑通所有示例后，尝试用你自己的 `.txt` 文件替换 `knowledge_base.txt`，并调整 `chunk_size` 参数，观察分块结果和 RAG 问答效果的变化。

README.md

@@ -23,24 +23,24 @@
 > 💡 每个模块对应独立目录（含代码、说明与示例），可独立运行与学习。  
 > 🔥 已更新至 05 LangChain 进阶篇，持续更新中！
 
-|     章节      | 模块                                                                                                      |                                 博客                                  | 核心关键词                           |  难度  |
+|     章节      | 模块                                                                                                      |                                 博客                                  | 核心关键词                                     |  难度  |
-|:-----------:|:--------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------:|:--------------------------------|:----:|
+|:-----------:|:--------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------:|:------------------------------------------|:----:|
-| 🏗️ **基础篇** | [01 Agent 入门 & 环境搭建](https://github.com/Annyfee/agent-craft/tree/main/01_agent_introduction)            | [🏠](https://blog.csdn.net/2401_87328929/article/details/153729555) | OpenAI API                      |  ⭐   |
+| 🏗️ **基础篇** | [01 Agent 入门 & 环境搭建](https://github.com/Annyfee/agent-craft/tree/main/01_agent_introduction)            | [🏠](https://blog.csdn.net/2401_87328929/article/details/153729555) | OpenAI API                                |  ⭐   |
-|             | [02 LLM 基础调用](https://github.com/Annyfee/agent-craft/tree/main/02_llm_fundamentals)                     | [🏠](https://blog.csdn.net/2401_87328929/article/details/153735431) | LLM API 调用 · prompt · 上下文记忆     |  ⭐   |
+|             | [02 LLM 基础调用](https://github.com/Annyfee/agent-craft/tree/main/02_llm_fundamentals)                     | [🏠](https://blog.csdn.net/2401_87328929/article/details/153735431) | LLM API 调用 · prompt · 上下文记忆               |  ⭐   |
-|             | [03 Function Calling 与工具调用](https://github.com/Annyfee/agent-craft/tree/main/03_function_calling_tools) | [🏠](https://blog.csdn.net/2401_87328929/article/details/153866573) | Function Call · 工具函数封装          |  ⭐⭐  |
+|             | [03 Function Calling 与工具调用](https://github.com/Annyfee/agent-craft/tree/main/03_function_calling_tools) | [🏠](https://blog.csdn.net/2401_87328929/article/details/153866573) | Function Call · 工具函数封装                    |  ⭐⭐  |
-| ⚙️ **框架篇**  | [04 LangChain 基础篇](https://github.com/Annyfee/agent-craft/tree/main/04_langchain_basics)                | [🏠](https://blog.csdn.net/2401_87328929/article/details/153978186) | LLM · Prompt · Chain · Memory   |  ⭐⭐  |
+| ⚙️ **框架篇**  | [04 LangChain 基础篇](https://github.com/Annyfee/agent-craft/tree/main/04_langchain_basics)                | [🏠](https://blog.csdn.net/2401_87328929/article/details/153978186) | LLM · Prompt · Chain · Memory             |  ⭐⭐  |
-|             | [05 LangChain 进阶篇](https://github.com/Annyfee/agent-craft/tree/main/05_langchain_advanced)              | [🏠](https://blog.csdn.net/2401_87328929/article/details/154064397) | Agents · 缓存 · 流式输出              | ⭐⭐⭐  |
+|             | [05 LangChain 进阶篇](https://github.com/Annyfee/agent-craft/tree/main/05_langchain_advanced)              | [🏠](https://blog.csdn.net/2401_87328929/article/details/154064397) | Agents · 缓存 · 流式输出                        | ⭐⭐⭐  |
-|             | 06 RAG 基础篇（Embedding & 向量）                                                                              |                                🚧撰写中                                | 向量化 · 检索匹配                      |  ⭐⭐  |
+|             | 06 RAG 基础篇（Embedding & 向量）                                                                              | [🏠](https://blog.csdn.net/2401_87328929/article/details/154230067) | RAG概念 · Split · Embedding · FAISS · RAG 链 |  ⭐⭐  |
-|             | 07 RAG 进阶篇（检索 + 生成）                                                                                     |                                 🚧                                  | RAG Pipeline · QA 系统            | ⭐⭐⭐  |
+|             | 07 RAG 进阶篇（检索 + 生成）                                                                                     |                                 🚧                                  | RAG Pipeline · QA 系统                      | ⭐⭐⭐  |
-|             | 08 LangGraph 入门                                                                                         |                                 🚧                                  | Flow · Node · Edge 控制           | ⭐⭐⭐  |
+|             | 08 LangGraph 入门                                                                                         |                                 🚧                                  | Flow · Node · Edge 控制                     | ⭐⭐⭐  |
-| 🧠 **智能篇**  | 09 MCP 基础                                                                                               |                                 🚧                                  | MCP 协议 · 客户端安装                  |  ⭐⭐  |
+| 🧠 **智能篇**  | 09 MCP 基础                                                                                               |                                 🚧                                  | MCP 协议 · 客户端安装                            |  ⭐⭐  |
-|             | 10 MCP 进阶                                                                                               |                                 🚧                                  | 在线模型接入 · 多轮任务                   | ⭐⭐⭐  |
+|             | 10 MCP 进阶                                                                                               |                                 🚧                                  | 在线模型接入 · 多轮任务                             | ⭐⭐⭐  |
-|             | 11 MCP 高级                                                                                               |                                 🚧                                  | 多服务组合 · 并发调用                    | ⭐⭐⭐⭐ |
+|             | 11 MCP 高级                                                                                               |                                 🚧                                  | 多服务组合 · 并发调用                              | ⭐⭐⭐⭐ |
-|             | 12 多步骤任务规划（MCP Task Planning）                                                                           |                                 🚧                                  | Task Planning · CoT             | ⭐⭐⭐  |
+|             | 12 多步骤任务规划（MCP Task Planning）                                                                           |                                 🚧                                  | Task Planning · CoT                       | ⭐⭐⭐  |
-|             | 13 多智能体协作                                                                                               |                                 🚧                                  | Multi-Agent · 通信机制              | ⭐⭐⭐⭐ |
+|             | 13 多智能体协作                                                                                               |                                 🚧                                  | Multi-Agent · 通信机制                        | ⭐⭐⭐⭐ |
-|             | 14 综合案例实战                                                                                               |                                 🚧                                  | LangChain + RAG + Tool + Memory | ⭐⭐⭐⭐ |
+|             | 14 综合案例实战                                                                                               |                                 🚧                                  | LangChain + RAG + Tool + Memory           | ⭐⭐⭐⭐ |
-| 🚀 **工程篇**  | 15 部署与本地化                                                                                               |                                 🚧                                  | Ollama · LM Studio · API代理      | ⭐⭐⭐  |
+| 🚀 **工程篇**  | 15 部署与本地化                                                                                               |                                 🚧                                  | Ollama · LM Studio · API代理                | ⭐⭐⭐  |
-|             | 16 Agent SDK 封装                                                                                         |                                 🚧                                  | 模块化封装 · SDK 架构                  | ⭐⭐⭐⭐ |
+|             | 16 Agent SDK 封装                                                                                         |                                 🚧                                  | 模块化封装 · SDK 架构                            | ⭐⭐⭐⭐ |
 
 ---
 
@@ -74,6 +74,11 @@
 - **目标**：掌握Langchain Agents的核心机制，构建能调用工具、持续思考、具备记忆的智能体。
 - **内容**：Function Calling｜@tool 工具封装｜ReAct 循环｜Agent 构建｜SQL Agent｜记忆+流式｜开发优化
 
+### ✅ 模块 06 — Rag 基础篇
+
+- **目标**：理解Rag的概念与整个运行流程，并能最终搭建一个可以引用外部知识库获取信息的智能体。
+- **内容**：RAG 概念｜文本加载与分块 (Load & Split)｜向量化 (Embedding)｜向量存储 (FAISS)｜LCEL RAG 链
+
 > 📌 后续模块将陆续开放（LangGraph、RAG、MCP、多智能体等）
 
 ---

requirements.txt

@@ -1,6 +1,8 @@
 python-dotenv~=1.0.0
-openai>=2.6.0
+openai<2.0.0,>=1.40.0
 requests~=2.32.4
 langchain~=0.2.16
+langchain-openai~=0.1.15
 langchain-huggingface>=0.0.3
-huggingface_hub[hf_xet]>=0.21.0
+huggingface_hub[hf_xet]>=0.21.0
+faiss-cpu>=1.7.0