From 6332ff93bb7e26a8d97a5d0dc592b6b6a92e7020 Mon Sep 17 00:00:00 2001 From: "2287551746@qq.com" <2287551746@example.com> Date: Sun, 2 Nov 2025 21:00:31 +0800 Subject: [PATCH] 2025.11.2 --- .github/workflows/ci.yml | 7 +- 06_rag_basics/01_load_and_split.py | 82 +++++++++++++++++++ 06_rag_basics/02_embedding.py | 19 +++++ 06_rag_basics/03_build_index.py | 77 ++++++++++++++++++ 06_rag_basics/04_rag_chain_full.py | 124 +++++++++++++++++++++++++++++ 06_rag_basics/README.md | 51 ++++++++++++ README.md | 41 +++++----- requirements.txt | 6 +- 8 files changed, 384 insertions(+), 23 deletions(-) create mode 100644 06_rag_basics/01_load_and_split.py create mode 100644 06_rag_basics/02_embedding.py create mode 100644 06_rag_basics/03_build_index.py create mode 100644 06_rag_basics/04_rag_chain_full.py create mode 100644 06_rag_basics/README.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 37cae60..5722771 100644 --- a/.github/workflows/ci.yml +++ b/.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 - pip install pytest + # 使用--use-deprecated=legacy-resolver来更好地处理依赖冲突 + pip install -r requirements.txt --use-deprecated=legacy-resolver + pip install pytest faiss-cpu - name: Run basic checks run: | diff --git a/06_rag_basics/01_load_and_split.py b/06_rag_basics/01_load_and_split.py new file mode 100644 index 0000000..c6b7159 --- /dev/null +++ b/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') + + + + + + + + + + + + + + + + diff --git a/06_rag_basics/02_embedding.py b/06_rag_basics/02_embedding.py new file mode 100644 index 0000000..bdaecea --- /dev/null +++ b/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)}') \ No newline at end of file diff --git a/06_rag_basics/03_build_index.py b/06_rag_basics/03_build_index.py new file mode 100644 index 0000000..4b28d6b --- /dev/null +++ b/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('---所有阶段已经完成!---') + + + + + + + + + + + + + + diff --git a/06_rag_basics/04_rag_chain_full.py b/06_rag_basics/04_rag_chain_full.py new file mode 100644 index 0000000..d02cbbb --- /dev/null +++ b/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") + + + + + + + + + + + + diff --git a/06_rag_basics/README.md b/06_rag_basics/README.md new file mode 100644 index 0000000..b568765 --- /dev/null +++ b/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 问答效果的变化。 \ No newline at end of file diff --git a/README.md b/README.md index e86c764..bb68038 100644 --- a/README.md +++ b/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 | ⭐ | -| | [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 · 工具函数封装 | ⭐⭐ | -| ⚙️ **框架篇** | [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 · 缓存 · 流式输出 | ⭐⭐⭐ | -| | 06 RAG 基础篇（Embedding & 向量） | 🚧撰写中 | 向量化 · 检索匹配 | ⭐⭐ | -| | 07 RAG 进阶篇（检索 + 生成） | 🚧 | RAG Pipeline · QA 系统 | ⭐⭐⭐ | -| | 08 LangGraph 入门 | 🚧 | Flow · Node · Edge 控制 | ⭐⭐⭐ | -| 🧠 **智能篇** | 09 MCP 基础 | 🚧 | MCP 协议 · 客户端安装 | ⭐⭐ | -| | 10 MCP 进阶 | 🚧 | 在线模型接入 · 多轮任务 | ⭐⭐⭐ | -| | 11 MCP 高级 | 🚧 | 多服务组合 · 并发调用 | ⭐⭐⭐⭐ | -| | 12 多步骤任务规划（MCP Task Planning） | 🚧 | Task Planning · CoT | ⭐⭐⭐ | -| | 13 多智能体协作 | 🚧 | Multi-Agent · 通信机制 | ⭐⭐⭐⭐ | -| | 14 综合案例实战 | 🚧 | LangChain + RAG + Tool + Memory | ⭐⭐⭐⭐ | -| 🚀 **工程篇** | 15 部署与本地化 | 🚧 | Ollama · LM Studio · API代理 | ⭐⭐⭐ | -| | 16 Agent SDK 封装 | 🚧 | 模块化封装 · SDK 架构 | ⭐⭐⭐⭐ | +| 章节 | 模块 | 博客 | 核心关键词 | 难度 | +|:-----------:|:--------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------:|:------------------------------------------|:----:| +| 🏗️ **基础篇** | [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 · 上下文记忆 | ⭐ | +| | [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 | ⭐⭐ | +| | [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 & 向量） | [🏠](https://blog.csdn.net/2401_87328929/article/details/154230067) | RAG概念 · Split · Embedding · FAISS · RAG 链 | ⭐⭐ | +| | 07 RAG 进阶篇（检索 + 生成） | 🚧 | RAG Pipeline · QA 系统 | ⭐⭐⭐ | +| | 08 LangGraph 入门 | 🚧 | Flow · Node · Edge 控制 | ⭐⭐⭐ | +| 🧠 **智能篇** | 09 MCP 基础 | 🚧 | MCP 协议 · 客户端安装 | ⭐⭐ | +| | 10 MCP 进阶 | 🚧 | 在线模型接入 · 多轮任务 | ⭐⭐⭐ | +| | 11 MCP 高级 | 🚧 | 多服务组合 · 并发调用 | ⭐⭐⭐⭐ | +| | 12 多步骤任务规划（MCP Task Planning） | 🚧 | Task Planning · CoT | ⭐⭐⭐ | +| | 13 多智能体协作 | 🚧 | Multi-Agent · 通信机制 | ⭐⭐⭐⭐ | +| | 14 综合案例实战 | 🚧 | LangChain + RAG + Tool + Memory | ⭐⭐⭐⭐ | +| 🚀 **工程篇** | 15 部署与本地化 | 🚧 | Ollama · LM Studio · API代理 | ⭐⭐⭐ | +| | 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、多智能体等） --- diff --git a/requirements.txt b/requirements.txt index ba3ceed..ec89bb5 100644 --- a/requirements.txt +++ b/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 \ No newline at end of file +huggingface_hub[hf_xet]>=0.21.0 +faiss-cpu>=1.7.0 \ No newline at end of file