部署

把 TurboOCR 从「我想在生产里跑起来」推到「跑起来了、有监控、不会塌」所需的全部信息。本页涵盖支持的 Docker 标签、GPU 与驱动基线、TensorRT 缓存卷、模型切换、基于 MPS 的扩容、监控端点，以及一份简短的生产 checklist。

环境要求

• 操作系统 —— Linux。容器基于 NVIDIA TensorRT 官方镜像构建，已在 Ubuntu 24.04 上验证。
• GPU —— Turing 或更新架构的 NVIDIA GPU（RTX 20-series、GTX 16-series 及以上）。
• 驱动 —— NVIDIA 驱动 595 或更高，并安装 NVIDIA Container Toolkit，使 Docker 能正确识别 --gpus all。
• 显存 —— 纯文本部署约 4 GB，完整流水线（版面 + 表格 + 公式）约 8 GB。每增加一个 PIPELINE_POOL_SIZE 副本，再加约一整套。
• CPU 回退 —— 提供纯 CPU 镜像供无 GPU 机器开发使用，但吞吐显著下降（个位数 张/秒），不建议用于生产。

Docker 镜像

预构建镜像发布在 GitHub Container Registry：ghcr.io/aiptimizer/turboocr。源码仓库的 docker/Dockerfile.gpu 与 docker/Dockerfile.cpu 分别产出两个变体。

标签	用途	说明
:latest	GPU 镜像，跟踪最新发布	Drogon HTTP 监听 8000（前置 nginx），gRPC 监听 50051。已内置全部识别模型、PP-DocLayoutV3 以及表格/公式权重。适合演示；生产请固定版本。
:v3.1.0	固定的 GPU 镜像	当前发布版本——生产请用它。
turboocr-cpu:v3.1.0	CPU 回退	使用 ONNX Runtime 替代 TensorRT（独立镜像：ghcr.io/aiptimizer/turboocr-cpu）。个位数张/秒——仅供开发/CI。

警告

生产环境请固定版本。 使用明确的标签（如 :v3.1.0）而非 :latest。固定版本能让回滚变得简单，并避免一次意外升级在事故中重新编译 TensorRT 引擎。

服务器二进制名称

镜像内的服务器二进制在 v3 中被重命名：GPU 为 turboocr-server（原 paddle_highspeed_cpp），CPU 为 turboocr-cpu-server（原 paddle_cpu_server）。Docker 用户不受影响；这只与原生构建和 --print-config 有关。

GPU 镜像

默认镜像运行完整的 TensorRT 流水线。首次启动会从 ONNX 编译引擎（在 RTX 5090 上约 90 秒，旧 GPU 上可能长达约 1 小时）；命名卷 trt-cache 会保留这些引擎，让后续每次重启都瞬间完成。

docker volume create trt-cache

docker run --gpus all -p 8000:8000 -p 50051:50051 \
  -v trt-cache:/home/ocr/.cache/turbo-ocr \
  ghcr.io/aiptimizer/turboocr:latest

HTTP 监听 8000（nginx 前置 Drogon，用于缓冲慢客户端），gRPC 监听 50051。两种协议共享同一个 GPU 流水线池——可以在同一容器中同时对外提供。

用 TRT_OPT_LEVEL 加速首次构建

引擎构建默认采用最高优化级别（TRT_OPT_LEVEL=5，运行最快）。在慢 GPU 上，设 TRT_OPT_LEVEL=3 可把这次性的构建时间缩短 3–5×，仅带来很小（<5%）的运行回退。该级别是引擎缓存键的一部分，因此修改它会触发一次重建。

CPU 镜像

CPU 镜像是无 NVIDIA GPU 主机的直接回退方案。它使用 ONNX Runtime 替代 TensorRT，基础镜像是普通的 ubuntu:24.04，对外暴露同一套 HTTP API。

docker run -p 8000:8000 \
  ghcr.io/aiptimizer/turboocr-cpu:v3.1.0

警告

吞吐为个位数 张/秒，而单卡 RTX 5090 上最高约 556 张/秒。CPU 构建用于本地开发、CI 与集成测试，不适合承载生产流量。

TensorRT 缓存卷

TensorRT 引擎与语言包位于容器内的 /home/ocr/.cache/turbo-ocr。请将该路径以命名卷的方式挂载——不要使用主机 bind-mount。

docker volume create trt-cache
docker run --gpus all -p 8000:8000 -p 50051:50051 \
  -v trt-cache:/home/ocr/.cache/turbo-ocr \
  ghcr.io/aiptimizer/turboocr:latest

