# 第一节 环境配置与项目架构 > 经过前面十几天的鏖战也是终于来到了项目实战环节。接下来，通过一个完整的实战项目来把前面学到的知识串联起来，构建一个真正可用的RAG系统。 ## 一、项目背景 这个项目的灵感来自于笔者前段时间刷视频时，偶然看到了一个有趣的开源项目介绍——[程序员做饭指南](https://github.com/Anduin2017/HowToCook)。这是一个菜谱项目，用Markdown格式记录了各种菜品的制作方法，从简单的家常菜到复杂的宴客菜，应有尽有。更完美的是，这个项目中每道菜的Markdown文件都严格使用统一的小标题。 看到这个项目，笔者立刻想到：能不能构建一个智能问答系统来解决我的选择困难症？每天面对"今天吃什么"这个世纪难题，如果有个AI助手能根据我的需求推荐菜品、告诉我怎么做，那该多好！于是就有了搭建这个**尝尝咸淡RAG系统**的想法。 ## 二、环境配置 ### 2.1 创建虚拟环境 ```bash # 使用conda创建环境 conda create -n cook-rag-1 python=3.12.7 conda activate cook-rag-1 ``` ### 2.2 安装核心依赖 老规矩，进入本章对应项目目录安装依赖包 ```bash cd code/C8 pip install -r requirements.txt ``` 如果 API Key 已经配置好了，可以直接使用下面命令运行项目 ```bash python main.py ``` ### 2.3 申请Kimi API Key Kimi2 发布第八天来尝尝咸淡，申请地址：[Kimi API官网](https://platform.moonshot.cn/console/api-keys)。目前注册会送15元的额度，绰绰有余了。 ### 2.4 API配置 参考前面章节 [**环境准备**](../chapter1/02_preparation.md) 中关于api_key的配置方法。在windows下，配置完成后应该如下图所示： ![API配置](./images/8_1_1.webp) ## 三、项目架构 ### 3.1 项目目标 我们将基于HowToCook项目的菜谱数据，构建一个智能的食谱问答系统。用户可以： - 询问具体菜品的制作方法："宫保鸡丁怎么做？" - 寻求菜品推荐："推荐几个简单的素菜" - 获取食材信息："红烧肉需要什么食材？" ### 3.2 数据分析 #### 3.2.1 文档分析 HowToCook项目包含了大约300多个Markdown格式的菜谱文件。这些菜谱有两个关键特点：一是结构高度规整，每个文件都严格按照统一的格式来组织内容；二是内容篇幅较短，单个菜谱通常在700字左右。 打开任意一个菜谱文件，可以发现它们都遵循着相似的结构模式。通常以菜品做法作为一级标题，开头会有一段简介和难度评级，然后分为"必备原料和工具"、"计算"、"操作"、"附加内容"等几个主要部分。比如西红柿炒鸡蛋这道菜： ```markdown # 西红柿炒鸡蛋的做法 西红柿炒蛋是中国家常几乎最常见的一道菜肴... 预估烹饪难度：★★ ## 必备原料和工具 * 西红柿 * 鸡蛋 * 食用油... ## 计算 每次制作前需要确定计划做几份... * 西红柿 = 1 个（约 180g） * 份数 * 鸡蛋 = 1.5 个 * 份数，向上取整... ## 操作 - 西红柿洗净 - 可选：去掉西红柿的外表皮... ## 附加内容 这道菜根据不同的口味偏好，存在诸多版本... ``` 从数据上来看，这种高度结构化的数据不需要过多处理就可以直接用于RAG系统构建。还记得我们在第2章学过的[**Markdown结构分块**](../chapter2/05_text_chunking.md#34-基于文档结构的分块)吗？这个数据完全契合那种按标题层级分块的思路。更重要的是，每个菜谱文件的内容都不算太长，单个章节的内容通常在几百字左右，这意味着可以直接按照标题进行分块，而不用担心第2章提到的那个问题——某个章节内容过长超出模型上下文窗口，需要与常规分块方法（如`RecursiveCharacterTextSplitter`）组合使用。 #### 3.2.2 结构分块局限 虽然Markdown结构分块看起来很理想，但在实际使用中可能会遇到一个问题：按照标题严格分块会把内容切得太细，导致上下文信息不完整。比如用户问"宫保鸡丁怎么做"，如果严格按标题分块，可能只检索到"操作"这一个章节，但缺少了"必备原料和工具"的信息，LLM就无法给出完整的制作指导。甚至有时候检索到的是"附加内容"中的某个变化做法，没有基础制作步骤，回答就会显得莫名其妙。如果你尝试直接把整个菜谱文档作为一个块，可以发现效果反而比结构分块要好，因为上下文信息是完整的。 为了解决这个矛盾，可以采用父子文本块的策略：用小的子块进行精确检索，但在生成时传递完整的父文档给LLM。这种方法在第3章的索引优化中虽然没有专门介绍，但本质上也属于上下文拓展的一种应用。通过这种方式，我们既保证了检索的精确性，又确保了生成时上下文的完整性。 > 反正都是把整个文档传给LLM，我为什么不直接用整个文档分块呢？ 这个问题问得很好！关键在于当用户问"宫保鸡丁需要什么调料"时，如果直接用整个文档做向量检索，这个具体问题在整个文档中的占比很小，很可能检索不到或者排名很靠后。但如果用小块检索，"必备原料和工具"这个章节就能精确匹配用户的需求。 简单来说，这种设计是"小块检索，大块生成"——用小块的精确性找到相关内容，用大块的完整性保证回答质量。如果直接用整个文档分块，就失去了检索的精确性优势。 ### 3.3 整体架构 数据处理好之后，剩余的部分就是四个主要流程的组合，每个流程对工具进行筛选和优化后就可以构建出一个简单的rag系统。当前项目的架构如下图所示： ```mermaid flowchart TD %% 系统初始化 START[🚀 系统启动] --> CONFIG[⚙️ 加载配置
RAGConfig] CONFIG --> INIT[🔧 初始化模块] %% 索引加载/构建 INIT --> INDEX_CHECK{📂 检查索引缓存} INDEX_CHECK -->|存在| LOAD_INDEX[⚡ 加载已保存索引
秒级启动] INDEX_CHECK -->|不存在| BUILD_NEW[🔨 构建新索引] %% 构建新索引的顺序流程 BUILD_NEW --> DataPrep DataPrep --> IndexBuild IndexBuild --> SAVE_INDEX[💾 保存索引到配置路径] %% 加载已有索引也需要数据准备（用于检索模块） LOAD_INDEX --> DataPrepForRetrieval[📚 加载文档和分块
用于检索模块] DataPrepForRetrieval --> READY[✅ 系统就绪] SAVE_INDEX --> READY %% 用户交互开始 READY --> A[👤 用户输入问题] A --> B{🎯 查询路由} %% 查询路由分支 B -->|list| C[📋 推荐查询] B -->|detail| D[📖 详细查询] B -->|general| E[ℹ️ 一般查询] %% 查询重写逻辑 - 合并相同处理 C --> KEEP[📝 保持原查询] D --> KEEP E --> REWRITE[🔄 查询重写] %% 所有查询都进入统一的检索流程 KEEP --> F[🔍 混合检索
top_k=config.top_k] REWRITE --> F %% 检索阶段 F --> G[📊 向量检索
config.embedding_model] F --> H[🔤 BM25检索
关键词匹配] %% RRF重排 G --> I[⚡ RRF重排融合] H --> I I --> J[📖 检索到子块] %% 父子文档处理 J --> K[🧠 智能去重
按相关性排序] K --> L[📚 获取父文档] %% 生成阶段 - 根据路由类型选择不同模式 L --> M{🎨 生成模式路由} M -->|list查询| N[📋 生成菜品列表
简洁输出] M -->|detail查询| O[📝 分步指导模式
config.llm_model
详细步骤] M -->|general查询| P[💬 基础回答模式
config.temperature
一般信息] %% 输出结果 N --> Q[✨ 返回结果] O --> Q P --> Q %% 数据准备子流程 subgraph DataPrep [📚 数据准备模块] R[📁 加载Markdown文件
config.data_path] --> S[🔧 元数据增强] S --> T[✂️ 按标题分块] T --> U[🏷️ 父子关系建立] U --> CHUNKS[📦 输出文本块chunks] end %% 索引构建子流程 subgraph IndexBuild [🔍 索引构建模块] CHUNKS --> V[🤖 BGE嵌入模型
config.embedding_model] V --> W[📊 FAISS向量索引] W --> X[💾 索引持久化
config.index_save_path] end %% 配置管理子流程 subgraph ConfigMgmt [⚙️ 配置管理] CFG1[🎛️ 默认配置
DEFAULT_CONFIG] CFG2[🔧 自定义配置
RAGConfig] CFG3[🌐 环境变量
HF_ENDPOINT] end %% 连接配置到各模块 ConfigMgmt --> DataPrep ConfigMgmt --> IndexBuild ConfigMgmt --> F ConfigMgmt --> O ConfigMgmt --> P %% 样式定义 classDef startup fill:#e3f2fd,stroke:#0277bd,stroke-width:2px classDef config fill:#f1f8e9,stroke:#388e3c,stroke-width:2px classDef userInput fill:#e1f5fe,stroke:#01579b,stroke-width:2px classDef routing fill:#f3e5f5,stroke:#4a148c,stroke-width:2px classDef rewrite fill:#e8eaf6,stroke:#3f51b5,stroke-width:2px classDef retrieval fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px classDef generation fill:#fff3e0,stroke:#e65100,stroke-width:2px classDef output fill:#fce4ec,stroke:#880e4f,stroke-width:2px classDef module fill:#f1f8e9,stroke:#33691e,stroke-width:2px classDef cache fill:#fff8e1,stroke:#f57c00,stroke-width:2px classDef dataflow fill:#e1f5fe,stroke:#0277bd,stroke-width:2px %% 应用样式 class START,INIT startup class CONFIG,ConfigMgmt,CFG1,CFG2,CFG3 config class INDEX_CHECK,LOAD_INDEX,SAVE_INDEX cache class A userInput class B,C,D,E,M routing class KEEP,REWRITE rewrite class F,G,H,I,J,K,L retrieval class N,O,P generation class Q output class DataPrep,IndexBuild module class BUILD_NEW,READY,DataPrepForRetrieval startup class CHUNKS dataflow ``` ### 3.4 项目结构 基于上面的架构，可以构建出如下项目结构： ```text code/C8/ ├── config.py # 配置管理 ├── main.py # 主程序入口 ├── requirements.txt # 依赖列表 ├── rag_modules/ # 核心模块 │ ├── __init__.py │ ├── data_preparation.py # 数据准备模块 │ ├── index_construction.py # 索引构建模块 │ ├── retrieval_optimization.py # 检索优化模块 │ └── generation_integration.py # 生成集成模块 └── vector_index/ # 向量索引缓存（自动生成） ``` ## 小结 本节从项目背景出发，完成了RAG系统的环境配置和整体架构设计。从下一节开始，我们将深入学习各个模块的具体实现，看看如何将这些设计思路转化为可运行的代码。