本地PDF转Markdown：Ollama+qwen2.5vl+ollama-ocr全指南

又到年底整理资料的时候，手头压着上百份 PDF：有扫描版的技术手册、有论文、有财报截图转出的文档，还有一堆网页另存的"假 PDF"。以往要么花钱买在线 OCR 会员，要么忍受第三方网站上传的隐私风险，最烦的是——转出来全是没格式的纯文本，标题级别、表格、代码块全丢了，拿去做知识库或者喂给大模型之前还得手动清理一遍。后来我把本地模型这条路彻底走通了：Ollama 拉起 qwen2.5vl 视觉模型，配上一个叫 ollama-ocr 的命令行工具，PDF 转 Markdown 基本就是一条命令的事，速度快、完全本地、不花一分钱，还能保留表格和层级结构。这篇文章就是把我这段时间的完整配置过程、踩过的坑、以及不同场景下的最优参数组合一次性写出来，适合每天跟 PDF 打交道的开发者、研究者，以及想在本地搭一套私有 OCR 管线的朋友。

1. 为什么我放弃了在线OCR，转向本地模型

1.1 在线工具的三个痛点：隐私、成本、格式丢失

先说结论：在线 OCR 不是不能用，而是当你的 PDF 量一上来、或者内容稍微敏感一点，它就变得很难受。

隐私方面不用我多说，合同、内部文档、未公开论文这类东西，往第三方平台一拖，等于默认把内容交给别人服务器处理。我见过不止一个团队因为"图省事传了一次内部报价单"然后被合规部门约谈的例子。成本方面，免费额度通常一个月只有几次，超过之后按页收费，批量处理一份几百页的扫描书，价格够买好几杯咖啡。最无语的是格式，大多数在线工具只给你"识别出的文字"，表格变成一行行堆叠的明文，标题层级消失，代码块里的缩进被吃掉，数学公式变成乱码符号。这种半成品丢进 Markdown 笔记或者 RAG 知识库，后续清洗的时间比手动打字还长。

本地模型的思路完全不同：模型权重、推理计算全部在你自己的电脑上跑，PDF 内容从头到尾不出机器。一次投入硬件资源，后面所有转换都免费，而且因为视觉语言模型本身是按"图像理解 + 文本生成"的方式输出的，它天然可以输出带 Markdown 标记的文本——标题用#，表格用|，代码块用反引号。也就是说，它不只是"认字"，而是"理解版面并重新排版"。这一步直接把传统 OCR 之后还要写脚本整理格式的环节省掉了。

1.2 qwen2.5vl 为什么是当下最合适的开源底座

选模型是这条链路里最关键的决定。我最初用的是 LLaVA 系列，后来又试过 MiniCPM-V，最后还是长期停在 qwen2.5vl 上。

原因有三个。第一，中文识别能力。qwen 系列本来就是中文语料训练出来的，面对中文扫描件、混合中英文的技术文档，准确率明显比同体量的英文向模型高一个档次，尤其是标点、单位、地名这些细节，很少出现"中文被识别成拼音"这种尴尬事。第二，Markdown 结构化输出稳定。这个模型在训练时做过大量的图文混排和结构化输出任务，让它"看图写 Markdown"，它真的会认真给你套上正确的标题层级、表格对齐、列表嵌套，而不是把 Markdown 符号当作普通字符一股脑吐出来。第三，生态兼容好。qwen2.5vl 可以直接通过 Ollama 拉取运行，不需要自己处理复杂的模型转换和依赖环境，这对只想快速用上 OCR 的人来说非常友好。

当然，如果你的文档以纯英文为主，或者机器配置很低，也可以用更小的量化版本甚至换用其他视觉模型。但对我来说，"中文优先 + 结构优先 + 部署简单"这三个条件同时满足的，qwen2.5vl 是当前最省心的选择。

1.3 Ollama + OCR 工具的整体工作链路

整个系统的工作原理其实不复杂，你可以把它理解成一条流水线：

• 第一站：输入处理。ollama-ocr 拿到 PDF 后，先把每一页渲染成图片。如果是文本型 PDF，这一步可以直接提取内嵌文本；如果是扫描件，就整页转成位图，交给视觉模型识别。
• 第二站：视觉模型推理。渲染好的图片发送到 Ollama 本地服务（默认监听127.0.0.1:11434），qwen2.5vl 看图理解内容，按提示词要求输出带 Markdown 标记的文本。
• 第三站：后处理与落盘。工具把模型返回的文本按页拼接，做掉分页符、页眉页脚等噪音，最后写成一个.md文件。

