在macOS/Linux下部署Surya OCR工具包并提供API服务的中文教程

Surya是一个功能强大的文档OCR工具包，支持多种语言的OCR、行级文本检测、布局分析、阅读顺序检测和表格识别。本教程将指导你在macOS或Linux系统下安装和使用Surya，并提供API服务。

系统要求

Python 3.9+
PyTorch

如果你没有使用Mac或GPU机器，可能需要先安装CPU版本的PyTorch。更多详情请参见这里。

安装步骤

MacOS 用户

可以通过 Homebrew 轻松安装：

brew install surya

Docker 安装

docker pull vikparuchuri/surya
docker run -v ${path_to_host_folder_to_scan}:/path vikparuchuri/surya:latest [COMMAND] [OPTIONS] [SOURCE_PATH]

从源码安装

git clone https://github.com/VikParuchuri/surya.git
cd surya
make build

安装PyTorch

首先，确保你已经安装了PyTorch。你可以使用以下命令安装CPU版本的PyTorch：

pip install torch torchvision torchaudio

如果你有GPU，可以安装GPU版本的PyTorch：

pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu113

PIP安装Surya OCR工具包

使用以下命令安装Surya OCR工具包：

pip install surya-ocr

第一次运行Surya时，模型会自动下载

使用Surya

交互式应用

Surya包含一个Streamlit应用，可以让你在图像或PDF文件上交互式地尝试Surya。运行以下命令启动应用：

pip install streamlit
surya_gui

OCR（文本识别）

以下命令将输出一个包含检测到的文本和边界框的JSON文件：

surya_ocr DATA_PATH

DATA_PATH 可以是图像、PDF或图像/PDF文件夹
--langs 是一个可选（但推荐）的参数，指定用于OCR的语言。你可以用逗号分隔多个语言。使用语言名称或两字母ISO代码，支持的语言列表请参见这里。Surya支持surya/languages.py中列出的90多种语言。
--lang_file 如果你想为不同的PDF/图像使用不同的语言，可以指定一个语言文件。格式为JSON字典，键为文件名，值为语言列表，例如{"file1.pdf": ["en", "hi"], "file2.pdf": ["en"]}。
--images 将保存页面和检测到的文本行的图像（可选）
--results_dir 指定保存结果的目录，而不是默认目录
--max 指定要处理的最大页数，如果你不想处理所有页面
--start_page 指定开始处理的页码

results.json文件将包含一个JSON字典，键为输入文件名（不带扩展名）。每个值是一个字典列表，每个字典对应输入文档的一页。每个页面字典包含：

text_lines - 检测到的每行文本及其边界框
- text - 行中的文本
- confidence - 模型对检测到的文本的置信度（0-1）
- polygon - 文本行的多边形，格式为(x1, y1), (x2, y2), (x3, y3), (x4, y4)。点按顺时针顺序从左上角开始。
- bbox - 文本行的轴对齐矩形，格式为(x1, y1, x2, y2)。(x1, y1)为左上角，(x2, y2)为右下角。
languages - 为页面指定的语言
page - 文件中的页码
image_bbox - 图像的边界框，格式为(x1, y1, x2, y2)。(x1, y1)为左上角，(x2, y2)为右下角。所有行边界框都将包含在此边界框内。

性能提示

设置RECOGNITION_BATCH_SIZE环境变量可以显著提高GPU使用时的性能。每个批次项目将使用40MB的VRAM，因此可以设置非常高的批次大小。默认批次大小为512，将使用约20GB的VRAM。根据CPU核心数量，也可能会有所帮助 - 默认CPU批次大小为32。

从Python调用

from PIL import Image
from surya.ocr import run_ocr
from surya.model.detection.model import load_model as load_det_model, load_processor as load_det_processor
from surya.model.recognition.model import load_model as load_rec_model
from surya.model.recognition.processor import load_processor as load_rec_processor

image = Image.open(IMAGE_PATH)
langs = ["en"] # 替换为你需要的语言 - 可选但推荐
det_processor, det_model = load_det_processor(), load_det_model()
rec_model, rec_processor = load_rec_model(), load_rec_processor()

predictions = run_ocr([image], [langs], det_model, det_processor, rec_model, rec_processor)

编译

