PDF → Markdown（MinerU）
使用 MinerU（opendatalab/MinerU）將 PDF 轉換為保留結構的乾淨 Markdown，這是最適合學術論文的高保真開源引擎。管線後端在 GPU（CUDA）上運行。輸出保留標題層級、行內 LaTeX 數學公式（$...$）、圖片和表格（以 HTML 呈現）。
使用時機
- 使用者要求「將這個 PDF 轉換/提取為 Markdown（或文字）。」
- 最適合：學術論文 — 多欄佈局、LaTeX 數學公式、表格、參考文獻。
- 也處理圖片、
.docx、.pptx、.xlsx（直接傳遞檔案）。
如何執行
MinerU 位於專屬的隔離環境中，並透過內建的 convert.py 包裝器驅動，該包裝器在處理程序中呼叫 MinerU 的 Python API。
不要在這裡使用
mineruCLI — 在 3.4.0 版本中，它會啟動一個本機 API 伺服器，在 Windows 上會回傳502 Bad Gateway。包裝器繞過了這個問題。
"$MINERU_PYTHON" \
"<SKILLS_DIR>/pdf-to-markdown/convert.py" \
"<input.pdf>" "<output_dir>" --lang en
- 參數 1 — 輸入檔案（pdf/圖片/docx/pptx/xlsx）。
- 參數 2 — 輸出目錄。
--lang— OCR 語言提示：en為英文，ch為中文/混合（預設為ch，也能處理英文）。僅影響 OCR（掃描）頁面。- 成功時腳本會印出
DONE -> <路徑>.md。
輸出結構
<output_dir>/<name>/auto/<name>.md # Markdown 檔案
<output_dir>/<name>/auto/images/ # 提取的圖片（由 Markdown 參照）
<output_dir>/<name>/auto/<name>_*.json # 版面/內容元資料（可以忽略）
轉換後
- 讀取印出的
DONE -> ...md路徑並回報給使用者。 - 可選擇顯示簡短預覽（標題 + 第一個標題）。
- 註明提取的圖片寫入位置。
- 品質通常很高：標題顯示為
#，行內數學公式顯示為$...$，表格顯示為<table>HTML（儲存格內含 LaTeX）。如果掃描的 PDF 出現亂碼，請使用--method ocr重新執行。
事前檢查/設定（僅在缺少某項時執行）
- 帶有 MinerU 的直譯器（環境變數
MINERU_PYTHON，預設為python）。 - 驗證 CUDA：
$MINERU_PYTHON -c "import torch; print(torch.cuda.is_available())"→True。 - 模型已預先下載至
~/.cache/huggingface/hub/（一次性）。
如果環境遺失，請重新建立（如有需要，先安裝 uv）：
uv venv --python 3.12 "<your-env>"
uv pip install --python "<your-env>/Scripts/python.exe" torch torchvision --index-url https://download.pytorch.org/whl/cu124
uv pip install --python "<your-env>/Scripts/python.exe" -U "mineru[core]"
"<your-env>/Scripts/mineru-models-download.exe" -s huggingface -m pipeline
然後將 MINERU_PYTHON 設定為 <your-env>/Scripts/python.exe（Windows）或 <your-env>/bin/python（macOS/Linux）。在 macOS/Linux 上，模型下載的二進位檔案是 mineru-models-download（沒有 .exe 後綴）。
疑難排解
cuda.is_available()為 False → 從cu124索引重新安裝 torch（請參閱設定）。 仍在必要時於 CPU 上執行管線，只是速度較慢。- 模型下載失敗/速度慢 → 使用
-s modelscope重新執行mineru-models-download。 - 掃描的 PDF 亂碼 → 在
convert.py呼叫中加入--method ocr。 vlm-engine/hybrid-engine後端 → 這些需要 vLLM/SGLang（Linux）；它們在 Windows 上回傳 502。請堅持使用包裝器使用的預設pipeline後端。
輕量級備用方案（簡單/Office 文件）
對於非論文檔案，如果版面保真度不重要，微軟的 MarkItDown 更快更簡單 — 但它會破壞學術雙欄 PDF 和表格，因此對於論文建議使用 MinerU：
"$MINERU_PYTHON" -m pip install markitdown
"$MINERU_PYTHON" -m markitdown "<input>" > out.md