Document Field Agent / 文档字段提取 Agent

把本地 PDF、图片和扫描件批量转换为可复核的字段结果与 Excel。支持标准 MCP，让任意兼容 Agent 调度任务、导出结果并生成复核报告。

Windows 已验证 · 本地优先 · MCP stdio · Excel 与复核报告

从文件到可复核结果

输入	处理	输出
图片、PDF、扫描件或文件夹	OCR、分页、字段候选召回与本地模型裁决	Excel、Markdown / JSON 复核报告，以及 TXT / CSV / HTML

适用于教案录入、合同台账、表单归档、档案整理、票据或证明信息提取等重复性文档工作。上传文件后，指定字段即可得到每页一行、字段为列的结构化结果；缺失项和低置信度字段会标出，方便人工复核。

为什么是 Document Field Agent

• 本地文档处理：默认用 PP-OCRv6 完成 OCR，以 MiniCPM5-1B 在 OCR 文本、候选召回和版面判断之后裁决字段值。
• 字段结果可复核：置信度低于 0.7 的结果会标记为复核项，不把不确定值伪装成最终答案。
• MCP 是通用接口：MCP Server 以 stdio 工作，经本地 HTTP API 调度工作台；不绑定某个特定 Agent 客户端。
• 云端模式可选：需要更高精度的文档解析时，可显式配置 PaddleOCR-VL-1.6 与 DashScope qwen-plus；本地模式仍是默认选择。

工作方式

本地 PDF / 图片 / 文件夹
  -> PDF 渲染与分页
  -> PP-OCRv6 本地 OCR 或可选云端解析
  -> 字段候选召回与版面判断
  -> MiniCPM5-1B 本地字段裁决
  -> 置信度校验与人工复核
  -> Excel / Markdown / CSV / HTML / TXT

MCP Server 位于 pilotdeck/mcp_server.py，默认连接 http://127.0.0.1:8766。它只负责调用本地工作台 API；OCR、字段抽取与导出仍由工作台完成。

快速开始

1. 克隆并安装依赖

git clone https://github.com/BHD110/document-field-agent.git
cd document-field-agent
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements-webapp.txt

macOS / Linux 可以使用以下等价命令，但当前仅 Windows 完整验证：

python -m venv .venv
source .venv/bin/activate
pip install -r requirements-webapp.txt

2. 下载本地模型

bash scripts/download_models.sh all
python scripts/setup_minicpm5_sidecar.py

上述命令下载 PP-OCRv6 Tiny / Small / Medium ONNX 模型，以及本地字段抽取所需的 MiniCPM5-1B-Q4_K_M.gguf 与 llama.cpp sidecar。模型文件保存在 Git 忽略目录，不会提交到仓库。

3. 启动本地字段抽取 sidecar

Windows PowerShell：

.\tools\llama\llama-server.exe `
  -m .\models\minicpm5-1b-q4_k_m.gguf `
  --host 127.0.0.1 `
  --port 11435 `
  -c 4096 `
  -t 8 `
  --chat-template chatml

macOS / Linux：

./tools/llama/llama-server \
  -m ./models/minicpm5-1b-q4_k_m.gguf \
  --host 127.0.0.1 \
  --port 11435 \
  -c 4096 \
  -t 8 \
  --chat-template chatml

4. 启动工作台

python webapp/server.py

浏览器打开 http://127.0.0.1:8766。需要改端口时，设置 DOC_WORKBENCH_PORT；sidecar 地址可通过 DOC_WORKBENCH_LOCAL_LLM_URL 调整。

接入 MCP Client

先保持工作台在运行状态。MCP Server 默认使用 stdio；以下是通用 MCP JSON 配置示意，具体配置入口名称由客户端决定：

{
  "mcpServers": {
    "document-field-agent": {
      "command": "python",
      "args": ["C:\\path\\to\\document-field-agent\\pilotdeck\\mcp_server.py"],
      "cwd": "C:\\path\\to\\document-field-agent",
      "env": {
        "DOC_WORKBENCH_URL": "http://127.0.0.1:8766"
      }
    }
  }
}

