author: ninehills (Tao Yang)

source: https://github.com/ninehills/pdf2md

tags: [pdf, markdown, ocr, vlm, go, docker, cli]

rating: ⭐⭐⭐⭐☆ (4/5)

pdf2md — Go 写的 PDF 转 Markdown CLI，Docker VLM 推理

一句话版本

一个纯 Go 单二进制 CLI 工具，通过自动拉 Docker 容器跑 VLM（视觉语言模型）把 PDF 文档转成 Markdown，本机零 Python/ONNX/CUDA 依赖，支持三种 OCR/解析模型可切换。

基本信息

• 作者: ninehills (Tao Yang) — 南开大学，455 GitHub followers，之前的报告 Matt Pocock Skills
• 仓库: ninehills/pdf2md
• 协议: MIT
• 语言: Go 96.2% + Python 3.4% + Dockerfile
• 最新版本: v0.2 (2026-05-20，今天发布)
• Stars: 5（极早期）

支持的模型

架构

设计哲学

纯 Go 单二进制，零本机 ML 依赖。所有机器学习推理都在 Docker 容器内完成——用户只需要 Docker + nvidia-container-toolkit，不需要安装 Python、CUDA、onnxruntime 等。

通用流水线

PDF → 渲染页面（MuPDF）
       → [Docker VLM 服务] 推理
       → Markdown 输出

PaddleOCR-VL 两阶段流水线

PDF → 渲染页面
       → [ONNX Docker 容器] PP-DocLayoutV3 布局检测 → bboxes + labels
         → 按 bbox 裁子图
           → [llama.cpp Docker 容器] PaddleOCR-VL VLM 按块识别
             → 合并 → Markdown + JSON

安装与使用

安装

# 预编译二进制（推荐）
curl -sL https://github.com/ninehills/pdf2md/releases/download/v0.1/pdf2md_0.1_linux_amd64.tar.gz | tar xz

# 从源码
git clone https://github.com/ninehills/pdf2md && cd pdf2md
go build -o pdf2md .

使用

# 默认模型 dots-ocr
./pdf2md paper.pdf

# 指定模型
./pdf2md --model logics-parsing-v2 paper.pdf
./pdf2md --model paddleocr-vl-1.5-gguf paper.pdf

# 指定输出目录
./pdf2md -o ./output paper.pdf

命令行参数

项目结构

pdf2md/
├── cmd/root/           # CLI 入口 + pipeline 编排
├── pkg/
│   ├── base64util/     # Base64 编解码
│   ├── docker/         # Docker 容器管理
│   ├── htmlmd/         # HTML → Markdown 转换
│   ├── inference/      # VLM HTTP 推理客户端
│   ├── layout/         # Label→Prompt 映射表
│   ├── layoutclient/   # ONNX Docker HTTP 客户端
│   ├── markdown/       # Markdown 合成/合并
│   ├── model/          # HF 模型下载
│   ├── models/         # 模型注册表
│   ├── paddlelayout/   # PaddleOCR layout 解析/裁图
│   └── pdf/            # PDF 页面渲染
├── docker/onnx/        # ONNX 容器镜像定义
├── docs/               # 设计文档
├── examples/           # 测试用 PDF
└── testdata/           # 测试数据

技术亮点

1. 全 Docker 化推理 — 用户只装 Docker + 显卡驱动，无 Python/ONNX/CUDA 依赖地狱

2. 三模型可切换 — 从轻量 OCR（dots-ocr）到结构化解析（logics-parsing）到两阶段检测（paddleocr）

3. vLLM + llama.cpp 双后端 — vLLM 适合 GPU 充裕场景，llama.cpp GGUF 适合资源受限

4. ONNX 独立容器 — 布局检测作为独立 Docker 服务，HTTP 通信，不与 VLM 共用 GPU

5. 纯 Go 单二进制 — 跨平台（linux/macos/windows × amd64/arm64），go build 即可

6. goreleaser CI/CD — 自动构建 6 平台二进制

不足/风险

1. 极早期 — v0.2，5 stars，只有 2 个 release，功能能级有限

2. GPU 依赖 — Docker GPU 推理意味着不可在无 GPU 环境运行

3. 启动慢 — 每次运行需要拉取 Docker 镜像 + 启动服务（可缓存）

4. 模型下载大 — VLM 模型文件体积大，首次使用时下载时间长

5. 生产可用性未知 — 测试覆盖（78 tests）还可以，但稳定性缺乏社区验证

与类似项目对比

评分：⭐⭐⭐⭐☆ (4/5)

• 创新性: ⭐⭐⭐⭐ — Go 写 PDF→Markdown + Docker 化推理是一个新思路
• 实用性: ⭐⭐⭐ — 依赖 GPU Docker，门槛不低，但效果可能好
• 工程品质: ⭐⭐⭐⭐⭐ — Go 代码结构清晰，goreleaser CI/CD，78 测试
• 成熟度: ⭐⭐ — v0.2，5 stars，社区待验证

参考资料

• pdf2md GitHub
• ninehills (Tao Yang)
• Matt Pocock Skills 报告
• vLLM
• llama.cpp
• go-fitz (MuPDF Go 绑定)