OCR模型可以编译以获得约15%的推理时间加速。第一次运行时会较慢，因为需要编译。首先设置RECOGNITION_STATIC_CACHE=true，然后：

import torch

rec_model.decoder.model = torch.compile(rec_model.decoder.model)

文本行检测

以下命令将输出一个包含检测到的边界框的JSON文件：

surya_detect DATA_PATH

DATA_PATH 可以是图像、PDF或图像/PDF文件夹
--images 将保存页面和检测到的文本行的图像（可选）
--max 指定要处理的最大页数，如果你不想处理所有页面
--results_dir 指定保存结果的目录，而不是默认目录

results.json文件将包含一个JSON字典，键为输入文件名（不带扩展名）。每个值是一个字典列表，每个字典对应输入文档的一页。每个页面字典包含：

bboxes - 检测到的文本边界框
- bbox - 文本行的轴对齐矩形，格式为(x1, y1, x2, y2)。(x1, y1)为左上角，(x2, y2)为右下角。
- polygon - 文本行的多边形，格式为(x1, y1), (x2, y2), (x3, y3), (x4, y4)。点按顺时针顺序从左上角开始。
- confidence - 模型对检测到的文本的置信度（0-1）
vertical_lines - 文档中检测到的垂直线
- bbox - 轴对齐的线坐标。
page - 文件中的页码
image_bbox - 图像的边界框，格式为(x1, y1, x2, y2)。(x1, y1)为左上角，(x2, y2)为右下角。所有行边界框都将包含在此边界框内。

性能提示

设置DETECTOR_BATCH_SIZE环境变量可以显著提高GPU使用时的性能。每个批次项目将使用440MB的VRAM，因此可以设置非常高的批次大小。默认批次大小为36，将使用约16GB的VRAM。根据CPU核心数量，也可能会有所帮助 - 默认CPU批次大小为6。

从Python调用

from PIL import Image
from surya.detection import batch_text_detection
from surya.model.detection.model import load_model, load_processor

image = Image.open(IMAGE_PATH)
model, processor = load_model(), load_processor()

# predictions 是一个字典列表，每个字典对应一个图像
predictions = batch_text_detection([image], model, processor)

布局分析

以下命令将输出一个包含检测到的布局的JSON文件：

surya_layout DATA_PATH

DATA_PATH 可以是图像、PDF或图像/PDF文件夹
--images 将保存页面和检测到的文本行的图像（可选）
--max 指定要处理的最大页数，如果你不想处理所有页面
--results_dir 指定保存结果的目录，而不是默认目录

results.json文件将包含一个JSON字典，键为输入文件名（不带扩展名）。每个值是一个字典列表，每个字典对应输入文档的一页。每个页面字典包含：

bboxes - 检测到的文本边界框
- bbox - 文本行的轴对齐矩形，格式为(x1, y1, x2, y2)。(x1, y1)为左上角，(x2, y2)为右下角。
- polygon - 文本行的多边形，格式为(x1, y1), (x2, y2), (x3, y3), (x4, y4)。点按顺时针顺序从左上角开始。
- confidence - 模型对检测到的文本的置信度（0-1）。目前不太可靠。
- label - 边界框的标签。可能是以下之一：Caption, Footnote, Formula, List-item, Page-footer, Page-header, Picture, Figure, Section-header, Table, Text, Title。
page - 文件中的页码
image_bbox - 图像的边界框，格式为(x1, y1, x2, y2)。(x1, y1)为左上角，(x2, y2)为右下角。所有行边界框都将包含在此边界框内。

性能提示

设置DETECTOR_BATCH_SIZE环境变量可以显著提高GPU使用时的性能。每个批次项目将使用400MB的VRAM，因此可以设置非常高的批次大小。默认批次大小为36，将使用约16GB的VRAM。根据CPU核心数量，也可能会有所帮助 - 默认CPU批次大小为6。

从Python调用

from PIL import Image
from surya.detection import batch_text_detection
from surya.layout import batch_layout_detection
from surya.model.detection.model import load_model, load_processor
from surya.settings import settings

image = Image.open(IMAGE_PATH)
model = load_model(checkpoint=settings.LAYOUT_MODEL_CHECKPOINT)
processor = load_processor(checkpoint=settings.LAYOUT_MODEL_CHECKPOINT)
det_model = load_model()
det_processor = load_processor()

