build: CPU/GPU 双环境、产物命名与打包修复

交付:
  · 产物按变体命名:CPU -> dist/ocr-server/,GPU -> dist/ocr-server-gpu/。
    变体由构建环境实际装的 paddle 自动判断,不需要人工声明
  · GPU 包额外加 --collect-binaries nvidia。漏收的后果实测是最难查的那种:
    引擎能正常加载、设备也识别成 GPU,但第一次推理才报
    cudnn64_9.dll error 126
  · --copy-metadata 的发行包名随变体变化(paddlepaddle / paddlepaddle-gpu),
    改由 scripts/paddle_env.py 动态取;写死任何一个在另一种环境下都打不出包
  · 新增 scripts/prepare_release_config.py 按变体覆盖发布配置(用 Python 改写
    以保持 UTF-8,PowerShell 的 Set-Content 会把中文注释写坏)

环境:
  · paddle 从 pyproject 依赖里移除,改用 scripts/install_paddle.py 安装。
    它没法写死:CPU/GPU 互斥,GPU 还得按显卡选 CUDA 通道(RTX 50 系必须 cu129)。
    钉死 CPU 版时,uv sync / uv run / PyCharm 自动同步都会把装好的
    paddlepaddle-gpu 静默挤掉、服务悄悄退回 CPU(实测踩过三次)
  · 新增 scripts/switch_env.py:.venv(CPU)与 .venv-gpu(GPU)两套环境共存,
    切换零成本;所有 uv run 补 --no-sync,打包改用 uv sync --inexact
  · 预置模型扩到 8 套(v4/v5 × 服务端/移动端 × 检测/识别,约 398MB)

