Surya 2 在 NVIDIA GPU 上如何通过 vllm 后端首次运行 surya_ocr？
【免费下载链接】suryaOCR, layout analysis, reading order, table recognition in 90+ languages项目地址: https://gitcode.com/GitHub_Trending/su/surya
本文面向有一块 NVIDIA GPU、想第一次在本地跑通 Surya 2 OCR 的开发者：安装surya-ocr包，让它在首次使用时通过 vllm 后端自动拉起推理服务器，对一份文档执行surya_ocr并核对输出。Surya 2 的 layout / OCR / table recognition 都走同一个 VLM，由SuryaInferenceManager在首次使用时自动 spawn（NVIDIA GPU 走 vllm，CPU / Apple Silicon 走 llama.cpp），本路径只覆盖 vllm 一侧。
准备条件
按 README.md 的 "Inference backend prerequisites"，vllm（NVIDIA GPU）路径的依赖只有两项：
- Docker（daemon 需在运行）
- NVIDIA Container Toolkit
源码中如果找不到docker可执行文件，直接抛出docker binary not found. Install Docker ... and ensure the daemon is running.，见 surya/inference/backends/vllm.py。
安装包本身是一条命令：
pip install surya-ocrPython 版本要求来自 pyproject.toml：requires-python = ">=3.10,<4"。
装完后会注册的 CLI 入口包括surya_ocr、surya_detect、surya_layout、surya_table、surya_gui（见 pyproject.toml 的[project.scripts]）。
确认 vllm 后端会被选中
后端选择逻辑在 surya/inference/init.py：SURYA_INFERENCE_BACKEND未设置时，检测到 NVIDIA GPU 就用vllm，否则用llamacpp。如果你希望显式指定而不是依赖自动检测：
export SURYA_INFERENCE_BACKEND=vllm首次运行时，vllm 后端会通过docker run拉起容器surya-vllm-<port>，关键参数都来自 surya/settings.py 的默认值，首次使用前需要先检查两个与 GPU 直接相关的设置：
VLLM_GPU_TYPE（默认"4090"）：用来按 VRAM 自动推算--max-num-batched-tokens和--max-num-seqs。可选值就是 vllm.py 中GPU_VRAM_GB表里的键：b300、b200、h200、h100、a100-80、a100、a100-40、l40s、a10、l4、5090、4090、3090、t4。如果你的卡不在其中（或想确认当前值），启动时会报Unknown VLLM_GPU_TYPE ... Available: ...并列出全部可用值。VLLM_DTYPE（默认"bfloat16"）：settings 注释明确 bfloat16 需要 Ampere 及以上（compute capability >= 8.0），更老的卡（如 T4 / Turing）上 vllm 会拒绝以 bf16 启动，需改为 float16。
其余默认值供参考：镜像VLLM_DOCKER_IMAGE = "vllm/vllm-openai:v0.20.1"，模型SURYA_MODEL_CHECKPOINT = "datalab-to/surya-ocr-2"，VLLM_GPUS = "0"，VLLM_MAX_MODEL_LEN = 18000，VLLM_GPU_MEMORY_UTILIZATION = 0.85，VLLM_ENABLE_MTP = True。
首次运行 surya_ocr
DATA_PATH可以是一张图片、一个 PDF，或一个包含图片/PDF 的目录（README.md OCR 一节）：
surya_ocr /path/to/your.pdf第一次执行时会发生的事（对应 surya/inference/backends/spawn.py 与 vllm.py）：
- 若没有已存在的 vllm 服务器，通过
docker run -d启动surya-vllm-<port>容器，挂载本地 HF 缓存目录（~/.cache/huggingface，由DOCKER_HF_CACHE_PATH控制）； - 轮询
http://127.0.0.1:<port>/health，直到返回 200，超时上限为SURYA_INFERENCE_STARTUP_TIMEOUT（默认 600 秒）； - 健康检查通过后校验服务器报告的模型名，日志输出
vllm server ready on port <port> (model=...)。
如果健康检查在超时内未通过，spawn 流程会先抓取容器日志再拆掉容器，抛出形如vllm server failed to become healthy at ... within 600s. --- last vllm server logs ---的错误，容器自身的日志尾段会附在异常信息里，这是第一次启动失败时最重要的排查信息。
常用参数（见 surya/scripts/config.py 的common_options）：
--output_dir：结果保存目录，默认为results/surya/<输入名>/；--page_range：只处理指定页，格式如0,5-10,20；--images：额外保存页面与检测框的标注图；--keep_server：命令退出后不关闭推理服务器。默认行为是"启动时 spawn、退出时关闭"，连跑多条命令时每条都要付一次启动（GPU 上还有模型加载）开销；加--keep_server后后续命令（如surya_layout）直接 attach 到运行中的服务器。
核对结果
surya_ocr结束后会写一个results.json到输出目录（默认results/surya/<输入名>/results.json）。按 README.md 的结构说明，该文件以输入文件名（不含扩展名）为键，每个值是每页一个 dict 的列表，每页包含：
blocks：按阅读顺序排列的块，每块含label、raw_label、reading_order、html（块内容 HTML，数学包在<math>...</math>里，表格为<table>...</table>）、polygon、bbox、confidence（0-1 的平均 token 概率）、skipped、error；image_bbox：[0, 0, width, height]。
核对方式：打开results.json，确认目标页有非空blocks、html里有识别出的文本内容、error不为true。命令行本身成功时的日志为Wrote results to <result_path>（见 surya/scripts/ocr_text.py）。
若某页 full-page 输出解析失败，RecognitionPredictor 会自动退回 layout + per-block OCR 路径，见 surya/scripts/ocr_text.py 的注释。
收尾与边界
- 用
--keep_server留下服务器后，用完后要手动停：docker stop掉surya-vllm-*容器（README.md "Server lifecycle" 一节）。也可以把SURYA_INFERENCE_KEEP_ALIVE=1设为默认 keep-alive。 - 若已有别的 OpenAI 兼容服务器在跑，可通过
export SURYA_INFERENCE_URL=http://host:port/v1直接 attach 而不 spawn；此时服务器/health不可达会报... is not reachable at /health，模型名不匹配会报Model mismatch at ...，两者都要求先修好外部服务器再重试。 - README 的 Limitations 一节明确：layout / OCR / table_rec 都需要一个运行中的推理后端（vllm 或 llama.cpp），只有 text line detection 是纯 torch 模型、不依赖后端。
至此，一次完整的 NVIDIA GPU + vllm 首跑路径是：装 Docker 与 NVIDIA Container Toolkit →pip install surya-ocr→ 按自己的卡核对VLLM_GPU_TYPE/VLLM_DTYPE→surya_ocr DATA_PATH→ 检查results.json中的blocks。
【免费下载链接】suryaOCR, layout analysis, reading order, table recognition in 90+ languages项目地址: https://gitcode.com/GitHub_Trending/su/surya
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
