在理论课程中，我们深入探讨了 RAG（检索增强生成）的核心原理、架构，以及从"流水线"到"智能体"的演进路径。

本项目是理论课程的配套实战环节。我们将跳出"纸上谈兵"，使用 TypeScript 结合业界前沿的 LangChain 生态和 LangGraph 编排框架，配合 Chroma 向量数据库，从零搭建一个具备自我反思、自我修正能力的 Agentic RAG（智能体 RAG） 系统。

通过本项目，你将深入理解 RAG 系统内部的数据流转与决策逻辑，而不仅仅是调用现成接口。

---

一个完整的 TypeScript 项目仓库，包含两个循序渐进的实践模块：

对应代码目录： src/1-simple-rag

核心内容：

• 本地向量数据库 (Chroma) 的搭建与连接
• 文本数据的清洗、分块 (Chunking) 与 向量化 (Embedding)
• 基础的相似度检索与问答链路

核心功能：

• 将非结构化文本（data/*）转化为向量索引
• 用户提问 → 检索 Top K 片段 → LLM 生成答案

对应代码目录： src/2-agentic-rag

核心内容：

• 基于 LangGraph 的图结构编排
• 实现 CRAG (Corrective RAG) 核心思想
• 具备"检索-评分-重写-生成"的闭环能力

核心功能：

• 检索：从 Chroma 获取文档
• 评分：LLM 充当"阅卷人"，判断检索到的文档是否与问题相关
• 反思与重写：当文档不相关时，系统会分析问题意图，重写查询词并重新检索
• 生成：确认文档相关或重写查询后仍无法检索时，生成最终答案

• 流程图解：

1. 环境配置：启动本地 Chroma 数据库，配置 OpenAI 或兼容 OpenAI 格式的模型（如本地 Ollama 或 CNB 提供的大模型接口）
2. 数据入库：运行脚本将示例文档（如公司政策）写入向量库
3. 代码研读与运行：
   • 运行基础查询，观察检索结果
   • 运行 Agent，观察系统如何处理"查不到"或"查不准"的情况（查看控制台日志中的决策过程）
4. 代码修改与拓展：
   • 修改现有示例代码，提升查询能力
   • 新增智能体处理节点，实现更智能的效果

---

语言：TypeScript / Node.js

编排框架：

• LangChain.js：构建基础组件（Loader, Splitter, Model）
• LangGraph.js：构建有状态、有循环的智能体图

向量数据库：Chroma（本地 Docker 部署）

模型服务：OpenAI (gpt-3.5/gpt-4) 或兼容 OpenAI 格式的模型（如 Ollama 或 CNB 提供的大模型接口）

---

本仓库为教学实践仓库，作业提交采用 Fork 仓库 → 修改代码并提交 → 向当前仓库提交 PR 的形式。

1. 修改示例代码中的提示词，提升问答效果
2. 增加关键词提取和检索的处理节点，实现"混合检索"能力（可选）
3. 增加 reRank 重排序节点，检索结果按相似度排序（可选）
4. 实现命令行实时对话查询知识库能力（可选）
5. 接入 Web Search 工具：当重写查询后仍找不到文档时，增加分支调用 Tavily 或 Google Search API 进行联网搜索（可选）
6. 增加多轮对话记忆：修改 GraphState 增加 history 字段，使 Agent 能够记住之前的对话上下文（可选）
7. 支持更多文档类型：修改 src/file-loaders/index.ts 和 src/file-splitter/index.ts，注册更多 loader 支持 PDF、Word、Excel 等格式文档的加载和分割（可选）

rag-bootcamp/
├── data/                    # 示例文档数据
├── src/
│   ├── models/              # 模型调用类
│   ├── db/                  # 向量数据库调用类
│   ├── file-loaders/        # 文件加载类
│   ├── file-splitter/       # 文件分割类
│   ├── 1-simple-rag/        # 实践1：基础 RAG 代码
│   └── 2-agentic-rag/       # 实践2：Agentic RAG 代码 (LangGraph)
├── docker-compose.yaml      # Chroma 数据库启动配置
├── .env.example             # 环境变量模版
└── package.json             # 依赖配置

---

• 10min：环境搭建（安装 Docker，配置 API Key，跑通 rag:ingest 数据入库）
• 30min：运行研读 1-simple-rag 代码，理解 Splitter 和 Embedding 的作用
• 40min：运行研读 2-agentic-rag，重点理解 graph.ts 中的 addConditionalEdges 逻辑，观察 Agent 如何进行"反思"；尝试修改 Prompt 或更换测试文档，观察系统表现
• 80min：根据作业要求，修改和完善代码实现，构建更智能的问答助手

---

Q：运行 rag:ingest 时报错 ChromaConnectionError: Failed to connect to chromadb？

A：请检查以下两项：

1. Chroma 容器是否已启动（docker ps），若没有，重新执行 docker compose up -d
2. .env 中的 CHROMA_DB_URL 是否正确（通常是 http://localhost:8000）

Q：执行本地向量化模型时报错 [E:onnxruntime:onnxruntime-node, env.cc:234 ThreadMain]？ 这个错误的原因在于开源的onnx在分配cpu时只能从0开始，因此如果一个docker的cpuset.cpus不是从0开始的就可能报这个错误。 可以忽略此报错正常运行。

Q：必须使用 OpenAI 吗？

A：代码默认配置为 OpenAI。如果需要使用 Azure 或 Ollama，请修改 src/models/llm.ts 文件。

Q：必须使用 本地 embeddings 模型吗？

A：代码默认使用由 Chroma 提供的本地运行的 embeddings 模型（ all-MiniLM-L6-v2 ）。如果需要其他模型，请修改 src/models/embedding.ts 文件。

Q：LangGraph 是什么？为什么要用它？

A：LangGraph 允许我们定义"循环"结构。传统的 Chain 是直线流程（A→B→C），而 LangGraph 支持条件判断（如"如果 B 效果不好，跳回 A 重做"），这是构建智能 Agent 的关键特性。

---

完成本项目后，你将掌握：

✅ 全栈思维：使用 TypeScript 进行 AI 工程开发

✅ 向量工程：Chroma 数据库的实际操作与数据治理

✅ 图编排能力：理解 StateGraph，掌握条件边（Conditional Edge）和节点（Node）的交互

✅ Agent 原理：亲手实现"反思"与"工具调用"模式

---

本项目使用 Chroma 作为本地向量库，请确保已安装 Docker。

# 在项目根目录下运行
docker compose up -d

等待片刻，确保 Chroma 服务在 localhost:8000 启动。

# 安装依赖
npm install # 建议使用 bun install ，速度更快

# 配置环境变量
# CNB 远程开发环境下直接执行，自动替换 CNB 环境变量
envsubst < .env.example > .env

# 或手动复制并编辑 .env 文件，填入你的 OPENAI_API_KEY
# cp .env.example .env

知识入库

npm run rag:ingest

基础查询测试

npm run rag:query

运行智能体

npm run agent:run

命令行交互式对话（新增）

npm run agent:cli

---

新增 src/2-agentic-rag/cli.ts，支持实时多轮对话：

使用方法：

npm run agent:cli

交互命令：

• 直接输入问题 → 进行问答
• clear / cls → 清空屏幕
• help / h / ? → 显示帮助
• exit / quit / q → 退出程序

特性：

• ✅ 支持多轮对话，自动保存对话历史
• ✅ 美化的命令行输出，带颜色和图标
• ✅ 显示执行统计信息（重写次数、文档数量等）
• ✅ 支持命令帮助系统

---

新增 webSearchNode，当本地知识库没有答案时自动联网搜索：

配置：

# 在 .env 文件中启用
ENABLE_WEB_SEARCH=true
TAVILY_API_KEY=your_tavily_api_key_here

工作流程：

1. 本地检索未找到相关文档
2. 查询重写后仍未找到
3. 自动调用 Tavily API 进行联网搜索
4. 基于搜索结果生成答案

注意：需要先在 Tavily 注册获取 API Key。

---

已在 GraphState 中新增 history 字段，支持多轮对话：

配置：

# 在 .env 文件中启用（默认已启用）
ENABLE_HISTORY=true

使用场景：

• 系统可以记住之前的对话内容
• 支持上下文相关的追问
• 最多保留最近 5 轮对话（可调整 MAX_HISTORY_ROUNDS）

---

结合向量检索和关键词检索，提高召回率：

配置：

# 在 .env 文件中启用
ENABLE_HYBRID_RETRIEVE=true

工作原理：

1. 提取问题核心关键词
2. 执行向量语义检索
3. 执行关键词精确匹配检索
4. 合并结果并去重
5. 按综合评分排序返回

优势：

• 向量检索：语义理解强
• 关键词检索：精确匹配
• 混合检索：结合两者优势

---

使用 LLM 对检索结果按相关性重新排序：

配置：

# 在 .env 文件中启用
ENABLE_RE_RANK=true

工作原理：

1. 对每个文档调用 LLM 进行相关性打分（0-10）
2. 按分数从高到低排序
3. 返回排序后的结果

优势：

• LLM 比向量相似度更能理解相关性
• 可以考虑上下文和语义深度
• 提高最相关文档的召回率

---

扩展了文件加载器，支持更多文档格式：

支持的格式：

• ✅ .txt - 纯文本文件
• ✅ .md - Markdown 文件
• ✅ .csv - CSV 表格文件
• ✅ .json - JSON 文件
• ✅ .pdf - PDF 文档

可扩展格式（需安装额外依赖）：

• .docx / .doc - Word 文档
• .xlsx / .xls - Excel 表格
• .pptx - PowerPoint 演示文稿
• .html - HTML 网页

如何添加更多格式支持：

1. 安装对应的 LangChain loader：

npm install @langchain/community

2. 在 src/file-loaders/index.ts 中注册新的 loader：

import { UnstructuredLoader } from "@langchain/community/document_loaders/fs/unstructured";

// 在 LOADER_REGISTRY 中添加
".docx": UnstructuredLoader,
".xlsx": UnstructuredLoader,

---

所有功能开关都可以通过 .env 文件配置：

# 功能开关
ENABLE_HYBRID_RETRIEVE=false  # 混合检索
ENABLE_RE_RANK=false          # 文档重排序
ENABLE_WEB_SEARCH=false       # Web 搜索
ENABLE_HISTORY=true           # 对话历史

---

1. 修改示例代码中的提示词 - 可在 nodes.ts 中调整 prompt 模板
2. 增加关键词提取和检索的处理节点，实现"混合检索"能力 ✅
   • 新增 extractKeywordsNode 提取关键词
   • 新增 hybridRetrieveNode 结合向量+关键词检索
3. 增加 reRank 重排序节点，检索结果按相似度排序 ✅
   • 新增 reRankNode 使用 LLM 重新排序
4. 实现命令行实时对话查询知识库能力 ✅
   • 新增 cli.ts 交互式命令行界面
5. 接入 Web Search 工具 ✅
   • 新增 webSearchNode 集成 Tavily API
6. 增加多轮对话记忆 ✅
   • 在 GraphState 中添加 history 字段
   • 新增 updateHistoryNode 更新历史
7. 支持更多文档类型 ✅
   • 扩展 src/file-loaders/index.ts 支持更多格式

---

祝你编码愉快！如有问题，请回顾理论课程 PPT 或查阅 LangChain 和 Chroma 官方文档。🎉