其它:
  · scripts/start.* 先找发布包再退回源码环境;入口脚本名固定是 ocr-server
  · benchmark_ocr.py 输出 segments 与 chars,换设备/模型时可直接比对召回
  · .gitignore 覆盖 .venv-gpu/ 与 dist*/

Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
zimoyin
2026-10-14 03:53:48 +08:00
parent 09ab14c707
commit 5ab4bef80e
18 changed files with 1366 additions and 306 deletions
+456 -46
View File
@@ -47,7 +47,7 @@ models/official_models/PP-OCRv5_server_rec
默认模型目录是项目根目录下的 `models`,可以直接修改项目根目录的 `config.yaml`:
```yaml
model_dir: /opt/ocr-server/models
model_dir: /opt/ocr-server-gpu/models
```
配置文件中的路径支持绝对路径,也支持相对于项目根目录的路径。服务启动时读取一次配置,修改后需要重启服务。
@@ -79,40 +79,42 @@ uv run python scripts/download_models.py
## 不同速度档位和模型选择
当前项目默认使用 PP-OCRv5 中文服务模型:
当前项目默认使用 **v5 检测 + v4 移动端识别** 的组合:
```yaml
det_model_name: PP-OCRv5_server_det
rec_model_name: PP-OCRv5_server_rec
rec_model_name: PP-OCRv4_mobile_rec
```
PaddleOCR 还提供更小的移动端模型,但 PP-OCRv5 中文识别模型当前默认映射为 `PP-OCRv5_server_rec`;不要只把检测模型替换成其他版本而保持识别模型不变,模型版本和配套模型应成套切换。
检测与识别可以独立指定,允许跨代际混用(本项目实测有效,见「推荐搭配」一节)。
`scripts/download_models.py` 已预置四套模型,切换时不需要联网。
| 档位 | 检测模型 | 识别模型 | 特点 |
| --- | --- | --- | --- |
| 速度优先 | PP-OCRv4_mobile_det | PP-OCRv4_mobile_rec | 体积和 CPU 推理开销更小,但不是 PP-OCRv5,中文准确率可能下降 |
| 当前默认 | PP-OCRv5_server_det | PP-OCRv5_server_rec | 中文准确率优先,模型约 166 MB |
| 新版模型 | PP-OCRv6_medium_det | PP-OCRv6_medium_rec | 需要单独下载并验证,模型版本不是 PP-OCRv5 |
| 低配 CPU | PP-OCRv5_mobile_det | PP-OCRv4_mobile_rec | 检测仅约 5MB,资源紧张时用 |
| **当前默认** | PP-OCRv5_server_det | PP-OCRv4_mobile_rec | 保召回 + 识别快 8 倍,约 96MB |
| 有 GPU | PP-OCRv5_server_det | PP-OCRv5_server_rec | 精度优先,配 `device: gpu` + `use_tensorrt` |
| 速度优先(会丢字)| PP-OCRv4_mobile_det | PP-OCRv4_mobile_rec | ⚠️ v4 移动端检测在密集图上丢字约 90%,仅适合文本稀疏的图 |
切换前建议:
1. 先把当前 `models/` 完整复制成独立备份,例如 `models.backup-ppocrv5/`;
2. 将新模型下载到另一个目录,例如 `models-ppocrv4-mobile/`;
3. 只修改 `config.yaml` 的 `model_dir` 和两个模型名称;
4. 用 `scripts/benchmark_ocr.py` 和真实业务图片对比耗时、漏检率和准确率;
5. 验证不满意时,把 `model_dir` 改回原目录即可,不改动原模型。
1. 先用 `scripts/benchmark_ocr.py` 和**真实业务图片**对比耗时、漏检率和**字符数**;
2. 只修改 `config.yaml` 的两个模型名(模型已预置,无需改 `model_dir`);
3. 验证不满意时,把模型名改回原值即可,不改动任何模型文件。
当前没有自动下载或替换任何小模型,也没有修改现有 PP-OCRv5 权重。服务只读加载模型;若要切换模型,必须使用新的模型目录或先制作备份。
服务只读加载模型,不会修改权重。模型文件不在 git 里(`.gitignore` 已排除 `models/`),
但打包脚本会自动把 `models/` 复制进发布目录。
### 当前推荐配置(实测最快且保召回)
```yaml
det_model_name: PP-OCRv5_server_det # 检测保持 v5,保证召回
rec_model_name: PP-OCRv4_mobile_rec # 识别换移动端,快约 8 倍
cpu_threads: max # 吃满逻辑核心
enable_mkldnn: true # 依赖 paddlepaddle 3.2.x
text_recognition_batch_size: 8
text_det_limit_side_len: 512
rec_model_name: PP-OCRv4_mobile_rec # 识别换移动端,快约 8 倍
enable_mkldnn: true # 依赖 paddlepaddle 3.2.x
text_recognition_batch_size: 32 # 1.png 实测 23.87s -> 19.03s,输出不变
text_det_limit_side_len: 1024 # 比 640 多召回约 28% 字符
cpu_threads: 1 # 开 oneDNN 后几乎无影响,省核给 worker
ocr_workers: 1 # 有并发上传时按核数加大
```
叠加效果(1.png,1920x1080,339 个文本框;经服务完整路径实测):
@@ -125,6 +127,24 @@ text_det_limit_side_len: 512
**提速约 28 倍,而框数与字符数与精度优先档基本一致**,召回没有损失。
在这之上再调 `text_recognition_batch_size`(上表是 side=512 的数据,下表统一用
当前默认的 side=1024,同一台机器、同一张 1.png):
| batch | 耗时 | 框数 | 字符数 |
| --- | --- | --- | --- |
| 8 | 23.87s | 428 | 2240 |
| 16 | 21.62s | 428 | 2241 |
| **32** | **19.03s** | 428 | 2241 |
| 64 | 18.32s | 428 | 2238 |
**框数完全一致,字符数只差 1~3 个**,调到 32 就能拿到大部分收益;换成 `64` 只再多省
0.7 秒,已经饱和。
⚠️ 注意批次大小**不是逐字节一致**的:同一张 1.png,`batch=8` 得 2240 字符、
`batch=32` 得 2241 字符;官方样例图则是 253 → 250。逐条对比后确认,差异只出现在
**英文分词空格**(`日期 DATE` → `日期DATE`)和个别低置信字符(`高级搜索>` → `高级搜索>>`)上,
正文中文没有差异。切换 batch 仍建议核对一下真实图片的字符数。
同一配置下另外两张图(完整服务路径):
| 图片 | 耗时 | 框数 | 字符数 |
@@ -132,26 +152,44 @@ text_det_limit_side_len: 512
| 2.png (1920x1080) | 7.49s(原 213.52s) | 73 | 430 |
| general_ocr_002.png (896x528) | 8.01s(原 70.45s) | 35 | 245 |
### cpu_threads 取 max 的含义
### cpu_threads:开启 oneDNN 之后几乎不影响耗时
```yaml
cpu_threads: max # = os.cpu_count(),本机 20 逻辑核 → 20
cpu_threads: 8 # 也可以直接写具体数字
cpu_threads: 1 # 当前默认
```
`max` 是「省心」选项,**不保证最快**:本机为 20 逻辑核 / 14 物理核,超过物理核心数后超线程会争抢,收益递减,还会挤占同机其它服务。建议用 `benchmark_ocr.py` 实测 8 / 14 / max 三档再定。
**⚠️ 本节结论已更新。** 早期(未启用 oneDNN 时)确实需要靠线程数提性能,
但启用 oneDNN 后识别推理本身就已是多线程,再加线程不再获益。官方样例图
(896×528) 实测:
```text
cpu_threads=1 -> 7.25s
cpu_threads=4 -> 6.82s
cpu_threads=8 -> 7.22s
cpu_threads=14 -> 7.29s
cpu_threads=20 -> 7.25s
```
差异全部落在测量噪声内。所以**保持 `1` 即可**,把省下的核留给
`ocr_workers`(并发吞吐)或同机其它服务。
### 不换模型的加速方式
先尝试以下配置,不会修改模型文件:
不用换模型、不用动模型文件,先调这几个参数(按收益排序):
```yaml
text_det_limit_side_len: 640
text_recognition_batch_size: 1
ocr_workers: 1
text_recognition_batch_size: 32 # 首选。1.png 实测 23.87s -> 19.03s,输出不变
text_det_limit_side_len: 768 # 其次。省约 3s,字符数约 -2%
ocr_workers: 4 # 只在有并发上传时才有效,每个 worker 约 +105MB
```
`text_det_limit_side_len` 从 `960` 调到 `640` 通常可以降低检测耗时,但小字可能漏检。`text_recognition_batch_size` 主要影响单张图片包含很多文本框时的吞吐;增大到 `2` 或 `4` 会增加内存,单张简单图片不一定更快。
`text_recognition_batch_size` 是性价比最高的旋钮:框越多收益越大,识别框数不变,
字符数只差 1~3 个(差异仅限英文分词空格与个别低置信字符)。调到 `32` 就能拿到
大部分收益,再往上饱和。
`text_det_limit_side_len` 主要影响检测耗时,调小会漏检小字,属于拿召回换速度,
务必用真实图片对比字符数后再定。详见下方「text_det_limit_side_len 与文本密度强相关」。
## 日志与推理进度
@@ -433,10 +471,15 @@ rec_model_name: PP-OCRv4_mobile_rec
### 如何测速
```powershell
uv run python scripts/benchmark_ocr.py
uv run --no-sync python scripts/benchmark_ocr.py 你的图.png 3
```
修改 `config.yaml` 后重新执行,比较输出的 `elapsed_ms`。建议至少使用 10 张代表性图片,不要只根据一张图片决定模型或参数。
⚠️ **`--no-sync` 不能省**。`uv run` 默认会按 `pyproject.toml` 同步环境,而那里声明的是
CPU 版 `paddlepaddle`,会把装好的 `paddlepaddle-gpu` 静默冲掉——测出来的其实是 CPU 成绩。
修改 `config.yaml` 后重新执行,比较输出的 `elapsed_ms`、`segments`、`chars`。
建议至少使用 10 张代表性图片,不要只根据一张图片决定模型或参数;换模型或换设备时
**重点看 `segments` 和 `chars`**,只快不准是没用的。
## Python 版本说明
@@ -477,6 +520,21 @@ powershell -ExecutionPolicy Bypass -File .\scripts\start.ps1
# 或双击 scripts\start.bat
```
⚠️ **`start.*` 会优先跑 `dist\ocr-server\` 里的发布包**,找不到才退回源码(`.venv`)。
所以只要 `dist\` 里有旧包,**你改的源码就不会生效**,而且日志里看不出区别。
实测踩过一次:改了 `device` 相关的源码后启动,跑的还是几天前那个包,
配上新写的 `config.yaml`,直接崩在 PaddleX 内部。
判断方法看启动日志的 `model_dir`——指向 `dist\ocr-server\models` 就是跑的发布包:
```text
INFO [ocr_server] 启动 OCR 服务 ... model_dir=D:\...\dist\ocr-server\models ← 发布包
INFO [ocr_server] 启动 OCR 服务 ... model_dir=D:\code\work\ocr-server\models ← 源码
```
改完源码要立刻验证,直接跑 `.venv\Scripts\ocr-server.exe`(Windows)或
`.venv/bin/ocr-server`(Linux),绕过发布包;要跑发布包就先重新打包。
Windows 打包为 exe:
```powershell
@@ -529,13 +587,15 @@ uv run python -m uvicorn ocr_server.app:app --host 0.0.0.0 --port 8000
sudo apt-get update
sudo apt-get install -y curl libgl1 libglib2.0-0
cd /opt/ocr-server
cd /opt/ocr-server-gpu
curl -LsSf https://astral.sh/uv/install.sh | sh
# 重新打开 shell,或按安装提示加载 ~/.local/bin
uv python install 3.12
uv sync --python 3.12
# paddle 不在依赖里,需按机器单独装一次;没有显卡就是 CPU 版
.venv/bin/python scripts/install_paddle.py
# 按需修改项目根目录 config.yaml,然后启动
uv run ocr-server
uv run --no-sync ocr-server
```
如果服务器不能访问模型下载源,请在联网机器上执行 `scripts/download_models.py`,将完整项目的 `models/` 目录复制到 Ubuntu 服务器,再启动服务。依赖安装仍需要提前完成;完全离线安装还需要准备本地 Python wheel 缓存。
@@ -546,13 +606,14 @@ uv run ocr-server
python3.10 -m venv .venv
.venv/bin/python -m pip install -U pip
.venv/bin/python -m pip install -e .
.venv/bin/python scripts/install_paddle.py
.venv/bin/ocr-server
```
Ubuntu 源码启动:
```bash
cd /opt/ocr-server
cd /opt/ocr-server-gpu
uv sync --python 3.12
chmod +x scripts/start.sh
./scripts/start.sh
@@ -561,25 +622,32 @@ chmod +x scripts/start.sh
Ubuntu 22.04 打包为原生 ELF 二进制:
```bash
cd /opt/ocr-server
cd /opt/ocr-server-gpu
chmod +x scripts/package-ubuntu.sh
./scripts/package-ubuntu.sh
./scripts/package-ubuntu.sh # CPU 包 -> dist/ocr-server/
./scripts/package-ubuntu.sh --gpu # GPU 包 -> dist/ocr-server-gpu/
```
发布目录:
发布目录(CPU 版与 GPU 版的目录名不同,一眼能分辨):
```text
dist/ocr-server/
dist/ocr-server/ # CPU 版
├── ocr-server
├── config.yaml
└── models/
dist/ocr-server-gpu/ # GPU 版,另有 _internal/nvidia/ 下的 CUDA 运行库
├── ocr-server-gpu
├── config.yaml
└── models/
```
启动:
```bash
./dist/ocr-server/ocr-server
# 或:./scripts/start.sh
./dist/ocr-server/ocr-server # CPU 版
./dist/ocr-server-gpu/ocr-server-gpu # GPU 版
# 或:./scripts/start.sh(优先 CPU 包,再 GPU 包,最后源码)
```
Windows 不能直接生成 Ubuntu ELF 二进制。`package-ubuntu.sh` 必须在 Ubuntu/Linux 构建机执行;Windows 使用 `package-windows.ps1` 生成 exe。两个平台的发布包不能混用,建议分别构建、分别测试。
@@ -898,19 +966,27 @@ port: 8000
upload_dir: data/uploads
model_dir: models
det_model_name: PP-OCRv5_server_det
rec_model_name: PP-OCRv5_server_rec
rec_model_name: PP-OCRv4_mobile_rec
ocr_workers: 1
device: cpu
lang: ch
max_upload_mb: 10
max_image_pixels: 20000000
text_det_limit_side_len: 960
text_det_limit_side_len: 1024
text_det_limit_type: max
text_det_input_shape: null
text_det_thresh: 0.3
text_det_box_thresh: 0.6
text_det_unclip_ratio: 1.5
text_rec_score_thresh: 0.0
text_recognition_batch_size: 1
text_rec_input_shape: null
text_recognition_batch_size: 32
cpu_threads: 1
enable_mkldnn: true
mkldnn_cache_capacity: 10
use_tensorrt: false
precision: fp32
enable_cinn: false
log_level: INFO
```
@@ -921,25 +997,359 @@ log_level: INFO
| `upload_dir` | `data/uploads` | 图片存储目录 |
| `model_dir` | `models` | PaddleOCR 模型下载和缓存目录 |
| `det_model_name` | `PP-OCRv5_server_det` | 文本检测模型名称 |
| `rec_model_name` | `PP-OCRv5_server_rec` | 文本识别模型名称 |
| `ocr_workers` | `1` | OCR 工作线程数;每个线程独立加载一份模型 |
| `rec_model_name` | `PP-OCRv4_mobile_rec` | 文本识别模型名称 |
| `ocr_workers` | `1` | OCR 工作线程数;每个 worker 独立加载一份模型(约 +105MB/个) |
| `max_upload_mb` | `10` | 单文件大小上限 |
| `max_image_pixels` | `20000000` | 图片像素上限 |
| `device` | `cpu` | `cpu` 或 GPU 设备配置 |
| `device` | `cpu` | `cpu` / `gpu` / `gpu:0` / `auto` / `npu` 等,见「CPU / GPU 切换」 |
| `lang` | `ch` | PaddleOCR 语言 |
| `text_det_limit_side_len` | `960` | 检测图像最长边;调小可加速,可能漏检小字 |
| `text_det_limit_side_len` | `1024` | 检测图像最长边;调小可加速,代价是漏检小字 |
| `text_det_limit_type` | `max` | 检测缩放限制类型 |
| `text_det_input_shape` | `null` | 固定检测输入尺寸(如 `[3, 960, 960]`);`null` 表示动态缩放 |
| `text_det_thresh` | `0.3` | 检测二值化阈值 |
| `text_det_box_thresh` | `0.6` | 检测框置信度阈值 |
| `text_det_unclip_ratio` | `1.5` | 检测框扩张比例 |
| `text_rec_score_thresh` | `0.0` | 识别结果阈值 |
| `text_recognition_batch_size` | `1` | 识别批量大小;内存足够时可提高 |
| `cpu_threads` | `max` | CPU 推理线程数;正整数或 `max`(`max` = 吃满所有逻辑核心) |
| `text_rec_input_shape` | `null` | 固定识别输入尺寸(如 `[3, 48, 320]`);`null` 表示按宽高比填充 |
| `text_recognition_batch_size` | `32` | 识别批量大小;**性价比最高的旋钮**,见下方说明 |
| `cpu_threads` | `1` | CPU 推理线程数;正整数或 `max`。开 oneDNN 后该值几乎无影响 |
| `enable_mkldnn` | `true` | 是否启用 oneDNN 加速;**需要 `paddlepaddle` 3.2.x**,见下方说明 |
| `mkldnn_cache_capacity` | `10` | oneDNN 算子缓存容量,仅 `enable_mkldnn: true` 时生效 |
| `use_tensorrt` | `false` | 是否启用 TensorRT;**只在 `device` 为 GPU 时生效** |
| `precision` | `fp32` | `fp32` / `fp16`;`fp16` 只在 GPU 上生效 |
| `enable_cinn` | `false` | 是否启用 CINN 编译器(面向国产加速卡);普通 CPU/GPU 保持 `false` |
| `log_level` | `INFO` | 日志级别:`DEBUG`、`INFO`、`WARNING`、`ERROR` |
接口文档:启动后访问 <http://127.0.0.1:8000/docs>。
### 调优参数速查(按收益排序)
| 参数 | 怎么调 | 实测收益 |
| --- | --- | --- |
| `text_recognition_batch_size` | `8` → `32` | 1.png 同分辨率 **23.87s → 19.03s**,框数不变,字符数 2240 → 2241 |
| `text_det_limit_side_len` | `1024` → `768` | 19s → 16s,字符数从 2240 降到 2191(约 −2%) |
| `ocr_workers` | 按并发量加大 | 推理接近单线程,并发上传时吞吐接近线性;每个 worker 约 +105MB 内存 |
| `cpu_threads` | 保持 `1` | 开了 oneDNN 之后 1/4/8/14/20 差异都在噪声内 |
| `device` / `use_tensorrt` | 有 NVIDIA 卡时改 GPU | 需换 `paddlepaddle-gpu`,见「CPU / GPU 切换」 |
### CPU / GPU 切换
```yaml
device: cpu # 默认。固定用 CPU,永远不碰 GPU
device: gpu # 固定用第 0 块卡
device: gpu:1 # 固定用第 1 块卡
device: auto # 启动时探测:有可用 CUDA 设备就用 GPU,否则用 CPU
```
**推荐用 `auto`**:同一份 `config.yaml` 在「有卡的开发机」和「没卡的客户机」之间
搬来搬去不用改这一行,日志里会明确打出实际选了什么:
```text
INFO [ocr_server.ocr] device=auto:检测到可用的 CUDA 设备,使用 GPU
INFO [ocr_server.ocr] device=auto:没有可用的 GPU(当前 PaddlePaddle 3.2.2 是纯 CPU 版本),使用 CPU
```
注意日志级别的区别:`auto` 探测不到卡是**预期行为**,报 INFO;
而显式写了 `device: gpu` 却用不了是**配置问题**,报 WARNING。
本机上三种取值的实际效果(有 RTX 5060,但装的是 CPU 版 paddle):
| 配置 | 实际使用 | 日志级别 |
| --- | --- | --- |
| `device: auto` | cpu | INFO |
| `device: cpu` | cpu | — |
| `device: gpu` | cpu(回落) | WARNING |
⚠️ **只改 yaml 是启不了 GPU 的。** PyPI 上的 `paddlepaddle` 是纯 CPU 版本,
需要换成 `paddlepaddle-gpu`:
```bash
# 先确认本机显卡型号和驱动版本
nvidia-smi
```
**先选对 CUDA 通道,选错装了也跑不起来**(见下表)。当前项目环境实测是
`paddlepaddle 3.2.2`(CPU 版),`is_compiled_with_cuda()` 为 `False`。
| 显卡 | 计算能力 | 该选哪个通道 |
| --- | --- | --- |
| RTX 50 系(5060 / 5070 / 5080 / 5090) | sm_120 Blackwell | **必须 `cu129`** |
| RTX 40 系 / 30 系 | sm_89 / sm_86 | `cu126` 或 `cu129` |
| 更老的卡 | ≤ sm_80 | `cu118` 也可以 |
⚠️ **RTX 50 系不能用 `cu118` / `cu126`**:这两个 wheel 的内核里没有 sm_120,
装上去会在第一次推理时抛
`Mismatched GPU Architecture: The installed PaddlePaddle package was compiled for 60 61 70 75 80 86, but your current GPU is 120`。
必须用 `cu129`,且 PaddlePaddle 版本要 ≥ 3.2.1。
### 两套环境共存,随时切换(推荐)
CPU 和 GPU **各用一套虚拟环境**,都建好之后切换是零成本的,不用卸载重装:
```bash
.venv/Scripts/python.exe scripts/switch_env.py --list # 查看两套环境的现状
.venv/Scripts/python.exe scripts/switch_env.py --cpu # 建立/更新 .venv(CPU)
.venv/Scripts/python.exe scripts/switch_env.py --gpu # 建立/更新 .venv-gpu(GPU)
```
```text
CPU 环境 .venv paddlepaddle==3.2.2 | CUDA 可用:False,GPU 数:0
GPU 环境 .venv-gpu paddlepaddle-gpu==3.2.2 | CUDA 可用:True,GPU 数:1
```
| 用途 | 命令 |
| --- | --- |
| 跑源码(CPU) | `.venv\Scripts\ocr-server.exe` |
| 跑源码(GPU) | `.venv-gpu\Scripts\ocr-server.exe` |
| 打 CPU 包 | `.\scripts\package-windows.ps1` |
| 打 GPU 包 | `$env:UV_PROJECT_ENVIRONMENT=".venv-gpu"; .\scripts\package-windows.ps1` |
之所以不做成「一个环境来回切」:`paddlepaddle` 与 `paddlepaddle-gpu` 互斥(都提供
`paddle` 顶层包和同一批文件),而且 GPU 版还要拖进约 **3.1GB** 的 CUDA 运行库,
反复装卸很浪费。代价是两套环境同时存在,磁盘多占约 4GB。
### 只要一套环境时
装的方式是用项目自带的脚本,它会读 `nvidia-smi` 自动判断装哪个版本和哪个 CUDA 通道:
```bash
uv run --no-sync python scripts/install_paddle.py # 有 N 卡就装 GPU 版,没有就装 CPU 版
uv run --no-sync python scripts/install_paddle.py --gpu # 强制 GPU 版,通道按显卡自动推荐
uv run --no-sync python scripts/install_paddle.py --cpu # 强制 CPU 版(顺带清掉 3GB 的 CUDA 库)
uv run --no-sync python scripts/install_paddle.py --gpu --dry-run # 只看方案,不动环境
```
想手工装也行,等价命令是:
```bash
uv pip uninstall paddlepaddle paddlepaddle-gpu
uv pip install "paddlepaddle-gpu==3.2.2" \
--extra-index-url https://www.paddlepaddle.org.cn/packages/stable/cu129/
```
> **为什么 `paddlepaddle` 不在 `pyproject.toml` 的依赖里?**
> 因为它没法写死:CPU 版和 GPU 版互斥(同一批 `paddle` 文件,装了会互相覆盖),
> GPU 版还要按显卡选 CUDA 通道。早先把它钉成 CPU 版时,`uv sync`、`uv run`、
> PyCharm 的自动同步都会把装好的 `paddlepaddle-gpu` 静默挤掉、服务悄悄退回 CPU——
> 实测踩过三次。
>
> 现在的取舍是:**任何一次环境同步都会把 paddle 整个移除**(连 `protobuf`、`opt-einsum`
> 这些依赖一起),服务启动时报错并告诉你运行 `install_paddle.py`。
> 会吵,但不会静默降级。**每次跑完 `uv sync` 记得重新执行一次 `install_paddle.py`。**
**注意:不要用 PyPI 上的 `paddlepaddle-gpu`**——它停在 2.6.2 且早已废弃,
装上去和本项目的 PaddleOCR 3.x / paddlepaddle 3.2.x 对不上。
只能用 PaddlePaddle 官方源,实测该源上 `cu118` / `cu126` / `cu129` 三个通道
都有 `paddlepaddle_gpu-3.2.2` 的 Windows 与 Linux 轮子。
⚠️ **RTX 50 系要留个心眼**:社区反馈 Blackwell 的预编译 wheel 支持还不够完整,
官方主要在 PaddleOCR-VL 上验证过(且只验证了 RTX 5070),经典 PP-OCR 推理管线
(也就是本项目用的这套)在部分平台仍有缺口,Windows 上尤其明显。
换完 wheel 后**务必先用 `benchmark_ocr.py` 跑通一次真实图片**再决定是否上 GPU;
跑不通就退回 CPU 包,不要卡在这里。
#### 装完之后能自由切换吗?能
GPU 版 wheel 里**同时带着完整的 CPU 内核**,PaddleX 在 `device` 为 cpu 时会显式
`config.disable_gpu()`,所以三种取值随时可切、不需要重装:
| 配置 | 行为 |
| --- | --- |
| `device: cpu` | 强制 CPU,走 oneDNN |
| `device: gpu` / `device: auto` | 走 GPU |
实测(RTX 5060 Laptop,paddlepaddle-gpu 3.2.2 cu129):
| 图片 | CPU | GPU | 加速 | 框数 | 字符数 |
| --- | --- | --- | --- | --- | --- |
| 1.png(1920×1080,428 框) | 17.45s | **1.44s** | **12×** | 428 → 428 | 2241 → 2241 |
| general_ocr_002.png(34 框) | 6.89s | **0.23s** | **30×** | 34 → 34 | 250 → 250 |
框数与字符数和 CPU **完全一致**——在这两张图上没有复现社区报告的 sm_120 静默丢框问题。
但**上线前必须用你自己的真实图片再核一遍**(尤其是扫描件 / PDF 渲染图,
社区那个 bug 正是在这类图上出现的,手机照片反而正常)。
#### ⚠️ `uv sync` / `uv run` 会把 GPU 环境悄悄冲掉
`pyproject.toml` 里声明的是 CPU 版 `paddlepaddle`。**裸跑 `uv sync` 或 `uv run`**
(`uv run` 启动前也会同步一次)的结果是**卸载 `paddlepaddle-gpu` 和全部
`nvidia-*` 运行库、装回 CPU 版**,而且不报错:
```text
Would uninstall 9 packages
- nvidia-cublas-cu12==12.9.0.13 ...(7 个 nvidia-* 运行库)
- paddlepaddle-gpu==3.2.2
+ paddlepaddle==3.2.2
```
项目里的脚本都已经处理好了:
| 场景 | 处理方式 |
| --- | --- |
| 打包脚本 | `uv sync --dev --inexact --no-install-package paddlepaddle`(实测 dry-run 为 no changes),其余 `uv run` 全部加了 `--no-sync` |
| 启动脚本 | 优先直接执行 `.venv` 里的入口程序,不经过 uv;不得已走 uv 时用 `uv run --no-sync` |
| `benchmark_ocr.py`、`download_models.py` | 命令里都要求带 `--no-sync` |
**但你自己手动敲 `uv sync` 或 `uv run` 时它照样会冲掉。** 装完 GPU 后如果发现
「怎么又变回 CPU 了」,先想想是不是跑过这两个命令。判断方法看启动日志:
```text
INFO [ocr_server.ocr] device=auto:检测到可用的 CUDA 设备,使用 GPU ← 正常
INFO [ocr_server.ocr] device=auto:没有可用的 GPU(当前 PaddlePaddle 3.2.2 是纯 CPU 版本)… ← 被冲掉了
```
(单独用 `--no-install-package paddlepaddle` 不够:它会把 `paddlepaddle-gpu` 当多余包删掉;
单独用 `--inexact` 也不够:它会装上 CPU 版造成两个发行包并存、文件互相覆盖。必须两个合用。)
#### 交付包:CPU / GPU 是两个产物
**光改配置在交付的 exe 包里是没用的**:PyInstaller 会把打包那一刻的 paddle 打进产物,
CPU 包无论客户怎么改 yaml 都用不了 GPU。所以交付时打两个包:
```powershell
# CPU 包 -> dist\ocr-server\ocr-server.exe
.\scripts\package-windows.ps1
# GPU 包 -> dist\ocr-server-gpu\ocr-server-gpu.exe
# 用 switch_env.py 建好的 GPU 环境来打,它会自动识别成 GPU 变体
$env:UV_PROJECT_ENVIRONMENT=".venv-gpu"
.\scripts\package-windows.ps1
```
```bash
# Linux 同理
./scripts/package-ubuntu.sh # CPU 包 -> dist/ocr-server/
./scripts/package-ubuntu.sh --gpu # GPU 包 -> dist/ocr-server-gpu/
```
打包脚本会自动做这几件事,不需要手工干预:
| 行为 | 说明 |
| --- | --- |
| 自动识别变体 | 按构建环境实际安装的 paddle 判断,不靠人工声明 |
| 产物名区分变体 | CPU → `dist/ocr-server/`,GPU → `dist/ocr-server-gpu/`,两个包不会互相覆盖 |
| 预置 `device` | GPU 包的 `config.yaml` 里 `device` 写成 `auto`:客户机有卡就用卡、没卡自动回落 CPU,两种机器都能直接跑 |
| `--copy-metadata` 用对发行包名 | CPU 版叫 `paddlepaddle`、GPU 版叫 `paddlepaddle-gpu`,写死任何一个在另一种环境下都会打包失败 |
| 环境不匹配直接报错 | 加 `-Gpu` / `--gpu` 断言时,如果构建环境装的是 CPU 版,脚本会带着安装命令报错退出 |
`-Gpu` / `--gpu` 只是**断言**,不是开关:不加该参数时脚本也按实际安装的版本判断。
⚠️ **不要指望 GPU 包能当 CPU 包用。** 运行时的兜底(`device: auto` / `device: gpu`)
只能兜住「能 import paddle、但拿不到 CUDA 设备」这一种情况。如果客户机上
根本没有 NVIDIA 的 CUDA 运行库,`paddlepaddle-gpu` 可能在 **import 阶段**就报错
(典型是缺 `libcublasLt.so.12` 这类),那时候我们的兜底代码还没机会执行。
PaddlePaddle 官方安装指南的口径也是「没有 NVIDIA GPU 就装 CPU 版」。
所以:**确定没卡的客户机,发 CPU 包**;不确定的,两个包都带上。
变体没有「强制」开关:产物里打进的就是构建环境当前的 paddle,改个名字不会改变这一点,
只会让包名和内容对不上。要打 CPU 包就换回 CPU 版 paddle 再打。
#### GPU 包必须额外收 nvidia 运行库(打包脚本已处理)
`paddlepaddle-gpu` 的 CUDA 运行库(cudnn / cublas / cufft 等)不在 `paddle` 包里,
而是装在**独立的 `nvidia-*` 发行包**里。PyInstaller 的 `--collect-all paddle` 收不到它们,
所以 GPU 包额外加了 `--collect-binaries nvidia`。
漏收的后果实测是**最难排查的那种**:引擎能正常加载、设备也正确识别成 GPU,
但第一次推理才报错:
```text
PreconditionNotMetError: The third-party dynamic library (cudnn64_9.dll)
that Paddle depends on is not configured correctly. (error code is 126)
```
收进来的落点是 `_internal/nvidia/<包>/bin/`,正好是 paddle 在 `__init__.py` 里用
`os.add_dll_directory(os.path.dirname(paddle.__file__) + "/../nvidia/<包>/bin")`
寻找的路径。
**体积**(实测):CPU 包约 1.0GB;GPU 包约 **5.0GB**,其中 3.1GB 是 CUDA 运行库
(cudnn 1.06GB、cublas 736MB、cusparse 456MB、cusolver 442MB、cufft 275MB…),
源目录本身就那么大,不是重复打包。要瘦身只能砍裁用不到的库,有运行时踩坑风险。
开启 GPU 后还可以叠加:
```yaml
device: gpu
use_tensorrt: true # TensorRT 加速,首次推理会花时间构建引擎
precision: fp16 # 半精度,更快、显存更省,但需核对字符数
```
**兜底行为**:如果配了 `device: gpu`(或 `auto`)但 GPU 实际不可用,
启动时会打印中文日志并**自动回落 CPU**,不会让服务起不来。
检查覆盖两种情况,不只是「装没装 GPU 版」:
- 装的是纯 CPU 版 paddle → 直接回落;
- 装的是 GPU 版但**机器上没有可用的 N 卡或驱动** → 也会回落
(这一点单查 `is_compiled_with_cuda()` 是查不出来的,那是编译期属性,
装了 GPU 版就返回 True,所以还要实际探一次可见设备数)。
上线前请确认启动日志里「加载 OCR 引擎」那一行打印的 `device=` 是你期望的值:
```text
WARNING [ocr_server.ocr] 配置 device=gpu,但 GPU 无法启用:当前 PaddlePaddle 3.2.2 是纯 CPU 版本。…
WARNING [ocr_server.ocr] use_tensorrt 已开启,但生效设备是 cpu;TensorRT 只在 GPU 上生效,本次忽略该项。
INFO [ocr_server.ocr] 加载 OCR 引擎: det=… rec=… device=cpu cpu_threads=1 …
```
同理,`use_tensorrt: true` 但设备是 CPU 时会打印警告并忽略该项
(TensorRT 只在 GPU 分支生效)。
#### 为什么不能照搬 ONNX Runtime 的调优文章
网上关于「PP-OCR 部署优化」的资料大多讲的是 **ONNX Runtime / TensorRT** 路线
(`intra_op_num_threads`、`providers`、`trt_max_workspace_size`、INT8 量化等)。
本项目走的是 **Paddle Inference**(`paddleocr` → `paddlex` → `paddlepaddle`),
模型格式和执行引擎都不一样,那些参数名在这里并不存在。对应关系:
| 常见文章里的说法 | 本项目实际参数 |
| --- | --- |
| `intra_op_num_threads` | `cpu_threads` |
| `inter_op_num_threads` | 无对应(Paddle 只有单一线程数) |
| `graph_optimization_level` | 无对应(Paddle 默认开启,`set_optimization_level(3)`) |
| `batch_size` | `text_recognition_batch_size` |
| `dynamic_shapes` | `text_det_limit_side_len`、`text_det_input_shape`、`text_rec_input_shape` |
| TensorRT + `trt_fp16_enable` | `use_tensorrt: true` + `precision: fp16` |
| `gpu_mem_limit` | 无对应(Paddle 用 `FLAGS_*` 环境变量控制) |
| INT8 量化、ONNX 导出 | 不适用(Paddle 需另建校准集走 `run_mode: trt_int8`) |
简单说:**照抄那些文章的代码在本项目里会直接报「不认识的参数」**,请以上表为准。
### 模型预置
`scripts/download_models.py` 会把交付包需要的八套模型一次性下载到
`model_dir/official_models/`,共约 398MB:
```bash
uv run python scripts/download_models.py
# 打包时 scripts/package-windows.ps1 / package-ubuntu.sh 会自动复制 models/ 进发布目录
```
**检测**
| 模型 | 体积 | 用途 |
| --- | --- | --- |
| `PP-OCRv5_server_det` | 85MB | 召回最好,密集小字靠它,默认用它 |
| `PP-OCRv5_mobile_det` | 5MB | 资源紧张时用(比 v4 移动端检测强得多) |
| `PP-OCRv4_server_det` | 109MB | v4 代际服务端,对比备选 |
| `PP-OCRv4_mobile_det` | 5MB | ⚠️ 密集文本大面积漏检(1.png 只检出 46 框),别用在表格/文档图上 |
**识别**
| 模型 | 体积 | 用途 |
| --- | --- | --- |
| `PP-OCRv5_server_rec` | 82MB | 精度最高,也最慢。GPU 机器上可用它冲精度 |
| `PP-OCRv5_mobile_rec` | 17MB | v5 代际移动端,速度与精度折中 |
| `PP-OCRv4_server_rec` | 87MB | v4 代际服务端,对比备选 |
| `PP-OCRv4_mobile_rec` | 11MB | 默认。密集文本字符数与 v5 服务端基本一致,快约 8 倍 |
八套都在本地之后,交付后**断网也能直接改 `det_model_name` / `rec_model_name` 切换**。
脚本会跳过已完整的目录,重复执行不会重新下载;上次下载中断留下的空壳目录(只含
`.cache`)会被自动清理。
体积提示:这八套会随发布包一起发给客户(约 398MB)。如果确定用不上某个代际,
可以从 `src/ocr_server/ocr.py` 的 `STAGED_DET_MODELS` / `STAGED_REC_MODELS`
里删掉再重新下载,打包时 `models/` 目录里没有的自然不会被带上。
## 测试
```bash