从零搭建基于用户上传文档的智能问答Agent MVP

基于大语言模型的智能文档问答系统，让您的文档"会说话"

📖 项目简介

本项目使用 LangChain + LangGraph 构建了一个基于用户上传文档的智能问答Agent MVP，并配套开发了完整的 Vue + Flask 全栈Web系统，具备任务分离、会话隔离、长短期记忆存储等核心特色

如果你是一个完全的新手，项目还整理了 LangChain 入门笔记以及部分官方实战代码，帮助你从0开始学习如何设计构建一个简单的MVP

✨ 核心功能

📌 任务分离

功能解耦设计：将问答生成与文档摘要任务分离，采用独立处理流程
独立上下文管理：问答任务专注语义理解，摘要任务专注内容提炼
精准任务路由：识别用户意图，自动路由至专用处理模块
突破上下文窗口限制：通过任务分离有效规避单一上下文窗口的容量瓶颈

💬 会话隔离

多类型文档支持：系统支持对pdf、markdown、doc、docs文档进行解析
独立会话隔离：每个文档创建独立的对话会话
精准上下文：问答仅基于当前文档内容，避免信息混淆
会话管理：支持会话查看、续聊、删除等操作

🗂️ 长短期记忆存储

短期记忆：对话记录存入图状态，对齐聊天上下文，实现多轮对话
本地持久化：对话记录本地存储，重启不丢失
长期记忆存储：提取用户信息、用户偏好、聊天记录要点等关键信息存入向量数据库，维护模型的长期记忆

🏗️ Agent系统架构

📁 项目结构

PDF-QA-Agent/
│
├── frontend/                   # Vue前端应用
│   ├── src/
│   ├── public/
│	├── package.json
│   └── ......
│
├── PersonalKnowledgeBase/     # Flask后端服务
│   ├── app.py                 # 主应用入口
│   ├── config.py              # 配置文件
│   ├── requirements.txt       # Python依赖
│   └── ......                 # Agent核心逻辑
│
├── langchain/                 # LangChain学习与实践（快速入门langchain、langgraph）
│	├── Tutorial.md            # agent开发入门知识说明文档
│	├── PromptEngineering.md   # 提示词工程技巧
│   └── tutorials/             # langchian官方项目实践
│
├── image/                     # 项目截图与素材
├── Guide-AutoDL.md            # 云服务器部署指南
└── README.md                  # 项目说明文档

🚀 快速开始

系统要求

Python: 3.11.5
Node.js: 22.11.0
存储: 至少10GB可用空间

后端部署

1. 环境准备

# 进入后端目录
cd PersonalKnowledgeBase

# 安装Python依赖
pip install -r requirements.txt

2. 聊天模型配置

方案一：API调用（推荐初学者）

访问 Google AI Studio 获取Gemini API Key
设置环境变量：

export GOOGLE_API_KEY="your-api-key-here"

在 config.py 中设置 use_model_way = "api"

💡 网络配置：如遇网络问题，请在 config.py 中配置你的代理端口（如：7890）

方案二：本地部署（推荐生产环境）

安装 Ollama并设置环境变量
下载支持工具调用的模型：

ollama pull llama3.2

如果希望性能更好一些，请使用更大的模型。注意，所选模型需要支持tool-calling

如果使用此方案，请在系统运行时确保ollama服务开启：
ollama serve

3. 嵌入模型配置

cd到嵌入模型保存文件夹下，并执行以下指令

huggingface-cli download sentence-transformers/all-mpnet-base-v2 --local-dir ./ --local-dir-use-symlinks False

修改config.py中的嵌入模型文件地址

除了huggingface上的嵌入模型，可以使用 gemini 的嵌入模型，详情见官方文档。

4. 数据库配置

创建一个新的Mysqp数据库用于存储历史聊天记录
根据以下命令创建表

CREATE TABLE chat_history (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    session_id VARCHAR(255) NOT NULL,
    role ENUM('human','ai') NOT NULL,
    content TEXT NOT NULL,
    filename VARCHAR(255),
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_session_created (session_id, created_at)
) ENGINE=InnoDB;

在 config.py 中设置你的数据库信息，如用户名、密码、数据库名称等

5. LangSmith监控agent行为（可选）

在LangSmith官网注册账号并申请一个api
配置系统环境变量，并修改 config.py 文件中的 os.environ['LANGSMITH_TRACING'] = 'False'为'True'

export LANGSMITH_API_KEY="your-api-key-here"
export LANGSMITH_PROJECT="default"  # 或者是其它

💡 网络配置：使用Langsmith进行监控需要vpn，如果既使用LangSmith又使用Ollama本地部署，请将代理设置为“规则模式”

6. 启动后端服务

python app.py

✅ 启动成功提示：

* Running on http://127.0.0.1:5000

前端部署

1. 环境检查

确保已安装 Node.js 和 npm：

node --version
npm --version

2. 安装依赖并启动

cd frontend
npm install
npm run dev

✅ 启动成功提示：

VITE v7.1.9  ready in 1359 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

访问 http://localhost:5173/ 即可开始使用系统！

📑历史更新

2025-10-06：首次提交
2025-10-09：修复了 api 调用方式下会话激活失败的问题；对比并修改了pdf的解析方式；完善补充了 langchain 入门笔记
2025-10-22：修改了意图识别无法跳转摘要任务的 bug ；用 mysql 数据库储存代替浏览器缓存；为模型增加了长期记忆，并更新了短期记忆的使用方法

🔮 未来规划

数据库升级：使用专业数据库替代浏览器缓存
多文档支持：增加支持文档的类型，如doc、markdown等
提示词工程：迭代优化提示词，提高模型表现
文档分类：自动分类文档并提供引导式提问
多文档对话支持：新增功能，允许用户上传多个文档并基于多文档进行提问
智能索引：在多文档支持的基础上，构建文档内容索引，提升检索效率
GPU加速：完善AutoDL云服务器部署指南
视频教程：录制详细的使用和开发教程

🛠️ 技术栈

后端技术

Flask - Python Web框架
LangChain - LLM应用开发框架
LangGraph - 多步骤工作流管理
ChromaDB - 向量数据库

前端技术

Vue 3 - 渐进式JavaScript框架
Vite - 前端构建工具

AI模型

Gemini API - Google大语言模型
Ollama - 本地模型管理
sentence-transformers - 文本嵌入模型

🤝 贡献指南

这是一个完全开源的小项目，欢迎并感谢各种形式的贡献！无论您是开发者、文档写作者还是普通用户，都能帮助这个项目变得更好！

报告问题：在GitHub Issues中提交bug报告（描述清晰的重现步骤和预期行为）或功能请求（说明使用场景与价值等）
代码贡献：提交Pull Request改进代码
文档完善：改进文档结构和清晰度、添加使用示例和教程、翻译多语言版本等
功能建议：分享您的使用场景和需求、提出改进和优化思路、参与功能设计和讨论等

❗请注意：您的修改需要在新分支下进行，pull request之前请更新相关文档，确保你的修改通过基础测试，且不影响现有功能的正常运行，提交时请详细说明你的贡献

📢 如果你的贡献包含提示词工程内容，请提供 bad case 数据集，并详细记录你的评估过程

⭐ 如果这个项目对您有帮助，请给出一个Star！
用AI赋能知识管理，让智能触手可及 ✨

Aapolaris/PDF-QA-Agent