在上一节理论课程中，我们已经深入探讨了 RAG（检索增强生成）的核心原理、架构以及从“流水线”到“智能体”的演进。
本项目是该课程的配套实战环节。不同于理论讲解，我们将不再“纸上谈兵”，而是使用 TypeScript 语言，结合业界最前沿的 LangChain 生态和 LangGraph 编排框架，配合 Chroma 向量数据库，从零搭建一个具备自我反思、自我修正能力的 Agentic RAG（智能体 RAG） 系统。
本项目旨在帮助开发者打破“只会调包”的困境，深入理解 RAG 系统内部的数据流转与决策逻辑。
一个完整的 TypeScript 项目仓库，包含两个循序渐进的实践模块：
-
实践 1：基础 RAG (Naive RAG)
-
✅ 本地向量数据库 (Chroma) 的搭建与连接
-
✅ 文本数据的清洗、分块 (Chunking) 与 向量化 (Embedding)
-
✅ 基础的相似度检索与问答链路
-
实践 2：智能体 RAG (Agentic RAG)
-
✅ 基于 LangGraph 的图结构编排
-
✅ 实现 CRAG (Corrective RAG) 核心思想
-
✅ 具备“检索-评分-重写-生成”的闭环能力
- 环境配置：启动本地 Chroma 数据库，配置 OpenAI API Key。
- 数据入库：运行脚本将提供的示例文档（如公司政策）写入向量库。
- 代码研读与运行：
- 运行基础查询，观察检索结果。
- 运行 Agent，观察系统如何处理“查不到”或“查不准”的情况（查看控制台日志中的决策过程）。
本项目代码已默认实现了以下核心场景，展示了从基础到高阶的演进：
对应代码目录： src/1-simple-rag
-
核心功能：
-
将非结构化文本（
src/data/*）转化为向量索引。 -
用户提问 -> 检索 Top K 片段 -> LLM 生成答案。
-
解决痛点：解决大模型无法回答企业私有数据的问题。
对应代码目录： src/2-agentic-rag
-
核心功能：
-
检索 (Retrieve)：从 Chroma 获取文档。
-
评分 (Grade)：LLM 充当“阅卷人”，判断检索到的文档是否真的与问题相关。
-
反思与重写 (Rewrite)：如果文档不相关，系统不会强行回答，而是分析问题意图，重写查询词，重新检索。
-
生成 (Generate)：只有当确认文档相关或者重写问题后仍然无法检索到相关问题，才生成最终答案。
-
流程图解：
-
语言: TypeScript / Node.js
-
编排框架:
-
LangChain.js: 用于构建基础组件（Loader, Splitter, Model）。
-
LangGraph.js: 用于构建有状态、有循环的智能体图。
-
向量数据库: Chroma (本地 Docker 部署)
-
模型服务: OpenAI (gpt-3.5/gpt-4) 或 兼容 OpenAI 格式的模型 (如 Ollama)
如果你已经跑通了现有代码，可以尝试以下挑战来提升分数：
- ✨ 更换 LLM 模型：修改
src/models/llm.ts或环境变量，将 OpenAI 替换为其他的 LLM 模型, 获取更好的效果。 - ✨ 更换 Embedding 模型：修改
src/models/embeding.ts或环境变量，将本地默认 Embedding 模型 替换为其他的 Embedding 模型, 获取更好的效果。 - ✨ 支持更多文档类型：修改
src/file-loaders/index.ts和src/file-splitter/index.ts，注册更多 loader 来 PDF、Word、Excel 等格式文档的加载和分割。 - ✨ 接入 Web Search 工具：在
src/2-agentic-rag中，当重写查询后依然找不到文档时，增加一个分支调用 Tavily 或 Google Search API 进行联网搜索。 - ✨ 增加多轮对话记忆：修改
GraphState，增加history字段，使 Agent 能够记住之前的对话上下文。
本仓库为教学实践仓库，无需提交作业。但在学习过程中，请确保你能完成以下操作：
能够成功执行 package.json 中定义的三个核心脚本：
npm run rag:ingest(数据入库无报错)npm run rag:query(基础问答返回正确结果)npm run agent:run(Agent 能够跑通完整流程)
- 确保 Docker 容器
chroma-server正常运行。 - 确保 Node.js 环境及依赖安装正确。
项目目录结构清晰，包含所有必要文件：
rag-bootcamp/ ├── src/ │ ├── data/ # 📂 示例文档数据 │ ├── models/ # 🤖 模型调用类 │ ├── db/ # 🗄️ 向量数据库调用类 │ ├── 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 的作用。 - 80min: 深入
2-agentic-rag。重点理解graph.ts中的addConditionalEdges逻辑，观察 Agent 是如何进行“反思”的。 尝试修改 Prompt 或更换测试文档，观察系统表现。
Q: 运行 rag:ingest 时报错 fetch failed?
A: 请检查：1. Chroma 容器是否已启动 (docker ps)。 2. .env 中的 CHROMA_DB_URL 是否正确 (通常是 http://localhost:8000)。
Q: 必须使用 OpenAI 吗？
A: 代码默认配置为 OpenAI。如果你想用 Azure 或 Ollama，需要修改 src/models/llm.ts 和 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 依赖
npm install # 或使用bun install获得更快的安装速度
# 配置环境变量
# 在CNB远程开发环境下直接执行，会自动替换CNB相关环境变量，使用CNB提供的大模型接口
envsubst < .env.example > .env
# 或者手动复制并替换里面的环境变量
# cp .env.example .env
# 编辑 .env 文件，填入你的 OPENAI_API_KEY
步骤一：知识入库 (Indexing)
npm run rag:ingest
步骤二：基础查询测试 (Retrieval)
npm run rag:query
步骤三：运行智能体 (Agentic RAG)
npm run agent:run
祝你编码愉快！如有问题，请随时回顾理论课程 PPT 或查看 LangChain 官方文档。🎉
