MinerU PDF 转 Markdown

按下面流程执行，默认只处理单个 PDF；批量处理时循环调用同一命令。

依赖与前置条件

•确保 MinerU API 服务可用。
•服务端安装/启动参考 env_install/mineru_server_deploy.md。
•客户端通常只需 SSH 端口转发到本机 18543，不需要重复安装 MinerU。
•使用 python3 运行脚本；requests 需要已安装。

输入约定

•必要输入: pdf_path: 待转换 PDF 路径（绝对路径或相对路径均可）。
•可选输入: output_base: 输出根目录，默认 example_data/md_with_images。 api_url: API 地址，默认 http://localhost:18543/file_parse。

标准执行流程

•将 pdf_path 拆成: input_base: PDF 所在目录。 pdf_file_name: PDF 文件名。
•可选：先计算标准化文件名，预估输出目录名。

bash

python3 scripts/pdf_name_utils.py --pdf-file-name "<pdf_file_name>"

•执行转换。

bash

python3 scripts/mineru_pdf2md.py \
  --input-base "<input_base>" \
  --pdf-file-name "<pdf_file_name>" \
  --output-base "<output_base>" \
  --api-url "http://localhost:18543/file_parse"

•检查输出目录 <output_base>/<normalized_pdf_name>/ 是否包含: <normalized_pdf_name>.md content_list.json images/（若原文含图）

输出结构说明（示例：Palimpzest）

以目录 example_data/md_with_images/Palimpzest_Liu_et_al_2024_A_Declarative_System_for_Optimizing_AI_Workloads/ 为例，输出结构如下：

text

Palimpzest_Liu_et_al_2024_A_Declarative_System_for_Optimizing_AI_Workloads/
├── Palimpzest_Liu_et_al_2024_A_Declarative_System_for_Optimizing_AI_Workloads.md
├── content_list.json
└── images/
    ├── <hash>.jpg
    └── ...

•
<normalized_name>.md: 主阅读文件，包含正文、标题、列表、图片引用、部分 HTML 表格。图片以 ![](images/<hash>.jpg) 引用。该示例中 Markdown 共引用 10 张图片。
•
content_list.json: 结构化解析结果，顶层是 list[object]，按版面阅读顺序排列。该示例共 315 条，包含 4 类 type: text 210 条 discarded 89 条 image 10 条 table 6 条
•
images/: 保存服务端返回并解码后的图片文件。该示例目录中共有 16 张图片，其中: 10 张对应 image 类型（通常在 Markdown 中被引用） 6 张对应 table 类型（常用于表格原图，不一定在 Markdown 中直接引用）

content_list.json 字段约定

•
通用字段: type: 块类型，取值通常为 text / discarded / image / table。 bbox: 版面坐标，格式 [x0, y0, x1, y1]，(x0,y0)是左上角坐标， (x1,y1)是右上角坐标。 page_idx: 页码，从 0 开始。
•
text: 字段通常为 type, text, bbox, page_idx，部分条目有 text_level（如标题层级）。
•
discarded: 字段通常为 type, text, bbox, page_idx，表示被识别但未纳入主正文的内容（如页眉页脚、侧边文字等）。
•
image: 字段通常为 type, img_path, image_caption, image_footnote, bbox, page_idx。 img_path 是相对当前输出目录的路径（如 images/<hash>.jpg）。 image_caption/image_footnote 为字符串列表，可能为空列表。
•
table: 字段通常为 type, img_path, table_caption, table_body, table_footnote, bbox, page_idx。 table_body 是 HTML table 字符串，可直接渲染或二次转换。 img_path 对应表格截图，常用于回溯版面或做 OCR 复核。

下游消费建议

•默认优先读取 <normalized_name>.md 作为全文语义输入。
•需要页码定位、版面坐标、结构化筛选时，再读取 content_list.json。
•需要图表溯源时，用 content_list.json 的 img_path 去 images/ 取图，不要假设 images/ 内文件都会出现在 Markdown 引用中。

批量处理模板

对一个目录内多个 PDF 批量处理时，循环调用脚本，不改脚本逻辑。

bash

for f in /path/to/pdfs/*.pdf; do
  python3 scripts/mineru_pdf2md.py \
    --input-base "$(dirname "$f")" \
    --pdf-file-name "$(basename "$f")" \
    --output-base "/path/to/output" \
    --api-url "http://localhost:18543/file_parse"
done

常见问题处理

•连接失败（Connection refused / timeout）: 先确认 API 进程是否运行，或 SSH 转发是否将远端 18543 映射到本地 18543。
•python3: No module named requests: 在当前环境安装 requests 后重试。
•输出缺少图片目录: 通常表示文档无可导出图片，或服务端未返回 images 字段；优先检查 content_list.json 和服务日志。