# PaddleOCR-VL-1.6 GPU 子项目

此目录是与根目录 CPU 版本隔离的 GPU 实验环境。

> **验证状态：未在 NVIDIA GPU 上实测。** 当前开发机器只有集成显卡，无法运行 CUDA。代码仅完成静态检查；最终安装、兼容性和性能必须在目标 NVIDIA GPU 机器上验证。

## 为什么独立环境

`paddlepaddle` 与 `paddlepaddle-gpu` 都提供 `paddle` 模块，不能安全共用同一个虚拟环境。本目录具有独立的：

- `pyproject.toml`
- `.python-version`（Python 3.11）
- `.venv`（执行安装后生成）
- `uv.lock`（在目标 GPU 机器安装后生成）

根目录 CPU 环境不会被修改。

## 前置条件

1. NVIDIA CUDA GPU（Intel/AMD 集成显卡不能运行 Paddle CUDA 版本）
2. 兼容的 NVIDIA 驱动
3. Python 3.11
4. uv
5. 根据 PaddlePaddle 官方兼容表选择 CUDA Wheel

先检查目标机器：

```bash
nvidia-smi
```

`nvidia-smi` 显示的 CUDA Version 是驱动支持上限，不等同于本机安装的 CUDA Toolkit，也不能单独用于判断 Wheel 版本。

## 安装

在仓库根目录运行：

```bash
# 只查看将执行的命令，不安装
python gpu/setup_env.py --cuda cu118 --dry-run

# CUDA 11.8 Wheel
python gpu/setup_env.py --cuda cu118

# 或 CUDA 12.6 Wheel
python gpu/setup_env.py --cuda cu126
```

安装脚本将在 `gpu/.venv` 创建独立环境。若官方 Wheel 支持范围发生变化，请同步更新 `gpu/pyproject.toml` 与 `gpu/setup_env.py`。

## 验证环境

```bash
uv run --project gpu python gpu/verify_env.py
```

该脚本会检查：

- PaddlePaddle 是否为 CUDA 构建
- CUDA GPU 数量及名称
- `gpu:0` 是否能完成矩阵乘法

任何检查失败都会以非零状态退出，不会自动回退到 CPU。

## 单图 Benchmark

```bash
uv run --project gpu python gpu/main.py
```

常用参数：

```bash
uv run --project gpu python gpu/main.py \
  --image images/手写01.png \
  --device-id 0 \
  --warmup 1 \
  --rounds 3
```

Windows PowerShell 可写为单行，或使用反引号续行。

Benchmark 会记录：

- GPU 型号和设备编号
- Python/PaddlePaddle 版本
- 模型初始化耗时
- 预热和正式推理轮数
- min/max/mean/median/stdev
- 可获取时的 CUDA 显存统计
- 图片尺寸和文本块数量

结果写入：

```text
benchmarks/gpu/gpu-benchmark-YYYYMMDD-HHMMSS.json
```

## PDF OCR

GPU PDF 入口复用仓库根目录 `pdf_ocr_core.py`，按页渲染、逐页保存并支持断点续传：

```bash
uv run --project gpu python gpu/pdf_ocr.py documents/sample.pdf \
  --device-id 0 \
  --pages "1-10" \
  --dpi 144
```

常用选项：

```bash
# 中断后继续
uv run --project gpu python gpu/pdf_ocr.py documents/sample.pdf --resume

# 删除现有输出后重跑
uv run --project gpu python gpu/pdf_ocr.py documents/sample.pdf --overwrite

# 保留 PDF 页面的渲染 PNG
uv run --project gpu python gpu/pdf_ocr.py documents/sample.pdf --keep-rendered
```

无 CUDA 时脚本会立即退出，不会自动回落到 CPU。当前开发机器没有 NVIDIA GPU，因此此入口尚未完成 GPU 实机验证。

## 当前范围

当前实现单 GPU、单图 Benchmark 和单 GPU PDF 逐页 OCR。暂未实现 GPU 多进程批处理，原因是：

- 同一 GPU 上启动多个模型实例会重复占用显存
- 多进程通常不会线性提升单卡吞吐
- 容易引发显存不足和 CUDA 上下文争抢

后续应优先评估模型/pipeline 原生批处理能力，再决定是否增加多 GPU 或任务队列。