DocAgent

面向本地文档的 Agentic-RAG 与 MCP 工具化问答系统

项目简介

基于 FastAPI、GLM-4-Flash、TF-IDF 构建的本地文档智能问答系统，支持多轮对话、意图识别、查询改写、工具路由和 MCP Server 封装。

核心功能

• 📄 文档上传解析 - 支持 PDF 和 Word 文档
• 🔍 中文检索 - jieba 分词 + TF-IDF 向量检索
• 🤖 LLM 问答 - 智谱 GLM-4-Flash 生成答案
• 📚 引用溯源 - 返回答案对应的文档来源
• 💬 多轮对话 - 支持连续追问，上下文记忆
• 🎯 意图识别 - 自动判断问题类型（新问题/追问/摘要/对比/计算/闲聊）
• ✏️ 查询改写 - 追问时自动将"它"等指代词改写为完整问题
• 🛠️ 工具路由 - 根据意图自动选择问答/摘要/计算工具
• 🔧 Tool Registry - 统一工具注册、调用和返回格式
• 🌐 MCP Server - 通过 Model Context Protocol 暴露本地文档能力

系统架构

┌─────────────────────────────────────────────────────────────┐
│                     HTML 前端 (index.html)                  │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTP
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                     FastAPI 后端 (端口 8000)                 │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │ Conversation │  │ Intent Router │  │   Tool Router    │   │
│  │  Manager    │  │ + Query       │  │   → Tool Registry│   │
│  └─────────────┘  │  Rewriter     │  └──────────────────┘   │
└───────────────────┴───────────────┴─────────────────────────┘
                           │
          ┌────────────────┼────────────────┐
          ▼                ▼                ▼
   ┌────────────┐   ┌────────────┐   ┌────────────┐
   │Document QA │   │  Summary   │   │ Calculator │
   │   Tool     │   │   Tool     │   │    Tool    │
   └─────┬──────┘   └─────┬──────┘   └────────────┘
         │                │
         ▼                ▼
   ┌─────────────────────────────────────┐
   │        RAG Service                  │
   │  ┌──────────┐    ┌──────────────┐   │
   │  │ TF-IDF   │───▶│  Retriever   │   │
   │  │ VectorDB │    └──────────────┘   │
   │  └──────────┘           │           │
   │                         ▼           │
   │                  ┌──────────────┐   │
   │                  │  GLM-4-Flash │   │
   │                  └──────────────┘   │
   └─────────────────────────────────────┘
                           │
                           ▼
   ┌─────────────────────────────────────┐
   │     MCP Server (stdio 模式)          │
   │  list_documents / search_document   │
   │  ask_document / summarize_document  │
   └─────────────────────────────────────┘

快速开始

1. 克隆项目

git clone <your-repo-url>
cd docagent-mcp

2. 创建虚拟环境并安装依赖

conda create -n docagent python=3.10
conda activate docagent
pip install -r requirements.txt

3. 配置 API Key

# 方式1：环境变量
export ZHIPU_API_KEY="your-api-key"

# 方式2：直接修改 backend/config.py
ZHIPU_API_KEY = "your-api-key"

4. 启动 FastAPI 后端

python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000

5. 打开前端

直接双击打开 frontend/index.html，或启动 HTTP 服务器：

cd frontend
python -m http.server 8080
# 访问 http://localhost:8080

6. (可选) 启动 MCP Server

python -m backend.mcp_server.server

API 接口

上传文档

curl -X POST "http://localhost:8000/api/upload" \
  -F "file=@/path/to/document.pdf"

问答

curl -X POST "http://localhost:8000/api/chat" \
  -H "Content-Type: application/json" \
  -d '{"question": "博士学位申请需要满足哪些条件？", "top_k": 4}'

列出工具

curl "http://localhost:8000/api/tools"

获取执行轨迹

curl "http://localhost:8000/api/conversations/{id}/trace"

意图识别示例

问题	识别意图	调用工具
"博士学位申请需要满足哪些条件？"	NEW_QUESTION	document_qa
"它的学制是几年？"	FOLLOW_UP	document_qa (查询改写后)
"总结一下这篇文章"	SUMMARY	document_summary
"它和硕士有什么区别？"	COMPARE	document_qa
"1+1 等于多少？"	CALCULATION	calculator
"你好"	CHITCHAT	direct_answer

项目结构

docagent-mcp/
├── backend/
│   ├── main.py                    # FastAPI 入口
│   ├── config.py                  # 配置
│   ├── agent/
│   │   ├── base_tool.py           # 工具基类
│   │   ├── tool_result.py         # 统一返回格式
│   │   ├── tool_registry.py       # 工具注册中心
│   │   ├── conversation_manager.py# 多轮对话管理
│   │   ├── intent_router.py       # 意图识别
│   │   ├── query_rewriter.py      # 查询改写
│   │   ├── tool_router.py         # 工具路由
│   │   └── tools/
│   │       ├── document_qa_tool.py
│   │       ├── document_summary_tool.py
│   │       └── calculator_tool.py
│   ├── rag/
│   │   ├── loader.py              # 文档加载
│   │   ├── splitter.py            # 文本分块
│   │   ├── vectorstore.py         # TF-IDF 向量库
│   │   ├── retriever.py           # 检索器
│   │   └── generator.py           # LLM 生成器
│   ├── api/
│   │   ├── chat.py                # 问答 API
│   │   ├── upload.py              # 上传 API
│   │   └── documents.py           # 文档 API
│   └── mcp_server/
│       ├── server.py              # MCP Server
│       ├── mcp_tools.py           # MCP 工具定义
│       ├── adapters.py            # 格式转换
│       └── README_MCP.md          # MCP 使用说明
├── frontend/
│   └── index.html                 # HTML 前端
├── data/
│   ├── uploads/                   # 上传文件 (不上传)
│   └── tfidf/                     # TF-IDF 持久化 (不上传)
├── requirements.txt
└── README.md

技术栈

• 后端框架: FastAPI + Uvicorn
• 中文分词: jieba
• 向量检索: TF-IDF (numpy/sklearn)
• LLM: 智谱 GLM-4-Flash
• 协议: Model Context Protocol (MCP)
• 前端: HTML + JavaScript (无框架)

简历描述

DocAgent-MCP：面向本地文档的 Agentic-RAG 与 MCP 工具化问答系统

- 基于 FastAPI、GLM-4-Flash、jieba、TF-IDF 构建本地文档 RAG 系统，
  支持 PDF/Word 解析、中文检索、持久化存储、引用溯源和基于检索增强的问答生成。

- 设计多轮对话管理、意图识别和查询改写模块，支持新问题、追问、摘要、对比、
  计算和闲聊等 6 类意图，并根据上下文动态选择检索策略。

- 抽象 Tool Registry 工具注册中心，统一封装文档问答、文档摘要和计算器工具，
  设计 ToolResult 标准返回格式，实现工具调用轨迹可视化。

- 基于 MCP Server 将本地文档检索、问答和摘要能力暴露为标准工具接口，
  支持外部 Agent 通过统一协议调用本地知识库能力。

License

MIT License