# layout_predictions 是一个字典列表，每个字典对应一个图像
line_predictions = batch_text_detection([image], det_model, det_processor)
layout_predictions = batch_layout_detection([image], model, processor, line_predictions)

阅读顺序

以下命令将输出一个包含检测到的阅读顺序和布局的JSON文件：

surya_order DATA_PATH

DATA_PATH 可以是图像、PDF或图像/PDF文件夹
--images 将保存页面和检测到的文本行的图像（可选）
--max 指定要处理的最大页数，如果你不想处理所有页面
--results_dir 指定保存结果的目录，而不是默认目录

results.json文件将包含一个JSON字典，键为输入文件名（不带扩展名）。每个值是一个字典列表，每个字典对应输入文档的一页。每个页面字典包含：

bboxes - 检测到的文本边界框
- bbox - 文本行的轴对齐矩形，格式为(x1, y1, x2, y2)。(x1, y1)为左上角，(x2, y2)为右下角。
- position - 边界框在阅读顺序中的位置，从0开始。
- label - 边界框的标签。请参见布局部分的文档以获取可能的标签列表。
page - 文件中的页码
image_bbox - 图像的边界框，格式为(x1, y1, x2, y2)。(x1, y1)为左上角，(x2, y2)为右下角。所有行边界框都将包含在此边界框内。

性能提示

设置ORDER_BATCH_SIZE环境变量可以显著提高GPU使用时的性能。每个批次项目将使用360MB的VRAM，因此可以设置非常高的批次大小。默认批次大小为32，将使用约11GB的VRAM。根据CPU核心数量，也可能会有所帮助 - 默认CPU批次大小为4。

从Python调用

from PIL import Image
from surya.ordering import batch_ordering
from surya.model.ordering.processor import load_processor
from surya.model.ordering.model import load_model

image = Image.open(IMAGE_PATH)
# bboxes 应该是一个列表，包含图像的布局边界框，格式为[x1, y1, x2, y2]
# 你可以从布局模型中获取这些边界框，参见上面的使用方法
bboxes = [bbox1, bbox2, ...]

model = load_model()
processor = load_processor()

# order_predictions 是一个字典列表，每个字典对应一个图像
order_predictions = batch_ordering([image], [bboxes], model, processor)

表格识别

以下命令将输出一个包含检测到的表格单元格和行/列ID的JSON文件，以及行/列的边界框：

surya_table DATA_PATH

DATA_PATH 可以是图像、PDF或图像/PDF文件夹
--images 将保存页面和检测到的表格单元格、行和列的图像（可选）
--max 指定要处理的最大页数，如果你不想处理所有页面
--results_dir 指定保存结果的目录，而不是默认目录
--detect_boxes 指定是否检测单元格。默认情况下，单元格是从PDF中提取的，但这并不总是可能的。
--skip_table_detection 告诉表格识别不要先检测表格。如果你的图像已经裁剪到表格，可以使用此选项。

results.json文件将包含一个JSON字典，键为输入文件名（不带扩展名）。每个值是一个字典列表，每个字典对应输入文档的一页。每个页面字典包含：

cells - 检测到的表格单元格
- bbox - 文本行的轴对齐矩形，格式为(x1, y1, x2, y2)。(x1, y1)为左上角，(x2, y2)为右下角。
- row_id - 该单元格所属行的ID。
- col_id - 该单元格所属列的ID。
- text - 如果可以从PDF中提取文本，则为该单元格的文本。
rows - 检测到的表格行
- bbox - 表格行的边界框
- row_id - 行的ID
cols - 检测到的表格列
- bbox - 表格列的边界框
- col_id - 列的ID
page - 文件中的页码
table_idx - 页面上的表格索引（按垂直顺序排序）
image_bbox - 图像的边界框，格式为(x1, y1, x2, y2)。(x1, y1)为左上角，(x2, y2)为右下角。所有行边界框都将包含在此边界框内。

性能提示

设置TABLE_REC_BATCH_SIZE环境变量可以显著提高GPU使用时的性能。每个批次项目将使用150MB的VRAM，因此可以设置非常高的批次大小。默认批次大小为64，将使用约10GB的VRAM。根据CPU核心数量，也可能会有所帮助 - 默认CPU批次大小为8。

