在理论课程中，我们深入探讨了 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 充当"阅卷人"，判断检索到的文档是否与问题相关
- 反思与重写：当文档不相关时，系统会分析问题意图，重写查询词并重新检索
- 联网搜索：当重写后仍找不到相关文档时，调用 Tavily API 进行联网搜索
- 生成：基于本地文档或联网搜索结果生成最终答案
- 流程图解：
- 环境配置：启动本地 Chroma 数据库，配置 OpenAI 或兼容 OpenAI 格式的模型（如本地 Ollama 或 CNB 提供的大模型接口）
- 数据入库：运行脚本将示例文档（如公司政策）写入向量库
- 代码研读与运行：
- 运行基础查询，观察检索结果
- 运行 Agent，观察系统如何处理"查不到"或"查不准"的情况（查看控制台日志中的决策过程）
- 代码修改与拓展：
- 修改现有示例代码，提升查询能力
- 新增智能体处理节点，实现更智能的效果
语言：TypeScript / Node.js
编排框架：
- LangChain.js：构建基础组件（Loader, Splitter, Model）
- LangGraph.js：构建有状态、有循环的智能体图
向量数据库：Chroma（本地 Docker 部署）
模型服务：OpenAI (gpt-3.5/gpt-4) 或兼容 OpenAI 格式的模型（如 Ollama 或 CNB 提供的大模型接口）
本仓库为教学实践仓库，作业提交采用 Fork 仓库 → 修改代码并提交 → 向当前仓库提交 PR 的形式。
- 修改示例代码中的提示词，提升问答效果
- 增加关键词提取和检索的处理节点，实现"混合检索"能力（可选）
- 增加 reRank 重排序节点，检索结果按相似度排序（可选）
- 实现命令行实时对话查询知识库能力（可选）
接入 Web Search 工具：当重写查询后仍找不到文档时，增加分支调用 Tavily 或 Google Search API 进行联网搜索（可选）✅ 已完成- 增加多轮对话记忆：修改
GraphState增加history字段，使 Agent 能够记住之前的对话上下文（可选） - 支持更多文档类型：修改
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：请检查以下两项：
- Chroma 容器是否已启动（
docker ps），若没有，重新执行docker compose up -d .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：如何使用 Web Search 功能？
A：需要在 .env 文件中配置 TAVILY_API_KEY。获取 API Key 的步骤：
- 访问 https://tavily.com/ 注册账号
- 获取免费的 API Key
- 在
.env文件中添加：TAVILY_API_KEY=your_api_key_here - 运行
npm run agent:run或npm run agent:test-web测试功能
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
测试联网搜索功能（需要先配置 TAVILY_API_KEY）
# 1. 在 .env 文件中配置 Tavily API Key
# TAVILY_API_KEY=your_api_key_here
# 2. 运行测试
npm run agent:test-web
祝你编码愉快！如有问题，请回顾理论课程 PPT 或查阅 LangChain 和 Chroma 官方文档。🎉
