# paddleocr_vl_api

**Repository Path**: fireae/paddleocr_vl_api

## Basic Information

- **Project Name**: paddleocr_vl_api
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-23
- **Last Updated**: 2026-10-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PaddleOCR-VL-ROCm

![PaddleOCR-VL-ROCm 在 Windows AMD GPU 上将文档转换为 Markdown 和 JSON](docs/assets/paddleocr-vl-rocm-readme-hero.png.jpg)

在 Windows AMD GPU 上本地运行 PaddleOCR-VL 1.6，将文档图片转换为 Markdown
和结构化 JSON。

本项目使用混合后端；整个流水线并非全部通过 ROCm 执行：

```text
图片
→ PP-DocLayoutV3 / ONNX Runtime DirectML
→ 区域裁剪
→ PaddleOCR-VL / llama.cpp HIP
→ Markdown + JSON
```

[English documentation](README.md)

> 发布状态：**v0.1.1 已发布（RELEASED）**；**G3 精度已 PASS**，
> 验收 Overall 为 **95.99**。PaddleOCR 已在线下确认该结果，项目 Maintainer
> 于 2026-07-17 决定无需再次全量运行。**G4 已 PASS**（均值 6.33 秒/页、
> P95 19.54 秒），**G5 已在记录公网传输豁免后 PASS**。详见
> [G3 Maintainer 验收记录](docs/releases/0.1.0-g3-attestation.md)和
> [G5 Maintainer 验收记录](docs/releases/0.1.0-g5-attestation.md)，以及
> [v0.1.1 补丁发布契约](docs/releases/0.1.1-release.md)和
> [发布收尾记录](docs/releases/0.1.1-closeout.md)。

| 指标 | PaddleOCR-VL（论文） | PaddleOCR-VL-ROCm（已验收） |
|---:|---:|---:|
| Overall | 96.33 | **95.99** |
| Text Edit-dist | 0.033 | 0.03488 |
| Reading-order Edit-dist | 0.127 | 0.12882 |
| Table TEDS | 94.76 | **94.09** |
| Formula CDM | 97.49 | **97.36** |

## 输入与输出

仓库包含真实的兼容性样例：

![杂志输入样例](examples/input/magazine.png)

- 输入：[`examples/input/magazine.png`](examples/input/magazine.png)
- Golden Markdown：[`tests/fixtures/golden/magazine.md`](tests/fixtures/golden/magazine.md)
- Golden 结构化 JSON：[`tests/fixtures/golden/magazine.json`](tests/fixtures/golden/magazine.json)

这是兼容性演示，不是发布证据。它展示公共输出格式，但不能证明当前硬件性能，
也不能证明 G4 已验收。

## 为什么需要它

PaddleOCR-VL 通常依赖在 Windows AMD 环境中较难部署的 VLM 服务栈。本项目组合了：

- DirectML 文档布局推理；
- 固定版本的 Windows llama.cpp HIP runtime 和经过哈希校验的 GGUF 资源；
- 外部 OpenAI-compatible endpoint 路径；
- 稳定的 CLI 与 Python 输出契约；
- 可审计的 OmniDocBench 工具。

## 已验证范围

- 一台 Windows 11 / Radeon 8060S 机器完成了缓存资源校验安装、DirectML
  布局激活、托管 server 冒烟推理和外部 server 冒烟推理。
- 该记录没有保存精确的 AMD 驱动和 HIP runtime 版本，因此不能作为可复现的
  性能或发布门禁 benchmark。
- 托管下载 manifest 固定了 2.27 GB（2.12 GiB）资源的大小和 SHA-256。
- 正式评分分母是 1,651 个 GT 页面。已批准的 official-local 运行包含
  1,650 个成功预测和 1 个失败页；失败页按空预测计分。它不是“对称排除 1 页”
  后得到的 1,650 页成绩。

证据和限制详见[兼容性矩阵](docs/compatibility/windows-amd.md)和
[benchmark 事实表](docs/benchmarks/omnidocbench-v1.6.md)。

## Install（安装）

推荐环境：Windows 11、Python 3.12、PowerShell、受当前 AMD HIP SDK 支持的
AMD GPU，以及至少 5 GiB 可用磁盘空间。

