前言¶
把 PDF 喂進 RAG、讓 Agent 做引用或結構化抽取時，常見瓶頸不是模型能力，而是輸入質量：掃描件、多欄排版、表格與公式混排時，普通文本抽取往往亂序或丟結構。下面介紹 SkillHub 上的社區 Skill「Convert dense PDFs into LLM-ready text and page-aligned markdown with olmOCR」，它把何時該用 olmOCR、環境依賴與安裝路徑寫進 Agent 的 SKILL.md，便於在對話裏自動走文檔 OCR 與 Markdown 導出流程。
這是什麼¶
該 Skill 座標爲 @user_3c6cb52e/convert-dense-pdfs-into-llm-ready-text-and-page-aligned-markdown-with-olmocr，版本 1.0.0，來源爲 community（SkillHub 分類 office-efficiency），發佈者爲 user_3c6cb52e，標籤 requires_api_key=false，表示 Skill 本身不要求配置 API Key。
一句話定位：當代理需要將掃描版或版式複雜的文檔轉換爲乾淨的 markdown 或文本，以進行分塊、搜索、提取或引用工作流時，請使用 olmOCR。
Skill 內容整理自上游 allenai/olmocr 文檔，並標註社區維護路徑 1991513ccie-png/skills。底層工具 olmOCR 由 Allen Institute for AI（AllenNLP）團隊維護，面向 PDF、PNG、JPEG 等圖像類文檔，輸出可讀純文本或 Markdown。
核心功能¶
結合 Skill 摘要與上游 README，可覈實的能力包括：
- 將 PDF 及 PNG、JPEG 等圖像類文檔轉爲乾淨的 Markdown 或純文本。
- 支持公式、表格、手寫與複雜版式；可去除常見頁眉頁腳，並按自然閱讀順序組織正文（含多欄、插圖等佈局）。
- 使用
--markdown時，在工作區下生成與輸入對應的 Markdown 文件，便於後續分塊與頁面對齊引用。 - 推理方式可選：本機 GPU（7B 級視覺語言模型）、遠程 vLLM/OpenAI 兼容服務，或 Docker 鏡像批量處理。
Skill 內列出的先決條件：Python 3.11、pip 或 conda、poppler-utils；本地推理可選 NVIDIA GPU。上游說明基於約 7B 參數的 VLM，本機完整推理通常需要 GPU（文檔中舉例爲至少約 12GB 顯存、約 30GB 磁盤等條件）。
安裝與啓用¶
安裝 SkillHub CLI 與 Skill¶
先確認是否已安裝 skillhub：
command -v skillhub && skillhub --version
未安裝時可按 SkillHub 官方說明執行完整安裝（CLI + 默認 Skill）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
安裝本 Skill 時必須用 --dir 指向當前 Agent 的 skills 目錄，否則默認落在 ./skills/ 可能不會被識別。在 Cursor 中常用路徑爲 ~/.cursor/skills/：
skillhub install convert-dense-pdfs-into-llm-ready-text-and-page-aligned-markdown-with-olmocr \
--namespace user_3c6cb52e \
--dir ~/.cursor/skills/
也可讓 Agent 按 SkillHub 安裝說明 安裝座標 @user_3c6cb52e/convert-dense-pdfs-into-llm-ready-text-and-page-aligned-markdown-with-olmocr。Claude Code 對應目錄一般爲 ~/.claude/skills/；Codex 爲 ~/.codex/skills/ 或項目下的 .agents/skills/。
安裝 olmOCR 運行時（上游）¶
Skill 要求單獨準備 olmOCR 環境。Ubuntu/Debian 可先裝系統依賴（含 poppler-utils 與字體）：
sudo apt-get update
sudo apt-get install poppler-utils ttf-mscorefonts-installer msttcorefonts fonts-crosextra-caladea fonts-crosextra-carlito gsfonts lcdf-typetools
建議新建 conda 環境：
conda create -n olmocr python=3.11
conda activate olmocr
僅連接遠程推理服務時，可裝輕量包：
pip install olmocr
本機 GPU 推理示例（與 Skill 內摘錄一致，CUDA 12.8 索引）：
pip install olmocr[gpu] --extra-index-url https://download.pytorch.org/whl/cu128
安裝完成後，在對話中描述「掃描 PDF / 複雜版式 PDF 轉 Markdown 用於 RAG」等需求，Agent 會按 SKILL.md 引導選擇 olmOCR 而非簡單 pdftotext。
典型用法¶
以下命令來自上游 olmOCR README，與 Skill 中引用的文檔一致，可在本機復現。
單份 PDF 轉 Markdown（本機 GPU）：
curl -o olmocr-sample.pdf https://olmocr.allenai.org/papers/olmocr_3pg_sample.pdf
olmocr ./localworkspace --markdown --pdfs olmocr-sample.pdf
--markdown 會將結果寫入 ./localworkspace/markdown/。查看輸出：
cat localworkspace/markdown/olmocr-sample.md
單張圖片：
olmocr ./localworkspace --markdown --pdfs random_page.png
使用遠程 vLLM 服務（無需在本機裝 GPU 依賴）：
olmocr ./localworkspace --server http://remote-server:8000/v1 \
--model allenai/olmOCR-2-7B-1025-FP8 --markdown --pdfs *.pdf
也可使用 python -m olmocr.pipeline 替代 olmocr 命令。在線試跑可參考 olmocr.allenai.org。
適用場景與注意¶
適合：
- 掃描件、舊版論文、版式密集的技術 PDF，需要乾淨 Markdown 或純文本再做 chunk、向量檢索或 Agent 引用。
- 需要保留閱讀順序、表格與公式可讀性的文檔流水線，而不是隻抽取嵌入字體層文本。
- 已有 GPU 或願意使用遠程推理/Docker 的團隊批量轉換。
注意：
- Skill 不負責替你安裝 GPU 驅動或下載模型；Docker 鏡像體積大（文檔說明含模型鏡像約 30GB 量級），需提前規劃磁盤與
--gpus環境。 - 本機推理對硬件有要求；無 GPU 時應走
pip install olmocr+--server遠程推理，或 Docker/在線 demo。 - SkillHub 頁面統計（截至抓取）：評分 100000，下載 952；與具體 olmOCR 版本發佈節奏無關，以 allenai/olmocr 爲準。
- Skill 元數據標註
verification: security_reviewed，仍建議在受信環境運行轉換命令，勿對不可信 PDF 在未隔離環境中盲目執行腳本。
結尾¶
若你的 Agent 工作流卡在「PDF 能打開但抽出來的字沒法用」，可以先把本 Skill 裝進 Cursor 等客戶端的 skills 目錄，再按上文準備 olmOCR 環境。它把觸發條件、依賴與上游命令收斂到一份 SKILL.md，減少每次臨時查文檔的成本。
官方 Skill 頁面：SkillHub - Convert dense PDFs into LLM-ready text and page-aligned markdown with olmOCR
API 元數據地址：https://api.skillhub.cn/user_3c6cb52e/convert-dense-pdfs-into-llm-ready-text-and-page-aligned-markdown-with-olmocr
