一张页面图像进去，文本、表格、公式有序流出------这正是端到端文档解析想做到的事。
几乎每一个组织，都有堆积如山的纸面文档：扫描合同、年度财报、学术论文、报销表单、手写记录，还有员工用手机随手翻拍的各种页面。把这些文档变成机器能检索、能计算、能入库的结构化数据，是一件做了几十年、却始终没有被彻底解决的事。
过去的标准答案是 OCR。但真正用过的人都知道它的痛点：字认出来了，结构却丢了。多栏文章被拼成一段，表格行列错位，数学公式变成乱码，标题正文不分，阅读顺序全乱。你拿到的不是"这一页"，而是一堆没有骨架的文字碎片，下游还得写大量规则去修补。
这两年，文档解析的技术分水岭正在从"OCR 认字"转向"视觉语言模型（VLM）理解并重构整页"。腾讯微信视觉团队（WeChat Vision）近期开源的WeVisDoc ，把这条路线推到了一个很有代表性的位置：不外挂任何 OCR 引擎、文档检测器、表格解析器或专用解码器，一个视觉语言模型看一眼页面图像，就直接生成保留阅读顺序的结构化 Markdown------ 公式是 LaTeX ，表格是 HTML。
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 本文看点 * 为什么传统 OCR 流水线在真实文档上总是"差一口气"，端到端方案到底省掉了什么 * WeVisDoc 的两阶段数据驱动框架（Coverage → Capability）到底做对了什么 * OmniDocBench v1.6、PureDocBench 上的成绩、子指标与竞品横向对比 * 可直接照做的 vLLM 服务化与 Transformers 本地部署、验收方法 * 它的能力边界在哪里，以及怎么判断它适不适合你的业务 |
01 文档数字化做了几十年，真正难的从来不是 " 认字 "
要理解 WeVisDoc 的价值，得先把"文档解析"这件事的难度看清楚。很多人以为 OCR 已经很成熟了------毕竟手机扫描 App 满地都是，识别印刷体准确率动辄 99%。但"把单个字符认对"和"把一整页正确地还原成结构化文档"，是两个完全不同量级的问题。
1.1 OCR 解决的是 " 点 " ，文档解析要还原的是 " 面 "
传统 OCR 的核心任务是文字识别：输入一块文字区域，输出对应的字符。它天然不关心、也不擅长回答这些问题：
•这一行属于哪个栏目？左右两栏的内容应该怎么穿插？
•这几行是标题、正文、脚注还是图注？层级关系是什么？
•这片内容是一张表格吗？哪些是表头，哪些单元格被合并了？
•这串符号是一个数学公式吗？分式、上下标、根号的嵌套关系如何？
•读者正确的阅读顺序是什么？侧栏、浮动元素、页眉页脚该插在哪？
而这些，恰恰是"把文档变回文档"的关键。一份合同里，一个数字属于"金额"还是"日期"，取决于它在表格里的位置；一篇论文里，公式乱了一个符号，含义可能完全改变。识别只解决了 " 写了什么字 " ，解析要解决的是 " 这些字以什么结构组织在一起 " 。
1.2 传统流水线：用一堆专家模块，拼出一条脆弱的链路
为了补上结构，工业界长期采用"流水线 + 专家模块"的方案。一条典型的文档解析流水线通常包含这些环节：
1.文档检测 / 矫正：先找到页面边界，做去倾斜、去弯曲；
2.版面分析：用一个模型把页面切成文本块、图片、表格、标题等区域；
3.文字识别（ OCR ）：对每个文本区域单独跑识别；
4.表格识别：对表格区域用专门的表格结构识别模型；
5.公式识别：对公式区域用专门的公式识别模型，转成 LaTeX；
6.阅读顺序排序：再用规则或模型把各区域按阅读顺序拼起来。
这条链路的问题，在于它是串联的、割裂的。
具体来说，这种串联结构有三个难以回避的结构性问题。
**第一，误差逐级累积，且无法回头修正。**流水线是"一错全错"的：如果版面分析把表格误判成了普通文本，后面的表格识别模块根本不会被触发；如果阅读顺序排错了，OCR识别得再准，拼出来的文档也是乱的。上游一个小小的切分错误，会被下游逐级放大，而且没有任何一个环节能"看到全局"并纠正它。
**第二，模块各自为政，无法做联合优化。**每个专家模块往往用不同的数据集、不同的训练目标、甚至不同团队开发。检测器不知道识别器需要什么样的输入，识别器也不知道最终要还原的是版面结构。它们优化的是各自的局部指标，而不是"最终还原的文档对不对"这个真正重要的全局目标。
**第三，工程复杂、维护昂贵。**一条流水线要同时部署和维护五六个模型，依赖、版本、算力、延迟层层叠加。任何一个模块升级，都要对整条链路做回归测试；想换一个更强的OCR，往往牵一发动全身。真实项目里，大量人力不是花在算法上，而是耗在模块之间的衔接、兜底规则和异常处理上。
1.3 端到端的思路：让一个模型，直接学会 " 从页面到文档 "
端到端方案的想法很直接：既然最终要的是结构化文档，那就让一个模型直接学习 " 页面图像 → 结构化文档 " 的映射，中间不再人工切分出一堆模块。
这带来三个层面的改变：
•统一目标、联合优化：视觉编码和语言生成在同一个模型、同一个目标下端到端训练，阅读顺序、表格结构、公式符号在同一次生成里协同产出，天然保证全局一致性；
•没有误差累积：不存在"上游切错、下游陪葬"，模型一次性看到整页、一次性给出整页结果；
•工程极简：对外就是一个模型、一次推理，部署、扩容、升级、监控都围绕一个服务展开。
一条连贯通道，对比一堆断裂模块------端到端与流水线最直观的差别。
当然，端到端绝不等于"把流水线删掉、让大模型硬猜"。把整条链路的责任压到一个模型身上，意味着它必须同时具备极强的视觉识别、版面理解、结构化生成和抗退化能力，这对模型能力 和训练数据的覆盖面都提出了高得多的要求。WeVisDoc 给出的答案，是一个纯视觉语言模型，加上一套精心设计的两阶段数据驱动训练框架------这也是整篇论文最值得讲的部分。
02 WeVisDoc 是什么：一个不外挂任何专家模块的端到端 VLM
2.1 用三句话把它说清楚
**一句人话：**WeVisDoc 是腾讯微信视觉团队开源的端到端文档解析模型，给它一张页面图像，它直接输出还原了版面结构的Markdown 文档，其中公式是LaTeX、表格是HTML、阅读顺序正确。
一句排除： 它不是一个新的 OCR 引擎，也不是"OCR + 一堆后处理规则"的组合。它不引入任何外部文档检测器、 OCR 引擎、表格解析器或专用解码器，本质上就是一个视觉语言模型（VLM），文档解析能力完全通过训练"长"在模型里。
**一句关系：**它由通义千问的 Qwen3-VL-Instruct（2B / 4B 两个尺寸）微调而来，保留了基座模型的动态分辨率视觉编码器、自回归语言模型、tokenizer 和位置编码，只通过数据和训练把它"教会"做文档解析。这意味着它和主流 VLM 生态完全兼容，能用现成的 vLLM、Transformers 工具链直接部署。
2.2 基本档案
|------|-----------------------------------------------------|
| 项目 | 说明 |
| 模型名称 | WeVisDoc（WeChat Vision Document Parser） |
| 开源团队 | 腾讯微信视觉团队（WeChat Vision, Tencent） |
| 提供版本 | WeVisDoc-2B、WeVisDoc-4B 两个尺寸 |
| 基座模型 | Qwen3-VL-2B-Instruct / Qwen3-VL-4B-Instruct |
| 输入 | PNG / JPEG / WebP 页面图像；PDF 需先渲染为页面图像 |
| 输出 | 保留阅读顺序的 Markdown；公式为 LaTeX；表格为 HTML |
| 外部依赖 | 无外部 OCR / 检测器 / 表格解析器 / 专用解码器，纯 VLM 端到端 |
| 推理方式 | Transformers 本地推理，或 vLLM 提供 OpenAI 兼容 API 服务 |
| 开放资源 | 论文（arXiv:2609.20423）、GitHub、项目主页、HuggingFace 权重均已开放 |
2.3 输出表示：为什么选 Markdown + LaTeX + HTML
端到端模型的一个关键设计，是"用什么格式承载输出"。WeVisDoc 选择了三种工程师都很熟悉、且机器可处理的标准表示：
•正文与版面 → Markdown：用标题层级、列表、引用、分段来表达正文结构和阅读顺序，天然适合大语言模型生成，也方便直接入库、检索或再渲染；
•数学公式 → LaTeX：行内公式用\( 与\) 包裹，独立成行的块级公式用\ 与\\ 包裹，完整保留分式、上下标、根号、矩阵等结构；
•表格 → HTML：用table、tr、td 等标签表达行列与合并关系，结构清晰、可被程序直接解析，也便于在网页端还原。
论文附录给出的官方解析 system prompt 还明确约束了行为边界：页面中的图片直接忽略、不做描述；严格按页面内容输出，保持结构与换行，不额外添加解释性文字。这种"克制"很重要------它让模型专注于"忠实还原页面"，而不是自由发挥，从而显著降低了幻觉风险，输出结果可直接用于严肃的业务场景。
2.4 选 2B 还是 4B
两个版本能力接近、用法完全一致，区别主要在精度、显存与成本。下表给出一个可直接参考的选型建议（具体显存与吞吐请以实际部署环境为准）：
|----------------------|------------------------|-------------------------|
| 维度 | WeVisDoc-2B | WeVisDoc-4B |
| 定位 | 轻量、低成本、易规模化 | 精度优先、复杂页面更稳 |
| OmniDocBench Overall | 95.06 | 95.38 |
| PureDocBench 三轨均值 | 73.86 | 75.54 |
| 适合场景 | 高并发批量解析、边缘/成本敏感、版式相对规整 | 复杂表格/公式密集、真实拍摄退化页、精度要求高 |
| 典型建议 | 先用 2B 跑通业务、压测成本 | 对 2B 不达标页面再用 4B 兜底 |
一个实用策略是"2B 打底、4B 兜底"：绝大多数规整页面用 2B 高并发处理，只有识别置信度低、表格公式特别复杂或真实拍摄退化严重的页面，才路由到 4B，从而在成本和精度之间取得平衡。
03 核心机制：两阶段数据驱动框架（ Coverage → Capability ）
WeVisDoc 真正的技术含量，不在"用了哪个模型"，而在它如何训练。论文标题里有两个关键词------Coverage（覆盖）和 Capability（能力），对应一套两阶段的数据驱动框架。要讲清它，得先回答一个问题：为什么"把数据规模做大"还不够。
3.1 为什么无脑堆数据，会遇到天花板
一种朴素的想法是：端到端模型能力不够，那就喂更多数据。但在文档解析这个任务上，单纯堆量会遇到两个问题。
**其一，真实数据天然长尾、且存在系统性盲区。**规整的单栏报告随处可见，但嵌套多层的复杂表格、密集的数学公式、弯曲褶皱的翻拍页、带摩尔纹的屏幕拍摄，在自然数据里占比极低。哪怕总量上亿，这些困难类型依然稀缺，模型很难学充分。
其二，平均用力意味着资源错配。 对模型已经掌握得很好的简单页面，喂再多也只是重复；真正薄弱的环节，却因为占比小而得不到足够训练。你需要先知道模型 " 到底在哪些页面上不会 " ，再把数据和算力精准投到这些短板上------这正是从 Coverage 走向 Capability 的核心逻辑。
3.2 两阶段框架总览
|--------------------------|--------------------------|-----------------------------------------|----------------------------|
| 阶段 | 目标 | 主要手段 | 训练范围 |
| Stage I Coverage 覆盖扩展 | 让模型"见多识广"，铺开语义、结构、外观的覆盖面 | 异构真实数据 + 结构保持的程序化退化合成 | 视觉编码器 ViT + 语言模型 LLM 全参数训练 |
| Stage II Capability 能力精炼 | "精准补短板"，针对残差最高的页面类型定向强化 | held-out 探针测簇残差、困难样本挖掘、定向合成、token 预算再分配 | 冻结 ViT，只精炼 LLM |
3.3 Stage I ：用 " 结构保持的退化合成 " 把覆盖面铺开
Stage I 的目标是覆盖。它的数据由两部分构成：大量异构的真实文档，加上一套可程序化控制的合成管线。后者是关键，因为真实数据无法覆盖的版式和退化，可以用合成精确、可控、且标签天然正确地补齐。
（ 1 **）结构与版式覆盖。**程序化生成或增强单栏、多栏、变栏、侧栏、浮动元素、脚注、表单、海报、演示稿、手写等各种版式，以及嵌套表格、密集公式等困难结构，让模型学会应对不同的版面组织方式。
（ 2 **）外观退化覆盖。**论文把真实世界里文档"变脏、变糊、变歪"的过程，归纳为四类代表性变换：
|--------------------|------------------------|
| 类别 | 模拟的真实情况 |
| (a) 色调 / 纹理 / 信号噪声 | 纸张泛黄、纹理、复印与传输过程中引入的噪声 |
| (b) 扫描条带 / 信号丢失 | 扫描仪条带、局部信号缺失、内容被部分遮挡 |
| (c) 透视 / 手持拍摄 | 手机手持翻拍带来的透视畸变、角度倾斜 |
| (d) 页面弯曲 / 不均光照 | 装订处书页弯曲、褶皱，以及不均匀的光照与阴影 |
这些退化不是随意叠加的，而是按真实采集路径成组出现------纸张、复印、传输是一条路径，物理采集是一条路径，屏幕翻拍（含摩尔纹）又是一条路径，从而让合成数据更贴近真实分布。
|------------------------------------------------------------------------------------------------------------------------------------------------------|
| 这里有一个很能体现方法论严谨度的约束：所有退化合成必须保证监督内容依然可见、可读。如果一次退化让某些内容彻底看不清，这个样本会被直接丢弃，或者改用"仅针对可见内容裁剪"的训练目标。道理很朴素------你不能要求模型去识别连人都看不清的内容，否则只会逼着它"猜"，反而污染训练、助长幻觉。 |
在这一阶段，模型从 Qwen3-VL-Instruct 初始化，视觉编码器和语言模型一起做全参数训练，目标是先得到一个覆盖面足够广、"什么页面都见过"的基础解析器。但"见过"不等于"精通"，真正把困难页面成绩拉起来的，是 Stage II。
3.4 Stage II ：先 " 诊断 " 残差，再 " 定向 " 开药
Stage II 的思路可以概括为一句话：不要平均地训练，要先测出模型在哪一类页面上最弱，再针对性地补。它由环环相扣的几步组成。
第一步，把页面分成 " 视觉 - 结构簇 " 。 要定位短板，先得给页面分门别类。论文用一个冻结的 SigLIP2 编码器 对页面提取单位长度的视觉 embedding，经 PCA 降维后，再拼上一组归一化的结构元数据------包括内容成分构成、信息密度、语言、版式、采集条件、目标输出长度等，最后聚类成若干"视觉-结构簇"。每个簇代表一类"长得像、结构也像"的页面。簇中心确定后即冻结，后续新样本按就近原则分配，保证分类标准稳定一致。
第二步，用留出探针测每个簇的残差。 论文专门设置了一个既不参与训练、也不参与最终评测的 held-out allocation probe （留出分配探针） ，用它在每个簇上测量Stage I 解析器的残差，也就是解析错误的严重程度。考虑到小簇样本少、直接估计不稳定，论文对簇残差采用了收缩估计（ shrinkage ）：把每个簇的经验残差向全局加权均值收缩，样本越少的簇越依赖全局先验。这是一个很标准也很稳健的统计处理，能避免被个别小簇的偶然误差带偏。
|--------------------------------------------------------------------------------------------------------------|
| 收缩估计的直觉很简单：如果一个簇只有寥寥几张页面，测出的残差可能只是偶然，不该全信；这时就往"所有页面的平均水平"上靠一靠。簇越大、证据越充分，越相信它自己的测量值；簇越小，越参考全局。这样得到的"短板地图"更可靠。 |
第三步，困难样本挖掘，并核验目标可靠性。 从残差高的薄弱簇中挖掘困难样本重点学习，但在使用前必须先核验标注（ground-truth）本身是否可靠，主动排除标注错误、以及内容本身就不可读的样本。这一步是为了避免把脏数据误当成"困难样本"去学，否则越练越偏。
第四步，定向程序化合成，并回放旧样本。 针对薄弱簇，定向合成对应的困难页面------复杂公式、嵌套表格、跨元素关系、密集版式等，精确补齐短板；同时回放（ replay ）一部分高质量的 Stage I 样本，防止模型"学了新本领、忘了旧能力"，缓解灾难性遗忘。
第五步，按残差重新分配 token **预算。**训练时根据各簇残差，重新分配目标 token 预算，把更多的学习与生成预算投向残差高的薄弱类型，真正实现"哪里不会，就重点练哪里"。
一个关键设计是： Stage II 冻结视觉编码器 ViT ，只精炼语言模型 LM **。**原因在于，经过 Stage I，模型"看清页面"的视觉能力已比较充分，Stage II 的主要矛盾是结构化生成与版面推理，集中在语言模型侧。冻结 ViT 既能把训练资源集中在真正的短板上，又能降低成本、稳定已学到的视觉表征、减少过拟合。
左侧铺开的是"覆盖"，右侧一束光精准修补薄弱点------先诊断、再强化的 Capability 阶段。
3.5 训练配置一览
论文公开了完整的训练超参，整理如下，便于复现与参考：
|------------|-----------------------------------------------------------------|-------------------------|
| 配置项 | Stage I | Stage II |
| 初始化 | Qwen3-VL-Instruct（对应尺寸） | 同尺寸的 Stage I checkpoint |
| 可训练部分 | ViT + LLM | 仅 LLM（ViT 冻结） |
| 优化器 | Fused AdamW（β1=0.9，β2=0.95，ε=1e-8） | 同左 |
| 学习率 | 5e-6，cosine 衰减，500 步 warmup | 同左 |
| 正则 | weight decay 0.1，梯度裁剪 1.0 | 同左 |
| 批大小 / 序列长度 | global batch 512 / seq len 8192 | 同左 |
| 精度与并行 | bfloat16，gradient checkpointing，FlashAttention，DeepSpeed ZeRO-2 | 同左 |
04 成绩说话： OmniDocBench 与 PureDocBench 上的表现
方法讲得再漂亮，最终要看数据。WeVisDoc 在两个主流文档解析基准上做了评测：侧重文档多样性的OmniDocBench v1.6 ，和侧重成对退化鲁棒性的PureDocBench。先把评测指标的含义讲清楚，再看分数。
4.1 评测指标都是什么意思
|-------------------------|-------------------------|--------|
| 指标 | 衡量内容 | 方向 |
| TextEdit | 文本编辑距离，衡量正文识别与还原的错误 | 越低越好 ↓ |
| FormulaCDM | 数学公式的识别与结构还原准确度 | 越高越好 ↑ |
| TableTEDS / TableTEDS_S | 表格结构（含单元格内容）的还原准确度 | 越高越好 ↑ |
| ROEdit | 阅读顺序（Reading Order）编辑距离 | 越低越好 ↓ |
| Overall | 综合上述子指标的总分 | 越高越好 ↑ |
PureDocBench 则把同一份文档分成三种采集条件分别评测：Clean （干净数字版）、 Digital Degraded （数字噪声退化）、 Real Degraded （真实拍摄退化），并用 Avg₃ 表示三轨 Overall 的均值。这种"成对"设计能专门检验模型在脏、糊、歪的真实条件下还稳不稳。
4.2 OmniDocBench v1.6 ：两个版本的子指标成绩
|-----------------|-----------|------------|--------------|-------------|---------------|----------|
| 模型 | Overall ↑ | TextEdit ↓ | FormulaCDM ↑ | TableTEDS ↑ | TableTEDS_S ↑ | ROEdit ↓ |
| WeVisDoc-4B | 95.38 | 0.036 | 96.81 | 92.95 | 95.34 | 0.125 |
| WeVisDoc-2B | 95.06 | 0.038 | 95.94 | 93.03 | 95.26 | 0.130 |
和主流方案横向对比 Overall（数据取自官方评测表，各模型参数量标注于括号内）：
|-------------------------|------------------------|
| 模型 | OmniDocBench Overall ↑ |
| WeVisDoc-4B | 95.38 |
| WeVisDoc-2B | 95.06 |
| Unlimited-OCR（3B-A0.5B） | 93.92 |
| Qianfan-OCR（4B） | 93.90 |
| FD-RL（4B） | 91.21 |
| DeepSeek-OCR 2（3B） | 90.25 |
| UniRec-0.1B | 88.91 |
| DeepSeek-OCR（3B） | 86.31 |
| olmOCR（7B） | 85.74 |
| olmOCR-2-7B | 85.51 |
| OCRFlux-3B | 83.31 |
| Nanonets-OCR2（3B） | 83.20 |
**所以呢？**WeVisDoc 两个版本的 Overall 都超过了表中所有竞品，包括参数量更大的 7B 方案；而 2B 仅用约一半的参数量，就把分数做到了和 4B 几乎同级（差距仅 0.32）。这说明它的优势不只是"模型更大"，更多来自训练框架带来的数据效率。
4.3 PureDocBench ：真实退化条件下的鲁棒性
|-----------------|-----------|---------|--------------------|-----------------|
| 模型 | Avg₃ ↑ | Clean ↑ | Digital Degraded ↑ | Real Degraded ↑ |
| WeVisDoc-4B | 75.54 | 79.81 | 77.74 | 69.08 |
| WeVisDoc-2B | 73.86 | 79.36 | 76.62 | 65.60 |
| FD-RL | 73.92 | --- | --- | --- |
| dots.mocr | 70.39 | --- | --- | --- |
| OCRVerse（4B） | 69.40 | --- | --- | --- |
| FireRed-OCR（2B） | 65.57 | --- | --- | --- |
| Nanonets-OCR-s | 65.37 | --- | --- | --- |
| dots.ocr | 64.55 | --- | --- | --- |
| Unlimited-OCR | 62.76 | --- | --- | --- |
| Nanonets-OCR2 | 58.36 | --- | --- | --- |
| olmOCR-7B | 55.90 | --- | --- | --- |
| Qianfan-OCR | 51.04 | --- | --- | --- |
按官方报告，WeVisDoc-4B 在全部 4 个评测设置的端到端解析器中均排名第一。值得注意的是纵向规律：无论哪个模型，Real Degraded（真实拍摄）的分数都明显低于 Clean，这是整个行业的共性难点；而 WeVisDoc 4B 把真实拍摄轨拉到了 69.08，相对竞品优势最明显。
4.4 Stage II 到底带来了多少增益
为了验证"能力精炼"阶段的作用，论文对比了 Stage I 与 Stage II 的分数变化：
|----|------------------|---------|----------|-------|
| 版本 | 设置 | Stage I | Stage II | 增益 |
| 2B | OmniDocBench | 93.50 | 95.06 | +1.56 |
| 2B | Clean | 78.90 | 79.36 | +0.46 |
| 2B | Digital Degraded | 74.24 | 76.62 | +2.38 |
| 2B | Real Degraded | 63.23 | 65.60 | +2.37 |
| 2B | Avg₃ | 72.12 | 73.86 | +1.74 |
| 4B | OmniDocBench | 94.22 | 95.38 | +1.16 |
| 4B | Clean | 79.32 | 79.81 | +0.49 |
| 4B | Digital Degraded | 75.19 | 77.74 | +2.55 |
| 4B | Real Degraded | 65.05 | 69.08 | +4.03 |
| 4B | Avg₃ | 73.19 | 75.54 | +2.35 |
这张表很能说明问题：退化轨（ Digital / Real ）的增益，明显大于干净轨（ Clean ）的增益。4B 的真实拍摄轨一举提升 4.03，而干净轨只提升 0.49。这印证了 Stage II 的设计意图------它不是在模型已经很好的地方锦上添花，而是通过残差诊断，把提升精准地投到了"脏、糊、歪"这些真正薄弱、也最有业务价值的环节上。
4.5 该怎么正确看待这些数字
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 几点必要的口径说明：上述基准分数均为论文作者自报 ，通常为多次（约三次）推理取平均，并非第三方独立机构复现；不同模型在评测时的输入分辨率、推理设置可能存在差异；基准本身的文档覆盖面、以及合成退化对真实世界的保真度，也构成了成绩的边界。因此，这些分数能说明 WeVisDoc 在标准测试集上处于第一梯队，但不能替代你在自己真实文档上的实测。 |
05 部署实战：从安装到推理，可直接照做
WeVisDoc 提供了两条推理路径：用 vLLM 起一个 OpenAI 兼容的在线服务（推荐用于生产和批量处理） ，或者用 Transformers 做本地单页推理（适合快速试用和调试）。下面按官方流程走一遍。
5.1 环境准备
基础要求：Python 3.10 及以上；服务化部署需要 vLLM ≥ 0.11.1。仓库按用途拆分了依赖文件，按需安装即可：
|------------------------|-------------------|
| 依赖文件 | 用途 |
| requirements-vllm.txt | 部署 vLLM 推理服务 |
| requirements-local.txt | Transformers 本地推理 |
| requirements.txt | 仅安装客户端调用环境 |
|---------------------------------------------------------------------------------------------------------------------------------------------------------|
| 官方建议把****vLLM 环境和 Transformers 环境放在独立的虚拟环境中 ，避免版本相互冲突。首次运行会自动从 HuggingFace 拉取权重（Tencent/WeVisDoc-2B 或 Tencent/WeVisDoc-4B），也可提前手动下载到本地。 |
5.2 方式一：用 vLLM 起在线服务（推荐）
一条脚本即可启动服务，把最后的模型名换成对应版本：
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| bash启动 vLLM 服务# 启动 2B 版本 bash scripts/serve_vllm.sh Tencent/WeVisDoc-2B # 或启动 4B 版本 bash scripts/serve_vllm.sh Tencent/WeVisDoc-4B # 批量跑演示（对示例目录中的页面批量解析） bash scripts/run_demo.sh |
服务脚本通过环境变量控制部署参数，常用项及默认值如下：
|------------------------|------------------|-----------------|
| 环境变量 | 默认值 | 含义 |
| SERVED_MODEL_NAME | wevisdoc | 对外暴露的模型名称 |
| HOST / PORT | 127.0.0.1 / 8000 | 服务监听地址与端口 |
| TENSOR_PARALLEL_SIZE | 1 | 张量并行的 GPU 数 |
| MAX_MODEL_LEN | 32768 | 最大上下文长度 |
| GPU_MEMORY_UTILIZATION | 0.9 | 显存占用比例 |
| MAX_NUM_SEQS | 8 | 最大并发请求序列数 |
| VLLM_API_KEY | 可选 | 访问服务所需的 API Key |
如果要在多卡上跑更大上下文，可在启动前调整，例如用两张卡、把上下文扩到 65536：
|------------------------------------------------------------------------------------------------------------------------|
| bash双卡 + 大上下文示例export TENSOR_PARALLEL_SIZE=2 export MAX_MODEL_LEN=65536 bash scripts/serve_vllm.sh Tencent/WeVisDoc-4B |
5.3 用客户端调用服务
服务启动后，用内置客户端解析单张图片，或批量处理整个目录：
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| bash客户端调用# 解析单张页面 python -m wevisdoc.client --image page.png --output results/page.md # 批量解析一个目录 python -m wevisdoc.client \ --image-dir ./images \ --result-dir ./results \ --workers 8 \ --overwrite |
客户端通过环境变量找到服务：读取OPENAI_BASE_URL （默认 http://127.0.0.1:8000/v1）、**OPENAI_API_KEY** （默认 EMPTY）、SERVED_MODEL_NAME 。请求参数上，默认temperature 取 0 （确定性输出）、 max-tokens 8192 、超时 600 秒。由于接口是标准 OpenAI 兼容格式，你也完全可以用任意语言的 OpenAI SDK 直接对接，方便集成进现有系统。
一个稳定的推理服务，向多个客户端分发结果------这正是 vLLM 服务化后的形态。
5.4 方式二： Transformers 本地推理
不想起服务、只想快速试几张图，可以直接本地推理：
|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| bash本地推理python -m wevisdoc.local \ --model Tencent/WeVisDoc-2B \ --image page.png \ --output results/page.md \ --device-map auto \ --max-tokens 8192 |
其中 --device-map auto 会让模型自动按可用显存分布到各设备，适合在单卡显存紧张时使用。
5.5 落地时容易忽略的几个细节
•PDF 必须先渲染成页面图像：WeVisDoc 的输入是图像，不是 PDF。需先用 PyMuPDF、pdf2image 等把每页渲染为 PNG/JPEG，建议用较高 DPI（如 200--300 DPI），保证小字、公式清晰；
•注意上下文长度：模型采用动态分辨率，页面越大、内容越密，视觉 token 越多。超长页面要关注 MAX_MODEL_LEN（默认 32768），必要时调大上下文或对页面做合理拆分；
•用确定性设置：正式解析把 temperature 设为 0，保证结果稳定可复现；max-tokens 要给足（默认 8192），避免长页面输出被截断；
•建立性能基线：批量上线前记录每页的渲染 DPI、像素尺寸、峰值显存、首 token 延迟（TTFT）和整页耗时，作为容量规划和成本核算的依据。
06 怎么判断它适不适合你，以及几个常见误区
6.1 上线前，用一套可操作的方法做验收
公开榜单只能说明第一梯队，真正决定能不能用的，是在你自己文档上的表现。建议在正式上线前，按文档类型构建一个小型但有代表性的测试集，至少覆盖五类页面：
1.干净的数字版报告（检验基础还原）；
2.扫描表单（检验框线、填写内容、手写）；
3.财务/数据表格（检验嵌套表、合并单元格、数字）；
4.科学公式页（检验 LaTeX 与复杂公式）；
5.混合语言、多栏或真实拍摄页（检验鲁棒性与阅读顺序）。
对每一类分别统计准确率，并同步记录渲染 DPI、像素尺寸、峰值显存、TTFT 和整页延迟。更重要的是给错误分级，因为不同错误的业务后果完全不同：
|--------------------------|-------------------|---------------|
| 错误等级 | 含义 | 处理建议 |
| Cosmetic 外观级 | 排版、空格、换行等小瑕疵，内容无误 | 可接受，规则轻修 |
| Searchable 检索级 | 影响关键词检索、标签或分类 | 需修正，影响入库质量 |
| Calculation-changing 计算级 | 数字、公式错误，会改变计算结果 | 必须校验拦截 |
| Legally material 法律级 | 合同条款、金额、权责等关键信息错误 | 强制人工复核，不可直接采信 |
6.2 别混淆 " 解析 " 和 " 检索 " ： WeVisDoc 与 EVIE 的分工
文档智能化通常包含两个不同环节，容易被混为一谈。WeVisDoc 负责的是 " 解析 / 页面重构 " ------把某一页图像变成结构化内容；而微信团队同体系的EVIE 负责的是 " 视觉文档检索 "------从海量文档图像中定位到你要找的那一页。
在真实生产链路里，二者往往是"先检索、后解析"的配合：先用 EVIE 从几万、几十万页里找到目标页面，再用 WeVisDoc 把这些页面解析成结构化数据入库。分清这两个职责，才能把系统搭对，而不是指望一个模型同时把检索和解析都做到最好。
6.3 几个常见误区，先排除掉
误区一：端到端 = **万能，不用校验。**不是。端到端解决的是流水线割裂和工程复杂度，但在真实拍摄、严重退化、极端复杂版式下，模型仍可能残留数字或字符级错误。合同、财务、公式这类严肃场景，关键内容必须有校验和人工兜底。
**误区二：合成退化能完全等价真实世界。**不能。结构保持的退化合成大幅拓宽了覆盖、提升了鲁棒性，但合成对真实物理退化的保真度总有边界。因此Stage I 的真实数据和上线前的真实样本验证都不可或缺。
误区三： 4B 一定全面优于 2B **，闭眼上大模型。**基准上两者差距很小（OmniDocBench 仅差 0.32），大量规整页面 2B 已经足够，且更省显存、更易高并发。更稳妥的做法是"2B 打底、4B 兜底"，按实测的精度与成本权衡，而不是一味追求大参数。
误区四：输出了 Markdown **就等于结果可信。**Markdown 只是承载格式，不保证内容正确。越是会影响计算、法律权责的字段，越要做针对性校验；模型"忽略图片、不自由发挥"的设计降低了幻觉，但并不等于零错误。
写在最后
回到最初的问题：怎么判断一个文档解析方案到底能不能用？与其只看公开榜单，不如盯住四件事：
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| * 在你自己真实文档上的端到端准确率 ，尤其是表格、公式和阅读顺序； * 对脏、糊、歪等退化页面的鲁棒性 ，这往往才是真实业务的常态； * 单页成本、延迟与可扩展性 ，决定了能不能大规模铺开； * 出错时是否可校验、可分级、可兜底 ，决定了它能不能进核心业务。 |
WeVisDoc 的意义，在于用一个开源、轻量、与主流 VLM 生态完全兼容的端到端模型，把"自建一整条文档解析流水线"的门槛和成本大幅降低。它用"先铺开覆盖、再诊断残差、最后定向精炼"的两阶段方法，证明了数据工程和训练范式的改进，往往比单纯堆参数更能带来效率。