实践指南（8）：PDF 摄取——从研究论文到可查询的 Wiki 页面
从 vault 中任选 PDF。插件通过你的 LLM 提供商读取、逐字转写为 Markdown，再接入标准的 Wiki 抽取流水线。
那 50 篇论文的困境
研究工作里，PDF 是最常见的素材来源。论文、产品手册、扫描的合同、技术规格——这些文件往往都堆在 vault 的各个角落，桌面上、下载文件夹里、Zotero 里，都有。你打算把它们都整理进 Obsidian，让它们真正成为知识库的一部分。
于是你打开第一篇，开始做笔记。摘要还好，复制粘贴几句话。然后你翻到第三页，那里有一张关键的对比表格，六列十行，是整篇论文的核心结论。你想把它搬进笔记里，却发现 Markdown 根本装不下——你要么手敲一遍 Markdown 表格（半小时过去了），要么截个图贴进去（然后它就再也不能被搜索、被链接、被查询了）。再往后翻，还有一个漂亮的架构示意图，一串你看不太懂但很重要的公式。
你忽然意识到一件让人沮丧的事：你的笔记只能装下这篇论文里最容易复制的那部分。 那些真正花了作者心血、也最难替代的图、表、公式，全被挡在门外。而你手上还有四十九篇。
这篇文章，就是讲 Karpathy LLM Wiki 从 v1.25.0 开始怎么解决这件事的。
PDF 不再是附件，而是源材料
在 v1.25.0 之前，PDF 对插件来说是个”外人”。你可以把它放进 vault，但它只是一个躺在那里的二进制文件，Wiki 生成流程看不见它的内容。
v1.25.0 改变了这件事：PDF 升为和 Markdown 笔记完全平级的一级来源。 从 vault 里挑一份研究论文、产品手册、扫描的合同或四百页的技术规格，插件就会像对待你手写的笔记一样对待它——读进来，理解里面的文字、表格、图示，然后生成互相链接的 Wiki 页面。
关键在于，这一切接进的是你已经在用的那条流水线。双向链接、跨语言别名、矛盾检测、对话式查询时的引用溯源——你为 Markdown 笔记熟悉的每一个功能，现在对 PDF 一样有效。你不需要学任何新东西，只是在熟悉的流程前面多接了一段 PDF 转换。
一句话：PDF 从”附件”变成了”源材料”。
它到底怎么工作的
如果要用人话讲清楚背后发生了什么，其实只有三步，而且后两步你早就见过：
PDF → （LLM 读它、转写成 Markdown） → 走和笔记一模一样的 Wiki 抽取流程第一步，插件把 PDF 交给你的 LLM。注意，这里不是某个第三方 OCR 服务，就是你自己在设置里配好的那个模型——比如 Claude 或 GPT-4o。模型直接”看”这份 PDF，把里面的文字、表格、图示的说明，逐字转写成干净的 Markdown。
第二步之后就没什么新鲜的了：这份转写出来的 Markdown，和你亲手敲的笔记走进的是同一道门。实体被抽出来、概念被识别、[[wiki-link]] 被生成、页面之间互相连起来。从这一步往后，插件根本分不清、也不关心这段内容当初是来自一篇 PDF 还是你敲的一段字。
这就是整个设计最舒服的地方：新能力没有另起炉灶，它只是在你熟悉的流程前面接了一小段。
你的服务商能不能用
这是大多数人真正想先弄清楚的问题。答案取决于你在用哪个 LLM。
如果你在用 Claude 或 GPT-4o（及更新版本），恭喜，直接能用。 这些模型原生就能把 PDF 当作一段文件内容来读，你什么都不用调。AWS Bedrock 上的 Claude 和 OpenAI 也一样，属于原生支持。
如果你在用别的，情况就要分两种看。 有些服务商——像自建的 OpenAI 兼容端点、Anthropic 兼容的镜像——技术上可能能处理 PDF，但插件不敢替你打包票，所以默认关着。你需要手动打开一个叫 Force PDF Support（强制 PDF 支持）的开关，自担风险地试一试（后面有一整节讲什么时候该开、什么时候别开）。
还有一些服务商，PDF 这条路是走不通的。 具体说就是 Ollama、LM Studio、DeepSeek、GLM 这几个——它们不接受把 PDF 作为文件内容直接喂进去。但别急着失望：这不代表你就跟离线 PDF 无缘了，你还有一条本地 OCR 路径可以走，后面「Apple Silicon 完全离线」那一节专门讲它。
如果你实在想要一张速查表，就是下面这张。但请记住，表里每一行对你的真正含义，上面几段已经说清楚了：
| 你的服务商 | PDF 能不能用 | 你要做什么 |
|---|---|---|
| Claude / GPT-4o+ / Bedrock | 原生支持 | 什么都不用做 |
| Custom / Anthropic-compatible | 要手动开开关 | 打开 Force PDF Support，自担风险 |
| Ollama / LM Studio / DeepSeek / GLM | 这条路不通 | 改走本地 OCR 路径（见下文） |
顺带一提，当你从别的服务商切回原生服务商（Claude、GPT-4o、Bedrock）时，那个强制开关会自动帮你关掉——因为原生服务商根本不需要它。
缓存：为什么这跟你有关
把一份 PDF 交给 LLM 转写，是要花钱、花时间的。一篇长论文可能要跑好几秒，还要消耗 token。如果你每次重新生成 Wiki 都得把同一批 PDF 再转一遍，那这个功能用起来会很心疼。
所以插件做了一件很自然的事：同一份 PDF 只转一次。 第一次转好之后，结果被缓存下来；之后无论你怎么重新摄取、重新生成，只要 PDF 内容没变，插件就直接拿现成的 Markdown 用，一个 LLM 请求都不再发。转换的代价，你这辈子对这份文件只付一次。
这时候一个很合理的担心会冒出来：“那如果插件升级了、转写的方式变好了，我那些旧缓存岂不是永远停留在旧质量上？”
不会。缓存并不是简单地”认文件”，它同时记住了当初是用哪一版转写逻辑生成的。当插件升级、转写方式改进之后，旧版本生成的缓存会自动失效，下次摄取时插件会用新方式重新转一遍。你不需要记得去手动清缓存，也不用担心自己一直吃着过期的老结果。它该用旧的时候用旧的（省钱），该更新的时候自己更新（保质量）。
你的 vault 是安全的
这一点值得单独拿出来讲，因为它关系到你敢不敢放心大胆地把一大堆 PDF 丢进去。
默认情况下，摄取 PDF 不会碰你 vault 里的任何文件。 你的 PDF 还是那些 PDF，一个字节都不变。转写出来的 Markdown 只安静地待在缓存里，你得到的只是新生成的 Wiki 页面。换句话说，就算你摄取了两百篇 PDF，你的文件树也不会突然冒出两百个新文件。
这不是偷懒，是刻意的设计。我们把它叫做”最少惊讶原则”——你的文件系统只应该在你明确要求时才增长。
那如果你确实想要在 vault 里留一份 PDF 的 Markdown 版本呢？比如你想对转写内容做全文搜索、想分享给别的工具、或者想在图谱视图里看到它——完全可以。设置里有一个可选开关，打开之后，每次成功转写，插件会在源 PDF 旁边写一个同名的 .pdf.md 旁注文件，内容和缓存里的完全一致。
关键是这是你主动选的。默认关着，是因为一觉醒来发现 vault 多了两百个文件不是好体验；但只要你需要，它随时在那儿等你打开。
对小模型的诚实
这里要讲一个容易被忽略、但对做研究的人极其重要的细节。
当 LLM 转写 PDF 时，最危险的不是它读不出某个字，而是它读不清却硬猜。一个模型面对一张模糊的扫描图、一个印糊了的公式，很可能自信地编出一段看起来很合理、其实完全错误的内容。对随便记记的场景这也许无所谓，但对一个”每条引用都必须能追溯到原文”的研究工作流来说，幻觉比缺失糟糕得多——一段留白你会去查证，一段编造你可能就直接信了。
所以插件用的转写方式，被明确框定成”OCR 风格的逐字转写器”：它的任务是老老实实抄，不是总结，不是润色，不是翻译。更重要的是，当它真的遇到读不清的地方时，我们给了它一个比猜测更好的选项——如实标记：
- 一段文字确实认不出，它写
[illegible] - 一张图没法忠实描述，它写
[figure: ...]加简短说明 - 一个公式没法干净转写，它写
[equation: ...]
这些标记的意义在于，它把”我不确定”变成了页面上一个看得见的记号，而不是一段以假乱真的内容。你在 Wiki 里翻到 [illegible]，就知道那里需要你回去看原文；这远比翻到一段流畅但错误的伪造要靠谱。这套框架和标记方式，专门为了在小模型、本地模型上也能守住底线而设计——因为越小的模型越爱脑补。
Apple Silicon 完全离线
如果你的 PDF 因为隐私或合规原因不能离开这台电脑——机密合同、未发表的研究、病历——那么下面这套技术栈就是为你准备的：整条流水线，从 PDF 到 Wiki 页面，全程不发出一个字节到外网。
在 Apple Silicon（M 系列芯片）上，推荐的组合是：
┌─────────────────────────────────────────────────┐
│ 服务商： Custom OpenAI-Compatible │
│ Base URL：http://localhost:1234/v1（oMLX） │
│ API 密钥：（空——本地服务器不需要） │
│ 模型： <你的本地模型> │
│ Force PDF：☑ 启用（在 Advanced 下） │
└─────────────────────────────────────────────────┘三个名字你需要认识：oMLX 是一个针对 M 系列芯片做了原生优化的本地服务器，对外提供 OpenAI 兼容的接口；Markitdown 负责把 PDF 喂给本地模型；Baidu Unlimited-OCR 则是那个真正干识别活的 OCR 模型，它专门解决了老一代 OCR 在长文档上”越读越慢”的毛病。
配好之后的妙处在于，插件对这一切毫不知情。它只看到一个”Custom OpenAI-Compatible 服务商”，缓存照缓存、失效照失效、生成的 Wiki 页面和用云端模型时一模一样。从它的视角，本地和云端只是”另一个服务商”的区别。而对你来说，这意味着你的 PDF 从头到尾没离开过这台机器。
什么时候该开 Force PDF Support
前面说过那个”自担风险”的开关，这里展开讲讲什么时候动它。
如果你跑的是一个你自己掌控、也信任的 Custom OpenAI-Compatible 端点，那开它是合理的——你清楚背后是什么模型。同样，如果你连的是一个自托管的 Anthropic 兼容镜像，或者你通过 OpenRouter 之类的路由用到了一个上游其实支持 PDF、只是接口层没声明的模型，这些情况下打开开关去试，都说得通。
反过来，有几种情况别开。如果某个服务商压根就直接拒绝 PDF 请求，那你不用开关也会看到清晰的报错，开了也没用。如果你已经发现这个服务商（往往是小模型配长 PDF）转出来的质量很差，那强开只会给你一堆不可靠的页面。而最该警惕的一种：如果你不确定这个服务商到底是老实转发、还是会悄悄记录你上传的 PDF，那就别开——尤其当文件敏感时，这个开关关着才是安全的默认。
三种你多半会遇到的状况
用得久了，下面这三种情况你至少会碰上一次，提前知道就不慌。
第一种是加密的 PDF。插件不会替你解密——这是故意的，一个会悄悄破解加密文件的工具会让处理机密材料的人很不安。碰到它，你自己先解密再放进来就好：macOS 用预览打开另存，Linux 可以用 qpdf，或者干脆在任意阅读器里”打印为 PDF”把加密展平。
第二种是纯图片的扫描件，也就是那种没有文字层、整页都是图的 PDF。云端原生服务商靠模型的视觉能力能读，Apple Silicon 上的本地 OCR 路径也能处理。只是要有心理准备：它比处理有文字层的 PDF 更慢、也更容易出错，时间和 token 预算上都留点余地。
第三种有点微妙——内容明明变了，读到的却是旧的。绝大多数时候这不会发生，因为缓存会自动失效；但万一你确实撞上转写结果和当前 PDF 对不上，最直接的办法就是把缓存里对应的那份删掉，下次摄取时它会自动重建。
收尾
把这些串起来看，PDF 摄取想做的事其实很朴素：让那五十篇论文里最难搬运的部分——表格、图示、公式——也能变成你 Wiki 里可搜索、可链接、可查询的一等公民，而不是被挡在 Markdown 门外。
如果你要挑一台机器、一个模型来扛住 PDF 转写的负担，去看看 入门必读（5）：选一个真正跑得动你 Wiki 的本地模型；如果你想把这条流水线接进 Zotero，搭一套完整的学术文献工作流，去看 实践指南（6）：Zotero → Obsidian → Wiki，学术文献流水线。
最后，用一句话概括整个设计的用心：缓存让你只付一次代价，校验让你能信任结果，旁注可选所以你的 vault 还是你的 vault。