---
title: paddleocr-vl-cpu-demo
canonical_url: "https://www.modelscope.cn/studios/zhuoning/paddleocr-vl-cpu-demo"
md_url: "https://www.modelscope.cn/studios/zhuoning/paddleocr-vl-cpu-demo.md"
repository: zhuoning/paddleocr-vl-cpu-demo
chinese_name: songpanda2.3
last_updated: 2026-07-19
sdk_type: gradio
sdk_version: 4.44.0
downloads: 0
stars: 1
---

# paddleocr-vl-cpu-demo

> paddleocr-vl-cpu-demo - zhuoning 在 ModelScope 创建的在线 Demo。基于 PaddleOCR-VL-1.6 的 SongPanda 2.3 古汉语 OCR Demo，【PaddleOCR 全球衍生模型挑战赛】参赛产出。

zhuoning/paddleocr-vl-cpu-demo 是 ModelScope 魔搭社区上的在线可交互 Demo（创空间），基于 gradio 4.44.0 构建，中文名为「songpanda2.3」。

- **Repository**: zhuoning/paddleocr-vl-cpu-demo
- **SDK**: gradio
- **SDK version**: 4.44.0
- **Downloads**: 0
- **Stars**: 1
- **Last updated**: 2026-07-19

Source: https://www.modelscope.cn/studios/zhuoning/paddleocr-vl-cpu-demo

---

# 📜 PaddleOCR-VL-1.6 CPU 推理 Demo

> 古汉语 OCR 视觉语言模型 · 0.9B 参数 · **纯 CPU 可跑**

这是 [PaddleOCR-VL-1.6](https://github.com/PaddlePaddle/PaddleOCR) 在 SFT 数据上微调后的模型的 CPU 推理演示，基于 Hugging Face transformers 栈，无 GPU 依赖。

## ✨ 特性

- ✅ **纯 CPU 推理**（无 vLLM、无 PaddlePaddle）
- ✅ 单图 OCR / 标题抽取 / 表格识别 / 自定义 prompt
- ✅ 基于 Gradio 的 Web 界面
- ✅ 兼容 ModelScope 创空间（`python app.py` 直接启动）

## 📊 实测性能（32 核 CPU + torch 2.4.1）

| 项 | 值 |
|---|---|
| 模型加载 | ~4 s |
| 单图推理 | 512 tokens ≈ 170 s (~3 tok/s) |
| 内存峰值 | ~6 GB |

> ⚠️ CPU 跑 0.9B 视觉语言模型比 H20 GPU 慢 **30-100 倍**，但能稳定推理。生产批量建议仍用 GPU + vLLM。

## 📁 目录结构

```
cpu_demo/
├── README.md                 # 本文件
├── requirements.txt          # 依赖
├── app.py                    # Gradio Web UI 入口（ModelScope 创空间用）
├── infer.py                  # 推理引擎（单例、线程安全）
├── transformers_compat.py    # transformers 4.57 API shim
├── test_cpu_infer.py         # 命令行单图测试
├── sample_images/            # 示例图片
│   ├── sample.jpg
│   └── sample2.jpg
└── test_results/             # 测试输出
    └── last_result.txt
```

## 🚀 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

如果需要 CPU 版 torch：
```bash
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
```

### 2. 指定模型路径（重要！）

模型文件较大（1.8 GB），本仓库**不打包**模型权重。你需要通过环境变量指定模型路径：

```bash
export PADDLEOCR_VL_MODEL_PATH=/path/to/paddleocr_vl_1_6_full_epoch3
```

或者放在默认路径（开发机内）：
```
/apdcephfs/weread_rain/paddleocr/output/paddleocr_vl_1_6_full_epoch3
```

### 3. 启动 Web UI

```bash
python app.py                       # 默认 http://localhost:7860
python app.py --port 8888 --share   # 自定义端口 + 生成公网链接
```

打开浏览器访问对应端口即可。

### 4. 命令行单图测试

```bash
python test_cpu_infer.py sample_images/sample.jpg "OCR:<footnote><head>:"
```

## 🔧 ModelScope 创空间部署

1. 把本目录推到 ModelScope 创空间代码仓库
2. 把模型权重推到 ModelScope Hub（命名空间 `paddleocr_vl_1_6_full_epoch3`）
3. 在创空间「环境变量」设置 `PADDLEOCR_VL_MODEL_PATH` = 模型在创空间内的下载路径
4. 启动命令：`python app.py --port 7860`

代码已经做好懒加载：Gradio UI 先起来，模型在第一次请求时才加载，不阻塞启动。

## ⚙️ 配置项（环境变量）

| 变量 | 默认值 | 说明 |
|---|---|---|
| `PADDLEOCR_VL_MODEL_PATH` | `/apdcephfs/weread_rain/paddleocr/training_stage3_4/output/grpo_harvard_bert_v5_continuous/merged_stage7_grpo_v5_step1500` | 模型目录 |
| `PADDLEOCR_VL_DEFAULT_PROMPT` | `OCR:<footnote><head>:` | UI 默认 prompt |
| `PADDLEOCR_VL_THREADS` | `0`（读 OMP_NUM_THREADS） | torch CPU 线程数 |

## 🛠️ 实现细节

### transformers 4.57 兼容性 shim

模型代码（`modeling_paddleocr_vl.py`）导出于 paddleformers SFT，使用了更新版本 transformers 的 API：

```python
create_causal_mask(inputs_embeds=..., ...)
```

而 transformers==4.57.6 仍叫：

```python
create_causal_mask(input_embeds=..., ...)
```

`transformers_compat.py` 在运行时替换 `create_causal_mask`，把 `inputs_embeds` 重命名为 `input_embeds`，**不需要修改模型文件本身**。

### 为什么 CPU 能跑

| 项 | 状态 |
|---|---|
| 模型代码基于 `torch.nn` + `transformers` | ✅ CPU 原生 |
| `attn_implementation="eager"`（纯 PyTorch） | ✅ CPU 可跑 |
| 3D RoPE autocast 自动 fallback CPU | ✅ 代码已处理 MPS→CPU |
| `flash_attention_2` | ❌ CUDA only → 用 eager |
| `flashmask`（paddleformers 专属） | ❌ 不支持 |

## 📜 License

继承自 PaddleOCR-VL 的 Apache 2.0 协议。