提供API服务

使用Flask提供API服务

你可以使用Flask框架来提供Surya的API服务。以下是一个简单的示例：

安装Flask：
```
pip install flask
```

创建一个Flask应用：

from flask import Flask, request, jsonify
from surya.ocr import run_ocr
from surya.model.detection.model import load_model as load_det_model, load_processor as load_det_processor
from surya.model.recognition.model import load_model as load_rec_model
from surya.model.recognition.processor import load_processor as load_rec_processor
from PIL import Image
import io

app = Flask(__name__)

@app.route('/ocr', methods=['POST'])
def ocr():
    file = request.files['file']
    image = Image.open(io.BytesIO(file.read()))
    langs = request.form.get('langs', 'en').split(',')
    det_processor, det_model = load_det_processor(), load_det_model()
    rec_model, rec_processor = load_rec_model(), load_rec_processor()
    predictions = run_ocr([image], [langs], det_model, det_processor, rec_model, rec_processor)
    return jsonify(predictions)

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

运行Flask应用：
```
python app.py
```

使用API：

你可以使用curl或其他HTTP客户端工具来测试API：

curl -X POST -F "file=@path/to/your/image.jpg" -F "langs=en,zh" http://localhost:5000/ocr

使用FastAPI提供API服务

FastAPI是一个现代、快速（高性能）的Web框架，适用于构建API。以下是一个使用FastAPI提供Surya API服务的示例：

安装FastAPI和Uvicorn：
```
pip install fastapi uvicorn
```

创建一个FastAPI应用：

from fastapi import FastAPI, File, UploadFile, Form
from fastapi.responses import JSONResponse
from surya.ocr import run_ocr
from surya.model.detection.model import load_model as load_det_model, load_processor as load_det_processor
from surya.model.recognition.model import load_model as load_rec_model
from surya.model.recognition.processor import load_processor as load_rec_processor
from PIL import Image
import io

app = FastAPI()

@app.post("/ocr")
async def ocr(file: UploadFile = File(...), langs: str = Form(...)):
    image = Image.open(io.BytesIO(await file.read()))
    langs = langs.split(',')
    det_processor, det_model = load_det_processor(), load_det_model()
    rec_model, rec_processor = load_rec_model(), load_rec_processor()
    predictions = run_ocr([image], [langs], det_model, det_processor, rec_model, rec_processor)
    return JSONResponse(content=predictions)

if __name__ == '__main__':
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

运行FastAPI应用：

uvicorn app:app --host 0.0.0.0 --port 8000

使用API：

你可以使用curl或其他HTTP客户端工具来测试API：

curl -X POST -F "file=@path/to/your/image.jpg" -F "langs=en,zh" http://localhost:8000/ocr

版权声明：本文为原创文章，版权归全栈开发技术博客所有。
本文链接：https://www.lvtao.net/tool/ocr-surya.html
转载时须注明出处及本声明

在macOS/Linux下部署Surya OCR工具包并提供API服务的中文教程

系统要求

安装步骤

MacOS 用户

Docker 安装

从源码安装

安装PyTorch

PIP安装Surya OCR工具包

使用Surya

交互式应用

OCR（文本识别）

从Python调用

编译

文本行检测

从Python调用

布局分析

从Python调用

阅读顺序

从Python调用

表格识别

提供API服务

使用Flask提供API服务

使用FastAPI提供API服务

相关文章

轻松将Python项目打包成独立运行软件包的工具-Pex入门及使用教程

微软开源的1-bit LLM推理框架——BitNet.cpp中文入门教程

离线分析、解析MySQL的Binlog日志的工具 - mysqlbinlog

离线解析MySQL InnoDB存储引擎的IBD文件生成SQL语句恢复数据库工具-ibd2sql

从PyTorch、TensorFlow和PaddlePaddle模型转换为ONNX的完整教程

使用Python3开发一个网站内链检查工具

使用色彩图标矩阵条码进行离线数据传输：Libcimbar 技术解析

AI批量生成与发布短视频、自动化变现利器MoneyPrinterPlus：支持本地与云端语音模型，结合AI生图创作

分类列表

热门文章

随机推荐