Surya 实战：从零搭建本地 OCR 流水线

Surya 实战：从零搭建本地 OCR 流水线

业务开发中经常遇到这样的场景：业务方甩来一堆扫描件 PDF、合同图片或发票照片，要求把里面的文字和表格提取出来存进数据库。传统的做法要么调付费 OCR API（按次计费且需上传数据），要么用 Tesseract 自己折腾（精度不稳定且需手动调参）。

本文将带你使用开源项目 Surya 将这个过程本地化。Surya 支持 91 种语言的 OCR 识别，能自动完成文档布局分析、阅读顺序排序和表格识别。在 RTX 5090 上可达 每秒 5 页 的处理速度，无 GPU 环境下也能通过 CPU 或 Apple Silicon 运行。

阅读完本篇教程，你将能够：

1. 独立部署完整的本地 OCR 服务
2. 使用 Python API 对图片/PDF 进行高精度文字识别
3. 自动提取文档中的表格并输出 HTML 结构化结果
4. 掌握常见问题的排查方法与性能调优技巧

环境准备

开始前请确认满足以下条件：

Surya 核心是一个视觉语言模型（VLM），OCR、布局分析、表格识别均通过同一模型完成，因此需要推理服务器支持。SuryaInferenceManager 会在首次调用时自动启动推理服务，无需手动部署。

快速上手：5 步跑通服务

第 1 步：安装 surya-ocr

pip install surya-ocr

安装过程会自动拉取所需依赖。

第 2 步：配置推理后端

NVIDIA GPU 用户：

确保已安装 Docker 和 NVIDIA Container Toolkit。运行以下命令验证 GPU 是否正确识别：

docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

正常输出 GPU 信息即表示配置成功。

CPU 或 Apple Silicon 用户：

需要安装 llama.cpp 服务器。macOS 用户执行：

brew install llama.cpp

Linux 用户从 llama.cpp releases 下载对应版本，确保 llama-server 已加入系统 PATH。

第 3 步：验证安装

准备一张带文字的测试图片（如 test.jpg），执行：

surya_ocr /path/to/your/test.jpg

首次运行会经历以下步骤：

1. 自动下载模型权重（约 1.3GB）
2. 启动推理服务器（vllm 或 llama.cpp）
3. 执行 OCR 并生成 results.json

复用推理服务器技巧

每次执行命令默认会启停服务器，连续操作时需重复加载模型。使用 --keep_server 参数可保持服务器常驻：

surya_ocr test.jpg --keep_server   # 启动并保持服务器运行
surya_layout test2.jpg             # 后续命令直接复用，秒级响应
surya_table test3.pdf --keep_server # 继续复用同一服务

实战演练：Python API 构建文档处理流水线

命令行适合快速测试，集成到业务系统推荐使用 Python API。以下示例实现：输入扫描件 → OCR 提取文字 → 识别布局 → 提取表格 → 输出结构化结果。

from PIL import Image
from surya.inference import SuryaInferenceManager
from surya.recognition import RecognitionPredictor
from surya.layout import LayoutPredictor
from surya.table_rec import TableRecPredictor
import json

## 1. 创建推理管理器（自动选择 vllm 或 llama.cpp）
manager = SuryaInferenceManager()

## 2. 加载测试图片
image_path = "scanned_invoice.jpg"  # 替换为你的文件路径
image = Image.open(image_path)

## 3. 布局分析（识别表格、正文等区域）
layout_predictor = LayoutPredictor(manager)
layouts = layout_predictor([image])

print("=== 布局分析结果 ===")
for page in layouts:
    for block in page["blocks"]:
        print(f"类型: {block['label']}, 阅读顺序: {block['reading_order']}, 置信度: {block['confidence']:.2f}")

## 4. 基于布局进行精细化 OCR
recognition_predictor = RecognitionPredictor(manager)
predictions = recognition_predictor([image], layouts)

print("\n=== OCR 文字提取 ===")
for page in predictions:
    for block in page["blocks"]:
        if not block["skipped"]:
            print(f"[{block['label']}] {block['html'][:100]}...")

## 5. 表格提取
table_predictor = TableRecPredictor(manager)
table_results = table_predictor.predict_full([image])

print("\n=== 表格提取结果 ===")
if table_results and not table_results[0]["error"]:
    for tbl in table_results:
        print(f"发现表格，共 {len(tbl['rows'])} 行 {len(tbl['cols'])} 列")
        print(tbl["html"][:200], "...")
        
        with open("table_output.json", "w", encoding="utf-8") as f:
            json.dump(table_results, f, ensure_ascii=False, indent=2)
    print("表格结果已保存到 table_output.json")
else:
    print("未检测到表格")

关键机制解析

布局分析与 OCR 的关系

Surya 提供两种 OCR 模式：

• 全页模式：单次 VLM 调用处理整页，速度快但可能遗漏细节
• Block 模式：先通过布局分析定位文本块，再逐个进行 OCR，精度更高

向 RecognitionPredictor 传入 layout_results 参数后，系统自动切换至 block 模式。处理合同、发票等结构化文档时，强烈建议采用 block 模式。

predict_full 方法说明

TableRecPredictor 默认返回行列几何信息（simple 模式）。调用 predict_full() 会输出完整 <table> HTML，保留合并单元格、表头 rowspan/colspan 等结构。下游需要标准表格格式时务必使用此方法。

常见问题排查指南

1. OCR 识别准确率低

重点检查图片参数：

• 文字过小 → 提升 DPI 或放大图片
• 图片过宽（>2048px）→ 适当缩小，模型对超高分辨率处理能力反而下降
• 老旧扫描件（模糊、倾斜）→ 建议先进行二值化、去噪、倾斜校正等预处理

2. 推理服务器启动失败

典型报错为无法连接后端。排查路径：

• GPU 用户：确认 Docker 可正常调用 GPU（通过 nvidia-smi 验证）
• CPU/Mac 用户：确认 llama-server 在 PATH 中（终端执行 llama-server --help 测试）
• 手动指定后端配置：
  bash 复制代码

  export SURYA_INFERENCE_BACKEND=vllm  # 或 llamacpp
  export SURYA_INFERENCE_URL=http://localhost:8000/v1  # 指向已有服务

3. 内存或显存不足

降低并发处理数：

export SURYA_INFERENCE_PARALLEL=4  # 默认值为 8，调小可降低内存峰值

GPU 用户还可降低 DPI 设置（默认 192，可尝试降至 96）：

import os
os.environ["SURYA_OCR_DPI"] = "96"

4. 中文识别效果优化

Surya 在 91 种语言上的综合通过率达 87.2%，中文单项为 82.5%。处理中英混排文档时：

• 确保图片清晰度充足
• 优先选用 block 模式替代全页模式
• 专业排版文档可联系项目方进行微调训练

进阶应用与生产建议

完成基础部署后，可尝试以下扩展：

• 批量处理目录：surya_ocr /path/to/folder --page_range 0-5 指定页码范围
• 启动交互式 UI：pip install streamlit pdftext && surya_gui
• 数学公式识别：Surya 2 自动将方程转换为 <math>...</math> 包裹的 KaTeX 兼容 LaTeX

投入生产环境需注意：

• 许可证说明：Apache 2.0 代码可自由使用，模型权重对初创公司（融资/收入 <$5M）免费商用，大规模使用需联系 Datalab 授权
• 性能压测：使用实际业务文档进行 benchmark 测试，调整 DPI 和并发参数寻找最佳性能平衡点

Surya 社区活跃度高，遇到问题可前往 GitHub Issues 或官方 Discord 频道交流。现在你可以动手搭建自己的本地 OCR 服务了。