Surya 文档 OCR 实战:如何用它读懂 90+ 种语言并输出结构化数据

Surya 文档 OCR 实战:如何用它读懂 90+ 种语言并输出结构化数据

【免费下载链接】suryaOCR, layout analysis, reading order, table recognition in 90+ languages项目地址: https://gitcode.com/GitHub_Trending/su/surya

扫描版合同、票据和双语资料堆在桌面,传统 OCR 工具把行业术语读错、表格顺序读乱、混合语言段落直接糊成一团——如果你被这些问题卡住,可以试试 Surya。它是一套轻量级文档 OCR 工具包:650M 参数的视觉语言模型,一次调用同时给出文本识别、版面分析、阅读顺序和表格结构,覆盖 90 多种语言。

读完本文,你会做到:

• 用两条命令完成安装并跑通第一次整页 OCR
• 看懂results.json的输出结构,把结果接进自己的流水线
• 按硬件条件选择 vllm 或 llama.cpp 后端,并调出可接受的吞吐
• 在识别效果不佳时,按固定路径排查和调参

📄 先分清架构:一个 VLM 扛三件事,一个独立小模型管检测

先看结论:Surya 2 里,版面分析、整页 OCR、表格识别走的是同一个视觉语言模型(Qwen3.5 风格,约 650M 参数);只有文本行检测是独立的小模型。

• 推理服务器首次使用时自动拉起,你不需要手动部署
• 文本行检测是独立的 torch 模型(改造版 EfficientViT),不依赖 VLM 后端,没有 GPU 也能跑
• 数学公式不需要单独识别:公式会以内联<math>标签形式混在 OCR 输出的 HTML 里,内容是 KaTeX 兼容的 LaTeX

安装并跑通第一次整页 OCR

普通用户两条命令就能跑起来,输入可以是单张图、PDF 或整个目录:

pip install surya-ocr surya_ocr ./sample_docs --output_dir ./results

如果你想改源码或看实现,仓库提供基于 uv 的开发安装:克隆仓库(仓库地址 https://gitcode.com/GitHub_Trending/su/surya)后执行uv sync --group dev即可,依赖清单见 pyproject.toml。

跑完后结果写入results/results.json,顶层按文件名做键,值是按页排好的列表。

看懂输出 JSON:五个字段决定你能做什么

每个页面对象里的核心字段如下:

提示:批量数字化时,把confidence低于阈值(比如 0.7)的块挑出来人工核对,比全量复查省时间得多。

⚙️ 按硬件选后端,再调参数提吞吐

结论:吞吐主要由推理后端决定,常用开关都是环境变量,默认值定义在 surya/settings.py 中。

几条实用经验:

• 连续跑多条命令时加--keep_server,让服务器常驻,避免每次都重新加载模型
• vllm 侧可提高--max-num-seqs;llama.cpp 侧把--parallel调大并对齐客户端并发
• DPI 从 192 降到 96 能显著提升吞吐,精度换速度,按业务权衡

后端实现放在 surya/inference/,各 CLI 入口在 surya/scripts/,排查启动问题时看这两个目录最快。

🔍 识别不准时,按这个顺序排查

1. 分辨率:文字太小是首要原因;如果原图已经很大,把宽度降到 2048px 以内再试
2. 预处理:旧扫描件先做二值化、纠偏,再进模型
3. 检测阈值:DETECTOR_TEXT_THRESHOLD控制文本行是否合并,DETECTOR_BLANK_THRESHOLD控制空隙是否算空白,前者必须大于后者;结合--images输出的调试热图看框有没有粘连或漏检,再决定往哪边调
4. 表格:如果输入本身就是裁好的表格,给surya_table加--skip_table_detection,跳过表格定位直接识别

--images参数会把带标注的可视化图连同 JSON 一起写出,对照原图逐块检查,比只看文本快很多。

多语言与表格:覆盖面比你想的宽

官方在 91 种语言的内部基准上整体通过率为 87.2%,其中 38 种语言在 90% 以上。几个有代表性的分数:

完整 91 语言清单见 static/docs/multilingual.md。

经验值:阿拉伯语、越南语这类基准分偏低(70% 出头)的语言,值得在你自己的测试集里单独抽查,别拿英语的分数外推。

表格方面,surya_table输出行、列、单元格的几何信息与行/列 ID;开启 full 模式时额外给出完整<table>HTML,能处理合并单元格和表头。

收尾:四件事记住就够

1. 装完先跑surya_ocr,再按results.json里的label、html、confidence三个字段接下游
2. 后端由硬件决定:有 NVIDIA GPU 用 vllm,CPU 或 Apple Silicon 用 llama.cpp,自动拉起不用管
3. 效果不好先查分辨率和预处理,再动检测阈值,顺序别反
4. 多语言场景按官方基准预估下限,低分语言单独建测试集验证

建议你先拿十几份自己业务里最"难啃"的文档跑一遍全流程,把标注图和 JSON 都留档——之后任何一次调参,好坏都有据可查。

【免费下载链接】suryaOCR, layout analysis, reading order, table recognition in 90+ languages项目地址: https://gitcode.com/GitHub_Trending/su/surya