项目使用 [uv](https://docs.astral.sh/uv/) 管理环境：`uv sync` 会按锁定的
Python 3.12 创建 `.venv`（必要时自动下载托管解释器），并从 `uv.lock` 安装
全部依赖。

```powershell
git clone https://github.com/AIwork4me/PaddleOCR-VL-ROCm.git
cd PaddleOCR-VL-ROCm

uv sync --extra download
.venv\Scripts\Activate.ps1

paddleocr-vl-rocm setup --auto
paddleocr-vl-rocm doctor
paddleocr-vl-rocm run examples/input/magazine.png
```

`setup --auto` 会下载、校验、安装资源，并在 8111 端口启动托管 server。
默认根目录为 `%LOCALAPPDATA%\PaddleOCR-VL-ROCm`；模型位于 `models\`，
runtime 位于 `runtime\`，下载缓存位于 `cache\`，活动路径记录在
`config.json` 中。

使用其他磁盘或目录：

```powershell
paddleocr-vl-rocm setup --auto --root D:\PaddleOCR-VL-ROCm
```

使用 `setup --no-start` 可以只安装、不启动 server。CLI 会打印稍后启动
`llama-server.exe` 所需的完整命令。

项目目前没有托管的 `stop` 或 `clean` 命令。删除托管根目录前，请先停止由你
启动的 `llama-server.exe` 进程；不要在未检查内容时删除共享的 `--root`。

## Demo（演示） + Evaluation（评测）

如需保留自己的 llama.cpp、vLLM 或其他 OpenAI-compatible endpoint：

```powershell
uv sync --extra download
paddleocr-vl-rocm doctor --server-url http://127.0.0.1:8111/v1
paddleocr-vl-rocm run examples/input/magazine.png --server-url http://127.0.0.1:8111/v1
```

仍支持向后兼容的旧命令形式：

```powershell
paddleocr-vl-rocm --input examples/input/magazine.png --server-url http://127.0.0.1:8111/v1
```

当 endpoint 要求特定模型标识时使用 `--api-model-name`。外部 server 自己负责
GPU/runtime 兼容性；本仓库不会验证或安装该 server。

## CLI

```text
paddleocr-vl-rocm setup [--auto | --no-start] [--root PATH] [--force]
paddleocr-vl-rocm doctor [--json] [--config PATH] [--server-url URL]
paddleocr-vl-rocm run INPUT [--output DIR] [--layout-model DIR]
                         [--layout-provider auto|directml|cpu]
                         [--server-url URL] [--api-model-name NAME]
                         [--vlm-max-workers N]
```

CLI、Python API 和底层 parser 共享公共并发默认值
`vlm_max_workers=8`。仅在内存压力或 server 请求容量不足时调低。

### HTTP 服务：统一网关（单端口 17201）

原本三个独立服务（baidu-api:8080、openai-api:8090、gradio-ui:7860）已合并为
**统一网关**：单进程、单端口，Baidu 兼容 API、OpenAI 兼容 API、Gradio UI 与
`/health` 全部由同一个 FastAPI 应用提供：

```text
# 推荐：CLI 入口（支持 --host/--port/--baidu-token 等参数）
paddleocr-vl-rocm-gateway

# 等价形式
paddleocr-vl-rocm gateway

# 或 uvicorn 直接运行 ASGI 入口（host/port 由 uvicorn 提供，业务参数走 .env）
uvicorn paddleocr_vl_rocm.gateway:app --host 127.0.0.1 --port 17201
```

默认监听 `127.0.0.1:17201`；`--host` / `--port`（环境变量
`PADDLEOCR_VL_GATEWAY_HOST` / `PADDLEOCR_VL_GATEWAY_PORT`）可调整。一个端口
提供以下端点：

| 端点 | 说明 | 鉴权头 |
|---|---|---|
| `POST /layout-parsing` | Baidu 兼容版面解析（对应 `infer`） | `Authorization: token {TOKEN}` |
| `POST /restructure-pages` | Baidu 兼容多页重组（对应 `restructurePages`） | 同上 |
| `GET /files/{id}/{name}` | 输出图片访问 | 同上 |
| `POST /v1/chat/completions` | OpenAI 兼容 image → markdown | `Authorization: Bearer {TOKEN}` |
| `GET /v1/models` | 模型列表 | 同上 |
| `GET /health` | 存活探针（恒 200） | 无 |
| `GET /gradio` | Gradio 可视化界面（默认挂载） | 无 |
| `GET /docs` `/redoc` | 交互式文档（覆盖全部端点） | 无 |

Baidu 端点响应信封为 `{logId, errorCode, errorMsg, result}`；OpenAI 端点为
OpenAI 风格 `{"error": {...}}`。未配置 token 时对应端点以本地开放模式运行。
两个 API 与 Gradio UI **共享同一个懒加载推理引擎实例**（单进程省显存），
并发上限为 `PADDLEOCR_VL_MAX_CONCURRENT`。

`/layout-parsing` 支持**图像与 PDF**（`fileType=0`，或按 `%PDF-` 魔数自动识别）：
PDF 按请求体 `dpi`（默认 200，配置项 `--pdf-render-dpi` /
`PADDLEOCR_VL_PDF_RENDER_DPI`）逐页渲染，每页一条 `layoutParsingResults`，
返回的 bbox 与 `prunedResult.width|height` 均为**该渲染图像的像素**——需要 PDF
点坐标时按 `点 = 像素 × 72 / dpi` 换算，实际生效 dpi 见 `dataInfo.dpi`
（图像输入无渲染环节，坐标即原图像素、`dpi` 为 `null`）；超过
`--pdf-max-pages` / `PADDLEOCR_VL_PDF_MAX_PAGES`（默认 100）页返回 400。

已知限制：`useDocOrientationClassify` / `useDocUnwarping` 不支持时返回 400。

### Gradio 可视化界面

不再独立运行/独立端口：Gradio UI 由统一网关直接挂载到 `/gradio`
（默认开启，`--no-gradio` 关闭，`--gradio-path` 调整路径），调用与 Baidu 端点
同一套 `BaiduAIService`（同一引擎实例），以 `data-url` 模式内嵌图片，浏览器
可直接渲染。界面包含两个标签页：

- **版面解析 layout-parsing**：上传文档图片，配置阈值/公式编号/采样参数后
  调用 `POST /layout-parsing`，展示 Markdown 结果、布局可视化图与完整 JSON；
- **多页重构 restructure-pages**：粘贴每页的 `prunedResult` JSON（或点击
  "填入最近一次版面解析结果"），调用 `POST /restructure-pages` 重建最终
  Markdown。

`gradio` 已包含在核心依赖中，`uv sync` 安装项目依赖后即可使用。

### .env 配置

网关的**全部参数**都可通过环境变量配置，无需命令行参数：

```bash
cp .env.example .env                            # 按需修改
uvicorn paddleocr_vl_rocm.gateway:app --host 0.0.0.0 --port 17201  # 读取 ./.env 中的 PADDLEOCR_VL_* 变量
```

优先级为：**命令行参数 > .env / 环境变量 > 内置默认值**。也可用 `--env-file PATH`
指定其他配置文件。变量统一使用 `PADDLEOCR_VL_*` 前缀，完整清单见 `.env.example`，
主要分组如下：

| 变量 | 对应 CLI 参数 | 默认值 |
|---|---|---|
| `PADDLEOCR_VL_LAYOUT_MODEL_DIR` | `--layout-model-dir` | `models/PP-DocLayoutV3-onnx` |
| `PADDLEOCR_VL_VLM_SERVER_URL` | `--vlm-server-url` | `http://127.0.0.1:8000/v1` |
| `PADDLEOCR_VL_API_MODEL_NAME` | `--api-model-name` | `PaddleOCR-VL-1.6-GGUF.gguf` |
| `PADDLEOCR_VL_VLM_BACKEND` | `--vlm-backend` | `llama-cpp-server` |
| `PADDLEOCR_VL_MAX_NEW_TOKENS` | `--max-new-tokens` | `4096` |
| `PADDLEOCR_VL_TIMEOUT` | `--timeout` | `300` |
| `PADDLEOCR_VL_SEED` | `--seed` | `1` |
| `PADDLEOCR_VL_THRESHOLD` | `--threshold` | `0.3` |
| `PADDLEOCR_VL_VLM_MAX_WORKERS` | `--vlm-max-workers` | `8` |
| `PADDLEOCR_VL_LAYOUT_PROVIDER` | `--layout-provider` | `auto` |
| `PADDLEOCR_VL_SKIP_SERVER_CHECK` | `--skip-server-check` | `false` |
| `PADDLEOCR_VL_REPETITION_PENALTY` | `--repetition-penalty` | 引擎默认 |
| `PADDLEOCR_VL_TEMPERATURE` | `--temperature` | 引擎默认 |
| `PADDLEOCR_VL_TOP_P` | `--top-p` | 引擎默认 |
| `PADDLEOCR_VL_LOG_LEVEL` | `--log-level` | `INFO` |
| `PADDLEOCR_VL_MAX_CONCURRENT` | `--max-concurrent` | `4` |
| `PADDLEOCR_VL_GATEWAY_HOST` | `--host`（网关） | `127.0.0.1` |
| `PADDLEOCR_VL_GATEWAY_PORT` | `--port`（网关） | `17201` |
| `PADDLEOCR_VL_BAIDU_TOKEN` | `--baidu-token` | 开放模式 |
| `PADDLEOCR_VL_OPENAI_TOKEN` | `--openai-token` | 开放模式 |
| `PADDLEOCR_VL_OUTPUT_DIR` | `--output-dir` | 临时目录 |
| `PADDLEOCR_VL_IMAGE_URL_MODE` | `--image-url-mode` | `static` |
| `PADDLEOCR_VL_VISUALIZE` | `--visualize` | 开启 |
| `PADDLEOCR_VL_WITH_GRADIO` | `--no-gradio` | `true` |
| `PADDLEOCR_VL_GRADIO_PATH` | `--gradio-path` | `/gradio` |
| `PADDLEOCR_VL_WEB_DIST` | `--web-dist` | `web/dist` |

布尔值接受 `1/true/yes/on` 或 `0/false/no/off`；留空表示使用内置默认值。

### Docker 部署

构建并运行打包好模型的镜像（ONNX 版面检测模型已内置，无需在容器内下载）：

```bash
# 构建镜像（models/PP-DocLayoutV3-onnx 一并打入）
docker build -t paddleocr-vl-rocm .

# 启动统一网关（默认，端口 17201；同时提供 /docs、/gradio 与 /health）
docker run --network host paddleocr-vl-rocm

# 或映射端口（17201 端口同时提供 Baidu/OpenAI API、/docs、/gradio 与 /health）
docker run -p 17201:17201 paddleocr-vl-rocm

# 仅 API（不挂载 Gradio UI）
docker run --network host -e PADDLEOCR_VL_WITH_GRADIO=false paddleocr-vl-rocm

# 使用自定义 .env 配置
docker run -p 17201:17201 --env-file .env paddleocr-vl-rocm
```

说明：

- 镜像基于 `python:3.12-slim`，仅包含 CPU 版 `onnxruntime` 与推理服务本身；
- VLM 由外部 OpenAI 兼容服务提供（llama.cpp HIP / vLLM ROCm），通过
  `PADDLEOCR_VL_VLM_SERVER_URL` 连接——`--network host` 可让容器直接访问
  宿主机 VLM 服务，同一 docker network 内则填写对应容器地址；
- 镜像内默认监听 `0.0.0.0`（`ENV PADDLEOCR_VL_GATEWAY_HOST=0.0.0.0`），自定义
  配置用 `--env-file` 覆盖；
- 需要持久化输出图片时：`docker run -p 17201:17201 -v $PWD/outputs:/app/outputs
  --env PADDLEOCR_VL_OUTPUT_DIR=/app/outputs paddleocr-vl-rocm`。

#### NVIDIA GPU 镜像（Dockerfile.gpu）

基于 `nvidia/cuda:12.8.1-cudnn-runtime-ubuntu24.04`，由 uv 管理 Python 3.12 环境，
安装 GPU 版 `onnxruntime-gpu`（CUDA 12.8 + cuDNN 9），版面检测模型
（`models/PP-DocLayoutV3-onnx`）同样打包进镜像，并优先在 GPU 上执行：

```bash
# 构建 GPU 镜像
docker build -f Dockerfile.gpu -t paddleocr-vl-rocm:gpu .

# 启动统一网关（需要 NVIDIA Container Toolkit；端口 17201，含 /docs、/gradio）
docker run --gpus all --network host paddleocr-vl-rocm:gpu

# 自定义配置
docker run --gpus all -p 17201:17201 --env-file .env paddleocr-vl-rocm:gpu
```

说明：

- 需宿主机已安装 NVIDIA 驱动与 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/)；
- `PADDLEOCR_VL_LAYOUT_PROVIDER` 默认 `auto`：Linux 下检测到
  `CUDAExecutionProvider` 自动启用 GPU，未检测到则回退 CPU；可显式设为
  `cuda` / `cpu` / `directml`；
