跳至正文
-
关注
IT极限技术分享汇

ITmax

IT极限技术分享汇

ITmax

  • 首页
  • 商店
  • 我的帐户
  • 结账
  • 购物车
  • 首页
  • 商店
  • 我的帐户
  • 结账
  • 购物车
关

搜索

Surya 文档 OCR 项目封面:689M 文档 VLM,版面、表格、阅读顺序一把抓
技术分享

多栏扫描件读出来是乱序|Surya 一个 689M 模型连版面带表格一起端走,我在 M2 上真跑了一遍

mumupudding 的头像
作者 mumupudding
2026年11月18日 3 分钟阅读
0
Surya 文档 OCR 项目封面:689M 文档 VLM,版面、表格、阅读顺序一把抓
Surya:689M 文档 VLM,一个模型管版面、表格和阅读顺序(GitHub 21,603 star,v0.24.0)

上个月帮同事救一场火。他们要把三年积累的纸质合同扫描件灌进检索库,第一版流水线用的是经典两段式:检测模型框出文字行,识别模型逐行转文字。单栏文件没毛病,一碰到盖章旁的备注栏、表格、页脚就露馅——识别出来是一列列孤立文字,顺序完全是按坐标从上往下排的,两栏并排的内容被读成了”上一句、下一句、再上一句”。灌进检索库之后,召回出来的片段前言不搭后语,业务方看了一眼就打回来了。

我当时给的权宜之计是写规则:按 x 坐标分栏,栏内按 y 排序,栏间再串起来。写了一下午,规则越堆越多,边界情况越修越崩。表头跨栏、脚注穿插正文、表格里嵌套文字,每一条都在打这套规则的脸。真正让我下决心换思路的,是后来翻到 Surya 的输出样例——阅读顺序不靠规则拼,是模型直接预测的,一个 689M 参数的 VLM 同时把版面分类、文字识别、表格转 HTML、数学公式转 LaTeX 全包了。这就是我这次要说的主角,datalab-to/surya,Apache-2.0 的代码,十月底刚发了 0.24.0。

一个 689M 的小模型,把三件麻烦事干成了一件

先说它到底是什么。Surya 2.5 是一个 689M 参数的文档 VLM,官方给的两个公开基准分数:OmniParseBench 85.9,官方声明是 1B 参数以下开源模型里最高;olmOCR-bench 83.7%。数字是官方自己跑的,我照录,后面会提独立榜单的情况。

能力分三块说。

第一块是全页 OCR。一页图进去,出来的是带标签的结构块:SectionHeader、Text、Table、Picture、Form 这些标签,每块带四角坐标、置信度、阅读顺序,内容直接是 HTML。数学公式不用单独跑一遍,行内和独立公式都包在 <math> 标签里,KaTeX 能直接渲染。

第二块是表格。merged cell 用 colspan/rowspan 表达,出来就是标准的 <table> HTML,直接能进前端或者转 markdown。我实测那部分细节放到后面。

第三块是版面和阅读顺序,就是开头那个救火场景的解药。多栏报纸、论文、页眉页脚穿插,模型按人类的阅读逻辑输出 reading_order,不用再自己写分栏规则。

命令行有四个入口:surya_ocr、surya_layout、surya_table,外加一个 surya_gui 起本地网页查看器,拖个 PDF 进去能逐页看检测框和阅读顺序,数学公式直接用 KaTeX 渲染出来,HTML 表格也带样式,做质检的时候不用再自己写可视化。0.24.0 还加了个很务实的功能:--stdout 直接把 JSON 吐到标准输出,--install_skill 能把自带的 SKILL.md 装进 .agents/skills/ 目录——明显是给自动化流水线和各类编程助手的调用口准备的。

输出的结构块也值得多说一句。每块除了轴对齐的 bbox,还给了 polygon 四角坐标——遇到扫描歪斜的页面,检测框是斜的,轴对齐框会裹进大半个页面,四角多边形才是真实形状,做裁剪时要用后者。confidence 是块内所有 token 解码概率的均值,0 到 1,低置信的块可以直接路由给人审。layout 模式还带一个 count 字段,是模型自己估的”这块 OCR 要写多少 token”,用 50 取整——这个数字直接喂给逐块解码的预算控制,属于把工程细节做进了输出里。

哪些是真能用、哪些还差口气,我的判断是:全页 OCR、版面、表格三条主路是扎实的,GUI 够用。MLX 后端官方自己标了 experimental,我不建议上生产。skip_labels=[] 这个参数是 11 月 13 日随 0.24.0 修的 issue #544——之前 Figure 和 Diagram 区域里的文字默认直接跳过不识别,现在可以显式打开,说明图内文字这个场景刚补上,稳定性还得观察。

