ocr-super-surya

OCR Super Surya

使用 Surya 进行 GPU 优化的 OCR。

适用场景

• OCR、从图像中提取文字、文字识别、画像から文字
• 从屏幕截图、照片或扫描图像中提取文字
• 处理包含嵌入图像的 PDF
• 多语言文档 OCR（支持 90 多种语言，包括日语）

提取与验证

1. 确认输入范围和用于敏感材料的非公开输出位置；保留源文件，不要绕过文档保护。文字脱敏不会使保留的图像匿名化，也不代表获准重新分发。
2. 首先提取 PDF／幻灯片中的原生文字，包括其中的幻灯片备注。非空文字层仍可能遗漏屏幕截图、图表或仅含图像的页面；选定 OCR 目标前，先梳理这些缺漏。对于图像目标，识别前先找到分辨率最高的原始图像：聊天附件和缩略图都是经过缩小的重新编码图像，因此应先按时间戳找到原始拍摄图像，再裁剪感兴趣区域并放大 4-7 倍（LANCZOS）。屏幕显示大小下的密集 CJK 字形容易模糊。
3. 记录相对于源文件的路径、源文件哈希、页码／幻灯片编号和图像哈希。对相同图像去重时，不要丢弃其源位置；区分待处理、已识别、无文字和失败状态。
4. 先运行一小批样本，并在缩放前与原始图像进行比对。在批处理中重复使用预测器，并为每个完成的项目创建检查点，以免中断后必须从头开始。
5. 将原始 OCR 结果与修正后的备注分开保存。标记置信度低或缺失的内容，并检查多栏顺序、代码符号和表格；高置信度不代表正确，无文字也不代表图像为空。放大裁剪图后逐行确认模糊的 CJK 字符，并标记未解决的字符；看似合理的形近字才是常见的失败模式，而不是空白。
6. 分别报告已提取的文档、已处理的 OCR 目标、未识别的目标和人工审核范围。验证已保存的文件和哈希；仅保存哈希既不能证明源文件是最新版本，也不能证明语义准确性。声称使用的是同一源文件版本时，请重新检查源文件哈希。

快速开始

安装

安装或声明 PDF／OCR 依赖不可用之前，请检查选定的解释器和现有专用环境。将 OcrPython 设置为已确定环境的解释器；不要假定当前工作区环境安装了相同的软件包。

& $OcrPython -c "import importlib.util,json; print(json.dumps({name: importlib.util.find_spec(name) is not None for name in ['surya','torch','pypdf','pypdfium2']}))"

成功导入后，请使用同一个解释器检查软件包版本和 torch.cuda.is_available()。GPU 不可用本身并不是卸载可用环境的理由。如果缺少依赖，请使用隔离环境；不要禁用证书验证来应对反复出现的同类 TLS 故障。

Windows + uv 环境（在 OneDrive 下安装）

在 OneDrive 下的文件夹中，uv 的硬链接会失败，因此请使用以下步骤：

# キャッシュをOneDrive外に設定
$env:UV_CACHE_DIR = "C:\Temp\uv_cache"

# 仮想環境をOneDrive外に作成
uv venv C:\Users\<USERNAME>\ocr_env --python 3.12

# surya-ocrをインストール（link-mode=copy でハードリンクを回避）
uv pip install surya-ocr --python C:\Users\<USERNAME>\ocr_env\Scripts\python.exe --link-mode=copy

# transformers 5.x は非互換 → 4.x を強制
uv pip install "transformers<5.0" --python C:\Users\<USERNAME>\ocr_env\Scripts\python.exe --link-mode=copy

用法

# CLI
python scripts/ocr_helper.py image.png
python scripts/ocr_helper.py document.pdf -o result.txt

# Or use surya directly
surya_ocr image.png --output_dir ./results

Python API

import sys, io
# Windows CP932エンコードエラー対策
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')

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

image = Image.open("document.png").convert("RGB")
found_pred = FoundationPredictor()
rec_pred = RecognitionPredictor(found_pred)  # v0.13+ : FoundationPredictor必須
det_pred = DetectionPredictor()

# v0.17.x以降: langs引数は廃止 → 渡さないこと
for page in rec_pred([image], det_predictor=det_pred):
    for line in page.text_lines:
        if line.text.strip():
            print(line.text)

API 变更历史（v0.17.x）：

• RecognitionPredictor(foundation_predictor) - FoundationPredictor 改为必需参数
• 从 __call__() 中移除 langs 参数（改为自动检测）

GPU 配置

变量	默认值	描述
RECOGNITION_BATCH_SIZE	512	显存较小时调低
DETECTOR_BATCH_SIZE	36	出现 OOM 时调低

export RECOGNITION_BATCH_SIZE=256
surya_ocr image.png

脚本

脚本	描述
scripts/ocr_helper.py	辅助工具，支持 OOM 自动重试和批处理

Troubleshooting

エラー	原因	対処
RecognitionPredictor.__init__() missing 1 required positional argument: 'foundation_predictor'	v0.13+ でAPIが変更	found_pred = FoundationPredictor() を作成して引数に渡す
TypeError: __call__() got an unexpected keyword argument 'langs'	v0.17.x で langs 引数廃止	langs 引数を削除する
AttributeError: 'SuryaDecoderConfig' object has no attribute 'pad_token_id'	transformers 5.x との非互換	pip install "transformers<5.0" でダウングレード
failed to hardlink file ... OneDrive (uv, os error 396)	OneDrive のハードリンク制限	--link-mode=copy を付けてインストール＋UV_CACHE_DIR をOneDrive外に設定
UnicodeEncodeError: 'cp932' codec can't encode character	Windows のCP932デフォルトエンコード	sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8') を先頭に追加
PdfDocument does not support the context manager protocol	Installed pypdfium2 API differs	Use explicit try/finally cleanup and close bitmap, page, and document after copying the rendered image; verify against the installed version.

License Note

• Surya: GPL-3.0 (code), commercial license required for >$2M revenue