ocr-server/README_GPU.md

GPU 推理部署指南

配置参数

在 .env 文件中设置：

# 推理设备: cpu / cuda / dml / tensorrt
OCR_DEVICE=cpu

# GPU设备编号（多GPU时指定，默认0）
OCR_DEVICE_ID=0

# CPU线程数（仅 cpu 模式生效）
OCR_INTRA_THREADS=4
OCR_INTER_THREADS=2

---

方案一：CUDA（NVIDIA 显卡）

适用：有 NVIDIA 独立显卡（GTX/RTX/Quadro/Tesla 等）。

1. 确认显卡支持 CUDA

nvidia-smi

确保 CUDA Version >= 11.8。

2. 安装 CUDA Toolkit 和 cuDNN

方法A（推荐）：直接安装 onnxruntime-gpu

onnxruntime-gpu 已内置必要的 CUDA/cuDNN 依赖（Windows 上通过 DirectML 或 CUDA EP）：

pip uninstall onnxruntime
pip install onnxruntime-gpu

方法B：手动安装 CUDA + cuDNN

1. 下载 CUDA Toolkit 11.8
2. 下载 cuDNN 8.x for CUDA 11.x
3. 安装后将 cuDNN 的 bin/lib/include 复制到 CUDA 安装目录

3. 配置 .env

OCR_DEVICE=cuda
OCR_DEVICE_ID=0

4. 验证

启动服务后查看日志：

推理设备: CUDA (device_id=0)

或用 Python 测试：

import onnxruntime as ort
print(ort.get_available_providers())
# 应包含: ['CUDAExecutionProvider', 'CPUExecutionProvider']

---

方案二：DirectML（Windows 任意 GPU）

适用：Windows 系统，任意显卡（NVIDIA/AMD/Intel 核显），无需安装 CUDA。

1. 安装 onnxruntime-directml

pip uninstall onnxruntime
pip install onnxruntime-directml

2. 配置 .env

OCR_DEVICE=dml

3. 验证

import onnxruntime as ort
print(ort.get_available_providers())
# 应包含: ['DmlExecutionProvider', 'CPUExecutionProvider']

注意：首次推理时 ONNX Runtime 会编译 DML 算子，可能耗时 10-30 秒，后续推理恢复正常速度。

4. 核显部署机（无独显）完整流程

开发机与部署机分离时，部署机常为只有核显的轻薄本/迷你主机。核显同样支持 DirectML 加速（Intel UHD / Iris Xe、AMD Radeon 核显均满足），无需任何 NVIDIA/AMD 驱动层面的额外配置。

前置条件

项目	要求
系统	Windows 10 1903（Build 18362）及以上（RapidOCR 会检查，不满足则自动回退 CPU）
显卡	支持 DirectX 12 的核显（现代 Intel/AMD 核显均满足）
Python	3.10+

全新环境安装

# 1. 安装项目依赖
pip install -r requirements.txt

# 2. 安装 DirectML 后端（替换掉 rapidocr 自带的 CPU 版 onnxruntime）
pip uninstall onnxruntime
pip install onnxruntime-directml

# 3. 验证后端可用
python -c "import onnxruntime as ort; print(ort.get_available_providers())"
# 应输出: ['DmlExecutionProvider', 'CPUExecutionProvider']

配置 .env

OCR_DEVICE=dml
# OCR_INTRA_THREADS / OCR_INTER_THREADS 仅 cpu 模式生效，dml 模式无需设置

启动并验证

uvicorn main:app --host 0.0.0.0 --port 8000

• 启动日志应出现 推理设备: DirectML
• 首次识别会编译着色器，等待 30-60 秒属正常现象，之后恢复正常速度

核显加速预期

场景	说明
加速比	约为 CPU 的 1.5-3 倍（Intel Iris Xe 单张 A4 约 1-2s）
CPU 较强的机器	核显与 CPU 共享内存带宽，加速比更接近下限 1.5x
双显卡机器	DML 使用系统默认适配器（通常为独显）；当前代码未将 OCR_DEVICE_ID 透传给 DML，该参数对 dml 模式不生效

---

方案三：TensorRT（NVIDIA 显卡，极致性能）

适用：追求最快推理速度的 NVIDIA GPU 用户。

1. 安装依赖

pip uninstall onnxruntime
pip install onnxruntime-gpu

# 安装 TensorRT
pip install tensorrt
# 或从 NVIDIA 官网下载: https://developer.nvidia.com/tensorrt

2. 配置 .env

OCR_DEVICE=tensorrt
OCR_DEVICE_ID=0

3. 首次运行

TensorRT 首次加载模型时需要构建 engine（耗时 30 秒到几分钟），之后会缓存到默认模型目录。

---

方案四：OpenVINO（Intel CPU/GPU）

如果你使用 Intel CPU（特别是第 10 代及更新），OpenVINO 比默认 ONNX Runtime CPU 更快。

1. 安装

pip install openvino

2. 修改 engine/ocr_engine.py

在 _build_device_params() 中添加 OpenVINO 分支（目前代码模板已预留结构）。

---

性能预期

设备	单张 A4 耗时	vs CPU	适用场景
CPU (i7-12700)	~2-5s	基准	低并发、开发调试
CUDA (RTX 3060)	~0.3-0.8s	3-8x	生产环境 NVIDIA GPU
DirectML (RTX 3060)	~0.5-1.0s	2-5x	Windows 任意 GPU
DirectML (Intel Iris Xe)	~1-2s	1.5-3x	轻薄本核显
TensorRT (RTX 3060)	~0.15-0.4s	5-15x	高吞吐生产环境

---

故障排查

CUDA 模式下报错 "CUDAExecutionProvider not found"

# 确认安装了 onnxruntime-gpu
pip show onnxruntime-gpu

# 确认 CUDA 可用
python -c "import onnxruntime; print(onnxruntime.get_available_providers())"

DirectML 下首次推理卡住

首次推理需要编译着色器，等待 30-60 秒即可。后续推理恢复正常。

GPU 显存不足

服务使用整图 OCR。如果处理大图时出现 OOM：

• 在调用服务前降低输入图片分辨率
• 降低并发请求数量
• 或降低 .env 中 OCR_REC_BATCH_NUM 的值

多 GPU 环境

设置 OCR_DEVICE_ID 指定使用哪张卡：

OCR_DEVICE=cuda
OCR_DEVICE_ID=1    # 使用第2张GPU