最完整Surya Python API集成指南：90+语言OCR功能无缝接入应用

瞿格女

602人浏览 · 2025-09-10 21:38:21

瞿格女 · 2025-09-10 21:38:21 发布

最完整Surya Python API集成指南：90+语言OCR功能无缝接入应用

【免费下载链接】surya OCR, layout analysis, and line detection in 90+ languages 项目地址: https://gitcode.com/GitHub_Trending/su/surya

你还在为多语言OCR集成头疼？还在忍受云服务的延迟和费用？本文将带你一步到位掌握Surya Python API的集成方法，让你在30分钟内拥有支持90+语言的文档智能处理能力，包括文本识别、版面分析和表格提取等核心功能。

读完本文后，你将能够：

正确安装和配置Surya环境
使用Python API实现多语言OCR识别
集成文本检测、版面分析和表格识别功能
优化模型性能以适应不同硬件环境

Surya核心功能概览

Surya是一个功能全面的文档OCR工具包，主要提供以下能力：

支持90+语言的OCR识别，性能媲美主流云服务
任意语言的行级文本检测
版面分析（检测表格、图片、标题等元素）
阅读顺序检测
表格识别（检测行/列结构）
LaTeX公式识别

Surya的核心优势在于其全面的本地化文档处理能力，无需依赖云服务即可在本地完成复杂的文档智能分析。其架构设计允许开发者灵活集成各个功能模块，满足不同场景的需求。

环境准备与安装

系统要求

Python 3.10+
PyTorch（根据系统配置选择CPU或GPU版本）
足够的存储空间（模型文件约需10GB）

快速安装

通过pip可以快速安装Surya：

pip install surya-ocr

模型权重将在首次运行时自动下载。对于国内用户，建议配置PyPI镜像源以加速安装过程。

手动安装（开发环境）

如果需要进行二次开发，可以选择手动安装：

git clone https://gitcode.com/GitHub_Trending/su/surya
cd surya
poetry install  # 安装主要和开发依赖
poetry shell    # 激活虚拟环境

详细的安装说明可参考Surya官方文档。

核心API模块详解

Surya的Python API设计遵循模块化原则，将不同功能封装为独立的预测器(Predictor)类，便于按需集成。

模块架构

Surya主要包含以下核心模块：

基础模型(Foundation): surya/foundation/
文本识别(Recognition): surya/recognition/
文本检测(Detection): surya/detection/
版面分析(Layout): surya/layout/
表格识别(TableRec): surya/table_rec/
LaTeX识别(Texify): surya/debug/katex.js

这些模块可以单独使用，也可以组合起来实现复杂的文档处理流程。

预测器(Predictor)设计模式

Surya采用预测器设计模式，每个主要功能都封装为一个Predictor类。这种设计使得API使用简单直观，同时保持了高度的灵活性。

所有预测器都遵循相似的使用模式：

创建预测器实例
调用实例方法处理输入数据
获取结构化结果

快速开始：基础OCR功能集成

下面通过一个简单示例，展示如何使用Surya的Python API实现基础的OCR功能。

单张图片OCR识别

from PIL import Image
from surya.foundation import FoundationPredictor
from surya.recognition import RecognitionPredictor
from surya.detection import DetectionPredictor

# 加载图片
image = Image.open("static/images/excerpt.png")

# 初始化预测器
foundation_predictor = FoundationPredictor()
recognition_predictor = RecognitionPredictor(foundation_predictor)
detection_predictor = DetectionPredictor()

# 执行OCR识别
predictions = recognition_predictor([image], det_predictor=detection_predictor)

# 处理结果
for page in predictions[0]:
    for line in page["text_lines"]:
        print(line["text"])

这段代码实现了对单张图片的OCR识别，输出识别到的文本内容。其中：

FoundationPredictor提供基础模型支持
DetectionPredictor负责文本区域检测
RecognitionPredictor负责文本内容识别

结果数据结构

OCR识别返回的结果是一个结构化字典，包含丰富的信息：

{
    "text_lines": [
        {
            "text": "识别到的文本内容",
            "confidence": 0.98,  # 置信度
            "bbox": [x1, y1, x2, y2],  # 边界框坐标
            "polygon": [(x1,y1), (x2,y2), (x3,y3), (x4,y4)],  # 多边形边界
            "words": [  # 单词级信息
                {
                    "text": "单词",
                    "confidence": 0.99,
                    "bbox": [x1, y1, x2, y2]
                }
            ]
        }
    ],
    "page": 0,  # 页码
    "image_bbox": [0, 0, 1000, 1500]  # 图片边界
}