去掉 torch 这步棋,代价是什么

0.24.0 最有意思的改动是把 PyTorch 从依赖里彻底踢掉了。装完 pip install surya-ocr 之后我特意数了一遍:36 个包,没有 torch,没有 torchvision,没有 transformers,连 opencv 都没有。整个 surya-ocr 包退化成一个客户端加编排器,推理交给三类后端:N 卡上走 vllm(自动拉 Docker 或 Podman 容器),CPU 和 Apple Silicon 走 llama.cpp 的 llama-server,Mac 还可以选 MLX(实验性)。第一次调用时自动帮你把后端拉起来。

这个设计的账我是这么算的。

收益很实在:客户端装得飞快,版本升级不用重新下载几百 MB 的 torch;同一个 689M 模型可以 attach 到任何 OpenAI 兼容的服务上,SURYA_INFERENCE_URL 一指就行,多台机器共享一个 vllm 实例是自然支持的事;对 llama.cpp 生态等于白捡了 Apple Silicon 和纯 CPU 的覆盖面。顺带一提,模型本身的 GGUF 和 MLX 转换脚本也在仓库里(surya-ocr[build]),官方甚至自己修了两个转换器都会踩的坑:字符级词表的 pre-tokenizer hash 注册、<|im_end|> 的 token 改名。愿意折腾的人可以把任何 checkpoint 转成 GGUF 自己起服务,不被官方发的权重绑死。

代价也很明确:你必须有一个推理后端。服务器上要么有 N 卡加 Docker,要么装 llama-server。没有容器运行时、只读文件系统的 serverless 环境,这条路直接堵死,官方文档留的 SURYA_INFERENCE_URL 就是在承认这一点。另外这带来一个容易被忽略的部署事实——以前跑 OCR 是个进程内函数调用,现在变成了一个常驻服务,--keep_server 的存在就是官方在提醒你:每条命令都重新拉起服务是要付启动成本的。

还有一层代价在许可上,很多人只看仓库徽章就错过了:代码是 Apache-2.0,但模型权重是修改版 OpenRAIL-M,免费范围是研究、个人用途和融资或营收低于 500 万美元的初创公司。公司过了这条线就得找 Datalab 买商业授权。要不要把它当生产依赖,这一条比性能数字更先要过目。

我的反对意见也有一条:把推理外包给后端之后,输出格式的正确性开始依赖后端实现。0.24.0 的输出里块头是特殊 token(<|Text|><|坐标|> 这种格式),llama-server 必须带 --special 才能把这些 token 返回来,vllm 的 VLLM_MAX_MODEL_LEN 也得手动保证能装下一页图加 12288 token 的输出预算。自主拼后端的人要额外读一节文档,这不是无痛的抽象。

安装这件事,我是怎么过的

我手头是一台 M2 芯片的 13 寸 MacBook Pro,走的是 llama.cpp 这条路,全程没有 GPU 服务器。

第一步,装客户端:

python3 -m venv .venv && source .venv/bin/activate
pip install surya-ocr

第二步,装后端,macOS 上官方给的路径就是 brew:

brew install llama.cpp

第三步什么都不用做。直接跑命令,Surya 检测到没有 vllm 会自动切 llama-server,从 Hugging Face 拉 datalab-to/surya-ocr-2.5-gguf,主模型加视觉投影一共 1.3GB。我这边走了镜像站,下载用了五分二十秒,存到 ~/.cache/huggingface/ 下。

硬件门槛官方没有给整机配置表,这点我直说。下面两档是我的实测加推算,不是官方数字:

档位 配置 依据
最低可用 16GB 内存的 Apple Silicon 或任意 x86 CPU,磁盘预留 2GB 模型 1.3GB;llama.cpp bf16 峰值内存官方 M4 Max 数据是 4,764MB,Q8 量化后 4,278MB
建议配置 12GB 以上显存的 N 卡,Docker 加 NVIDIA Container Toolkit,走 vllm 官方吞吐数据全部基于 H100;689M 权重 fp16 约 1.4GB,但 vllm 的 KV cache 预留不小,第三方有 T4 16GB 在高分辨率大图上爆显存的反馈

CPU 路径能不能干活?能,但别指望速度,后面有数字。

还有一个使用技巧藏在设置里:每条命令默认拉起又杀掉服务,连着跑好几条就要反复付启动成本。--keep_server 让第一条命令把服务留在后台,后面的命令自动 attach。我测了一把:冷启动加单页推理 13.9 秒,热服务上第二页只要 9.0 秒。批量场景里这差不多是白捡的三分之一提速,代价是你得记得自己收尾——docker stop 掉 surya-vllm-* 容器,或者 kill 掉 llama-server 进程,不然它就一直挂着吃内存。SURYA_INFERENCE_KEEP_ALIVE=1 可以把 keep-alive 设成默认。

