[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"tool-bragai--bRAG-langchain":3,"similar-bragai--bRAG-langchain":94},{"id":4,"github_repo":5,"name":6,"description_en":7,"description_zh":8,"ai_summary_zh":8,"readme_en":9,"readme_zh":10,"quickstart_zh":11,"use_case_zh":12,"hero_image_url":13,"owner_login":14,"owner_name":15,"owner_avatar_url":16,"owner_bio":17,"owner_company":18,"owner_location":18,"owner_email":19,"owner_twitter":20,"owner_website":21,"owner_url":22,"languages":23,"stars":28,"forks":29,"last_commit_at":30,"license":31,"difficulty_score":32,"env_os":33,"env_gpu":34,"env_ram":34,"env_deps":35,"category_tags":44,"github_topics":50,"view_count":32,"oss_zip_url":18,"oss_zip_packed_at":18,"status":59,"created_at":60,"updated_at":61,"faqs":62,"releases":93},9306,"bragai\u002FbRAG-langchain","bRAG-langchain","Everything you need to know to build your own RAG application","bRAG-langchain 是一个基于 LangChain 框架构建的检索增强生成（RAG）开源学习项目，旨在为开发者提供从零开始搭建自定义 RAG 应用的全套指南。它有效解决了大语言模型在面对私有数据或特定领域知识时容易产生“幻觉”、回答不准确以及难以整合外部信息的痛点。\n\n该项目特别适合希望深入理解 RAG 架构原理并动手实践的 AI 工程师、研究人员及技术爱好者。通过一系列结构清晰的 Jupyter Notebook，bRAG-langchain 引导用户循序渐进地掌握核心技术：从基础的环境配置、文档加载、向量化存储，到进阶的多查询策略、逻辑与语义路由、元数据过滤搜索。其独特的技术亮点在于涵盖了多向量索引、RAPTOR 递归摘要树以及 ColBERT 细粒度令牌级检索等前沿方案，帮助用户构建更精准、高效的知识问答系统。无论是想快速获得一个可定制的聊天机器人模板，还是探索复杂的检索优化技巧，bRAG-langchain 都提供了详实的代码示例和理论支撑，是进入 RAG 开发领域的实用宝库。","# Retrieval-Augmented Generation (RAG) Project\n\n#### 🔜 Check out [bragai.dev](https:\u002F\u002Fbragai.dev) (launching soon)\n\n---------------------\n\nThis repository contains a comprehensive exploration of Retrieval-Augmented Generation (RAG) for various applications.\nEach notebook provides a detailed, hands-on guide to setting up and experimenting with RAG from an introductory level to advanced implementations, including multi-querying and custom RAG builds.\n\n![rag_detail_v2](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fbragai_bRAG-langchain_readme_84fad047d893.png)\n\n## Project Structure\n\nIf you want to jump straight into it, check out the file `full_basic_rag.ipynb` -> this file will give you a boilerplate starter code of a fully customizable RAG chatbot.\n\nMake sure to run your files in a virtual environment (checkout section `Get Started`)\n\nThe following notebooks can be found under the directory `notebooks\u002F`.\n\n### [1]\\_rag_setup_overview.ipynb\n\nThis introductory notebook provides an overview of RAG architecture and its foundational setup.\nThe notebook walks through: \n- **Environment Setup**: Configuring the environment, installing necessary libraries, and API setups.\n- **Initial Data Loading**: Basic document loaders and data preprocessing methods.\n- **Embedding Generation**: Generating embeddings using various models, including OpenAI's embeddings.\n- **Vector Store**: Setting up a vector store (ChromaDB\u002FPinecone) for efficient similarity search.\n- **Basic RAG Pipeline**: Creating a simple retrieval and generation pipeline to serve as a baseline.\n\n### [2]\\_rag_with_multi_query.ipynb\n\nBuilding on the basics, this notebook introduces multi-querying techniques in the RAG pipeline, exploring: \n- **Multi-Query Setup**: Configuring multiple queries to diversify retrieval.\n- **Advanced Embedding Techniques**: Utilizing multiple embedding models to refine retrieval.\n- **Pipeline with Multi-Querying**: Implementing multi-query handling to improve relevance in response generation.\n- **Comparison & Analysis**: Comparing results with single-query pipelines and analyzing performance improvements.\n\n### [3]_rag_routing_and_query_construction.ipynb\n\nThis notebook delves deeper into customizing a RAG pipeline.\nIt covers: \n- **Logical Routing:** Implements function-based routing for classifying user queries to appropriate data sources based on programming languages.\n- **Semantic Routing:** Uses embeddings and cosine similarity to direct questions to either a math or physics prompt, optimizing response accuracy.\n- **Query Structuring for Metadata Filters:** Defines structured search schema for YouTube tutorial metadata, enabling advanced filtering (e.g., by view count, publication date).\n- **Structured Search Prompting:** Leverages LLM prompts to generate database queries for retrieving relevant content based on user input.\n- **Integration with Vector Stores:** Links structured queries to vector stores for efficient data retrieval.\n\n\n### [4]_rag_indexing_and_advanced_retrieval.ipynb\n\nContinuing from the previous customization, this notebook explores:\n- **Preface on Document Chunking:** Points to external resources for document chunking techniques.\n- **Multi-representation Indexing:** Sets up a multi-vector indexing structure for handling documents with different embeddings and representations.\n- **In-Memory Storage for Summaries:** Uses InMemoryByteStore for storing document summaries alongside parent documents, enabling efficient retrieval.\n- **MultiVectorRetriever Setup:** Integrates multiple vector representations to retrieve relevant documents based on user queries.\n- **RAPTOR Implementation:** Explores RAPTOR, an advanced indexing and retrieval model, linking to in-depth resources.\n- **ColBERT Integration:** Demonstrates ColBERT-based token-level vector indexing and retrieval, which captures contextual meaning at a fine-grained level.\n- **Wikipedia Example with ColBERT:** Retrieves information about Hayao Miyazaki using the ColBERT retrieval model for demonstration.\n\n### [5]_rag_retrieval_and_reranking.ipynb\n\nThis final notebook brings together the RAG system components, with a focus on scalability and optimization: \n- **Document Loading and Splitting:** Loads and chunks documents for indexing, preparing them for vector storage.\n- **Multi-query Generation with RAG-Fusion:** Uses a prompt-based approach to generate multiple search queries from a single input question.\n- **Reciprocal Rank Fusion (RRF):** Implements RRF for re-ranking multiple retrieval lists, merging results for improved relevance.\n- **Retriever and RAG Chain Setup:** Constructs a retrieval chain for answering queries, using fused rankings and RAG chains to pull contextually relevant information.\n- **Cohere Re-Ranking:** Demonstrates re-ranking with Cohere’s model for additional contextual compression and refinement.\n- **CRAG and Self-RAG Retrieval:** Explores advanced retrieval approaches like CRAG and Self-RAG, with links to examples.\n- **Exploration of Long-Context Impact:** Links to resources explaining the impact of long-context retrieval on RAG models.\n\n## Getting Started\n\n### Pre-requisites\n\nEnsure **Python 3.11.11** (preferred) is installed on your system. Follow the platform-specific instructions below to install it if not already installed.\n\n#### macOS\n1. Install [Homebrew](https:\u002F\u002Fbrew.sh\u002F) if not already installed:\n   ```bash\n   \u002Fbin\u002Fbash -c \"$(curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FHomebrew\u002Finstall\u002FHEAD\u002Finstall.sh)\"\n   ```\n2. Install Python 3.11.11:\n   ```bash\n   brew install python@3.11\n   ```\n3. Verify installation:\n   ```bash\n   python3.11 --version\n   ```\n\n#### Linux\n1. Update your package manager:\n   ```bash\n   sudo apt update\n   ```\n2. Install Python 3.11.11:\n   ```bash\n   sudo apt install python3.11 python3.11-venv\n   ```\n3. Verify installation:\n   ```bash\n   python3.11 --version\n   ```\n\n#### Windows\n1. Download the Python 3.11.11 installer from [Python.org](https:\u002F\u002Fwww.python.org\u002Fdownloads\u002F).\n2. Run the installer and ensure you check the box **\"Add Python to PATH\"**.\n3. Verify installation:\n   ```cmd\n   python --version\n   ```\n---\n\n### Installation Instructions\n\n#### 1. Clone the Repository\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FbRAGAI\u002FbRAG-langchain.git\ncd bRAG-langchain\n```\n\n#### 2. Create a Virtual Environment\nUse Python 3.11.11 to create a virtual environment:\n```bash\npython3.11 -m venv venv\n```\n\nActivate the virtual environment:\n- **macOS\u002FLinux**:\n  ```bash\n  source venv\u002Fbin\u002Factivate\n  ```\n- **Windows**:\n  ```cmd\n  venv\\Scripts\\activate\n  ```\n\n#### 3. Verify and Fix Python Version\nIf the virtual environment defaults to a different Python version (e.g., Python 3.13):\n1. Verify the current Python version inside the virtual environment:\n   ```bash\n   python --version\n   ```\n2. Use Python 3.11 explicitly within the virtual environment:\n   ```bash\n   python3.11\n   ```\n3. Ensure the `python` command uses Python 3.11 by creating a symbolic link:\n   ```bash\n   ln -sf $(which python3.11) $(dirname $(which python))\u002Fpython\n   ```\n4. Verify the fix:\n   ```bash\n   python --version\n   ```\n\n#### 4. Install Dependencies\nInstall the required packages:\n```bash\npip install -r requirements.txt\n```\n\n---\n\n### Additional Steps\n\n#### 5. Run the Notebooks\nBegin with `[1]_rag_setup_overview.ipynb` to get familiar with the setup process. Proceed sequentially through the other notebooks:\n\n- `[1]_rag_setup_overview.ipynb`\n- `[2]_rag_with_multi_query.ipynb`\n- `[3]_rag_routing_and_query_construction.ipynb`\n- `[4]_rag_indexing_and_advanced_retrieval.ipynb`\n- `[5]_rag_retrieval_and_reranking.ipynb`\n\n#### 6. Set Up Environment Variables\n1. Duplicate the `.env.example` file in the root directory and rename it to `.env`.\n2. Add the following keys (replace with your actual values):\n\n   ```env\n   # LLM Model - Get key at https:\u002F\u002Fplatform.openai.com\u002Fapi-keys\n   OPENAI_API_KEY=\"your-api-key\"\n\n   # LangSmith - Get key at https:\u002F\u002Fsmith.langchain.com\n   LANGCHAIN_TRACING_V2=true\n   LANGCHAIN_ENDPOINT=\"https:\u002F\u002Fapi.smith.langchain.com\"\n   LANGCHAIN_API_KEY=\"your-api-key\"\n   LANGCHAIN_PROJECT=\"your-project-name\"\n\n   # Pinecone Vector Database - Get key at https:\u002F\u002Fapp.pinecone.io\n   PINECONE_INDEX_NAME=\"your-project-index\"\n   PINECONE_API_HOST=\"your-host-url\"\n   PINECONE_API_KEY=\"your-api-key\"\n\n   # Cohere - Get key at https:\u002F\u002Fdashboard.cohere.com\u002Fapi-keys\n   COHERE_API_KEY=your-api-key\n   ```\n\n---\n\nYou're now ready to use the project!\n\n## Usage\n\nAfter setting up the environment and running the notebooks in sequence, you can:\n\n1.  **Experiment with Retrieval-Augmented Generation**:\n    Use the foundational setup in `[1]_rag_setup_overview.ipynb` to understand the basics of RAG.\n\n2.  **Implement Multi-Querying**:\n    Learn how to improve response relevance by introducing multi-querying techniques in `[2]_rag_with_multi_query.ipynb`.\n\n## Star History\n\n\u003Ca href=\"https:\u002F\u002Fstar-history.com\u002F#bragai\u002Fbrag-langchain&Date\">\n \u003Cpicture>\n   \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fbragai_bRAG-langchain_readme_eafe90f77912.png&theme=dark\" \u002F>\n   \u003Csource media=\"(prefers-color-scheme: light)\" srcset=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fbragai_bRAG-langchain_readme_eafe90f77912.png\" \u002F>\n   \u003Cimg alt=\"Star History Chart\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fbragai_bRAG-langchain_readme_eafe90f77912.png\" \u002F>\n \u003C\u002Fpicture>\n\u003C\u002Fa>\n\n## Contact\nDo you have questions or want to collaborate? Please open an issue or email Taha Ababou at taha@bragai.dev\n\n`If this project helps you, consider buying me a coffee ☕. Your support helps me keep contributing to the open-source community!`\n\u003Cp>\n    \u003Ca href=\"https:\u002F\u002Fbuymeacoffee.com\u002Fbragai\" target=\"_blank\" rel=\"noopener noreferrer\">\n        \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fsponsor-30363D?style=for-the-badge&logo=GitHub-Sponsors&logoColor=#white\" \u002F>\n    \u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cbr>\n\n    The notebooks and visual diagrams were inspired by Lance Martin's LangChain Tutorial.\n\n    \n","# 检索增强生成 (RAG) 项目\n\n#### 🔜 请访问 [bragai.dev](https:\u002F\u002Fbragai.dev)（即将上线）\n\n---------------------\n\n此仓库包含对检索增强生成 (RAG) 在各种应用场景中的全面探索。每个笔记本都提供了从入门级到高级实现的详细、实践性指南，涵盖多查询和自定义 RAG 构建等内容。\n\n![rag_detail_v2](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fbragai_bRAG-langchain_readme_84fad047d893.png)\n\n## 项目结构\n\n如果你想直接上手，请查看文件 `full_basic_rag.ipynb` —— 这个文件将为你提供一个完全可定制的 RAG 聊天机器人模板代码。\n\n请确保在虚拟环境中运行你的文件（参见“开始使用”部分）。\n\n以下笔记本位于 `notebooks\u002F` 目录下。\n\n### [1]\\_rag_setup_overview.ipynb\n\n这个入门笔记本概述了 RAG 架构及其基础设置。笔记本内容包括：\n- **环境设置**：配置环境、安装必要的库以及 API 设置。\n- **初始数据加载**：基本的文档加载器和数据预处理方法。\n- **嵌入生成**：使用多种模型生成嵌入，包括 OpenAI 的嵌入。\n- **向量存储**：设置向量存储（ChromaDB\u002FPinecone），用于高效的相似性搜索。\n- **基础 RAG 流程**：创建一个简单的检索与生成流程，作为基准。\n\n### [2]\\_rag_with_multi_query.ipynb\n\n在此基础上，本笔记本引入了 RAG 流程中的多查询技术，探讨：\n- **多查询设置**：配置多个查询以丰富检索结果。\n- **高级嵌入技术**：利用多种嵌入模型来优化检索效果。\n- **多查询处理流程**：实现多查询处理，以提高响应的相关性。\n- **比较与分析**：将多查询流程的结果与单查询流程进行对比，并分析性能提升。\n\n### [3]_rag_routing_and_query_construction.ipynb\n\n本笔记本更深入地探讨了自定义 RAG 流程。内容包括：\n- **逻辑路由**：基于函数实现路由，根据编程语言将用户查询分类到相应数据源。\n- **语义路由**：利用嵌入和余弦相似度，将问题导向数学或物理提示，从而优化响应准确性。\n- **元数据过滤的查询构建**：为 YouTube 教程元数据定义结构化搜索模式，支持高级筛选（如按观看次数、发布日期等）。\n- **结构化搜索提示**：借助 LLM 提示生成数据库查询，以根据用户输入检索相关内容。\n- **与向量存储集成**：将结构化查询与向量存储连接，实现高效的数据检索。\n\n### [4]_rag_indexing_and_advanced_retrieval.ipynb\n\n延续之前的自定义工作，本笔记本进一步探索：\n- **文档分块简介**：提供外部资源链接，介绍文档分块技术。\n- **多表示索引**：设置多向量索引结构，以处理具有不同嵌入和表示形式的文档。\n- **摘要的内存存储**：使用 InMemoryByteStore 存储文档摘要及父文档，便于高效检索。\n- **MultiVectorRetriever 设置**：整合多种向量表示，根据用户查询检索相关文档。\n- **RAPTOR 实现**：探索 RAPTOR 这一先进的索引与检索模型，并提供深度学习资源链接。\n- **ColBERT 集成**：演示基于 ColBERT 的标记级向量索引与检索，能够捕捉细粒度的上下文语义。\n- **ColBERT 示例：宫崎骏**：使用 ColBERT 检索模型演示如何获取关于宫崎骏的信息。\n\n### [5]_rag_retrieval_and_reranking.ipynb\n\n最后这个笔记本将 RAG 系统的各个组件整合在一起，重点在于可扩展性和优化：\n- **文档加载与分割**：加载并分块文档以便索引，为向量存储做准备。\n- **基于 RAG-Fusion 的多查询生成**：采用提示驱动的方式，从单个输入问题生成多个搜索查询。\n- **倒数排名融合 (RRF)**：实现 RRF 对多个检索列表进行重新排序，合并结果以提高相关性。\n- **检索器与 RAG 链设置**：构建用于回答查询的检索链，利用融合排名和 RAG 链提取上下文相关信息。\n- **Cohere 重排序**：演示使用 Cohere 模型进行额外的上下文压缩与优化。\n- **CRAG 和 Self-RAG 检索**：探索 CRAG 和 Self-RAG 等高级检索方法，并提供示例链接。\n- **长上下文影响的探讨**：提供资源链接，解释长上下文检索对 RAG 模型的影响。\n\n## 开始使用\n\n### 前置条件\n\n请确保系统中已安装 **Python 3.11.11**（推荐版本）。如果尚未安装，请按照以下平台特定说明进行安装。\n\n#### macOS\n1. 如果尚未安装 Homebrew，请先安装：\n   ```bash\n   \u002Fbin\u002Fbash -c \"$(curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FHomebrew\u002Finstall\u002FHEAD\u002Finstall.sh)\"\n   ```\n2. 安装 Python 3.11.11：\n   ```bash\n   brew install python@3.11\n   ```\n3. 验证安装：\n   ```bash\n   python3.11 --version\n   ```\n\n#### Linux\n1. 更新包管理器：\n   ```bash\n   sudo apt update\n   ```\n2. 安装 Python 3.11.11：\n   ```bash\n   sudo apt install python3.11 python3.11-venv\n   ```\n3. 验证安装：\n   ```bash\n   python3.11 --version\n   ```\n\n#### Windows\n1. 从 [Python.org](https:\u002F\u002Fwww.python.org\u002Fdownloads\u002F) 下载 Python 3.11.11 安装程序。\n2. 运行安装程序，并确保勾选 **“将 Python 添加到 PATH”** 选项。\n3. 验证安装：\n   ```cmd\n   python --version\n   ```\n---\n\n### 安装说明\n\n#### 1. 克隆仓库\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FbRAGAI\u002FbRAG-langchain.git\ncd bRAG-langchain\n```\n\n#### 2. 创建虚拟环境\n使用 Python 3.11.11 创建虚拟环境：\n```bash\npython3.11 -m venv venv\n```\n\n激活虚拟环境：\n- **macOS\u002FLinux**：\n  ```bash\n  source venv\u002Fbin\u002Factivate\n  ```\n- **Windows**：\n  ```cmd\n  venv\\Scripts\\activate\n  ```\n\n#### 3. 验证并修复 Python 版本\n如果虚拟环境中默认使用的是其他版本的 Python（例如 Python 3.13）：\n1. 验证当前虚拟环境中的 Python 版本：\n   ```bash\n   python --version\n   ```\n2. 在虚拟环境中显式使用 Python 3.11：\n   ```bash\n   python3.11\n   ```\n3. 确保 `python` 命令指向 Python 3.11，可通过创建符号链接实现：\n   ```bash\n   ln -sf $(which python3.11) $(dirname $(which python))\u002Fpython\n   ```\n4. 再次验证修复是否成功：\n   ```bash\n   python --version\n   ```\n\n#### 4. 安装依赖\n安装所需的软件包：\n```bash\npip install -r requirements.txt\n```\n\n---\n\n### 其他步骤\n\n#### 5. 运行笔记本\n从 `[1]_rag_setup_overview.ipynb` 开始，熟悉整个设置流程。然后按顺序依次运行其他笔记本：\n\n- `[1]_rag_setup_overview.ipynb`\n- `[2]_rag_with_multi_query.ipynb`\n- `[3]_rag_routing_and_query_construction.ipynb`\n- `[4]_rag_indexing_and_advanced_retrieval.ipynb`\n- `[5]_rag_retrieval_and_reranking.ipynb`\n\n#### 6. 设置环境变量\n1. 复制根目录下的 `.env.example` 文件，并将其重命名为 `.env`。\n2. 添加以下键值对（请替换为您的实际值）：\n\n   ```env\n   # LLM 模型 - 从 https:\u002F\u002Fplatform.openai.com\u002Fapi-keys 获取密钥\n   OPENAI_API_KEY=\"your-api-key\"\n\n   # LangSmith - 从 https:\u002F\u002Fsmith.langchain.com 获取密钥\n   LANGCHAIN_TRACING_V2=true\n   LANGCHAIN_ENDPOINT=\"https:\u002F\u002Fapi.smith.langchain.com\"\n   LANGCHAIN_API_KEY=\"your-api-key\"\n   LANGCHAIN_PROJECT=\"your-project-name\"\n\n   # Pinecone 向量数据库 - 从 https:\u002F\u002Fapp.pinecone.io 获取密钥\n   PINECONE_INDEX_NAME=\"your-project-index\"\n   PINECONE_API_HOST=\"your-host-url\"\n   PINECONE_API_KEY=\"your-api-key\"\n\n   # Cohere - 从 https:\u002F\u002Fdashboard.cohere.com\u002Fapi-keys 获取密钥\n   COHERE_API_KEY=your-api-key\n   ```\n\n---\n\n现在您已经准备好使用该项目了！\n\n## 使用方法\n\n完成环境设置并按顺序运行所有笔记本后，您可以：\n\n1.  **尝试检索增强生成**：\n    使用 `[1]_rag_setup_overview.ipynb` 中的基础设置，了解 RAG 的基本原理。\n\n2.  **实现多查询技术**：\n    在 `[2]_rag_with_multi_query.ipynb` 中学习如何通过引入多查询技术来提升响应的相关性。\n\n## 星级历史\n\n\u003Ca href=\"https:\u002F\u002Fstar-history.com\u002F#bragai\u002Fbrag-langchain&Date\">\n \u003Cpicture>\n   \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fbragai_bRAG-langchain_readme_eafe90f77912.png&theme=dark\" \u002F>\n   \u003Csource media=\"(prefers-color-scheme: light)\" srcset=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fbragai_bRAG-langchain_readme_eafe90f77912.png\" \u002F>\n   \u003Cimg alt=\"星级历史图表\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fbragai_bRAG-langchain_readme_eafe90f77912.png\" \u002F>\n \u003C\u002Fpicture>\n\u003C\u002Fa>\n\n## 联系方式\n如果您有任何问题或希望合作，请提交一个 issue，或发送邮件至 Taha Ababou：taha@bragai.dev。\n\n`如果这个项目对您有所帮助，请考虑请我喝杯咖啡 ☕。您的支持将帮助我继续为开源社区做出贡献！`\n\u003Cp>\n    \u003Ca href=\"https:\u002F\u002Fbuymeacoffee.com\u002Fbragai\" target=\"_blank\" rel=\"noopener noreferrer\">\n        \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fsponsor-30363D?style=for-the-badge&logo=GitHub-Sponsors&logoColor=#white\" \u002F>\n    \u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cbr>\n\n    本项目的笔记本和可视化图表灵感来源于 Lance Martin 的 LangChain 教程。","# bRAG-langchain 快速上手指南\n\n本指南旨在帮助开发者快速搭建基于 LangChain 的检索增强生成（RAG）实验环境，涵盖从基础架构到高级检索策略的全流程。\n\n## 环境准备\n\n### 系统要求\n- **Python 版本**：推荐 **Python 3.11.11**（项目强依赖此版本，其他版本可能导致兼容性问题）。\n- **操作系统**：macOS, Linux, 或 Windows。\n\n### 前置依赖安装\n请根据操作系统选择对应命令安装 Python 3.11.11：\n\n**macOS**\n```bash\n# 安装 Homebrew (若未安装)\n\u002Fbin\u002Fbash -c \"$(curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FHomebrew\u002Finstall\u002FHEAD\u002Finstall.sh)\"\n# 安装 Python 3.11\nbrew install python@3.11\n# 验证版本\npython3.11 --version\n```\n\n**Linux (Ubuntu\u002FDebian)**\n```bash\nsudo apt update\nsudo apt install python3.11 python3.11-venv\npython3.11 --version\n```\n\n**Windows**\n1. 访问 [Python.org](https:\u002F\u002Fwww.python.org\u002Fdownloads\u002F) 下载 Python 3.11.11 安装包。\n2. 运行安装程序，务必勾选 **\"Add Python to PATH\"**。\n3. 在命令行验证：\n   ```cmd\n   python --version\n   ```\n\n## 安装步骤\n\n### 1. 克隆项目\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FbRAGAI\u002FbRAG-langchain.git\ncd bRAG-langchain\n```\n\n### 2. 创建并激活虚拟环境\n建议使用 `python3.11` 明确指定版本创建环境：\n\n```bash\npython3.11 -m venv venv\n```\n\n激活环境：\n- **macOS\u002FLinux**:\n  ```bash\n  source venv\u002Fbin\u002Factivate\n  ```\n- **Windows**:\n  ```cmd\n  venv\\Scripts\\activate\n  ```\n\n> **注意**：若激活后 `python --version` 仍显示非 3.11 版本，请在虚拟环境中执行以下命令修复符号链接：\n> ```bash\n> ln -sf $(which python3.11) $(dirname $(which python))\u002Fpython\n> ```\n\n### 3. 安装依赖\n```bash\npip install -r requirements.txt\n```\n*(注：国内用户若下载缓慢，可添加清华源加速：`pip install -r requirements.txt -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple`)*\n\n### 4. 配置环境变量\n复制示例配置文件并填入你的 API Key：\n\n```bash\ncp .env.example .env\n```\n\n编辑 `.env` 文件，填入以下关键信息：\n```env\n# OpenAI API Key (用于 LLM 和 Embedding)\nOPENAI_API_KEY=\"sk-...\"\n\n# LangSmith (可选，用于追踪调试)\nLANGCHAIN_TRACING_V2=true\nLANGCHAIN_ENDPOINT=\"https:\u002F\u002Fapi.smith.langchain.com\"\nLANGCHAIN_API_KEY=\"your-langsmith-key\"\nLANGCHAIN_PROJECT=\"your-project-name\"\n\n# Pinecone (向量数据库，若使用 ChromaDB 本地运行可不填此项)\nPINECONE_INDEX_NAME=\"your-index\"\nPINECONE_API_HOST=\"your-host\"\nPINECONE_API_KEY=\"your-key\"\n\n# Cohere (用于重排序 Rerank，可选)\nCOHERE_API_KEY=\"your-cohere-key\"\n```\n\n## 基本使用\n\n本项目通过一系列 Jupyter Notebook 循序渐进地展示 RAG 的实现。请按顺序执行 `notebooks\u002F` 目录下的文件。\n\n### 第一步：运行基础 RAG 示例\n这是最简单的入门方式，将构建一个可定制的 RAG 聊天机器人基线。\n\n1. 启动 Jupyter Lab\u002FNotebook：\n   ```bash\n   jupyter lab\n   ```\n2. 打开并运行 **`notebooks\u002F[1]_rag_setup_overview.ipynb`**。\n   - 该笔记将引导你完成：环境配置、文档加载、Embedding 生成、向量存储（ChromaDB\u002FPinecone）设置以及基础 RAG 管道构建。\n\n### 第二步：进阶实验\n熟悉基础后，可依次运行后续笔记以探索高级功能：\n- **多查询策略**：运行 `[2]_rag_with_multi_query.ipynb` 学习如何通过多查询提升检索相关性。\n- **路由与查询构造**：运行 `[3]_rag_routing_and_query_construction.ipynb` 实现基于语义或逻辑的路由分发。\n- **高级索引与检索**：运行 `[4]_rag_indexing_and_advanced_retrieval.ipynb` 探索 MultiVector、RAPTOR 及 ColBERT 等技术。\n- **重排序优化**：运行 `[5]_rag_retrieval_and_reranking.ipynb` 学习 RAG-Fusion 和 Cohere Re-Ranking。\n\n### 快速启动模板\n若只想获取一个完整的 RAG 聊天机器人代码模板，可直接查看根目录下的：\n- `full_basic_rag.ipynb`\n\n现在你可以开始探索 Retrieval-Augmented Generation 的各种应用场景了！","某教育科技公司的研发团队正致力于构建一个能精准回答编程与理科问题的智能辅导助手，以解决学生在学习过程中遇到的复杂疑问。\n\n### 没有 bRAG-langchain 时\n- **检索结果单一且偏差大**：仅靠单次查询匹配向量库，面对“如何用 Python 解物理题”这类跨领域问题时，常遗漏关键代码片段或物理公式，导致回答空洞。\n- **路由逻辑僵化**：缺乏智能路由机制，系统无法自动区分用户问的是数学推导还是代码调试，往往将数学问题错误地导向代码库检索，降低准确率。\n- **长文档理解能力弱**：处理长篇技术教程时，简单的切片索引丢失了上下文关联，模型难以捕捉章节间的逻辑联系，生成的答案经常断章取义。\n- **开发试错成本高昂**：从基础环境搭建到高级检索策略（如多向量索引、重排序），团队需从零编写大量样板代码，耗时数周才能验证一个想法。\n\n### 使用 bRAG-langchain 后\n- **多查询提升覆盖率**：利用内置的多查询（Multi-Query）技术，系统自动将用户问题拆解为多个视角的子查询，显著提升了跨领域问题的检索完整度。\n- **语义路由精准分发**：通过语义路由功能，系统能基于嵌入相似度自动将数学题导向物理知识库、代码题导向编程库，大幅优化了回答的专业性。\n- **高级索引增强上下文**：借助多向量索引和父文档检索策略，系统能在保留细粒度信息的同时关联宏观上下文，使长文档问答逻辑严密、连贯自然。\n- **快速迭代高级功能**：直接复用项目中现成的 Notebook 模板（如 RAPTOR、ColBERT 集成），团队在几天内就完成了从原型到高级检索管线的部署，效率提升十倍。\n\nbRAG-langchain 将复杂的 RAG 架构探索转化为可落地的标准化流程，让开发者能专注于业务逻辑而非底层基建，迅速打造出高智商的行业专属助手。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fbragai_bRAG-langchain_c62e04e6.png","bragai","BragAI","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fbragai_3d33a936.png","Turn your ideas into full-stack web apps, straight from your browser.",null,"taha@bragai.dev","bragai_","https:\u002F\u002Fbragai.dev","https:\u002F\u002Fgithub.com\u002Fbragai",[24],{"name":25,"color":26,"percentage":27},"Jupyter Notebook","#DA5B0B",100,4078,488,"2026-04-17T17:52:49","NOASSERTION",2,"Linux, macOS, Windows","未说明",{"notes":36,"python":37,"dependencies":38},"必须使用 Python 3.11.11 版本，强烈建议在虚拟环境中运行。需要配置多个 API 密钥（OpenAI, LangSmith, Pinecone, Cohere）才能完整运行所有示例。项目包含多个 Jupyter Notebook，需按顺序执行以体验从基础到高级的 RAG 功能。","3.11.11",[39,40,41,42,43],"langchain","openai","pinecone-client","cohere","chromadb",[45,46,47,48,49],"Agent","其他","开发框架","图像","语言模型",[51,52,53,54,55,56,57,58],"agentic-rag","chatbot","llm","machine-learning","python","rag","ai","retrieval-augmented-generation","ready","2026-03-27T02:49:30.150509","2026-04-19T06:02:07.905462",[63,68,73,78,83,88],{"id":64,"question_zh":65,"answer_zh":66,"source_url":67},41761,"安装依赖时遇到 pyobjc、milvus-lite 或 sklearn 等包冲突或找不到版本的错误怎么办？","该问题已由维护者修复。所有依赖安装问题（包括 pyobjc 冲突、milvus-lite 版本缺失及 sklearn 弃用警告）均已解决。请执行以下操作：\n1. 拉取仓库的最新代码变更（git pull）。\n2. 严格按照 README 文件中更新后的说明进行操作。\n3. 如果问题依旧，可以尝试在每个 Notebook 中单独安装所需的依赖，这样通常更容易解决冲突。","https:\u002F\u002Fgithub.com\u002Fbragai\u002FbRAG-langchain\u002Fissues\u002F4",{"id":69,"question_zh":70,"answer_zh":71,"source_url":72},41762,"运行代码时出现 'APIConnectionError: Connection error' 网络连接错误如何解决？","此错误通常由网络问题或配置不当引起。请按以下步骤排查：\n1. 检查网络连接是否正常。\n2. 确认项目根目录下的 `.env` 文件已正确创建（可复制 `.env.example` 生成）。\n3. 仔细检查 `.env` 文件中是否填入了所有必需的 API Keys 和正确的 URL 地址。","https:\u002F\u002Fgithub.com\u002Fbragai\u002FbRAG-langchain\u002Fissues\u002F14",{"id":74,"question_zh":75,"answer_zh":76,"source_url":77},41763,"为什么导入 langchain 模块时会报错，提示找不到对应的类或函数？","这是因为 `requirements.txt` 中的依赖包未锁定具体版本号，导致随时间推移安装的包版本发生变化，从而引发导入错误（例如 `RecursiveCharacterTextSplitter` 或 `langchainhub` 导入失败）。\n解决方案：维护者已更新并冻结了依赖包的版本号。请务必拉取仓库的最新代码，重新安装依赖即可解决。","https:\u002F\u002Fgithub.com\u002Fbragai\u002FbRAG-langchain\u002Fissues\u002F15",{"id":79,"question_zh":80,"answer_zh":81,"source_url":82},41764,"Notebook 中的源代码链接失效（404 错误）怎么办？","维护者已收到反馈并更新了所有 Notebook 文件及 `docs\u002F` 文件夹中过期的源链接。请拉取最新的代码仓库版本，即可访问正确的资源链接。","https:\u002F\u002Fgithub.com\u002Fbragai\u002FbRAG-langchain\u002Fissues\u002F12",{"id":84,"question_zh":85,"answer_zh":86,"source_url":87},41765,"如何获取最新版本的 AutoGen 包支持？","维护者已将 AutoGen 包更新至 `autogen-agentchat~=0.2.0` 版本以解决兼容性问题。请拉取仓库的最新更改，依赖安装问题将自动解决。","https:\u002F\u002Fgithub.com\u002Fbragai\u002FbRAG-langchain\u002Fissues\u002F11",{"id":89,"question_zh":90,"answer_zh":91,"source_url":92},41766,"依赖安装过程极其繁琐且报错众多，是否有更简单的部署方式（如 Docker）？","目前维护者已通过修复 `requirements.txt` 解决了绝大多数依赖安装问题。建议先拉取最新代码并遵循 README 中的新指南进行安装，通常不再需要复杂的变通方法或容器化部署即可顺利运行。","https:\u002F\u002Fgithub.com\u002Fbragai\u002FbRAG-langchain\u002Fissues\u002F8",[],[95,105,113,121,131,139],{"id":96,"name":97,"github_repo":98,"description_zh":99,"stars":100,"difficulty_score":101,"last_commit_at":102,"category_tags":103,"status":59},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[45,47,48,104],"数据工具",{"id":106,"name":107,"github_repo":108,"description_zh":109,"stars":110,"difficulty_score":101,"last_commit_at":111,"category_tags":112,"status":59},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[47,48,45],{"id":114,"name":115,"github_repo":116,"description_zh":117,"stars":118,"difficulty_score":32,"last_commit_at":119,"category_tags":120,"status":59},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",160015,"2026-04-18T11:30:52",[47,45,49],{"id":122,"name":123,"github_repo":124,"description_zh":125,"stars":126,"difficulty_score":127,"last_commit_at":128,"category_tags":129,"status":59},8272,"opencode","anomalyco\u002Fopencode","OpenCode 是一款开源的 AI 编程助手（Coding Agent），旨在像一位智能搭档一样融入您的开发流程。它不仅仅是一个代码补全插件，而是一个能够理解项目上下文、自主规划任务并执行复杂编码操作的智能体。无论是生成全新功能、重构现有代码，还是排查难以定位的 Bug，OpenCode 都能通过自然语言交互高效完成，显著减少开发者在重复性劳动和上下文切换上的时间消耗。\n\n这款工具专为软件开发者、工程师及技术研究人员设计，特别适合希望利用大模型能力来提升编码效率、加速原型开发或处理遗留代码维护的专业人群。其核心亮点在于完全开源的架构，这意味着用户可以审查代码逻辑、自定义行为策略，甚至私有化部署以保障数据安全，彻底打破了传统闭源 AI 助手的“黑盒”限制。\n\n在技术体验上，OpenCode 提供了灵活的终端界面（Terminal UI）和正在测试中的桌面应用程序，支持 macOS、Windows 及 Linux 全平台。它兼容多种包管理工具，安装便捷，并能无缝集成到现有的开发环境中。无论您是追求极致控制权的资深极客，还是渴望提升产出的独立开发者，OpenCode 都提供了一个透明、可信",144296,1,"2026-04-16T14:50:03",[45,130],"插件",{"id":132,"name":133,"github_repo":134,"description_zh":135,"stars":136,"difficulty_score":32,"last_commit_at":137,"category_tags":138,"status":59},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",109154,"2026-04-18T11:18:24",[47,48,45],{"id":140,"name":141,"github_repo":142,"description_zh":143,"stars":144,"difficulty_score":32,"last_commit_at":145,"category_tags":146,"status":59},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[130,45,48,47]]