# opendataloader-pdf-fastapi-project

**Repository Path**: aylerh/opendataloader-pdf-fastapi-project

## Basic Information

- **Project Name**: opendataloader-pdf-fastapi-project
- **Description**: 总览：（1）opendataloader-pdf的web化（去除fastapi-纯java）；创新：（1）pp-doclayout-v3布局识别引入；
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-20
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenDataLoader PDF FastAPI Web Service

本项目基于 [OpenDataLoader PDF](https://github.com/opendataloader-project/opendataloader-pdf) 提供开箱即用的多格式高精度文档解析与 REST API 服务。内置美观、交互性强的 Dark-Glassmorphism 风格前端页面，支持配置各种转换参数，并将结果统一打包为 ZIP 下载。

---
## 页面样式

### 主页-OCR高精度布局识别（无OpenDataLoader）-约1秒每页

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

具体效果：
![1-2](./images/1-2.png)

### 快速模式（使用OpenDataLoader）-小于0.1秒每页（无布局识别）
![2](./images/2.png)

## 🚀 优点与核心渲染模式

1. **Non-OCR Layout (非OCR高精度布局识别) — [默认模式]**
   - **特点**：结合高精度版面分析网络（PP-DocLayoutV3）与矢量 PDF 原生字符提取（基于 pypdfium2 / pdfplumber），对正文直接抓取矢量字形（避开 OCR 错别字与相似字误判），双栏自然阅读流重组，结构化表格保真提取，同时支持图像高保真裁剪。
   - **重要声明**：**本模式完全不使用 OpenDataLoader 默认的 Java JRE Fast 技术。** 
     - *普通的 JRE Fast 技术*是基于原生 PDF 数据流块的简单平铺提取，容易丢失栏目阅读顺序与标题级别层级。
     - *Non-OCR Layout* 引入了高精度 AI 深度学习版面分析网络重排双栏、识别标题并智能重构列表，精度和版面理解力显著超越普通的 Fast 技术。
   
2. **Fast (本地极速渲染)**
   - **特点**：**已启用 OpenDataLoader 的 JRE Fast 本地直出技术。** 速度极快（单页 < 0.1s），零外部依赖，适合纯英文或排版极简单的电子版 PDF。

---

## 🎯 解决的核心痛点

在处理复杂的学术论文或技术报告（如包含双栏排版、复杂数学公式、多图片并排等）时，本项目成功解决以下行业核心痛点：

1. **折行标题错乱与多余子弹头**：
   - *痛点*：PDF 中的标题若跨越两行，在解析时极易被切割为两行，甚至因为 PDF 提取图层顺序问题，被误判为带有 `-`、`▪` 等前缀符号的无序列表项。
   - *解决*：引入智能标题折行重组算法，在 block-level 自动判定多行标题并强力清洗首尾的冗余列表标志，将跨行标题完美合并为单行 Markdown `#` / `##` 格式。

2. **段落尾部标点符号截断（例如 `is:` 变成 `i`，句号丢失）**：
   - *痛点*：使用 PDFium 进行物理边界框（Bounding Box）剪裁时，行尾或段尾的最后一个单词常会发生末尾 2~3 个字符丢失（如冒号、句号、连字符截断）。
   - *解决*：**我们深入诊断并定位了 PDFium 原生 C-API `FPDFText_GetBoundedText` 的字符计数 Bug（传入空缓冲区查询的 `n_chars` 比实际需要写入的数据少 3 个字符）**。为此设计了基于 `ctypes` 的 **+32 盈余缓冲区分配封装 `get_text_bounded_safe`**，在 C-level 层级直接消除了原生的字符截断缺陷，实现 100% 完整段尾还原。

3. **数学斜体公式符号丢失（例如 `CO2e (B)` 变成 `CO2 ()`）**：
   - *痛点*：大部分自研逐字 PDF 提取器仅支持普通的 UCS-2 编码，无法解析位于 Unicode 辅助多语言平面（SMP）的数学斜体特殊符号（如代理对表示的 `𝐵`、`𝐴`、`𝑒`），导致公式和正文数学公式缺字。
   - *解决*：`get_text_bounded_safe` 引擎不仅修复了计数 bug，同时保留了 native textpage 完整的 Unicode 支持，无论是 inline 公式还是段落行，特殊数学字形和公式符号均 100% 高保真还原。

4. **双栏混淆与多图片并排**：
   - *痛点*：传统提取在边界框左右扩充时，容易侵入相邻栏导致文本混淆（Column Bleeding）。同时，水平并排的多张图表容易在 Markdown 中被割裂。
   - *解决*：设计了带有**左右物理邻界隔离框限制**的坐标引擎，即便水平外扩也绝不侵染相邻列。同时，引入 **`image_row` 多图群组合并算法**，将水平共线的图片合并为一个 inline-block responsive container，并排精美展示。

---

## 💻 采用的关键技术

本项目依托现代深度学习、底层 C 语言缓冲区操纵以及高级数据流清洗技术：

- **PP-DocLayoutV3 ONNX (ONNXRuntime)**：由百度提供的高保真文档版面分析深度学习模型，智能框定物理边界框，高精度识别语义类别（段落、标题、图例、公式、表格、图表等）。
- **pypdfium2 (ctypes / PDFium)**：底层基于 Chrome 同款开源 PDFIUM 高速矢量提取库，通过底层 `FPDFText_GetBoundedText` 抓取最底层的矢量字形与空间坐标，速度与准确率领跑行业。
- **C-Level 盈余分配缓冲区技术 (ctypes)**：自制 `get_text_bounded_safe` 缓冲扩容接口，操纵 C 指针并注入安全盈余字节，根治了原生 PDFium 字符截断缺陷，提供了对 SMP 代理对平面（数学斜体符号）的完美解码支持。
- **pdfplumber & PIL Image Processing**：高保真提取电子版矢量表格，并对布局图进行无损物理像素级别剪裁。

---

## 📂 项目结构重构与优化

为了将项目打造成易于扩展的 SaaS MVP，我们对代码结构和 Docker 容器打包机制进行了彻底重构，确保没有任何 Python 脚本散落在项目根目录下：

### 1. 源码归口管理与辅助工具隔离 (`src/` & `tools/`)
- **核心源码目录 (`src/`)**：所有核心业务逻辑的 `.py` 文件均从根目录移动至专用的源文件目录 `src/` 中，让项目结构极为清爽：
  - **`src/main.py`**：FastAPI 控制层，负责文件接收、Abort 状态拦截以及耗时统计响应头。
  - **`src/layout_pipeline.py`**：核心解析缝合引擎，包含 C-level 提取接口、多图群组、列边界计算及 markdown 拼接。
  - **`src/layout_service.py`**：高精度版面分析模型服务，采用 Lazy Loading（延迟加载）机制保证容器秒级冷启动。
- **辅助/测试工具目录 (`tools/`)**：我们将所有底层调试、字符搜索、接口测试等辅助脚本全部移动到 `tools/` 文件夹下，保持根目录极致纯净：
  - **`tools/inspect_get_text_range.py`**：测试 PDFium 文字范围提取机制的底层脚本。
  - **`tools/inspect_individual_bounded.py`**：调试特定字符/标点物理坐标边界框的检测工具。
  - **`tools/inspect_source.py`**：检查底层库方法签名的探测工具。
  - **`tools/search_math_chars.py`**：搜索/验证 PDF 中 Unicode 辅助平面数学特殊字符的提取效果。

### 2. 精简 Docker 打包，防范源码级污染
修改 `Dockerfile`，彻底弃用了不安全的 `COPY . .` 指令，仅拷贝必要的文件与服务代码：
- **隐式安全隔离**：显式指定 `COPY src/ /app/src/` 与 `COPY templates/ /app/templates/`。**绝不拷贝 `tools/` 调试文件夹、`err-files/` 测试集、本地打包生成的 ZIP 以及敏感的环境变量 `.env`**，保证生产环境容器的轻量与绝对安全。
- **拒绝构建污染**：本地临时生成的打包 ZIP（如 `test_out.zip`）、大型的测试 PDF（如 `err-files/`）、宿主机缓存及敏感的环境文件 `.env` 均被强制隔离在容器之外，使构建层更轻、启动镜像更小、系统安全性极高。
- **跨目录引入机制**：通过在 `Dockerfile` 中写入 `ENV PYTHONPATH=/app/src`，优雅地实现了模块跨目录动态解析。

---

## ⚙ 本地配置与快速启动

### 1. 变量配置
检查 `.env` 环境变量配置：
```env
INNER_PORT=8212
OUTER_PORT=8212
```

### 2. 构建与运行服务
本项目完美兼容 Windows 11/10 PowerShell 终端，使用如下命令进行项目重构和后台启动：
```powershell
# Windows PowerShell 中执行
docker compose down; docker compose up --build -d
```

### 3. 使用与验证
- **精美控制台**：打开浏览器访问 `http://localhost:8212` 体验 Dark-Glassmorphism 前端解析配置台。
- **上传即时展示**：支持一键拖拽上传文件，即时计算并以绿色字样展示文件名及大小。
- **成功反馈卡片**：解析成功后不仅会拉起 ZIP 下载，还会在前端渲染出**大大的绿色解析成功反馈卡片**并生成性能处理报告。
- **RESTful API**：可向 `http://localhost:8212/upload` 发送 `POST` 请求（传入 `file`、`mode` 等参数）对接业务系统流水线。