一页混排文档,24 秒出了结构化 HTML

为了模拟同事那批扫描件的真实成分,我用 PIL 造了一张 A4 尺寸的测试页:中文大标题、元信息行、一段中文正文、一张 4 列 3 行的表格(表头是中文,内容里混英文 staging、H100 x4)、再一段正文、一个英文小节标题加一段英文列表。中英混排、段落表格穿插,故意往复杂了做。

surya_ocr test-page.png --stdout > result.json

第一次跑的耗时结构是这样的:模型下载五分二十秒,llama-server 冷启动十秒,单页推理约二十三秒。模型进了缓存之后我又跑了一遍拿干净数字:总耗时 24.99 秒,其中服务就绪只要 2.2 秒,剩下全是推理。命令行最后会自动把拉起的 llama-server 杀掉,不留垃圾进程。

输出 JSON 里那一页被切成 7 个块,我逐个对着原图核过:

[0] SectionHeader  conf=0.98  <h1>GPU 推理服务部署手册</h1>
[1] Text           conf=0.98  <p>v3.2 修订 · 基础设施组 · 2026 年 11 月</p>
[2] Text           conf=0.98  <p>本手册描述推理集群的灰度发布流程。上线前需确认模型版本号与配置清单一致……</p>
[3] Table          conf=0.98  <table><tr><th>环境</th><th>副本数</th>……
[4] Text           conf=0.98  <p>表格之外,所有变更都必须记录在工单系统里……</p>
[5] SectionHeader  conf=0.98  <h2>Section 2: Rollback checklist</h2>
[6] ListGroup      conf=0.98  <ol><li>1. Freeze traffic to the failing shard.</li>……

中文正文一字没错,包括”灰度发布””显存占用””KV cache”这些词。表格整张转成了 <table> HTML,我抽查了合并逻辑——我这张是简单表,colspan 场景还没验证,不敢替它打包票。阅读顺序全对:表格夹在两段正文中间,位置准确;页脚没有出现在正文流里。唯一的小瑕疵是英文列表被标成 ListGroup 之后,<li> 里把原本手写的”1.” 序号又保留了一份,属于无害的冗余。

这页 24 秒意味着什么?官方基准里 M4 Max 跑 96 DPI 全页 OCR 是 0.19 页每秒,我这台 M2 单页二十来秒,同一个量级。也就是说 Apple Silicon 上它是”偶尔来几页能忍、批量灌库不行”的定位,批量请看 H100 的 4.5 页每秒(192 DPI)或者 96 DPI 下的 6.19 页每秒。输出 token 从上一代的每页 3,917 砍到 1,514,这是 0.24.0 速度提升 1.7 倍的根源,块头改紧凑格式比模型本身功劳大。