- VLM 仍为外部 OpenAI 兼容服务（llama.cpp CUDA / vLLM），用 `--network host`
  直连宿主机 VLM，或同一 docker network 内填写容器地址。

中文用户可从
[ModelScope](https://modelscope.cn/models/PaddlePaddle/PP-DocLayoutV3_onnx)
获取 PP-DocLayoutV3 ONNX；英文用户可使用
[Hugging Face](https://huggingface.co/PaddlePaddle/PP-DocLayoutV3_onnx)。
托管安装会自动下载固定版本。

## Python API

```python
from paddleocr_vl_rocm import PaddleOCRVLROCm

pipeline = PaddleOCRVLROCm(
    layout_model_dir="models/PP-DocLayoutV3-onnx",
    vlm_server_url="http://127.0.0.1:8111/v1",
)
result = pipeline.predict("examples/input/magazine.png")
print(result.markdown_text)
```

## 输出结构

CLI 会在 `--output`（默认 `outputs`）下写入 `result.md` 和 `result.json`。
JSON 包含来源路径、页面尺寸、有序 block、标签、边界框、识别内容和 provider
元数据。坐标和标签属于版本化兼容性契约；修改布局或序列化逻辑时，应与仓库内
golden fixtures 对比。

## Reproducibility（复现评测）

下载数据或运行评分前，请先阅读 [`eval/README.md`](eval/README.md)。其中固定了
OmniDocBench checkout，说明推理/评分阶段，并拒绝不完整的发布 artifact。
公开数字和门禁状态只在
[OmniDocBench v1.6 事实表](docs/benchmarks/omnidocbench-v1.6.md)维护。

不要发布子集、scorer 不匹配、使用 fallback 或未经验证 artifact 的成绩。

## 常见问题

- **PowerShell 阻止激活：**执行
  `Set-ExecutionPolicy -Scope Process Bypass`，再激活虚拟环境。
- **8111 端口被占用：**停止预期进程，或在其他端口运行外部 server，并传入
  `--server-url`。
- **下载失败：**重新运行 setup；部分下载可以续传。代理、DNS 和 GitHub
  release assets 必须可访问。
- **DirectML 不可用：**更新 AMD 显卡驱动，再运行
  `paddleocr-vl-rocm doctor --json`。Windows 托管验证要求 DirectML 排在首位，
  且不会静默回退到 CPU。
- **HIP DLL 或 server 启动失败：**对照 AMD 当前 Windows HIP 支持表检查 GPU
  和系统，再查看
  `%LOCALAPPDATA%\PaddleOCR-VL-ROCm\logs\server.log`。
- **诊断信息敏感：**公开 Doctor JSON 或日志前，删除用户名、本地路径、token、
  私有文档和 endpoint 凭据。

## Known Gaps（已知限制）

- v0.1.1 已包含完整 G5 closeout；G0、G1、G3、G4、G5 均为 PASS。
- 项目只记录了一台 Windows AMD 机器的冒烟验证。
- G4 性能和定向 GT 精度投影均已通过；与历史 G3 基线相比仍有 8/27 页
  输出哈希不同，因此不声明原始输出等价。详见
  [G4 诊断](docs/releases/0.1.0-g4-diagnostic.md)。
- 托管安装仅支持 Windows，且没有 stop/cleanup 命令。
- 空缓存公网传输仍为明确豁免，且不声明该路径成功；预校验缓存安装已通过。

## Roadmap

参见 [`ROADMAP.md`](ROADMAP.md)。近期重点是收集可复现硬件报告，以及
改进离线安装与镜像指引。

## 贡献、安全与许可证

提交改动前请阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md)，并选择合适的
[Issue Form](.github/ISSUE_TEMPLATE)。安全问题请按
[`SECURITY.md`](SECURITY.md) 私下报告。项目使用 [MIT License](LICENSE)。