完整的结果结构定义可参考surya/recognition/schema.py。

高级功能集成指南

文本检测功能

文本检测用于定位图片中的文本区域，获取文本行的边界框信息：

from PIL import Image
from surya.detection import DetectionPredictor

# 加载图片
image = Image.open("static/images/japanese.jpg")

# 初始化文本检测预测器
det_predictor = DetectionPredictor()

# 执行文本检测
predictions = det_predictor([image])

# 处理结果
for bbox in predictions[0]["bboxes"]:
    print(f"文本区域: {bbox['bbox']}, 置信度: {bbox['confidence']}")

文本检测模块的核心代码实现可参考surya/detection/model/。

性能优化提示：设置DETECTOR_BATCH_SIZE环境变量可以显著影响GPU使用效率。每个批次项约使用440MB显存，默认批次大小为36，约使用16GB显存。对于CPU，默认批次大小为6。

版面分析与阅读顺序

版面分析可以识别文档中的不同元素类型（如标题、段落、表格、图片等），并确定正确的阅读顺序：

from PIL import Image
from surya.foundation import FoundationPredictor
from surya.layout import LayoutPredictor
from surya.settings import settings

# 加载图片
image = Image.open("static/images/pres.png")

# 初始化版面分析预测器
layout_predictor = LayoutPredictor(FoundationPredictor(checkpoint=settings.LAYOUT_MODEL_CHECKPOINT))

# 执行版面分析
layout_predictions = layout_predictor([image])

# 处理结果
for bbox in layout_predictions[0]["bboxes"]:
    print(f"元素类型: {bbox['label']}, 位置: {bbox['position']}, 坐标: {bbox['bbox']}")

版面分析支持的元素类型包括：Caption、Footnote、Formula、List-item、Page-footer、Page-header、Picture、Figure、Section-header、Table、Form、Table-of-contents、Handwriting、Text等。

表格识别

表格识别功能可以从文档中提取表格结构，包括行、列和单元格信息：

from PIL import Image
from surya.table_rec import TableRecPredictor

# 加载图片
image = Image.open("static/images/scanned_tablerec.png")

# 初始化表格识别预测器
table_rec_predictor = TableRecPredictor()

# 执行表格识别
table_predictions = table_rec_predictor([image])

# 处理结果
for table in table_predictions[0]:
    for cell in table["cells"]:
        print(f"单元格: 行{cell['row_id']}, 列{cell['col_id']}, 内容: {cell['text']}")

表格识别的详细实现可参考surya/table_rec/。

LaTeX公式识别

Surya提供专门的LaTeX公式识别功能，可以将图片中的数学公式转换为LaTeX代码：

from PIL import Image
from surya.texify import TexifyPredictor

# 加载包含公式的图片
image = Image.open("static/images/latex_ocr.png")

# 初始化LaTeX识别预测器
predictor = TexifyPredictor()

# 执行公式识别
latex_results = predictor([image])

# 处理结果
for page in latex_results:
    for line in page["text_lines"]:
        print(f"LaTeX代码: {line['text']}")

你还可以通过运行交互式应用来测试公式识别功能：

pip install streamlit==1.40 streamlit-drawable-canvas-jsretry
texify_gui

性能优化与部署建议

模型编译加速

Surya支持模型编译功能，可以显著提高推理速度。通过设置环境变量启用编译：

# 在代码中设置环境变量
import os
os.environ["COMPILE_ALL"] = "true"  # 编译所有模型
# 或者分别编译特定模型
# os.environ["COMPILE_DETECTOR"] = "true"
# os.environ["COMPILE_LAYOUT"] = "true"
# os.environ["COMPILE_TABLE_REC"] = "true"

# 然后正常初始化预测器
from surya.detection import DetectionPredictor
det_predictor = DetectionPredictor()

在A10 GPU上的加速效果如下：

模型	每页处理时间(秒)	编译后每页处理时间(秒)	加速比(%)
文本检测	0.108808	0.10521	3.306742151
版面分析	0.27319	0.27063	0.93707676
表格识别	0.0219	0.01938	11.50684932

批处理与并发处理

对于大量图片的OCR处理，使用批处理可以显著提高效率：

from PIL import Image
import os
from surya.recognition import RecognitionPredictor
from surya.detection import DetectionPredictor
from surya.foundation import FoundationPredictor

# 加载多张图片
image_dir = "static/images/"
images = [Image.open(os.path.join(image_dir, f)) for f in os.listdir(image_dir) if f.endswith(('.png', '.jpg'))]