为什么要用命名卷。 镜像把 /app/models/rec 软链到该缓存目录，使非默认语言包也存放其中。若把空的主机目录 bind-mount 到这里，会覆盖镜像内置的语言包，服务器将无可加载之物。命名卷在首次使用时会从镜像自动填充——这正是你需要的行为。

如果你删除该卷。 下次启动会从 ONNX 重新编译全部 TensorRT 引擎（约 90 秒），并重新解压内置语言包。不会丢数据，只是冷启动慢一些。

模型选择

启动时设置环境变量 OCR_MODEL。所有模型都在构建阶段从固定版本的 PaddleOCR release 烘焙进镜像，运行时无需任何下载。

docker run --gpus all -p 8000:8000 -p 50051:50051 \
  -v trt-cache:/home/ocr/.cache/turbo-ocr \
  -e OCR_MODEL=medium \
  ghcr.io/aiptimizer/turboocr:latest

PP-OCRv6 档位 tiny（默认）/ small / medium 覆盖拉丁文 + 中文 + 日文，以精度换速度。其他文字通过同一变量使用保留的 PP-OCRv5 识别模型：arabic、eslav（西里尔文）、korean、thai、greek。OCR_LANG 仍可用，但作为已弃用的别名（使用时会警告）。完整说明见配置页面。

Web GUI（Studio）

仓库自带一个浏览器 UI——拖入一张图片或 PDF，运行 OCR，查看版面叠加层与阅读顺序，选中识别出的文本，并下载可搜索的 PDF。它作为第二个容器运行，把 /api/* 代理到 OCR 服务，因此浏览器保持同源，服务端无需 CORS。

在源码仓库根目录：

# GPU
docker compose -f docker-compose.demo.yml up --build

# CPU（开发/CI）
docker compose -f docker-compose.demo.cpu.yml up --build

然后打开 **http://localhost:3000**。demo compose 已开启 TABLE_BACKEND=slanext 和 FORMULA_BACKEND=ppformulanet_s，表格与公式端到端可用。OCR 服务仍可在 http://localhost:8000 上用 curl 直接访问。

持久连接

警告

请使用 HTTP keep-alive。 每次请求都开一个短连接（例如循环里反复调用 curl）会把服务器打懵，甚至导致挂起。所有主流 HTTP 客户端（requests.Session、aiohttp、httpx.Client、JDK HttpClient、Go http.Client、带长生命周期句柄的 libcurl）默认都会复用连接，前提是你复用客户端对象。不要每次请求都新建客户端。

镜像内已用 nginx 前置 Drogon 来缓冲慢客户端，但 nginx 救不了一个为每次请求都新建 TCP 连接的客户端。Python、Java 和 C++ 的可运行示例见客户端指南。

监控

Prometheus 指标

抓取 GET /metrics 即可获取 Prometheus 兼容的指标。服务器按路由暴露请求计数器、延迟直方图、显存占用以及流水线池饱和度：

turbo_ocr_requests_total{route="/ocr/raw",status="2xx"} 1042
turbo_ocr_request_duration_seconds_bucket{route="/ocr/raw",le="0.025"} 980
turbo_ocr_request_duration_seconds_sum{route="/ocr/raw"} 12.345
turbo_ocr_request_duration_seconds_count{route="/ocr/raw"} 1042
turbo_ocr_gpu_vram_used_bytes 9052815360
turbo_ocr_gpu_vram_total_bytes 33661911040
turbo_ocr_pipeline_pool_size 5
turbo_ocr_pool_exhaustions_total 0
turbo_ocr_request_bytes_total 49493243
turbo_ocr_request_body_avg_bytes 9407

提示

盯紧 turbo_ocr_pool_exhaustions_total。非零意味着客户端在流水线池排队——要么调大 PIPELINE_POOL_SIZE，要么扩副本。延迟直方图按路由分桶，可以为每个端点独立设定 SLO。

健康探针

端点	用途
GET /health	基础存活检查——返回 "ok"。
GET /health/live	Kubernetes liveness 探针。进程拉起后即返回 200。
GET /health/ready	readiness 探针。仅当 GPU 流水线通过冒烟测试后才返回 200——以此控制流量准入。

从源码构建

如需本地构建、定制 CUDA 目标或离网部署，请查看 GitHub 仓库中的构建说明。docker/ 下的 Dockerfile 是权威参考；README 的「Building from Source」章节列出了 GPU 与 CPU 目标的全部依赖与 CMake 调用方式。

配置 所有环境变量：语言包、流水线池大小、PDF 并行度、日志。

客户端 可直接上线的 Python、Java、C++ 范例 —— 持久连接、并发分发、gRPC。