LangChain Chatbot：让 AI 读懂你的文档

你是否遇到过这种情况：手头有一堆 PDF 合同、产品手册、研究论文，想问 AI「帮我总结一下这份文档的核心要点」，却发现 AI 完全答非所问？问题的根源在于，通用大语言模型（如 GPT-4）训练数据有截止日期，它根本不认识你手里的那份文件。

Haste171/langchain-chatbot 解决的就是这个问题——它是一个基于检索增强生成（RAG）架构的文档对话机器人，能够理解并回答用户针对自有文档的提问，实现「文档即知识库」的体验。

背景：从 GPT4-PDF-Chatbot 到独立项目

本项目的直接灵感来源是 Mayo 的开源项目 GPT4 & LangChain Chatbot for large PDF docs。该项目的 Node.js 版本在 GitHub 上积累了可观的 stars，但 Mayo 原版缺乏工程化封装，难以直接在实际业务中部署。

开发者 Haste171 将其移植为 Python 版本，并在此基础上进行了大量工程化改造：添加了 FastAPI 后端实现 RESTful 接口、Streamlit 前端提供可视化交互界面、支持多模态文档加载（txt/pdf/docx）、引入对话历史记忆机制，以及对多款大语言模型（GPT-3.5 / GPT-4 / Claude-3）的统一抽象。

从项目 topic 可以看出其技术栈全貌：langchain、openai、pinecone、chromadb、discord-bot、embeddings 等，覆盖了从向量检索到对话生成的全链路。

核心架构：RAG 的工程化实现

整体技术架构

项目采用经典的前后端分离架构，后端由 FastAPI 提供 API 服务，前端由 Streamlit 提供可视化交互界面。两个服务通过 startup.py 中的多线程机制同时启动，用户在 Streamlit 界面输入查询，请求转发至 localhost:9091 的 FastAPI 服务进行处理。

核心处理链路遵循 RAG（Retrieval-Augmented Generation）标准范式：

文档加载与分块（Ingestion Pipeline）

用户上传文档后，系统通过 PyMuPDFLoader（PDF）、Docx2txtLoader（Word）和 TextLoader（纯文本）三种加载器将文档解析为文本，然后使用 LangChain 的 RecursiveCharacterTextSplitter 按语义边界进行切分。切分策略考虑了 token 数量和重叠长度，确保每个文本块既保留足够的上下文，又不会超出 LLM 的上下文窗口限制。

向量存储与检索（Retrieval）

切分后的文本块通过 OpenAI Embedding 模型（默认使用 text-embedding-3-small，维度 1536）转换为向量，存入 Pinecone 向量数据库。查询时，系统从 Pinecone 检索 Top-K 个最相关的文本块（默认 K=5，可通过前端调节 1-10），作为上下文提供给大语言模型。Pinecone 的 namespace 机制允许用户在不同文档集合间隔离数据，实现多租户支持。

对话生成（Generation）

检索到的文档块作为上下文，通过 LangChain 的 ConversationalRetrievalChain 注入对话 prompt。系统支持以下模型：

模型	提供商	最大上下文
gpt-3.5-turbo	OpenAI	16K tokens
gpt-4	OpenAI	8K tokens
gpt-4-32k	OpenAI	32K tokens
claude-3-sonnet	Anthropic	200K tokens
claude-3-opus	Anthropic	200K tokens

对话历史（chat_history）会被一并传入 chain，支持多轮追问，这是区别于单次问答的关键特性。

关键代码解析

BaseHandler：核心业务逻辑中枢

handlers/base.py 中的 BaseHandler 类是整个系统的核心。它初始化向量存储连接（通过 Pinecone.from_documents / Pinecone.from_existing_index），管理 LLM 实例映射，并暴露 load_documents、ingest_documents、chat 三个主要方法。

load_documents 方法维护了一个 loader_map，将文件扩展名映射到对应的 LangChain 文档加载器。关键细节在于，它将上传文件写入临时文件（通过 tempfile.NamedTemporaryFile）后再加载，这样即使是多格式、大体积文档也不会导致内存溢出。

API 路由：清晰的服务边界

FastAPI 后端只包含两个核心路由：POST /ingest 和 POST /chat。/ingest 接收 multipart/form-data 格式的文件上传，返回确认消息；/chat 接收 JSON 格式的查询请求，支持动态选择模型、温度参数和向量检索数量。温度参数在 0.0-2.0 范围内可调，高温度带来更多创造性但降低准确性，适合创意写作场景。

Streamlit 前端：极简交互设计

ui/main.py 的前端实现了两个页面（Ingestion 和 Chat），通过侧边栏导航切换。Chat 页面支持实时调节模型、温度、返回文档数量等参数，并在返回结果中同时展示 AI 回答和对应的源文档片段（含文件来源和页码），方便用户核实信息准确性。这种「回答 + 溯源」的设计在专业文档分析场景中非常重要。

部署与上手

环境准备

项目依赖管理使用 Poetry，要求 Python 3.10+。安装前需准备：

1. OpenAI API Key（必需）：从 platform.openai.com 获取，用于 Embedding 生成和对话生成，按 token 计费
2. Pinecone API Key（必需）：从 pinecone.io 注册免费账号创建 index，用于向量存储
3. Anthropic API Key（可选）：如需使用 Claude-3 模型

安装流程：

git clone https://github.com/Haste171/langchain-chatbot.git
cd langchain-chatbot
cp example.env .env  # 填入 API Key
poetry install
poetry shell
python3 startup.py

启动后访问 http://localhost:8501 进入 Streamlit 界面。

部署注意事项

API 成本：本项目涉及 OpenAI Embedding 和 ChatGPT 两类 API 调用——Embedding 按 token 计费（text-embedding-3-small 约 $0.00002/1K tokens），Chat 接口按模型不同从 $0.002/1K tokens（GPT-3.5）到 $0.015/1K tokens（GPT-4）不等。大规模文档处理前建议先估算成本。

数据隐私：所有文档内容会上传至 OpenAI API 和 Pinecone 云服务，不适合处理高度敏感的机密文档。如需完全本地化部署，需将 OpenAI 替换为本地 LLM（如 Ollama + Llama2），将 Pinecone 替换为本地向量数据库（如 Qdrant、Milvus）。

维护状态：README 中明确标注了「Maintained? no」，项目已停止主动维护，但核心功能仍然可用，LangChain 版本已锁定在 0.1.11，后续 LangChain API 变更可能导致兼容性问题。

行业意义与项目定位

Haste171/langchain-chatbot 代表的不是一项原创研究，而是将 RAG 范式工程化落地的典型案例。从行业角度看，2023-2024 年间，LangChain 生态迅速成熟，类似的可私有化部署文档问答系统大量涌现，其共同价值在于：让企业不再依赖通用 AI，而是拥有专属的知识库 AI。

相比更复杂的 RAG 架构（如带有 reranker、query decomposition、多跳推理的系统），本项目刻意保持简洁：只有 PDF/Word/Txt 三种格式、不支持图像、对话历史有限制。这种「小而美」的定位降低了上手门槛，也使其成为学习 LangChain + Pinecone 组合的最佳实战项目之一。

对于想构建类似系统的开发者，本项目是理解 RAG 全流程的优质参考：文档加载 - 文本分块 - Embedding - 向量检索 - 对话生成，完整链路清晰可循，是入门检索增强生成不可多得的实战教材。