分辨率和时间是可以换的。DPI 拉高字更清楚但每页 token 变多,官方给的调法是 IMAGE_DPI_HIGHRES 从 192 降到 96 换吞吐,H100 上差距接近四成。另外还有个模式选择要想清楚:全页模式一次调用出整页,快但偶尔偷懒(后面 #551 那个坑);--block_mode 先跑 layout 再逐块 OCR,质量稳但调用次数多。粗扫用全页,精加工用块模式,我的建议就这么简单。

别人踩过的坑,我一条条对过

issue 区现在的状态很有意思:309 条 issue 只剩 2 条开着,11 月 13 日发布当天集中关了一大批。翻记录比看现状有用,这几条是真实发生过、也最可能再发生的:

  • #542,llama.cpp 后端直接报 400。bbox 的 JSON schema 里用了 \d 转义,llama-server 的 grammar 解析不认,推理一开始就挂。用 GGUF 后端的注意版本匹配,别混着用太老的 llama.cpp。
  • #547,容器端口绑到了所有网卡。自动拉起的 vllm 容器用 -p {port}:8000 发布,Docker 默认绑 0.0.0.0——一次普通的本地 OCR 调用,会把一个无鉴权的推理端点开到局域网和 VPN 网段里。这个在 0.24.0 已修(我实测 llama-server 路径绑的是 127.0.0.1),但如果你的流水线还跑在旧版上,先查防火墙再谈别的。
  • #544,图和示意图里的文字默认不识别。Figure、Picture、Diagram 区域默认当视觉块跳过,skip_labels=[] 才会去 OCR 里面的字。扫描件里”图注即正文”的文档类型要留心。
  • #551,全页模式下表格被写成一句话。模型没转表格,而是叙述了一句”这是一张表格”放进 <p>。默认单次全页调用容易出这种偷懒输出,块模式(先跑 layout 再逐块 OCR)会好很多。
  • API 破坏性变更。Surya 2.5 把输出从 text_lines 换成了 blocks,layout 输出去掉了 top_k,表格 cell 的 is_header、colspan、rowspan 字段被移走。网上大量旧教程的示例代码现在跑起来直接 KeyError,别照抄,以 README 的迁移说明为准。

第三方讨论里,一篇扫描书籍数字化的实战文章(ocrproducts.cn)提到高清扫描件上显存压力不小,A3 幅面 600DPI 的图在 T4 上批量跑容易 OOM,黑边会严重干扰版面判断,建议先裁剪;这篇还给了个很工程化的建议——单栏文档直接降级到传统 OCR,别为简单页面付 VLM 的启动成本。FAUN 上的对比文章也点了同一个问题:CPU 上 VLM 每页一跑,吞吐被传统引擎碾压,它是为复杂版面付的智商税,不是为简单文字。独立基准方面,reviewramble 提到在 BHL 的历史印刷品 OCR 榜单上 Surya 排第 12(26 个模型里),官方 olmOCR-bench 的 OldScan 分项也只有 44.3%——高度退化的老扫描件,别指望它一个人兜底。中文使用者关心的数字:91 种语言内测里中文从 66.7% 提到了 75.7%,涨了 9 个点,但离英文的 90.3% 还有距离。

公开的 Reddit/HN 长帖讨论不算多,大部分用户是经由同团队的 Marker(PDF 转 markdown)间接用上 Surya 的,单独使用的一手反馈集中在 issue 区——这也是我把坑全部落在 issue 编号上的原因。

我最后的判断

值不值得上手,我按场景切:

该上:文档类型复杂(多栏、表格、公式、页眉页脚混杂)、数据不允许出门、公司规模在许可线以内。这种场景下它一个模型顶掉”检测+识别+分栏规则+表格还原”四段流水线,维护成本断崖式下降。我同事那批合同件,现在的答案是明确的。

别上:输入是照片和街景(官方明说不做自然场景);单栏印刷体为主(PaddleOCR 的 CPU 路径更快更省);需要表格的行列几何坐标(Surya 只给 HTML 不给格线坐标,官方留着 Surya 2 干这活);重度商业使用且公司过了 500 万美元线(权重要花钱,代码免费没用)。

替代方案点名两个。PaddleOCR-VL:0.9B 参数,中文和多语种覆盖更强,榜单分数也是第一梯队,代价是被绑在 PaddlePaddle 框架上,部署栈和 PyTorch 生态是两套东西,团队已有 N 卡+vllm 基建的话 Surya 反而更顺。Docling(IBM):定位是文档转换全家桶,PDF/DOCX 到 markdown/JSON,带 LangChain/LlamaIndex 生态集成,还有一个 258M 的 Granite-Docling 端到端小模型;如果你要的是”进 RAG 管线”而不是”OCR 原件”,Docling 的集成面更宽,但版面细节的可控性不如 Surya 直出的结构块。另外同门的 Marker(PDF 转 markdown,构建在 Surya 之上)也值得知道——只关心”PDF 进 markdown 出”的话直接用 Marker,不用自己拼 Surya 的输出;要坐标、置信度、逐块控制的才落到 Surya 这一层。对比维度就一句话:要 OCR 原件和坐标,选 Surya;要中文优先和榜单顶格,选 PaddleOCR-VL;要 RAG 管线全家桶,选 Docling;要 PDF 转 markdown 的现成品,选 Marker。

一句话总结:Surya 0.24.0 把”跑个 OCR 先装 2GB torch”的历史翻篇了,21,603 个 star、11 月 13 日刚发的 v0.24.0、最近四周 13 次提交,活跃度在线,坑都写在明面上。我那 1.3GB 的模型和 36 个包,现在就在缓存里躺着,下次扫描件再闹脾气,直接 surya_ocr --stdout 接进流水线就行。

mumupudding 的头像
作者

mumupudding

关注我
其他文章
Liger-Kernel 项目封面:显存不够先换 kernel 再想加卡,6,704 star、最新版 0.8.5、近四周 26 次提交
上一个

微调一开长序列就爆显存|Liger-Kernel 我在 Mac 上没装成,账倒是算明白了

Graphify 项目首图:把代码库解析成可查询的知识图谱,150182 star,近四周 592 次提交,实测 34.9 倍 token 缩减
下一个

十万行的仓库,别让助手每次都重新迷路|Graphify 我在 M2 上真跑了一遍

暂无评论!成为第一个。

发表回复 取消回复

您的邮箱地址不会被公开。 必填项已用 * 标注

Copyright 2026 — IT极限技术分享汇. 备案号:浙ICP备17006560号-2