在上一节理论课程中，我们已经深入探讨了 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) 核心思想

• ✅ 具备“检索-评分-重写-生成”的闭环能力

1. 环境配置：启动本地 Chroma 数据库，配置 OpenAI API Key。
2. 数据入库：运行脚本将提供的示例文档（如公司政策）写入向量库。
3. 代码研读与运行：

• 运行基础查询，观察检索结果。
• 运行 Agent，观察系统如何处理“查不到”或“查不准”的情况（查看控制台日志中的决策过程）。

---

本项目代码已默认实现了以下核心场景，展示了从基础到高阶的演进：

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

• 核心功能：

• 将非结构化文本（company_policy.txt）转化为向量索引。

• 用户提问 -> 检索 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)

• 验证与工具: Zod (Schema定义), Dotenv

---

如果你已经跑通了现有代码，可以尝试以下挑战来提升分数：

• ✨ 接入 Web Search 工具：在 src/2-agentic-rag 中，当重写查询后依然找不到文档时，增加一个分支调用 Tavily 或 Google Search API 进行联网搜索。
• ✨ 更换为本地模型：修改 src/config 或环境变量，将 OpenAI 替换为本地运行的 Ollama (Llama3 或 Mistral)，实现完全离线的 RAG 系统。
• ✨ 增加多轮对话记忆：修改 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/                # 💡 示例文档数据
│   ├── 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/1-simple-rag/ingest.ts 和 src/2-agentic-rag/nodes.ts 中的 new ChatOpenAI(...) 和 new OpenAIEmbeddings(...) 初始化参数。

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

# 配置环境变量
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 官方文档。🎉