Ollama 在这里的角色是"模型运行时"，它负责把 qwen2.5vl 跑起来并提供 HTTP API；ollama-ocr 是"调度器"，负责把 PDF 拆页、调 API、收结果。整条链路完全本地，没有外部请求，所以也不存在上传带宽瓶颈，转换速度只取决于你机器的 CPU/GPU 性能。理解了这个结构，后面所有参数配置和问题排查就都有方向了。

2. 环境准备：Ollama 安装与 qwen2.5vl 模型配置

2.1 装 Ollama：三条命令搞定（Windows/Mac/Linux）

Ollama 的安装没有太多技术含量，但不同平台的注意点不一样，我分别说。

Linux / macOS打开终端执行：

curl -fsSL https://ollama.com/install.sh | sh

装完执行ollama --version，能输出版本号就是成功了。Windows更方便，直接去官网下载安装包，双击一路下一步。装完 Ollama 会自动在系统托盘里运行，我强烈建议安装后手动确认一下服务状态：

ollama serve

正常情况下终端会打印Listening on 127.0.0.1:11434，这说明 API 已经在本地端口上待命了。这一步是很多新手容易忽略的——工具装好了，但后台服务没起来，后面所有请求都会报连接失败。

2.2 拉取 qwen2.5vl 模型：选对量化版本

安装完 Ollama，下一步就是拉模型。命令非常简单：

ollama pull qwen2.5vl:7b

但这里有个选择问题：qwen2.5vl 在 Ollama 仓库里有多个 tag，常见的有7b、3b，以及带fp16、q4_K_M等量化标识的版本。我的建议是绝大多数人直接拉默认的7b，它是 4-bit 量化的版本，显存占用大概 6GB 左右，一张 8GB 显存的显卡就能跑得动；如果只有 CPU 没有 GPU，那就选3b或者等更小的量化版，速度会慢一些但至少能跑。千万别一上来就拉fp16全精度版本，那玩意儿显存要求直接翻倍，普通机器必炸。

我整理过一个简单的选型对照表：

拉取完成后执行ollama list确认模型已经就位。如果列表里看不到刚拉取的模型，大概率是模型存储路径有问题，这个放到后面排查章节细说。

2.3 必改环境变量与自定义模型参数

很多教程到"拉完模型"就结束了，但实际用的时候你会发现默认配置不够顺手，至少要改三个地方。

第一个是模型存储路径。Ollama 默认把模型文件放在用户目录下，C 盘空间紧张的朋友迟早会爆盘。Linux 用export OLLAMA_MODELS=/data/ollama_models，Windows 在"系统属性-环境变量"里新增OLLAMA_MODELS指向 D 盘目录，改完必须重启 Ollama 服务才生效。第二个是监听地址和端口。如果 Ollama 和 ollama-ocr 在同一台机器，默认127.0.0.1:11434就够了，不用动；但如果你打算让局域网内其他设备调用，就要设置OLLAMA_HOST=0.0.0.0:11434，同时记得在防火墙放行这个端口。

第三个才是重头戏——自定义模型参数。OCR 任务有两个参数特别关键：temperature和num_ctx。temperature控制生成随机性，OCR 是"照抄"任务，不需要任何创造性，所以我一般把它压到 0.1 甚至 0，防止模型自己脑补内容；num_ctx控制上下文长度，处理多页拼接的长文档时可以适当调大。具体做法是先写一个 Modelfile：

FROM qwen2.5vl:7b PARAMETER temperature 0.1 PARAMETER num_ctx 8192

然后执行：

ollama create qwen2.5vl-ocr -f Modelfile

这样我们就拥有一个针对 OCR 优化的定制模型qwen2.5vl-ocr，后面所有转换命令都指向这个名字。注意num_ctx不是越大越好，它跟显存占用成正比，8GB 显存开到 8192 已经是比较稳妥的上限。

2.4 模型配置失败的几个典型场景

配置这块我踩过的坑实在太多，挑三个最高频的说。

第一个是"模型拉取成功但调用时报错 model not found"。这种情况十有八九是 Ollama 服务用了旧配置启动，或者你在一个终端里改了OLLAMA_MODELS而服务是另一个终端启动的，环境变量没生效。处理办法是彻底退出 Ollama 进程再重新启动，Linux 下用pkill ollama再ollama serve，Windows 上从任务管理器结束托盘进程再重新运行，然后ollama list再确认一遍。

