GPU-optimized OCR using Surya. Use when: (1) Extracting text from images/screenshots, (2) Processing PDFs with embedded images, (3) Multi-language document OCR, (4) Layout analysis and table detection. Supports 90+ languages with 2x accuracy over Tesseract.
GPU-optimized OCR using Surya.
Check the selected interpreter and existing dedicated environments before installing or declaring a PDF/OCR dependency unavailable. Set OcrPython to the resolved environment's interpreter; do not assume the active workspace environment has the same packages.
& $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']}))"
After imports succeed, check package versions and torch.cuda.is_available() with that same interpreter. GPU unavailability alone is not a reason to uninstall a working environment. If dependencies are missing, use an isolated environment; stop repeated equivalent TLS failures instead of disabling certificate validation.
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 -l ja en -o result.txt
# Or use surya directly
surya_ocr image.png --output_dir ./results
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引数が削除（自動検出に変更）
| Variable | Default | Description |
| ------------------------ | ------- | --------------------- |
| RECOGNITION_BATCH_SIZE | 512 | Reduce for lower VRAM |
| DETECTOR_BATCH_SIZE | 36 | Reduce if OOM |
export RECOGNITION_BATCH_SIZE=256
surya_ocr image.png
| Script | Description |
| ----------------------- | ----------------------------------------- |
| scripts/ocr_helper.py | Helper with OOM auto-retry, batch support |
| エラー | 原因 | 対処 |
| ------------------------------------------------------------------------------------------------ | ----------------------------------- | --------------------------------------------------------------------------------- |
| 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. |
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer