# unidoc-java

**Repository Path**: johnnie_walker/unidoc-java

## Basic Information

- **Project Name**: unidoc-java
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-12
- **Last Updated**: 2026-07-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Unidoc Java

**Java 文档解析与导出引擎** — 将多种格式的办公文档解析为统一的文档模型（UnidocDocument），并导出为 HTML、Markdown、纯文本、JSON 或双层可搜索 PDF。

对标 [IBM Docling](https://github.com/DS4SD/docling)（Python），提供 Java 生态中的等价能力。

## 能力一览

### 输入格式（15 种）

| 类别 | 格式 |
|------|------|
| Office Open XML | `.docx` `.pptx` `.xlsx` |
| 旧版 Office | `.doc` `.ppt` `.xls` |
| 排版与标记 | `.pdf` `.html` `.md` `.rtf` |
| 数据 | `.csv` `.txt` |
| 国产标准 | `.ofd` (GB/T 33190) |
| 图形 | `.vsdx` (Visio)、`.jpg` `.png` `.tiff` `.bmp` `.gif` `.webp` |

### 输出格式（5 种）

| 格式 | 导出器 |
|------|--------|
| HTML | `HtmlExporter` — 高保真/RAG 两种模式 |
| Markdown | `MarkdownExporter` — GFM 表格、任务列表 |
| Plain Text | `PlaintextExporter` — 纯文本提取 |
| JSON | `JacksonExporter` — 完整文档树序列化 |
| 双层 PDF | `PdfLayeredExporter` — 可搜索 PDF（OCR 文本层叠加） |

### AI 能力

- **OCR 文字识别** — PaddleOCR v4 / v6（ONNX Runtime 推理），支持 GPU (CUDA/TensorRT)
- **版面分析** — PP-DocLayoutV3 深度学习模型 / GapTree 规则算法
- **文字方向分类** — 自动检测 180° 旋转
- **智能编码检测** — TXT 文件自动识别 UTF-8 / GB18030 / GBK 等

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.6+

### 构建

```bash
mvn clean package -DskipTests
```

生成的 fat JAR 位于 `target/unidoc-java.jar`。

### CLI 使用

```bash
# 解析单个文件，导出为 Markdown
java -jar target/unidoc-java.jar -f document.pdf -ot markdown

# 批量处理目录下所有 PDF 和 DOCX
java -jar target/unidoc-java.jar -d ./documents --filter pdf,docx -ot html

# 导出为 JSON（完整文档树）
java -jar target/unidoc-java.jar -f document.docx -ot json
```

### 编程 API

```java
UnidocConfig config = UnidocConfig.defaults();

try (UnidocEngine engine = UnidocEngine.create(config)) {
    // 解析
    UnidocDocument doc = engine.parse(Path.of("document.pdf"));
    
    // 导出
    String markdown = engine.export(doc, ExportFormat.MARKDOWN);
    String html = engine.export(doc, ExportFormat.HTML);
    
    // 一步完成
    String result = engine.parseAndExport(Path.of("doc.docx"), ExportFormat.MARKDOWN);
}
```

### 启用 OCR

```java
UnidocConfig config = UnidocConfig.builder()
    .ocr(OcrConfig.defaults())
    .build();

try (UnidocEngine engine = UnidocEngine.create(config)) {
    UnidocDocument doc = engine.parse(Path.of("scanned.pdf"), ParseContext.withOcr());
    String text = engine.export(doc, ExportFormat.PLAIN_TEXT);
}
```

### 启动 HTTP 服务

```java
UnidocConfig config = UnidocConfig.builder()
    .server(ServerConfig.builder().port(8080).build())
    .build();

UnidocServer server = new UnidocServer(config);
server.start();
// 访问 http://localhost:8080 打开 Web Inspector
```

### Web Inspector

构建后运行 `java -jar target/unidoc-java.jar`（默认以 CLI 模式运行），或通过 API 启动 Server 模式后访问内置的 Web Inspector 界面：

- 拖拽上传文档
- 三栏布局浏览文档树结构
- 实时切换输出格式预览
- 节点属性面板

## OCR 与版面分析配置

OCR 和版面分析需要 ONNX 模型文件。模型文件**不打包在 JAR 中**，需要从外部目录加载。

### 模型下载

模型文件预计约 300MB，按以下方式获取：

**方式一：环境变量指定目录**

```bash
export UNIDOC_MODELS_DIR=/path/to/models
export UNIDOC_NATIVE_DIR=/path/to/native-libs
```

**方式二：放在项目根目录**

```bash
# 将模型文件放在 models/ 目录下
# 将原生库放在 native-libs/{os}-{arch}/ 目录下
```

### 模型文件列表

| 模型 | 用途 | 必需 |
|------|------|------|
| `PP-OCRv6_medium_det.onnx` | 文字检测 (v6) | OCR v6 |
| `PP-OCRv6_medium_rec.onnx` | 文字识别 (v6) | OCR v6 |
| `ch_PP-OCRv4_det_infer.onnx` | 文字检测 (v4) | OCR v4 |
| `rec_ch_PP-OCRv4_infer.onnx` | 文字识别 (v4) | OCR v4 |
| `ch_ppocr_mobile_v2.0_cls_infer.onnx` | 方向分类器 | 推荐 |
| `PP-DocLayoutV3.onnx` | 版面检测 | 版面分析 |
| `ppocrv6_keys_v1.txt` | 字符字典 (v6) | OCR v6 |
| `ppocr_keys_v1.txt` / `dict_*.txt` | 字符字典 | OCR v4 |

### 原生库

ONNX Runtime 原生库（`.dll` / `.so`）需要放置在 `native-libs/{os}-{arch}/` 目录下，支持：
- `linux-x64` / `linux-aarch64`
- `win-x64`

GPU 加速需要额外的 CUDA/TensorRT 提供者库。

## 项目架构

```
UnidocEngine          ← 唯一编程入口（AutoCloseable）
  ├── ParsePipeline   ← 解析调度（格式检测 → Parser 选择 → 执行）
  ├── ExportPipeline  ← 导出调度（format → Exporter 选择 → 执行）
  ├── ConvertPipeline ← 格式转换（DOC → DOCX 等）
  ├── OcrPipeline     ← OCR 流水线（det → cls → rec）
  └── LayoutPipeline  ← 版面分析流水线（detector → TBPU）
```

所有组件通过 **Java SPI (ServiceLoader)** 自动发现，可自由替换：

| SPI 接口 | 已注册实现数 |
|----------|-------------|
| `DocumentParser` | 15 |
| `DocumentExporter` | 5 |
| `OcrEngine` | 2 |
| `LayoutAnalyzer` | 2 |
| `FormatConverter` | 1 |

## 配置预设

```java
UnidocConfig.defaults();          // 基础解析，无 OCR
UnidocConfig.forRag();            // RAG 场景：纯文本，优化分段
UnidocConfig.forHighPrecision();  // 高精度：OCR + DocLayoutV3 版面分析
UnidocConfig.forBatch();          // 批量处理：OCR + GapTree 快速版面分析
UnidocConfig.forMetadata();       // 仅元数据提取
```

## 运行测试

```bash
mvn test
```

冒烟测试覆盖全部支持格式的 端到端解析 → 导出 → JSON 往返验证。

## 许可证

本项目采用 [Apache License 2.0](LICENSE)。

### 第三方依赖许可证

| 依赖 | 许可证 |
|------|--------|
| Apache POI / PDFBox / Tika / Commons CSV / Log4j2 | Apache 2.0 |
| Jackson / Picocli / OpenCV 4.5+ | Apache 2.0 |
| ONNX Runtime | MIT |
| Jsoup | MIT |
| Flexmark | BSD 2-Clause |
| JTS | EPL 2.0 / BSD |
| PaddleOCR Models | Apache 2.0 |

完整归属声明见 [NOTICE](NOTICE) 文件。

## 与 IBM Docling 的关系

本项目受 IBM Docling 启发，是其 Java 生态的独立实现。两者共享以下设计理念：
- 多格式输入 → 统一文档模型 → 多格式输出
- AI 驱动的 OCR 与版面分析
- 插件化解析器架构

Unidoc 不是 Docling 的官方 Java 移植，也不隶属于 IBM。