第二个是"WorkBuddy 保存本地模型配置失败"。如果你是 OSS 客户端或者第三方 GUI 工具的使用者，它们的模型配置往往是写进自己的配置文件里的，跟 Ollama 无关。这类工具通常要求你手填 API 地址和模型名，很多人把地址填成了https://ollama.com，那是官方云端地址，本地服务地址应该是http://127.0.0.1:11434，模型名要填ollama list里显示的完整名字，比如qwen2.5vl:7b，而不是qwen2.5vl。这种"看起来是软件问题，其实是地址填错"的情况发生率极高。

第三个是端口被占用。Ollama 服务起不来，先查11434是不是被别的进程占了，Linux 用lsof -i :11434，Windows 用netstat -ano | findstr 11434，找到占用进程后改 Ollama 的端口或者停掉冲突进程。

3. 核心实操：5分钟把 PDF 转成 Markdown

3.1 安装 ollama-ocr 命令行工具

环境备齐之后，主角登场。ollama-ocr 是一个开源命令行工具，本质上是把"PDF 渲染为图片、调用 Ollama API、收集模型输出"这三件事封装成了几个简洁的子命令。安装方式很简单，Python 环境直接：

pip install ollama-ocr

如果你的网络环境对 GitHub 更友好，也可以直接从源码装，但 pip 版一般够用。装完先跑一下ollama-ocr --help，确认命令可用，同时它会列出所有支持的参数，我建议花三十秒把参数列表过一遍，后面用起来会顺手很多。工具本身并不绑定某个模型，默认会去连本地 Ollama 服务，你也可以通过参数指定任意已拉取的模型。

3.2 一条命令完成转换：参数逐个拆解

准备工作就绪后，最核心的转换命令长这样：

ollama-ocr -i 技术手册.pdf -o 技术手册.md -m qwen2.5vl-ocr

拆开来看，-i指定输入文件，支持 PDF 和常见图片；-o指定输出 Markdown 文件路径，不写的话默认输出到当前目录；-m指定模型名，这里用的是我刚才创建定制模型。数一下，从打开终端到得到 Markdown，整个过程一分钟都用不了，熟练之后确实能控制在 5 分钟内，标题里的"5分钟"不是夸张。

如果你的 PDF 里有页眉页脚、页码这种干扰信息，加一个重写参数：

ollama-ocr -i 技术手册.pdf -o 技术手册.md -m qwen2.5vl-ocr -a "请忽略页眉页脚和页码，只保留正文内容"

-a是附加指令参数，相当于你给模型的额外要求。这是我最喜欢的一个参数，因为不同 PDF 的版面风格差异很大，有时候需要告诉模型"这是双栏排版从左到右读"、"表格内容必须逐行保留"、"代码块保持缩进"，通过-a动态调整提示词，比改代码灵活多了。实测下来，带附加指令的转换结果在格式完整度上比默认输出高不少。

转换完成后，打开生成的 Markdown 文件检查三件事：标题层级是否正确、表格是否对齐、图片有没有被转成引用占位。如果这三项都没问题，这份文档基本可以无缝丢进 Obsidian 或者语雀。

3.3 扫描版 PDF 与图片型页面处理

文本型 PDF 转换相对简单，真正的考验是扫描版。所谓扫描版 PDF，本质是每一页都是一张图片，没有任何文字层，这种文件必须走完整的视觉识别流程。处理这种文件有个关键动作：提高渲染分辨率。ollama-ocr 内部在渲染 PDF 页面时会设置 DPI（每英寸点数），默认值对清晰扫描件够用，但遇到字小、纸张泛黄的老书，建议在转换前用 Python 的 PyMuPDF 把页面重新渲染成高清图片。比如：

python -c "import fitz; doc = fitz.open('scanned.pdf'); [doc[i].get_pixmap(dpi=200).save(f'page_{i+1:03d}.png') for i in range(len(doc))]"

渲染成图片之后，再用ollama-ocr -i page_001.png -o page_001.md -m qwen2.5vl-ocr逐页转换。注意这里千万别直接用低分辨率原图，我做过对比，同一个 300dpi 扫描页，直接用原始 PDF 转会有不少字识别错，渲染到 200dpi 以上之后准确率肉眼可见提升。缺点是一个文件拆成了多个 Markdown，最后需要拼接，不过这在第 3.4 节有专门的批量方案。

另外，某些"图片型 PDF"会夹杂旋转页面、倾斜扫描、手指遮挡这些噪声。倾斜和旋转问题可以在渲染前用图像处理库自动矫正，也可以直接加一句附加指令"如果图片方向不对请忽略方向直接识别"，后一种更省事但要容忍一定的错误率。手指遮挡这种物理损坏没有太好的办法，只能靠模型猜，这时候-a "遇到不清晰的字符请根据上下文合理推测"能救一部分。

