# mineruocr

**Repository Path**: fmscole/mineruocr

## Basic Information

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

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-06-12
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mineruocr

MinerU OCR → 公式修复 → Word 文档一键转换流水线（支持 PDF / PNG / JPG / JPEG 输入）。

## 安装

> **环境说明**：`run_ocr.py` 中只有 `mineru` 命令通过 `conda run -n miner` 在 miner 环境中执行，
> 其余工具（`pandoc`、`pypdfium2`、`lxml` 等）全部在**启动 `run_ocr.py` 的 Python 环境**中运行。
> 因此以下依赖都需要安装到启动环境中。

### 1. 安装 MinerU（在 conda miner 环境中）

```bash
pip install uv -i https://mirrors.aliyun.com/pypi/simple
uv pip install -U "mineru[all]" -i https://mirrors.aliyun.com/pypi/simple
```

### 2. 安装 pandoc（在启动环境中，md→docx 转换）

```bash
# 系统级安装（推荐—脚本直接调用 pandoc 命令）
sudo apt install pandoc

# 也可用 conda 安装（需在启动环境中）
conda install pandoc
```

> pandoc 在启动环境的 PATH 中可直接调用，不仅是 miner conda 环境内。

### 3. 安装 Python 依赖（在启动环境中）

```bash
pip install pypdfium2 lxml pylatexenc
```

> `pypdfium2` 用于加密 PDF 预检；`lxml` 用于 DOCX 后处理；`pylatexenc` 用于 LaTeX 深度修复。

### 4. （可选）安装 Node.js 验证依赖

```bash
# 安装 Node.js（系统级或 nvm），然后：
npm install
```

> - **生产管线（`run_ocr.py` / `md2docx.py`）不需要 Node.js**——仅依赖 Python + pandoc。
> - Node.js + npm 包（katex, latex-to-omml）**仅用于测试**：`check_formulas.py` 用 KaTeX 验证公式正确性，
>   `tests/check_pandoc.py` 用 pandoc 验证转换兼容性。

## 使用

### 国内用户：切换至 ModelScope 镜像

```bash
export MINERU_MODEL_SOURCE=modelscope
```

**温馨提示**：`run_ocr.py` 已内置此设置，无需重复 export。

### 运行流水线

```bash
python run_ocr.py -i /path/to/document.pdf        # 单文件
python run_ocr.py -i /path/to/pdf_directory        # 递归目录
python run_ocr.py -i /path/to/dir --effort medium   # 快速模式
python run_ocr.py -i /path/to/dir --review          # 公式后加红色【需校对】
python run_ocr.py -i /path/to/dir --skip-ocr        # 仅后处理
```

> 脚本会自动在 conda 的 `miner` 环境中调用 MinerU，无需手动 `conda activate miner`。
> 目录模式下会递归扫描所有子目录，加密 PDF 自动跳过。

### 输出

- **最终 Word 文档**：与输入文件放在同一目录，文件名相同，扩展名为 `.docx`。
  例如 `/path/to/数学/试卷.pdf` → `/path/to/数学/试卷.docx`
- **中间产物**：在 `work/` 下镜像输入目录结构：

```
work/<镜像目录结构>/
  └── <文件名>/
        └── hybrid_auto/
              ├── <文件名>.md           ← MinerU 输出的 Markdown
              ├── <文件名>_middle.json  ← 图片 bbox / 页面尺寸
              └── images/              ← 识别的图片
```

### 重复运行

- `.docx` 已存在 → 完全跳过
- `work/` 镜像目录已存在但 `.docx` 不存在 → 跳过 OCR，仅后处理
- 均不存在 → 完整 OCR + 后处理

## 全部命令行参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `-i`, `--input` | 内置路径 | PDF / 图片文件或目录（目录模式递归扫描子目录） |
| `-o`, `--output-dir` | `work` | 中间产物目录 |
| `--force` | 否 | 强制重跑 OCR |
| `--force-docx` | 否 | 强制重新生成 DOCX，跳过 OCR |
| `--skip-ocr` | 否 | 跳过 OCR，仅执行后处理 |
| `--no-fix` | 否 | 跳过公式修复，用原始 Markdown |
| `--review` | 否 | 在行间公式后添加红色【需校对】标记（默认关闭） |
| `--conda-env` | `miner` | MinerU 所在的 conda 环境名 |
| `--model-source` | `modelscope` | MinerU 模型下载源 |
| `--effort` | **`high`** | MinerU 解析精度：`high`（高准确率，较慢）/ `medium`（快速） |

> `--effort high` 会启用图片/图表分析，整体识别准确率更高，公式识别也会受益，代价是速度变慢。仅 `hybrid-engine` / `hybrid-http-client` 后端有效（默认即为 `hybrid-engine`）。

## 流水线步骤

| 步骤 | 说明 |
|------|------|
| OCR | MinerU 识别 PDF / 图片 → Markdown（默认 `--effort high`，加密 PDF 自动跳过） |
| 修复 | HTML 转换、LaTeX 公式修复、公式内多余空格清理、中文 `\text{}` 包裹 |
| 图片尺寸 | 从 `_middle.json` 读取 bbox，还原 PDF 中的原始显示尺寸（`![](x.jpg){width=Xin}`） |
| 转 docx | pandoc 转换 + 表格边框 + 公式字体（Times New Roman，字母斜体数字正体） |

## 独立 md→docx 转换（不依赖 MinerU / Conda）

如果你已经有 `.md` 文件（无论来源），可以直接用 `md2docx.py` 转换为精美 Word 文档：

```bash
python md2docx.py -i document.md                       # 最简用法
python md2docx.py -i doc.md -o output.docx --review     # 公式后加红色【需校对】
python md2docx.py -i doc.md --middle-json _middle.json  # 修复图片显示尺寸
python md2docx.py -i doc.md --no-fix                    # 跳过公式修复
python md2docx.py -i doc.md --font "Latin Modern Math"  # 自定义公式字体
```

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `-i`, `--input` | **(必需)** | 输入 Markdown 文件路径 |
| `-o`, `--output` | 同目录同名 | 输出 DOCX 路径 |
| `--middle-json` | 无 | MinerU `_middle.json` 路径，用于图片尺寸修复 |
| `--review` | 否 | 在行间公式后添加红色【需校对】标记 |
| `--no-fix` | 否 | 跳过公式修复，直接用原始 Markdown |
| `--font` | Times New Roman | OMML 公式字体名称 |
| `--no-borders` | 否 | 跳过表格边框添加 |
| `--no-math-font` | 否 | 跳过公式字体设置 |

**处理流程**：公式修复 → pandoc md→docx → 表格边框 → 公式字体 → [审阅标记]

> `md2docx.py` 仅依赖 **pandoc** + Python 包（`lxml`, `pylatexenc`），无需 MinerU 或 Conda。

## OMML 公式转 MathType

Word 原生 OMML 公式排版不如 MathType 美观（分子分母偏小）。可用 MathType 内置功能批量转换：

1. 打开 Word，点击 MathType 选项卡 → "Convert Equations"
2. 选择 "OMML to MathType"，点击 Convert

如果提示"找不到公式"，原因是 Office 自带的 `OMML2MML.XSL` 版本不兼容。
解决方法：将项目根目录下的 `OMML2MML.XSL` 复制到：
```
C:\Program Files\Microsoft Office\root\Office16\OMML2MML.XSL
```
替换后重新打开 Word 即可正常转换。