AI PDF Chatbot & Agent：LangChain + LangGraph 驱动的文档智能问答系统

图1：项目作者 Mayo Oshin（数据来源：GitHub）

开篇：一个科研工作者的"最后一公里"困境

想象一下：你是某大学的研究员，刚刚完成了为期两年的深度调研，手头积累了 200 多篇 PDF 论文，阅读笔记写了一整个硬盘。导师突然问了一个问题：「这些文献里，有哪些研究讨论了大型语言模型的伦理风险管控？」你翻遍笔记，记忆已经开始模糊——那种绝望感，每个做过学术研究的人都懂。

这就是 AI PDF Chatbot & Agent 试图解决的核心问题：让人类能够用自然语言对话的方式，与自己的 PDF 文档库进行交互。不是简单的关键词搜索，而是真正理解语义、从多个文档中综合提炼答案，并附带来源引用。

这个项目由独立开发者 Mayo Oshin 创建，配套出版了 O'Reilly 书籍《Learning LangChain》。截至 2025 年初，已收获超过 16,000 颗 GitHub Stars，成为 LangChain 生态中最具代表性的生产级参考项目之一。

---

项目背景：从"玩具"到"教科书"的演进路径

Mayo Oshin 的技术博客和 YouTube 频道是 LangChain 社区的重要知识来源。在 2023 年初，LangChain 刚刚起步、文档尚不完善的阶段，他便开始用 TypeScript 实现 PDF 问答系统，并将开发过程完整公开。这种"边做边写、写完即出书"的方式，让《Learning LangChain》成为当时市面上最贴近实战的 LangChain 教材之一。

值得注意的是，项目的 README 明确标注了「不活跃维护」状态（not actively maintained），Issues 和 PR 不会得到及时响应。这是一个常见的生命周期现象：作者通过出书获得了更可持续的知识变现路径后，开源项目自然进入维护末期。但这并不妨碍它作为学习 LangChain/LangGraph 的高质量参考模板。

---

核心功能：从 PDF 上传到智能问答的完整链路

文档摄入（Ingestion）流程

用户上传 PDF 文件后，后端通过 LangGraph 的 Ingestion Graph 进行处理：

1. PDF 解析：使用 pdf-parse 库提取文本内容
2. 文本分块（Chunking）：将长文档切分为适合嵌入的文本块（通常 500-1000 tokens）
3. 向量化存储：通过 OpenAI 的 text-embedding-3-small 模型生成向量，存入 Supabase 的向量存储（基于 pgvector 扩展）

整个过程通过 Next.js 前端的 /api/ingest 路由触发，用户上传后可以在界面上看到摄入进度。

问答（Retrieval）流程

当用户发起问题时，Retrieval Graph 接管：

1. 用户问题被转换为向量，在 Supabase 向量数据库中检索最相似的 Top-K 文档块
2. 检索结果（相关文档片段）作为上下文，连同用户问题一起发给 LLM（OpenAI GPT-4o）
3. LLM 综合上下文生成回答，并在回答中标注来源（引用原始 PDF 的文件名或页码）
4. 答案通过 Server-Sent Events（SSE）实时流式返回，前端逐字展示

LangGraph 状态机架构

项目最值得研究的部分是 LangGraph 的使用方式。与传统的 LangChain Chain（链式调用）不同，LangGraph 将 Agent 建模为状态机——每个节点是一个处理函数，边定义了状态转移规则。这种建模方式的优势在于：

• 可可视化：可以将整个 Agent 工作流绘制成流程图，调试时一目了然
• 可控性：显式定义状态转移逻辑，便于处理复杂的多轮对话
• 可扩展：新增节点（如增加一个「生成思维导图」的步骤）只需添加节点和边即可

项目根目录包含 langgraph.json 配置文件，配合 @langchain/langgraph-cli 可以启动交互式调试界面，实时查看状态流转。

---

技术栈拆解：Monorepo 架构下的前后端协同

项目采用 Yarn Workspaces + Turbo 的 Monorepo 结构，将前后端放在同一个代码库中：

模块	技术栈	职责
Backend	TypeScript + LangChain + LangGraph + Supabase	PDF 摄入、向量检索、Agent 逻辑
Frontend	Next.js 14 + React 18 + Tailwind CSS + Radix UI	文件上传、聊天界面、SSE 流式展示
数据库	Supabase（PostgreSQL + pgvector）	结构化数据 + 向量存储
LLM	OpenAI GPT-4o / GPT-4o-mini	答案生成
嵌入模型	text-embedding-3-small	文档向量化

后端依赖亮点：chromadb（Chroma 向量库）也是项目依赖之一，尽管默认使用 Supabase，说明项目方在架构上是支持多向量库的。另外，@mendable/firecrawl-js 的引入暗示了未来可能支持从网页而非 PDF 中摄取内容。

前端组件库选择：项目大量使用 Radix UI 的原始组件（@radix-ui/react-*），而非直接使用 shadcn/ui，这意味着代码具有较好的定制性，但维护成本相对较高。

---

上手门槛：适合谁、不适合谁

适合学习的群体

• 想学 LangChain/LangGraph 的开发者：这是目前最完整、最贴近生产的 LangGraph + Next.js 集成参考
• 想构建私有知识库的产品团队：可以直接 fork 并修改为自己的知识库后端
• AI 应用开发者：流式响应、SSE 前端集成、向量检索等都是生产中常用的模式

不适合的场景

• 完全没有编程背景的用户：需要手动配置 Supabase、OpenAI API Key，门槛不低
• 需要生产级部署的用户：项目明确不再活跃维护，生产使用需自己负责
• 需要中文 embedding 的场景：默认使用 OpenAI embedding，不支持中文优化的嵌入模型

---

局限与争议：每个开源项目都有两面

1. 不再活跃维护：作者明确表示不会响应新 Issues/PR，使用者需要较强的独立 debug 能力
2. 强依赖 OpenAI：虽然 LangChain 支持多 LLM 提供商，但默认配置和文档都是围绕 OpenAI 展开的
3. Supabase 绑定：向量存储默认使用 Supabase，更换为 Pinecone 或 Weaviate 需要自己动手
4. PDF 解析质量：使用 pdf-parse 库，对扫描件（图片型 PDF）支持差，需要 OCR 前处理

---

行业意义：RAG 浪潮中的一个坐标

2023-2024 年，基于检索增强生成（RAG）的 AI 应用爆发式增长，而 mayooear/gpt4-pdf-langchain 系列（该项目的前身）正是这股浪潮中的标志性项目之一。从最早的 GPT-4 单文件脚本，到 LangChain 集成，再到 LangGraph 状态机架构，这个项目的演进史几乎等同于 RAG 技术栈的成熟史。

16,000+ Stars 的体量说明：市场对「快速构建私有文档问答系统」的需求从未消退。即使 LangChain 本身备受争议（社区对其 DX 的批评从未停止），围绕它构建的最佳实践模板仍然具有极高的参考价值。

---

快速启动

# 1. 克隆仓库
git clone https://github.com/mayooear/ai-pdf-chatbot-langchain.git
cd ai-pdf-chatbot-langchain

# 2. 安装依赖
yarn install

# 3. 配置环境变量
# backend/.env 和 frontend/.env 填写 OpenAI API Key、Supabase 密钥等

# 4. 启动开发服务
# 后端（需单独开一个终端）
cd backend && npx @langchain/langgraph-cli dev

# 前端（另一个终端）
cd frontend && yarn dev

提示：项目配套 O'Reilly 书籍《Learning LangChain》中有更详细的部署说明和原理解析，适合系统学习。