3.4 批量转换与长文档拆分合并

一次性处理几十份 PDF 是另一个高频场景。ollama-ocr 本身支持输入一个目录吗？不同版本行为不一样，我习惯用 Shell 循环来做，干净利落：

for f in *.pdf; do ollama-ocr -i "$f" -o "${f%.pdf}.md" -m qwen2.5vl-ocr done

这个循环会把当前目录下所有 PDF 依次转换，文件名保持同名。如果机器配置一般，建议在循环里加sleep 2，给模型留一点喘息时间，防止连续调用把显存打满。

长文档拆分方面，我的经验阈值是超过 40 页就拆。因为即便是 8192 的上下文，多页内容拼接后仍然可能被模型截断，导致后半部分内容丢失。拆分方法可以参考第 3.3 节的 PyMuPDF 渲染脚本，先把 PDF 按页码切成多个小段，再逐段转换，最后用cat合并：

cat page_*.md > 合并.md

合并之后还要注意清理重复的页眉页脚、页间空白和重复标题，我一般用正则替换掉形如第 X 页的内容，这部分后续还会再提到。

4. 实战中高频踩坑与排查速查表

4.1 中文乱码、公式崩坏怎么办

中文乱码是本地 OCR 最常见的翻车现场，但成因各不相同，要分情况处理。

如果你转换的是扫描版并且乱码表现为"错字连篇"，问题基本出在图片质量上。先检查渲染 DPI，低于 150 的重新渲染到 200 以上；再检查原图是否倾斜，倾斜页面识别率下降得很厉害。如果乱码表现为"大量问号"或"无法识别的方块"，那多半是模型本身不支持你输入的语言风格，比如用了纯英文向的视觉模型处理中文文档，这时候换回 qwen2.5vl 基本能解决；如果你确实需要同时识别中日韩等多语言，建议在-a里明确写出"这是一份包含中文和英文的文档，请用中文输出语义，保留英文专有名词"。

公式崩坏是论文党最痛的问题。qwen2.5vl 不是专门的公式识别模型，遇到复杂数学公式时，它可能会把分数、积分号、上下标弄乱。我的实测经验是：简单行内公式（如$x^2$、$a/b$）基本没问题；复杂公式建议在附加指令里写清楚规则，比如"公式请用 LaTeX 格式输出，行内公式用$...$，独立公式用$$...$$"，能解决相当一部分问题。如果文档是数学教材级别，那还是老老实实配合专业的公式 OCR 工具处理，别指望一个通用视觉大模型全包。

4.2 表格样式丢失与多栏排版错乱

表格是 PDF 转 Markdown 的重灾区。普通表格还好，一旦遇到合并单元格、跨页表格、细边框表，模型输出经常会漏行列或者把多行并成一行。处理这类问题，我最推荐的方案是在附加指令里强制结构化：

ollama-ocr -i 财报.pdf -o 财报.md -m qwen2.5vl-ocr -a "这是一个会计表格页面，请按 Markdown 表格完整输出，保留所有列和行，不要遗漏任何数据，表格列名用加粗表示"

实测这种强约束能显著提升表格完整性。另外一个技巧是给模型"人设"：告诉它"你是一名严谨的数据录入员"，这类角色提示词对提高结构化输出的服从度非常有效。

多栏排版错乱主要出现在论文和杂志扫描件上。双栏文章如果渲染成整页图片，模型有概率把左右两栏交错着读。解决思路和人类阅读一致：先分栏再识别。用图像处理把每页的左右栏切出来，分别转成图片再喂给模型，识别顺序强制为"左栏从上到下，再右栏从上到下"。不过这个操作偏高级，日常使用中我更多是用附加指令告诉模型"这是双栏文档，请先读左栏再读右栏"，大部分时候也够用。

4.3 显存不足、推理太慢的调优方案

最后聊聊性能和资源问题，这也是本地方案劝退最多人的地方。

显存不足的典型报错是CUDA out of memory或者 Ollama 直接崩溃。三个解决思路按优先级排序：第一，换更小的模型，从7b降到3b；第二，降低num_ctx，从 8192 降到 4096，减少 KV Cache 占用；第三，关闭并行任务，同一个时刻只跑一个转换。如果你用的是 Windows，还要注意检查显存是不是被桌面特效或者浏览器硬件加速霸占了，关掉几个 Chrome 标签页经常就能解决问题。