# 初始化预测器
foundation_predictor = FoundationPredictor()
recognition_predictor = RecognitionPredictor(foundation_predictor)
detection_predictor = DetectionPredictor()

# 批量处理图片
batch_size = 8
for i in range(0, len(images), batch_size):
    batch = images[i:i+batch_size]
    predictions = recognition_predictor(batch, det_predictor=detection_predictor)
    # 处理当前批次结果
    for page in predictions:
        # 结果处理逻辑
        pass

对于OCR识别，设置RECOGNITION_BATCH_SIZE环境变量可以优化GPU使用效率。每个批次项约使用40MB显存，默认批次大小为512，约使用20GB显存。CPU默认批次大小为32。

多语言支持

Surya支持90+种语言的OCR识别。语言支持相关代码可参考surya/recognition/languages.py。虽然文本检测、版面分析和阅读顺序功能不依赖于特定语言，但在使用时仍需注意：

对于特定语言，可能需要调整预处理参数
部分语言可能需要额外的字体支持
从右到左(RTL)语言的文本顺序需要特殊处理

常见问题与解决方案

安装问题

PyTorch版本不兼容

Surya需要PyTorch 1.10+版本。如果遇到PyTorch相关错误，请参考PyTorch官方安装指南安装适合你系统的版本。

模型下载失败

如果模型权重自动下载失败，可以手动下载并放置到指定目录。模型路径配置可在surya/settings.py中找到。

性能问题

识别速度慢

确保已根据硬件配置正确设置批次大小
考虑启用模型编译加速
对于大量图片，使用批处理而非单张处理

识别准确率低

尝试调整图片分辨率，确保文本清晰可见
对模糊或老旧图片进行预处理（如二值化、去歪斜等）
调整检测阈值参数DETECTOR_BLANK_THRESHOLD和DETECTOR_TEXT_THRESHOLD

结果处理问题

文本顺序不正确

文本顺序问题通常可以通过启用阅读顺序检测解决：

# 在版面分析中启用阅读顺序检测
layout_predictions = layout_predictor([image], detect_reading_order=True)

表格结构识别错误

对于复杂表格，可尝试调整表格识别参数：

# 调整表格识别参数
table_predictions = table_rec_predictor([image], detect_boxes=True)

实际应用案例

文档数字化系统

Surya非常适合构建文档数字化系统，将纸质文档或图片中的内容转换为可编辑的结构化数据。结合批量处理功能，可以高效处理大量文档：

import os
from PIL import Image
from surya.foundation import FoundationPredictor
from surya.recognition import RecognitionPredictor
from surya.detection import DetectionPredictor
from surya.layout import LayoutPredictor

def process_document(image_dir, output_dir):
    # 初始化所有预测器
    foundation_predictor = FoundationPredictor()
    recognition_predictor = RecognitionPredictor(foundation_predictor)
    detection_predictor = DetectionPredictor()
    layout_predictor = LayoutPredictor(foundation_predictor)
    
    # 创建输出目录
    os.makedirs(output_dir, exist_ok=True)
    
    # 处理目录中所有图片
    for filename in os.listdir(image_dir):
        if filename.lower().endswith(('.png', '.jpg', '.jpeg')):
            image_path = os.path.join(image_dir, filename)
            image = Image.open(image_path)
            
            # 执行完整文档分析
            det_results = detection_predictor([image])
            layout_results = layout_predictor([image])
            ocr_results = recognition_predictor([image], det_predictor=detection_predictor)
            
            # 保存结果
            output_path = os.path.join(output_dir, f"{os.path.splitext(filename)[0]}.json")
            with open(output_path, 'w', encoding='utf-8') as f:
                json.dump({
                    'detection': det_results,
                    'layout': layout_results,
                    'ocr': ocr_results
                }, f, ensure_ascii=False, indent=2)

# 使用示例
process_document("input_images/", "output_results/")

学术论文处理系统

Surya的LaTeX识别和表格识别功能特别适合学术论文处理。下面是一个提取论文中公式和表格的示例：

from PIL import Image
from surya.texify import TexifyPredictor
from surya.table_rec import TableRecPredictor

def extract_scientific_content(image_path):
    image = Image.open(image_path)
    
    # 提取LaTeX公式
    texify_predictor = TexifyPredictor()
    latex_results = texify_predictor([image])
    
    # 提取表格
    table_predictor = TableRecPredictor()
    table_results = table_predictor([image])
    
    return {
        'latex_formulas': latex_results,
        'tables': table_results
    }

# 使用示例
content = extract_scientific_content("static/images/paper.jpg")
print(f"发现{len(content['latex_formulas'])}个公式，{len(content['tables'])}个表格")