PDF 转 Markdown Skill (v1.1)

将 PDF 文件（含扫描件、图片）转换为 Markdown 格式，支持 OCR 识别。

核心功能

Token 申请

1. MinerU Token

申请地址：https://mineru.net/apiManage/token

申请步骤：

1. 打开 https://mineru.net 注册账号
2. 进入「API管理」→「Token管理」
3. 点击「创建新Token」
4. 复制 Token 并妥善保存

使用方式：

# 设置环境变量
$env:MINERU_API_KEY = "你的Token"

# 或在脚本中传入
from magic_pdf import MagicPDF
md = MagicPDF(api_key="你的Token")

2. PaddleOCR Token

申请地址：

• 主入口：https://aistudio.baidu.com/paddleocr
• Token管理：https://aistudio.baidu.com/account/accessToken

申请步骤：

1. 打开 https://aistudio.baidu.com 注册/登录百度账号
2. 进入「个人中心」→「AccessToken管理」
3. 点击「创建令牌」或复制现有 Token
4. 勾选「使用PaddleOcr令牌」

使用方式：

# 设置环境变量
$env:PADDLEOCR_ACCESS_TOKEN = "你的Token"

# 或在脚本中传入
from aistudio import AccessToken
token = AccessToken(access_token="你的Token")

接入引擎

1. MinerU

两种使用方式：

方式 A：本地部署（免费，无需 Token）

pip install magic-pdf[full]

• 完全离线可用
• 首次运行下载模型（约 2GB）
• 推荐配置：8GB+ 内存

方式 B：云端 API（需要 Token）

pip install magic-pdf[full]
# 设置Token后自动使用云端
$env:MINERU_API_KEY = "你的Token"

2. PaddleOCR

两种使用方式：

方式 A：本地部署（免费，无需 Token）

pip install paddleocr paddlepaddle pymupdf

• 完全离线可用
• 首次运行下载模型（约 300MB）
• 适合中英文纯文字识别

方式 B：在线 API（需要 Token）

pip install paddleseg aistudio
$env:PADDLEOCR_ACCESS_TOKEN = "你的Token"

3. 兼容本地 OCR（无 Token）

兼容以下本地识别方式：

环境要求

• Python 3.10+
• 需要网络下载模型（首次使用，可离线后续）
• 推荐 8GB+ 内存，GPU 可选（加速）

实现脚本

1. MinerU 封装 (scripts/mineru_parser.py)

import os
from magic_pdf import MagicPDF

# 方式一：本地模式（默认）
md = MagicPDF(mode="local")

# 方式二：API模式（自动检测Token）
api_key = os.environ.get("MINERU_API_KEY", "")
if api_key:
    md = MagicPDF(mode="api", api_key=api_key)
else:
    md = MagicPDF(mode="local")

result = md.parse("document.pdf", lang="zh_en")
print(result.content)

2. PaddleOCR 封装 (scripts/paddleocr_parser.py)

import os
from paddleocr import PaddleOCR
import fitz

def ocr_local(file_path: str, lang: str = "ch"):
    """本地 OCR"""
    ocr = PaddleOCR(use_angle_cls=True, lang=lang, show_log=False)
    return ocr.ocr(file_path, cls=True)

def ocr_api(file_path: str, access_token: str):
    """API OCR"""
    from aistudio import AccessToken
    # 使用云端API
    pass

3. 自动选引擎 (scripts/auto_convert.py)

def detect_and_convert(input_path, output_path=None, engine="auto"):
    """自动检测可用引擎并转换"""
    engines = []
    
    # 优先检测Token是否存在
    if os.environ.get("MINERU_API_KEY"):
        engines.append("mineru-api")
    else:
        try:
            from magic_pdf import MagicPDF
            engines.append("mineru-local")
        except: pass
    
    if os.environ.get("PADDLEOCR_ACCESS_TOKEN"):
        engines.append("paddleocr-api")
    else:
        try:
            from paddleocr import PaddleOCR
            engines.append("paddleocr-local")
        except: pass
    
    # 兼容之前技能
    try:
        import pytesseract
        engines.append("tesseract")
    except: pass
    
    # 自动选（优先API）
    if engine == "auto":
        # 优先选API模式的引擎
        for e in engines:
            if "-api" in e:
                engine = e
                break
        else:
            engine = engines[0] if engines else None
    
    # 执行转换...

使用方法

快速开始

# 1. 本地模式（推荐首次试用）
pip install magic-pdf[full]
python scripts/mineru_parser.py -i document.pdf -o result.md

# 2. 使用 API 模式
$env:MINERU_API_KEY = "你的Token"
python scripts/auto_convert.py -i document.pdf -o result.md -e mineru-api

# 3. 自动选择
python scripts/auto_convert.py -i document.pdf -o result.md

带 Token 调用

# MinerU API 模式
from magic_pdf import MagicPDF
md = MagicPDF(api_key="你的MINERU_TOKEN")
result = md.parse("test.pdf")
print(result.content)

# PaddleOCR API 模式  
from aistudio import AccessToken
token = AccessToken(access_token="你的PADDLEOCR_TOKEN")

安装依赖

本地模式（免费）

# MinerU 本地
pip install magic-pdf[full]

# PaddleOCR 本地
pip install paddleocr paddlepaddle pymupdf

API 模式（需要 Token）

# MinerU API
pip install magic-pdf[full]  # 本地包即可，用环境变量指定Token

# PaddleOCR API
pip install aistudio

额度限制

注：超过单文件上限时自动分片处理

推荐方案

推荐优先使用云端 API（本地OCR较慢，云端效果更好）：

自动切换策略：

• 检测到 Token 时自动使用云端 API
• 本地模式作为 fallback（无 Token 时备选）
• 超额自动切换到另一引擎

推荐配置：

1. 首次使用 → 本地版测试流程
2. 正式使用 → 申请 Token 接入云端
3. 大批量 → 使用 PaddleOCR（额度更高）

版本历史