前言¶
把 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
