docext：开源文档智能解析与评测工具箱

一款让文档"开口说话"的AI工具

想象这样一个场景：一家跨境电商公司每天收到数百份来自不同国家供应商的发票——有英文的、中文的、日文的，有扫描件、有PDF、有照片。传统做法是人工录入，效率低、出错率高。而现在，只需把文档丢给 docext，几秒钟内就能提取出发票号、商品明细、金额、日期等所有关键字段，结构化输出为 JSON 或 Markdown，整个过程无需 OCR，完全依赖视觉语言模型（VLM）的理解能力。

这就是 NanoNets 团队开源的 docext 给文档处理领域带来的改变。

图1：docext Web 界面（Gradio），支持自定义字段提取与多文档批量处理

背景：为什么需要端侧文档解析？

文档智能解析（Document Intelligence / IDP）并不是新问题，但传统方案长期依赖 OCR 引擎（Tesseract、ABBYY 等）将图像转文字，再配合规则或 NLP 模型提取信息。这条技术路线存在三个固有缺陷：

第一，OCR 错误会级联放大。 表格错位、扫描噪点、手写体等都会导致 OCR 识别率骤降，后续提取准确率随之崩塌。第二，多语言支持成本高。 每种语言都需要单独训练 OCR 模型或词典，维护成本极高。第三，端侧部署困难。 商业 OCR 服务有隐私风险，云端调用有网络延迟和数据合规问题。

2023 年起，随着 GPT-4V、Qwen-VL 等视觉语言模型成熟，研究者开始探索"OCR-Free"路线——让 VLM 直接"看"文档图像，理解布局结构和语义内容，绕过传统 OCR 环节。docext 正是在这一趋势下诞生的开源工具包，目标是为开发者和企业提供一套可在本地运行的完整文档解析与评测解决方案。

docext 由 Nanonets 团队开发和维护。Nanonets 是一家专注于文档 AI 的商业公司，其云端产品已服务大量企业客户。选择将核心技术开源，体现了对开源生态的重视，也希望通过社区力量推动 IDP 基准测试的标准化。

核心功能：三大模块一览

模块一：PDF/图片转 Markdown（PDF2MD）

这是 docext 最直观的功能——将任意格式的文档转换为结构化 Markdown，保留语义层次。

其技术实现基于 Qwen2.5-VL 等多模态模型，输出包含丰富的语义标签：

标签	含义
<img></img>	文档内嵌图片的描述
<signature></signature>	检测到的签名区域
<watermark></watermark>	水印文本
<page_number></page_number>	页码
<table>	HTML 格式表格

特别值得关注的是 LaTeX 公式识别能力——对于学术论文、技术文档中的数学公式，docext 能准确转换为 Markdown 数学语法，这是大多数通用 OCR 工具的盲区。表单中的复选框、单选按钮也会被转换为标准化 Unicode 符号（☐、☑、☒），便于后续自动化处理。

图2：PDF 转 Markdown 效果示意，支持公式、表格、签名、水印等多种语义元素

模块二：智能信息提取（Docext KIE）

这是面向企业场景的核心能力。用户可以定义自定义提取字段，或使用预置模板（发票、护照等），VLM 会在理解文档语义的基础上直接输出结构化结果，而非中间文字转录。

主要特性：

• 无 OCR 依赖：VLM 直接端到端输出结构化字段，跳过 OCR 环节
• 置信度评分：每个提取字段附带置信度分数，便于人工复核或自动阈值过滤
• 多页文档支持：自动处理多页 PDF，跨页关联信息（如总金额汇总）
• 表格提取：将复杂表格转为结构化 JSON/CSV，保留行列关系
• REST API：Gradio 底层封装为可调用接口，方便集成到企业工作流

模块三：文档智能评测基准（IDP Leaderboard）

这是 docext 区别于其他文档处理工具的独特价值——它不仅仅是一个工具，更是一套可复现的评测体系。

评测任务覆盖七大维度：

• KIE（关键信息提取）：从发票、合同等提取结构化字段
• VQA（视觉问答）：基于文档内容回答问题
• OCR：纯文本识别准确率评测
• 文档分类：判断文档类型（发票/合同/表单等）
• 长文档处理：跨多页的推理与关联能力
• 表格提取：表格结构与内容的还原质量
• 置信度校准：模型输出置信度与实际准确率的匹配程度

评测平台托管于 idp-leaderboard.org，已收录 Gemini、Claude、Qwen-VL、InternVL 等主流 VLM 的评测数据，作者团队持续更新新模型结果。评测代码完全开源，用户可自行部署评测环境，对自有模型或微调版本进行评测。