推理太慢的优化方向更明确。首先确认模型确实跑在 GPU 上，ollama ps可以查看当前模型运行设备；如果显示 CPU 运行，检查显存是否足够加载模型，不够的话先考虑量化版本。其次，把温度参数调低除了能提高准确率，其实也能略微提速，因为低温下模型生成更"果断"，减少了无谓的候选分支计算。最后，批量文档老老实实排队处理，不要试图一次开多个 ollama-ocr 进程，那样只会让两个任务互相争抢显存，整体耗时反而增加。

为了让你以后排查方便，我把这次实战中遇到的高频问题整理成速查表：

5. 实操思路扩展与效率提升

5.1 与剪贴板配合实现"截图即 Markdown"

本地 OCR 链路通了之后，我做的第一件事就是把流程接到日常截图工具里。原理非常简单：截图软件把选中区域保存为 PNG，然后一个快捷键调用 ollama-ocr 识别，再把结果写进剪贴板，你就能直接粘贴到任何 Markdown 编辑器里。

具体实现上，Windows 可以用 PowerShell 脚本绑定全局快捷键，macOS 用 Automator 或者 Raycast 的自定义脚本。脚本核心就一行：

ollama-ocr -i /tmp/screenshot.png -o /tmp/result.md -m qwen2.5vl-ocr -a "输出简洁的 Markdown，不要解释"

识别完再用clip < /tmp/result.md把内容塞回剪贴板。这个小改造的价值在于，它把"图文混排的网页、微信截图、扫描内容"都变成了可编辑的文本，我写文档的速度至少快了一倍。这里的核心思路是复用第 2 章配好的模型和参数，把 OCR 能力从一个"文件转换工具"升级成"系统级生产力组件"。

5.2 后续接入 RAG、知识库的处理建议

转出来的 Markdown 另一个大用途是喂给 RAG（检索增强生成）知识库。但直接拿去用会有一个坑：转换结果里通常残留页眉页脚、目录页码、"第 X 页"这类噪音，这些碎片会严重干扰向量检索的切分质量。我的建议是入库前做一次清洗，把明显的重复噪音行去掉，用正则匹配掉连续的数字页码，再按标题层级把文档切成语义完整的 chunk。切成 chunk 时注意保留标题上下文，这样检索命中后大模型才能知道"这段内容属于哪个章节"。

另一个更进阶的玩法是保留转换过程中得到的版面信息。如果你需要精确的引用定位，让模型在输出 Markdown 的同时，用 HTML 注释标注每一段对应的原 PDF 页码，比如在转换指令里要求"每个段落末尾用<!-- page 12 -->标记来源页"。这样知识库回答问题时还能反向溯源到原文档的具体位置，对论文、合同这类需要严谨引用的场景特别有用。

5.3 把 OCR 结果接入自动化工作流

整套流程稳定之后，我又用系统定时任务把"PDF 转 Markdown"自动化了：设置一个监视文件夹，任何新 PDF 丢进去，脚本自动转换并把 Markdown 和源文件一起归档。核心逻辑不复杂，就是第 3.4 节的循环加一层文件监听。这一步做完，日常基本处于"丢文件进去，然后去 Obsidian 里直接看到整理好的笔记"的状态。

如果用的是 Obsidian 这类 Markdown 生态工具，还可以再进一步：转换输出的 Markdown 直接落在 Obsidian 仓库的固定目录，并把文件名统一成YYYY-MM-DD-标题.md的格式，这样每天的 PDF 转换成果自动进入知识库体系，跟手动写的笔记混排在一起，时间线统一管理。整个过程我跑了两个月，稳定性很高，唯一的建议是定时任务里加上失败重试和日志输出，防止某次显存被占导致静默失败，这一点在批量处理场景下尤其重要。

6. 写在最后的实操心得

我从一开始用在线 OCR，到后来折腾各种开源识别工具，再到最终敲定 Ollama-OCR + qwen2.5vl 这套组合，最大的体会是"本地化"带来的掌控感确实无可替代。它不需要你懂深度学习，不需要配 Python 训练环境，只要照着把 Ollama 装好、模型拉下来、参数调顺，剩下的就是一条命令的事。真要给后来者什么建议，我想说三点：一是模型参数别照抄别人的，显存大小决定了你能跑多大的模型和多大的上下文，先小后大逐步试；二是附加指令-a是这套工具的灵魂，花十分钟根据你的文档类型提炼一段稳定的提示词，回报远远大于折腾各种预处理脚本；三是转完一定要抽查几页，大模型偶尔会一本正经地编造内容，对关键文档来说，人工复核这步省不掉。这套链路我目前已经稳定使用了几个月，后续有精力的话我会继续分享批量清洗和知识库接入的细节。