---
name: pdf-analyzer
description: 使用 MinerU API 读取并分析 PDF 文件，支持文件解析、表格/公式提取、OCR 识别、异步任务管理
license: MIT
compatibility: opencode
metadata:
  server: http://192.168.31.138:8312
---

## 概述

通过 MinerU API (`http://192.168.31.138:8312`) 分析 PDF/图片/DOCX/PPTX/XLSX 文件。

## API 端点

### 1. 同步解析 `POST /file_parse`

上传文件并等待解析完成，直接返回结果。

```bash
curl -X POST "http://192.168.31.138:8312/file_parse" \
  -F "files=@/path/to/document.pdf" \
  -F "lang_list=ch" \
  -F "backend=hybrid-auto-engine" \
  -F "parse_method=auto" \
  -F "formula_enable=true" \
  -F "table_enable=true" \
  -F "image_analysis=true" \
  -F "return_md=true"
```

### 2. 异步提交 `POST /tasks`

提交解析任务，立即返回 `task_id`。

```bash
curl -X POST "http://192.168.31.138:8312/tasks" \
  -F "files=@/path/to/document.pdf" \
  -F "lang_list=ch" \
  -F "backend=hybrid-auto-engine" \
  -F "return_md=true"
```

### 3. 查询任务状态 `GET /tasks/{task_id}`

```bash
curl "http://192.168.31.138:8312/tasks/{task_id}"
```

返回状态: `pending`, `running`, `completed`, `failed`

### 4. 获取任务结果 `GET /tasks/{task_id}/result`

```bash
curl "http://192.168.31.138:8312/tasks/{task_id}/result"
```

### 5. 健康检查 `GET /health`

```bash
curl "http://192.168.31.138:8312/health"
```

## 参数说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `files` | array | 必填 | 上传 PDF/图片/DOCX/PPTX/XLSX 文件 |
| `lang_list` | array | `["ch"]` | OCR 语言: `ch`, `en`, `korean`, `japan`, `arabic`, `latin`, `cyrillic`, `devanagari` 等 |
| `backend` | string | `hybrid-auto-engine` | 解析后端: `pipeline`, `vlm-auto-engine`, `vlm-http-client`, `hybrid-auto-engine`, `hybrid-http-client` |
| `parse_method` | string | `auto` | 解析方法: `auto`, `txt`, `ocr`（仅 pipeline/hybrid） |
| `formula_enable` | bool | `true` | 是否解析公式 |
| `table_enable` | bool | `true` | 是否解析表格 |
| `image_analysis` | bool | `true` | 是否分析图片/图表（VLM/hybrid 后端） |
| `server_url` | string | null | OpenAI 兼容服务器 URL（仅 http-client 后端） |
| `return_md` | bool | `true` | 返回 Markdown 内容 |
| `return_middle_json` | bool | `false` | 返回中间 JSON |
| `return_model_output` | bool | `false` | 返回模型输出 JSON |
| `return_content_list` | bool | `false` | 返回内容列表 JSON |
| `return_images` | bool | `false` | 返回提取的图片 |
| `response_format_zip` | bool | `false` | 返回 ZIP 格式结果 |
| `return_original_file` | bool | `false` | ZIP 中包含原始文件 |
| `client_side_output_generation` | bool | `false` | 客户端生成最终输出 |
| `start_page_id` | int | 0 | 开始页码（从 0 开始） |
| `end_page_id` | int | 99999 | 结束页码（从 0 开始） |

## Python 使用示例

```python
import requests

API_BASE = "http://192.168.31.138:8312"

# 同步解析
with open("document.pdf", "rb") as f:
    resp = requests.post(f"{API_BASE}/file_parse", files=[
        ("files", ("document.pdf", f, "application/pdf"))
    ], data={
        "lang_list": ["ch", "en"],
        "backend": "hybrid-auto-engine",
        "formula_enable": True,
        "table_enable": True,
        "return_md": True,
        "return_content_list": True
    })
    result = resp.json()
    print(result.get("md", ""))  # Markdown 内容

# 异步解析
with open("document.pdf", "rb") as f:
    resp = requests.post(f"{API_BASE}/tasks", files=[
        ("files", ("document.pdf", f, "application/pdf"))
    ], data={"return_md": True})
    task_id = resp.json()["task_id"]

import time
while True:
    status = requests.get(f"{API_BASE}/tasks/{task_id}").json()
    if status["status"] in ("completed", "failed"):
        break
    time.sleep(2)

result = requests.get(f"{API_BASE}/tasks/{task_id}/result").json()
```

## 使用场景

1. **PDF 转 Markdown** — 提取 PDF 内容为结构化 Markdown
2. **表格提取** — 从 PDF 中识别并提取表格数据
3. **公式提取** — 提取数学公式（LaTeX 格式）
4. **图片分析** — 识别并分析 PDF 中的图片/图表
5. **OCR 识别** — 扫描件/图片型 PDF 的文字识别
6. **多语言文档** — 支持中文、英文、日文、韩文、阿拉伯语等多种语言
7. **分页解析** — 通过 `start_page_id` / `end_page_id` 指定页码范围