图3：IDP 评测基准平台，覆盖主流多模态模型的文档理解能力对比

技术架构解析

从代码结构看，docext 采用模块化设计，核心分为四层：

1. 入口层（docext/app）：app.py 基于 Gradio 构建 Web UI，args.py 处理命令行参数，pdf2md.py 封装 PDF 转 Markdown 的调用入口。

2. 核心逻辑层（docext/core）：

• extract.py：KIE 任务主逻辑，调用 VLM 提取字段
• client.py：统一客户端封装，屏蔽底层模型差异
• vllm.py：vLLM 推理引擎封装，支持本地 GPU 推理
• config.py / prompts.py：配置管理和提示词模板
• confidence.py：置信度评分计算
• file_converters/：文件格式转换（PDF、图片等）
• pdf2md/：PDF 转 Markdown 的详细实现（ocr.py、kie.py、tables.py、vqa.py 等）

3. 评测层（docext/benchmark）：

• benchmark.py：评测流程编排
• tasks.py：评测任务定义（KIE/VQA/OCR 等）
• metrics/：评测指标实现
• vlm_datasets/：数据集加载器

4. 推理后端：支持 vLLM（本地 GPU 推理）和 Ollama（本地 CPU/GPU）两种本地部署方案，以及 OpenAI、Anthropic、OpenRouter 等商业 API 的统一调用（通过 litellm 封装）。

主要依赖：

• vllm==0.8.3：高效本地 LLM/VLM 推理
• litellm：统一 LLM API 调用
• transformers>=4.51.1：HuggingFace 模型生态
• gradio==5.23.2：Web UI 界面
• PyMuPDF：PDF 处理
• pdf2image：PDF 转图片

上手体验：安装与运行

安装方式

# 推荐用 uv 创建虚拟环境
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv --python=3.11
source .venv/bin/activate
uv pip install docext

或从源码安装：

git clone https://github.com/nanonets/docext.git
cd docext
uv pip install -e .

Web 界面启动

python -m docext.app.app
# 默认地址：http://localhost:7860
# 默认账号：admin / admin

Docker 快速部署

项目提供了基于 vllm/vllm-openai:v0.8.2 的多阶段 Dockerfile，已包含所有依赖，一键构建：

docker build -t docext .
docker run --gpus all -p 7860:7860 docext

GPU 硬件需求

vLLM 推理对显存要求较高，官方推荐 16GB+ VRAM（如 RTX 3090/A100/A10G）。CPU 模式下可通过 Ollama 运行，但处理速度会显著下降。

局限与挑战

客观地说，docext 仍面临一些现实问题：

部署门槛不低。 vLLM 本地部署需要 GPU 硬件支持，对于没有 GPU 基础设施的团队，仍需依赖商业 API（这又绕回了隐私问题）。Colab notebook 提供了云端 GPU 的快速体验，但不适合大规模生产使用。

模型选择依赖商业 API 密钥。 开箱即用的默认配置通常需要 OpenAI/Anthropic API Key，本地模型（如 Qwen2.5-VL）需要额外下载和配置权重文件，过程不如云端 API 流畅。

评测基准的客观性。 作为 Nanonets 维护的项目，IDP Leaderboard 的评测设计可能存在偏向自家模型的打分标准（尽管评测代码开源，但具体数据集和评估 Prompt 的选择仍有主观空间）。建议有条件的用户在自有数据集上复现评测结果。

长文档处理的 token 限制。 当前 VLM 的上下文窗口虽有提升，但对于超长 PDF（如 100+ 页的年报），仍需要分块处理，跨页信息的关联能力有待验证。

行业意义与趋势

docext 的出现反映了文档 AI 领域的一个深刻变化：从"文字识别优先"到"视觉理解优先"的范式转变。传统 OCR→NLP 管道在端到端 VLM 面前，正在被逐步取代。

这一趋势在 2024-2025 年尤为明显：Google Document AI、Azure Form Recognizer 等云服务已全面引入 VLM 能力；开源社区也涌现出大量类似工具（如 Marker、Parmise 等）。docext 的差异化在于"评测基准"这一环——它不只是一个工具，更试图建立文档理解能力的标准化评测体系，这对推动整个领域的技术进步有重要价值。

对于开发者而言，docext 的开源也意味着可以在本地部署自己的评测环境，不依赖第三方评测结果，对模型选型和微调效果有更直接的判断依据。

---

一句话总结：docext 是一款以 VLM 为核心的端侧文档智能解析工具包，同时提供配套的评测基准平台，适合需要本地化文档处理能力、且关注模型评测透明度的团队使用。