# pp-doclayout-gpu-project

**Repository Path**: aylerh/pp-doclayout-gpu-project

## Basic Information

- **Project Name**: pp-doclayout-gpu-project
- **Description**: 功能:(1)纯布局识别：gpu版的pp-doclayout-v3的布局版面识别-基于onnxruntime-gpu；(2）pdf2md（md的zip）：基于pp-doclayout-v3和pdf-inspector（文本获取）；
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-06
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PP-DocLayout-v3 GPU 版文档布局识别与 PDF2MD / PDF2DOCX 服务

本项目基于 PaddleOCR 开源生态的 PP-DocLayout-v3 及 `rapid_layout` 框架，构建高性能 GPU 加速与 ONNXRuntime 引擎驱动的文档版面分析、PDF2MD 及 PDF2DOCX 服务。支持常见图像及 PDF 复杂版面分析、15+ 种元素分类（标题、正文、表格、插图、公式、页眉页脚等）与自动画框可视化，并提供带布局识别、无 OCR 文本损耗的 PDF 转 Markdown (ZIP 打包) 与保留复杂版面排版（Word 原生分栏、同行多图并排、学术缩进、两端对齐）的 Word (.docx) 导出功能。

## 主要功能

- 📐 **版面布局分析 (Detect)**：支持单张/多张图片及多页 PDF，自动检测 15+ 种版面区域，生成高精度标注图像、重构标注 PDF 及坐标 JSON；
- 📝 **PDF2MD (非 OCR 式 Markdown 导出-仅单栏)**：基于矢量字符定位与阅读流重排，无 OCR 错别字损耗，自动裁剪插图/公式并打包 ZIP；
- 📄 **PDF2DOCX (非 OCR 式保留排版 Word 导出)**：基于分层分栏（Hierarchical Bands）与 Word 原生连续分节分栏（Continuous Section + w:cols），还原原 PDF 排版（左右双栏、同行多图等高并排、学术段落智能缩进、英文两端对齐、严格边界约束），单页 100% 饱满容纳。

## 速度与性能

- **全自动启动预热**：FastAPI 启动时自动完成 PP-DocLayout-v3 ONNX 模型预热与 CUDA JIT 编译，消除冷启动耗时；
- **极速转换处理**：复杂学术论文与科研文档处理速度达 **0.85 ~ 3.0 秒/页**。

## 页面样式
### 主页
![1](./images/1.png)

### 1. pdf2md (Markdown 导出 / 无 OCR)

![2](./images/2.png)

### 2. 版面识别与画框可视化

![4](./images/4.png)

### 3. 主页-pdf2docx (保留排版 Word 导出 / 0.85~1.0 秒每页)

![3](./images/3.png)

## 缺点与说明
1. **字体字形映射缺失问题**：若 PDF 嵌入的字体采用了私有/自定义字形映射（Identity-H Custom Encoding）且缺失了标准 ToUnicode CMap 映射流（如某些扫描翻印特殊公文），矢量字符会提取为乱码。【应对机制：系统自动识别乱码或纯扫描页，智能降级为整页超高清图像嵌入 Word，确保视觉内容 100% 保真】。

## 解决痛点与核心技术

### 解决痛点
1. **复杂非结构化 PDF/文档版面难识别问题**：提供全自动化视觉版面元素定位与 15+ 细粒度分类，准确区分标题、正文、表格、图形与公式区域。
2. **多栏 Word 导出跨页断裂与排版混乱痛点**：
   - 彻底废弃无边框表格容器排版，全面升级为 **Word 原生连续分节多栏机制 (Continuous Section + w:cols)**，实现左栏写满自然流向右栏的流式排版；
   - **跨栏连续段落智能缝合**：精准识别跨栏长句与延续词，将跨栏段落无缝拼合为一个整体，消除硬性换行与后半句多余缩进；
   - **学术文献智能缩进状态机**：标题后首段顶格（0 缩进）、同标题后续段落自动首行缩进（0.18 inch）、插图/独立公式后首段顶格；
   - **英文正文两端对齐与严格边界约束**：正文段落默认两端对齐（Justify），注入 `<w:overflowPunct w:val="0"/>` 严格杜绝 `50%` 等百分号和标点悬挂外凸；
   - **同行多图等高并排**：自动聚合水平相邻多图（`image_row`），等高自适应居中排布，杜绝竖直堆叠。
3. **带布局 PDF 转 Markdown 字符错乱与 OCR 耗时痛点**：
   - 采用 **纯矢量字符定位与抽取**，完全无需 OCR，确保 100% 文本真实度与零识别错别字；
   - 结合 PP-DocLayout-v3 自动判定单栏与双/多栏排版（左栏 -> 右栏 -> 通栏），自动按自然阅读流重排；
   - 自动平滑合并跨行与跨栏连贯段落，清洗软连字符与行末连字符（如 `E-\nwaste` -> `E-waste`），过滤孤立页码；
   - 自动裁剪保存插图、表格与公式图片至 `images/` 目录并生成相对链接，一键打包 ZIP。
4. **前端白屏闪烁与临时文件残留**：
   - 前端下载升级为异步 Blob 静默下载，彻底杜绝点击下载时的网页闪烁；
   - 页面刷新与加载自动触发服务端与前端缓存清理，保证 100% 纯净初始状态。

### 使用技术
- **FastAPI**: 高性能异步 Web API 接口服务框架与启动生命周期自动预热。
- **PP-DocLayout-v3 / RapidLayout**: PaddleOCR 最新开源的高精度文档版面分析神经网络模型。
- **ONNXRuntime GPU**: CUDA 硬件加速深度学习推理引擎。
- **python-docx**: Word (.docx) 原生 OpenXML 深度定制排版引擎（连续节分栏、两端对齐、严格边界约束、图片行自适应）。
- **pdf-inspector / pdfplumber**: PDF 文本提取与排版检测库。
- **PyPDFium2**: 高性能 PDF 矢量渲染与精准字符坐标定位工具库。
- **Docker Compose**: 容器化多阶段隔离、热重载挂载与一键部署。

## API 接口说明

| 接口 Endpoint | 请求方式 | 说明 |
| :--- | :--- | :--- |
| `GET /api/health` | GET | 检查服务在线状态与 GPU 引擎初始化状态 |
| `POST /api/clear_cache` | POST | 递归清理服务端上传临时文件与输出缓存目录 |
| `POST /api/detect/image` | POST (multipart/form-data) | 上传单张图片，执行版面检测，返回标注图片与 JSON |
| `POST /api/detect/pdf` | POST (multipart/form-data) | 上传 PDF 文件，逐页识别版面，返回标注 PDF、逐页画框图及 ZIP |
| `POST /api/convert/pdf2md` | POST (multipart/form-data) | 上传 PDF 文件，执行带布局无 OCR 转 Markdown，返回全量 MD、预览及 ZIP |
| `POST /api/convert/pdf2docx` | POST (multipart/form-data) | 上传 PDF / 图片 / ZIP 文件，执行分层分栏 Word 导出，返回 DOCX、JSON 及 ZIP |
| `GET /api/download/{job_id}/{filename:path}` | GET | 安全下载标注 PDF、图片、Markdown (.md)、Word (.docx)、JSON 及 ZIP |

## 构建与运行

### 环境变量设置 (.env)
```env
INNER_PORT=8563
OUTER_PORT=8563
DATA_DIR=H:/docker-data/pp-doclayout-gpu-project-data/data
```

### 启动服务
```powershell
$OutputEncoding = [Console]::InputEncoding = [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
docker compose down; docker compose up --build -d
```
服务启动后，访问地址: `http://localhost:8563/`

## 致谢

- [rapid_layout](https://github.com/RapidAI/RapidLayout): 快捷高效的开源布局识别引擎。
- [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR): 优秀强大的飞桨多语言及版面 OCR 算法库。
- [python-docx](https://github.com/python-openxml/python-docx): 强大灵活的 Python Word 文档生成库。
- [pdf-inspector](https://pypi.org/project/pdf-inspector/): 高效的 PDF 特征检测与文本分析库。
- [PyPDFium2](https://github.com/pypdfium2-team/pypdfium2): 高性能 Python PDF 渲染与字符坐标提取库。