mineru-cpu-deploy

純 CPU 環境下的 MinerU 3.1.6 容器化部署設定，提供 PDF → Markdown 解析 API（mineru-api，FastAPI），鎖定 pipeline backend，供其他容器化 Web 應用（如 mad-professor）透過內部網路呼叫。

Requirements

• Linux x86_64（已驗證於 Ubuntu 24.04 / GCP n1-standard-4）
• Docker 24+（含 Compose v2，docker compose 而非 docker-compose）
• 至少 10GB 可用磁碟（映像檔 + 模型權重 ~3.2GB + 解析輸出）
• 至少 8GB RAM（建議 10GB，concurrency=3 時尤其）

⚠️ macOS Apple Silicon 警告

Docker Desktop on macOS 跑的是 Linux VM，容器內無法使用 Metal/MPS 加速，即使你的 Mac 是 Apple Silicon 也一樣只能跑 CPU，且因虛擬化開銷會比原生 Linux 明顯更慢。macOS 僅適合功能驗證，正式部署請用 Linux x86_64 主機。

Quick start

git clone https://github.com/jialuncheng/mineru-cpu-deploy.git
cd mineru-cpu-deploy

# 建置並背景啟動
docker compose up -d

# 觀察啟動 log
docker compose logs -f mineru

第一次解析會 lazy load 模型：服務啟動本身很快，但第一個 /file_parse 請求會即時下載並載入模型權重（約 3.2GB），這次請求會明顯較久且需要對外網路。權重會存進 mineru-models volume，之後重啟不需重新下載。

驗證服務

# 預期回傳 HTTP 200，Swagger UI HTML
curl -fsS http://localhost:8000/docs && echo OK

也可瀏覽器開 http://localhost:8000/docs（需在主機本機，因為只 bind loopback）。

API 使用範例

解析一份 PDF（務必帶 backend=pipeline，這是 CPU 模式唯一支援的 backend）：

curl -X POST "http://localhost:8000/file_parse" \
  -F "files=@/path/to/input.pdf" \
  -F "backend=pipeline" \
  -F "lang=ch" \
  -F "return_md=true"

回應為 JSON，含解析後的 Markdown；輸出檔同時寫入 mineru-output volume（容器內 /data/output）。完整參數見 /docs。

Port 暴露策略

預設 docker-compose.yml 只把服務綁在 127.0.0.1:8000，不對外網路開放。視呼叫端位置選一種：

1. 127.0.0.1 only（預設）：呼叫端跑在同一台主機（非容器）時，直接打 http://localhost:8000。最安全。
2. Docker network：呼叫端是另一個容器時，把它接到 mineru-net 網路（見下方 external 範例），用服務名 http://mineru:8000 互通，不需要對主機暴露任何 port。建議移除 compose 中的 ports 區塊。
3. SSH tunnel：從遠端開發機臨時存取，不要改 firewall：

   ssh -L 8000:127.0.0.1:8000 user@your-gcp-vm
   # 之後本機 http://localhost:8000/docs 即為遠端服務

Volumes

Volume	容器路徑	用途
mineru-models	/data/huggingface	HF 模型權重快取（~3.2GB），重啟不需重抓
mineru-output	/data/output	解析輸出，設計為跨容器共用

讓其他容器共用 mineru-output

在另一個 compose 專案（如 mad-professor）以 external volume / network 接入：

services:
  mad-professor:
    # ...
    volumes:
      - mineru-output:/shared/mineru-output:ro   # 唯讀掛載解析輸出
    networks:
      - mineru-net                                # 用 http://mineru:8000 呼叫

volumes:
  mineru-output:
    external: true
    name: mineru-cpu-deploy_mineru-output   # docker volume ls 確認實際名稱

networks:
  mineru-net:
    external: true

external volume / network 的實際名稱依 compose 專案前綴而定，請先用 docker volume ls 與 docker network ls 確認。

更新 MinerU 版本

版本鎖在 Dockerfile，更新步驟：

1. 編輯 Dockerfile，把 pip install "mineru[core]==3.1.6" 改成目標版本（例如 ==3.2.0）。
2. 同步更新 docker-compose.yml 的 image: mineru-cpu:<新版本> tag。
3. 重新建置並重啟：

   docker compose build --no-cache
   docker compose up -d

模型 volume 會保留；若新版需要不同模型，第一次解析會自動補抓。

Troubleshooting

• 報 CUDA / GPU 相關錯誤：通常是請求沒帶 backend=pipeline，被導向 vlm/hybrid GPU backend。CPU 部署請務必在每個 /file_parse 帶 -F "backend=pipeline"。
• OOM / 容器被 kill：降低併發 — 把 MINERU_API_MAX_CONCURRENT_REQUESTS 調低（例如 2 或 1），或調高 docker-compose.yml 的 memory limit；大型 PDF 記憶體用量較高。
• 第一個請求很久 / timeout：屬正常的模型 lazy load（~3.2GB 下載），確認對外網路可達 Hugging Face，或改 MINERU_MODEL_SOURCE=modelscope。

Inspired by

• opendatalab/MinerU
• praveen-ks-2001/mineru-railway

License

詳見本 repo 內的 LICENSE 檔（GitHub 建立 repo 時預設產生）。