先在项目根目录执行下面的命令，确认 MCP Server 能列出工具：

python pilotdeck/mcp_server.py --list-tools

然后可让 Agent 按以下顺序工作：

1. create_document_task：传入明确的本地文件或文件夹路径与目标字段。
2. get_task_status：获取任务状态、缺失字段和低置信度字段。
3. list_task_pages：需要页面级 OCR 与字段证据时调用。
4. export_task_excel：导出 Excel。
5. export_task_report：导出 Markdown 或 JSON 复核报告。

mode="local" 是隐私敏感文档的默认选择；仅在明确需要云端处理时使用 mode="cloud"。

使用工作台

1. 在首页上传 PDF、图片或文件夹。
2. 填写需要抽取的字段，例如姓名、单位、课程名称、合同编号、日期或金额；也可上传 Excel 模板，系统读取第一个 sheet 的第一行字段名。
3. 选择本地或云端模式，等待任务处理完成。
4. 在结果页查看 OCR 全文、字段结果、缺失项与低置信度提示。
5. 导出 Excel 或其他格式，并按复核报告处理待确认项。

运行边界

项目	当前状态
Windows	已验证 OCR、任务处理、字段抽取、Excel 导出与 MCP 调用流程。
macOS / Linux	理论上可运行 FastAPI、ONNX Runtime 与 llama.cpp，但启动脚本、模型下载、MCP 调用和 sidecar 尚未完整实机验证。
本地字段抽取	需要约 700 MB 的 MiniCPM5-1B GGUF 模型，使用 llama.cpp CPU sidecar。
PDF	依赖 pypdfium2 进行渲染与分页。

可选云端模式

云端模式用于更高精度的文档解析与字段抽取，需自行配置环境变量：

DASHSCOPE_API_KEY=...
PADDLEOCR_VL_TOKEN=...

请勿将 API Key、token、.env、secrets.blob 或运行日志提交到仓库。scripts/make_secret_blob.py 仅提供本地运行时混淆，并非密钥安全边界。

API 概览

接口	说明
GET /health	健康检查
GET /info	当前模型、配置和工作台信息
POST /tasks	从上传文件创建任务
GET /tasks	获取历史任务
GET /tasks/{id}	获取任务详情
GET /tasks/{id}/pages	获取任务页面
GET /tasks/{id}/export?fmt=xlsx|txt|md|csv|html	导出任务结果
POST /templates/fields	从 Excel 模板读取字段名
POST /agent/tasks/from-path	从本地路径创建 Agent 任务
GET /agent/tasks/{id}/summary	获取 Agent 任务摘要
GET /agent/tasks/{id}/report?fmt=md|json	获取复核报告

旧版 /ocr 接口仍保留，用于兼容单图 OCR 调用。

开发与检查

python -m compileall webapp bench_local_v2.py gen_result_vis.py run_apple_vision.py scripts/make_secret_blob.py scripts/setup_minicpm5_sidecar.py pilotdeck/mcp_server.py

常用 smoke test：

• 上传单张图片，确认生成一个任务和一条页面记录。
• 上传多页 PDF，确认历史页只显示一个任务。
• 从 Excel 模板读取字段，并导出字段结果 Excel。
• 检查低置信度字段提示与无字段模式的 TXT / Markdown / CSV / HTML 导出。
• 运行 python pilotdeck/mcp_server.py --list-tools，再通过 MCP 创建任务。

企业合作 / 定制服务

查看可支持的方向

可基于本项目或现有 AI 自动化能力交付文档识别、字段抽取与自动录入系统，以及企业知识库、资料检索、运营助手、内容工作流、数据处理等定制场景。

开源与致谢

本项目基于 andyhuo520/ppocrv6-studio 二次开发，感谢原作者提供的 PP-OCRv6 本地工作台、评测流程与真实场景样例基础。

同时感谢 PaddleOCR、ONNX Runtime、llama.cpp、OpenBMB MiniCPM 与 FastAPI。

License

本项目沿用 MIT License，详见 LICENSE。第三方模型、数据集与云端 API 的使用请遵循其各自许可证和服务条款。