5分钟上手 Nemotron 3.5 Parse：Transformers 文档解析快速入门教程

Nemotron 3.5 Parse 是 NVIDIA 推出的文档图像解析模型，输入一张文档图片（PDF 页面、幻灯片、表单、报表等），即可输出带语义布局类别、边界框和阅读顺序的结构化 Markdown 文本。本教程带你用 Transformers 在 5 分钟内完成文档解析模型的安装、推理与后处理全流程，零基础也能跑通。

一、Nemotron 3.5 Parse 能做什么？

简单说，它把"看不懂的文档图片"变成"机器可读的结构化文本"：

• OCR 文本识别：输出纯文本，支持多语言（72,505 个 token 的多语言词表）
• 版面理解：每个文本块带语义类别（标题、正文、表格、图表等）和归一化边界框
• 表格/图表解析：表格可转换为 LaTeX、HTML、Markdown、JSON、CSV 等多种格式
• 阅读顺序保留：输出顺序与人工阅读顺序一致

在 ParseBench 基准上，三遍解析（triple pass）平均分为 75.20，表格解析 84.67、内容忠实度 87.96，且单卡 H100 吞吐达 10.62 页/秒，明显快于同档位的开源解析模型。

💡 模型架构：C-RADIOv4-SO400M 视觉编码器 + 10 层 mBART 因果解码器，约 0.63B 参数，推荐输入分辨率上限 1664×2048。

二、环境准备：一键安装依赖

推荐使用 Python 3.12 和一个全新的虚拟环境：

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install "transformers==5.14.1" "torchvision==0.26.0" "timm==1.0.22"

注意两点：

1. Transformers 会自动下载模型权重、processor 和自定义模型代码，无需额外安装任何 Nemotron 包
2. 如果模型仓库需要鉴权，先执行 hf auth login

三、三步跑通文档解析

第 1 步：加载模型

import torch
from PIL import Image
from transformers import AutoModel, AutoProcessor, GenerationConfig

model_path = "nvidia/Nemotron-3.5-Parse"
device = "cuda:0"

model = AutoModel.from_pretrained(
    model_path, trust_remote_code=True, dtype=torch.bfloat16
).to(device).eval()
processor = AutoProcessor.from_pretrained(model_path, trust_remote_code=True)

第 2 步：准备图片与任务提示词

默认的文档解析任务提示词由控制 token 组成，一次性提取边界框、语义类别和 Markdown 文本：

image = Image.open("path/to/your/image.jpg").convert("RGB")
task_prompt = "</s><s><predict_bbox><predict_classes><output_markdown><predict_text_in_pic>"

inputs = processor(images=[image], text=task_prompt,
                   return_tensors="pt", add_special_tokens=False).to(device)

⚠️ 图片必须先转换为 RGB 模式，这是该模型的输入要求。

第 3 步：生成并解码结果

generation_config = GenerationConfig.from_pretrained(model_path)
generation_config.max_new_tokens = 8744

with torch.inference_mode():
    outputs = model.generate(**inputs, generation_config=generation_config)

generated_text = processor.batch_decode(outputs, skip_special_tokens=False)[0]
print(generated_text)

输出是编码了文档文本、语义类别和归一化边界框的字符串。坐标换算方法：x 坐标乘以图片宽度，y 坐标乘以图片高度，即可得到像素位置。

仓库中还提供了一个现成的命令行脚本 run_transformers_inference.py，支持 --image、--max-new-tokens、--repetition-penalty 等参数，还能用 --save-overlay 把检测框画回原图，适合快速验证效果：

python run_transformers_inference.py --image page.jpg --save-overlay out.png

四、后处理：把原始输出变成精美 Markdown

模型的原始输出还需要一次后处理才能直接用于文档归档。仓库内置的共享工具会把整页渲染为带 HTML 表格的 Markdown，并返回带归一化/像素边界框的结构化块，同时保留表格跨行跨列、空单元格和单元格内换行：

python -m pip install "beautifulsoup4==4.13.3"
hf download nvidia/Nemotron-3.5-Parse \
  --include 'postprocessing.py' 'latex2html.py' 'nemotron_parse/**' --local-dir .

from pathlib import Path
from PIL import ImageDraw
from postprocessing import postprocess_document

document = postprocess_document(generated_text, image_size=image.size)
Path("prediction.md").write_text(document["markdown"], encoding="utf-8")

# 把检测框画回原图
draw = ImageDraw.Draw(image)
for block in document["blocks"]:
    draw.rectangle(block["bbox_pixels"], outline="red", width=2)
image.save("prediction.png")

表格导出支持 latex、HTML、markdown、json、json_hierarchical、csv 六种格式，其中 HTML 和分层 JSON 能保留合并单元格结构。更完整的选项说明见 docs/postprocessing.md。

五、核心文件速查 📂

文件/目录	说明
README.md	模型卡，含 Quick Start、vLLM 部署与基准测试
run_transformers_inference.py	Transformers 命令行推理脚本
postprocessing.py	后处理入口：Markdown 渲染、表格转换
nemotron_parse/inference.py	单遍/双遍/三遍解析的 DocumentParser 封装
docs/postprocessing.md	后处理与多遍解析完整指南
generation_config.json	默认生成参数配置

六、进阶：更高精度与更高吞吐

• 双遍/三遍解析：整页解析后再对表格/图表裁剪区域精修，双遍可提升 2.18 分，三遍再提升 0.28 分（吞吐约降 9%）。参考 reference/parsebench/pipeline/
• vLLM 部署：仓库内置 vLLM 插件与 MTP 投机解码头，服务化后吞吐更高，详见 docs/serving.md
• 质量校验：官方提供了 quick20 / full500 两组参考输出，可对照 reference/parse_3_5/ 验证你的环境与结果是否一致

七、常见问题 FAQ

Q：没有 GPU 能跑吗？ CPU 可以运行（脚本会自动选择 float32），但速度明显变慢，建议至少配备一张支持 bfloat16 的显卡。

Q：输出里出现大量特殊 token 正常吗？ 正常。skip_special_tokens=False 是刻意为之，控制 token 本身就是版面信息的一部分，后处理阶段会自动处理它们。

Q：解析扫描件效果如何？ 合成数据上的 OCR 分数很高（MOSCAR 字符级 F1 达 99.51），但官方明确提示：复杂扫描件、手写体、低质量图片等真实场景精度可能下降，建议先用 reference/parse_3_5/quick20/ 的 20 页样例快速试跑自己的文档。

---

小结：Nemotron 3.5 Parse 的安装只需一条 pip 命令，推理只需三行核心代码，再配合官方后处理工具即可产出可直接入库的结构化 Markdown。接下来你可以尝试用它搭建自己的 RAG 文档解析流水线，或者阅读 docs/serving.md 体验 vLLM 高性能部署。