# mineru

**Repository Path**: hrdt/mineru

## Basic Information

- **Project Name**: mineru
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-07
- **Last Updated**: 2026-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mineru-cli

一个 Python 命令行工具，把 PDF 文档通过 [MinerU 精准解析 API](https://mineru.net/apiManage/docs) 转换为 Markdown。

## 特性

- 自动处理 **超过 200 页硬性上限的 PDF**（在客户端按 `max_pages_per_chunk` 拆分，转换后合并 Markdown、图片与 JSON）。
- 规范的输出目录：每个 PDF 一个子目录，含合并后的 `.md`、`images/`、`metadata.json`、`content_list.json`、`model.json`。
- **可选 `translate` 子命令**：把转换后的 Markdown 翻译为另一种语言，**保留原文件**输出并列双语版本。两阶段术语表保证前后文名词一致，占位符保护图片/代码块 byte-identical 还原。
- 异步 I/O，支持 `--concurrency N` 控制并发。
- 类型化错误体系，自动重试 429，按 `retry_after` 退避。
- 完整的 `respx` 测试覆盖，测试中无真实网络调用。

## 安装

```bash
git clone <this-repo>
cd mineru
make dev        # 或：pip install -e ".[dev]"
```

## 配置

```bash
cp .env.example .env
# 编辑 .env，填入 MINERU_TOKEN（在 https://mineru.net/apiManage/token 申请，90 天有效期）
```

也可以直接通过环境变量传入：

```bash
export MINERU_TOKEN=eyJhbGciOi...
```

## 使用

### 单个文件

```bash
mineru convert path/to/file.pdf -o ./output
```

### 多个文件 / 目录

```bash
mineru convert ./reports/ -o ./output --concurrency 3
```

目录默认递归扫描；非 PDF 文件会被跳过并给出警告。

### 大文件（> 200 页）

工具会自动按 `--max-pages-per-chunk`（默认 200，对应官方硬性上限）拆分文件，并行上传、提交任务。任务完成后合并 Markdown，统一管理 `images/`，并把元数据写入 `metadata.json`。

```bash
mineru convert big.pdf -o ./output --max-pages-per-chunk 200
```

### 全部参数

```text
mineru convert [PATH ...]
  -o, --output DIR                输出目录（默认 ./mineru_output）
  --concurrency N                 并发上限（默认 1）
  --max-pages-per-chunk N         每块最大页数（默认 200）
  --model-version {pipeline,vlm,MinerU-HTML}
                                  模型版本（默认 pipeline）
  --is-ocr                        强制 OCR
  --enable-formula / --no-enable-formula
                                  是否识别公式（默认启用）
  --enable-table / --no-enable-table
                                  是否识别表格（默认启用）
  --language LANG                 语言提示，如 en / ch
  --page-ranges RANGES            页码范围（如 "1-10,50-60"），仅对未拆分文件生效
  --extra-formats CSV             额外输出格式，可选 docx,html,latex
  --timeout SECONDS               单 PDF 总超时（默认 900）
  --data-id-prefix PREFIX         自定义幂等键前缀
  --keep-chunks                   保留中间 chunk-N/ 目录（调试用）
  --dry-run                       仅打印请求体，不实际上传
  -v, --verbose                   -v=INFO, -vv=DEBUG
  --env-file PATH                  自定义 .env 路径

mineru status TASK_ID             轮询单个任务的状态
mineru --version
```

### 翻译（`translate`）

对已经转换好的 Markdown 调用任意 OpenAI Chat Completions **或 Anthropic Messages** 兼容接口进行翻译，并保留原文件输出**并列双语**版本。

```bash
export TRANSLATE_API_KEY=sk-...
mineru translate "output/Annual Report 2025/Annual Report 2025.md" \
    --target-lang zh \
    --model gpt-4o-mini \
    --output ./translated
# 产出: ./translated/Annual Report 2025/Annual Report 2025.zh.md
#       ./translated/Annual Report 2025/translation_meta.json
# 保留: ./translated/Annual Report 2025/Annual Report 2025.md  (原文件)
#       ./translated/Annual Report 2025/images/                (共享)
```

`translate` 自动检测 API 协议：

| `TRANSLATE_BASE_URL` 包含 `/anthropic` | 协议 | 鉴权头 |
|---|---|---|
| 否 | OpenAI Chat Completions | `Authorization: Bearer ...` |
| 是 | Anthropic Messages | `x-api-key: ...` + `anthropic-version: 2023-06-01` |

`translate` 关键设计：

- **两阶段术语表**：先调用 LLM 从文档样本中抽取 `document_type` 和领域术语，再带着术语表翻译每个块。
- **占位符保护**：图片 `⟪IMG ...⟫`、代码块 `⟪CODE ...⟫`、数学块 `⟪MATH:...⟫` 占位后交给 LLM，翻译完 byte-identical 还原。
- **滑动上下文**：上一块译文最后 ~200 字符作为下一块的 `previous_translation_context`，避免术语/风格跳变。
- **一致性扫尾**：≥30 块的文档翻译完后，扫描残留的高比例 ASCII 行并重新送 LLM 修补。
- **输出 `<basename>.<lang>.md` 与 `translation_meta.json`**，原始 `.md` 和 `images/` 保留不动。

`translate` 完整参数：

```text
mineru translate [PATH ...]
  -o, --output DIR                输出目录（默认 ./mineru_output）
  --target-lang LANG              必填（如 zh, en, ja, fr）
  --source-lang LANG              源语言提示（默认 auto）
  --base-url URL                  OpenAI 兼容端点（默认 https://api.openai.com/v1）
  --api-key KEY                   Bearer token（或环境变量 TRANSLATE_API_KEY）
  --model NAME                    模型 id（默认 gpt-4o-mini）
  --glossary PATH                 用户预定义术语表 JSON（覆盖抽取结果）
  --max-chars-per-chunk N         单块字符上限（默认 4000）
  --concurrency N                 并发（默认 1）
  --max-glossary-terms N          自动抽取术语上限（默认 80）
  --temperature FLOAT              默认 0.2
  --skip-glossary                  跳过 phase-1 抽取，仅用 --glossary
  --no-consistency-pass            关闭译文扫尾
  -q, --quiet
  -v, --verbose
  --env-file PATH
```

环境变量：

```bash
TRANSLATE_BASE_URL=https://api.openai.com/v1
TRANSLATE_API_KEY=sk-...
TRANSLATE_MODEL=gpt-4o-mini
TRANSLATE_TEMPERATURE=0.2
TRANSLATE_MAX_CHARS_PER_CHUNK=4000
TRANSLATE_CONCURRENCY=1
TRANSLATE_MAX_GLOSSARY_TERMS=80
TRANSLATE_SOURCE_LANG=auto
```

预定义术语表示例（`--glossary ./terms.json`）：

```json
{
  "document_type": "academic",
  "domain": "machine learning",
  "terms": {
    "machine learning": "机器学习",
    "neural network": "神经网络"
  }
}
```

## 输出结构

### `convert` 产出

```text
output/<basename>/
├── <basename>.md              ← 合并后的 Markdown
├── images/                     ← 全部图片，统一加上 chunk-N 前缀
├── metadata.json               ← 运行元数据
├── content_list.json           ← MinerU 抽取的结构化内容
└── model.json                  ← 模型元数据
```

### `translate` 产出（与 convert 共用目录）

```text
output/<basename>/
├── <basename>.md              ← 原文件，保留不动
├── <basename>.<lang>.md       ← 翻译后的并列双语版本（新增）
├── images/                     ← 共享
├── metadata.json               ← convert 阶段留下的
├── content_list.json
├── model.json
└── translation_meta.json       ← 翻译元数据：术语表大小、块数、token（新增）
```

`metadata.json` 记录每个分块的 `index`、`pages`、`task_id`、`trace_id`、`pages_count`、`data_id`，可用于排查或重试。

## 错误处理

- **HTTP 401/403**：Token 无效或过期。
- **HTTP 429**：根据 `retry_after` 自动重试。
- **响应体 `-60018` / `-60019`**：当日额度耗尽，立即退出，不重试。
- **`state="failed"`**：从 `err_msg` 给出提示，并附上 `trace_id` 以便联系 MinerU 支持。

所有错误都带有 `trace_id` 便于在 MinerU 控制台查询日志。

## 运行测试

```bash
make test
```

## 已知限制

- MinerU 精准解析 API 单文件 ≤ 200 页、≤ 200 MB；超出会被服务端拒绝。
- 每日高优先级额度约 2,000 页/账号；超出后排队优先级降低。
- 合并后的 Markdown 图片引用使用相对路径（如 `./images/chunk-1-fig1.png`）；如需在其他位置使用，请保持目录结构一起移动。

## License

MIT