一、项目概述

Surya-OCR 是一个面向文档理解的多语言OCR工具，支持超过90种语言的文本识别、行级文本定位与文档布局分析（如表格、标题、图像区域等）。其核心优势在于无需预设语言即可自动识别混合文本，并输出结构化结果。本文基于 v0.3.0 版本，详细介绍如何在无外网环境下完成模型部署与文本检测。

二、环境准备与依赖安装

1. 创建Python虚拟环境

推荐使用 Conda 管理环境，确保 Python 版本 ≥ 3.9：

conda create -n surya python=3.9
conda activate surya

2. 安装 PyTorch（离线模式）

由于部署环境可能受限于网络，推荐通过离线 Whl 包安装。需确保 torch、torchvision 和 torchaudio 版本严格匹配。

从官方仓库下载对应版本（如 CUDA 11.7）：

• https://download.pytorch.org/whl/cu117

下载以下三个包（示例为 Python 3.9 + Windows）：

• torch-1.13.0+cu117-cp39-cp39-win_amd64.whl
• torchvision-0.14.0+cu117-cp39-cp39-win_amd64.whl
• torchaudio-0.13.0+cu117-cp39-cp39-win_amd64.whl

将文件复制至虚拟环境的 Scripts 目录，执行安装：

cd E:\anaconda3\envs\surya\Scripts
pip install torch-1.13.0+cu117-cp39-cp39-win_amd64.whl
pip install torchvision-0.14.0+cu117-cp39-cp39-win_amd64.whl
pip install torchaudio-0.13.0+cu117-cp39-cp39-win_amd64.whl

验证安装：

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"

3. 安装 Surya-OCR v0.3.0

指定版本安装，避免兼容性问题：

pip install surya-ocr==0.3.0

若出现依赖缺失（如 transformers），降级至兼容版本：

pip install transformers==4.36.2

4. 获取源码与模型权重

克隆官方仓库以获取配置与示例代码：

git clone https://github.com/VikParuchuri/surya

模型权重需手动下载（因模型托管于 Hugging Face）：

• 文本检测模型： vikp/surya_det2
• 布局分析模型： vikp/surya_layout

可使用百度网盘离线获取（提取码：jqbx）：

https://pan.baidu.com/s/1NlOD8Naq8g9xt9oCcd_7ag

将下载的模型文件夹（含 config.json、pytorch_model.bin 等）存放于本地路径，如：

D:\surya_models\surya_det2
D:\surya_models\surya_layout

三、文本检测实现

1. 文本识别（OCR）——单图处理

以下代码实现离线加载模型并执行OCR，仅支持单张图片输入：

from PIL import Image
from surya.ocr import run_ocr
from surya.model.detection import segformer
from surya.model.recognition.model import load_model
from surya.model.recognition.processor import load_processor

# 配置参数
IMAGE_PATH = r"D:\test\document.jpg"
LANGUAGES = ["zh"]  # 支持: zh, en, de, fr, ru 等
MODEL_DET_PATH = r"D:\surya_models\surya_det2"
MODEL_REC_PATH = r"D:\surya_models\surya_recognition"

# 加载模型（离线）
image = Image.open(IMAGE_PATH)
det_processor = segformer.load_processor(MODEL_DET_PATH)
det_model = segformer.load_model(MODEL_DET_PATH)
rec_model = load_model(MODEL_REC_PATH)
rec_processor = load_processor(MODEL_REC_PATH)

# 执行识别
predictions = run_ocr(
    images=[image],
    langs=LANGUAGES,
    det_model=det_model,
    det_processor=det_processor,
    rec_model=rec_model,
    rec_processor=rec_processor
)

# 输出结果结构（含文本、坐标、置信度）
for pred in predictions:
    for text_line in pred.text_lines:
        print(f"Text: {text_line.text}, Bbox: {text_line.bbox}")

2. 文本行检测（Text Line Detection）

仅检测文本行位置，不进行文字识别，适用于快速定位：

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

IMAGE_PATH = r"D:\test\document.jpg"
MODEL_PATH = r"D:\surya_models\surya_det2"

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

predictions = batch_text_detection([image], model, processor)

# 遍历检测框
for pred in predictions:
    for bbox in pred.bboxes:
        print(f"Detected line at: {bbox}")

3. 布局分析（Layout Analysis）

识别文档结构，包括标题、表格、图像区域等：

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

IMAGE_PATH = r"D:\test\document.jpg"
MODEL_DET_PATH = r"D:\surya_models\surya_det2"
MODEL_LAYOUT_PATH = r"D:\surya_models\surya_layout"

image = Image.open(IMAGE_PATH)

# 先检测文本行
det_model = load_model(MODEL_DET_PATH)
det_processor = load_processor(MODEL_DET_PATH)
line_preds = batch_text_detection([image], det_model, det_processor)

# 再进行布局分析
layout_model = load_model(MODEL_LAYOUT_PATH)
layout_processor = load_processor(MODEL_LAYOUT_PATH)
layout_preds = batch_layout_detection([image], layout_model, layout_processor, line_preds)

# 输出区域类型与坐标
for pred in layout_preds:
    for region in pred.bboxes:
        print(f"Region: {region.label}, Bbox: {region.bbox}")

四、关键注意事项

• 路径规范：所有模型路径必须为绝对路径，避免相对路径导致加载失败。
• 模型版本匹配：确保 surya-ocr==0.3.0 与模型权重版本一致，否则会报 RuntimeError: "linspace_cpu" not implemented for 'Half'，需修改源码中 dtype 强制转为 float32。
• 单图输入：当前接口仅支持单张图片，批量处理需封装循环逻辑。
• GPU加速：若需指定GPU，可在加载模型前添加：torch.cuda.set_device(0)

模型输出为自定义类对象，包含 text_lines、bboxes、confidences 等字段，建议封装为 JSON 或 CSV 便于下游处理。