pdf-brain 是一款运行在本地的 PDF 知识库工具，通过本地 LLM（如 Ollama 的 llama3.2:3b）对文档进行AI 增强（enrichment）：自动提取标题、作者、摘要、标签和概念，并匹配 SKOS 分类体系，全程无需云端 API、不产生费用。本文带你完整解析这套自动元数据提取机制的工作原理与使用方法。

🧠 快速了解：AI 增强到底做了什么

当你用--enrich参数添加文档时，pdf-brain 会把文档内容交给 LLM，自动产出一整套结构化元数据：

整个过程完全在本地完成，核心逻辑集中在 src/services/AutoTagger.ts 中。

🚀 一键启用：开启 AI 增强的 3 个步骤

第 1 步：安装 pdf-brain

curl -fsSL https://raw.githubusercontent.com/joelhooks/pdf-brain/main/scripts/install.sh | bash

也可以从源码构建：

git clone https://gitcode.com/gh_mirrors/pd/pdf-brain cd pdf-brain && bun install

第 2 步：准备 Ollama 与模型

向量检索需要嵌入模型（必需），AI 增强需要 LLM 模型（推荐）：

ollama pull mxbai-embed-large # 嵌入模型（1024 维，必需） ollama pull llama3.2:3b # 本地 LLM（AI 增强用，推荐） ollama serve

第 3 步：添加文档并开启增强

pdf-brain init # 初始化数据库 + 内置分类体系 pdf-brain add paper.pdf --enrich # 触发 AI 增强

批量导入整个目录同样支持：

pdf-brain ingest ~/Documents/papers --enrich

默认增强 provider 为本地 Ollama，可在 README.md 的 Configuration 一节看到全部配置项。

🔍 深度解析：自动提取的 4 类信息

1️⃣ 标题与作者：从文件名到规范标题

LLM 会读取文件名 + 正文前 6000 字符（见 AutoTagger.ts），输出规范化的标题。比如cognitive_load_theory_sweller.pdf会被识别为：

{"title": "Cognitive Load Theory", "author": "John Sweller", ...}

即使 LLM 不可用，内置的启发式函数cleanTitle也会把my-notes_v2-final.pdf清理成 "My Notes V2 Final" 这样可读的标题（AutoTagger.ts）。

2️⃣ 摘要：2-3 句话的文档速览

摘要字段要求 LLM 用 2-3 句话概括文档内容与价值，例如："Reviews cognitive load theory and its implications for instructional design."。这在后续用pdf-brain search检索时非常有用——你搜"工作记忆对学习的影响"，摘要命中的概率远高于原始正文。

3️⃣ 标签与分类：5-10 个语义标签

LLM 会生成 5-10 个小写连字符风格的标签（如cognitive-load、working-memory），并归类到documentType（论文/书籍/教程等 10 种类型，见 DocumentType 定义）。提示词中内置了多组 few-shot 示例来约束本地小模型输出稳定的 JSON 格式（AutoTagger.ts），这是本地 LLM 场景下保证稳定性的关键技巧。

4️⃣ 概念匹配：对齐 SKOS 分类体系

这是 pdf-brain AI 增强最有特色的部分。项目内置了一套 SKOS 分类体系（种子数据见 data/taxonomy.json），涵盖编程、教育、商业、设计、元技能五大领域。

LLM 不是随意打标签，而是从你的分类体系中"选"概念 ID，例如education/cognitive-load、programming/react。概念的管理逻辑在 src/services/TaxonomyService.ts 中实现，可用以下命令查看：

pdf-brain taxonomy tree # 查看概念树 pdf-brain taxonomy proposed # 查看 LLM 建议的新概念 pdf-brain taxonomy accept --all # 接受全部建议

⚙️ 幕后机制：三步 RAG 增强流程

pdf-brain 的enrich()方法（AutoTagger.ts）并非简单地把文档丢给 LLM，而是执行了一个精巧的三步流程：

STEP 1 — 提取 RAG 上下文先把文档前 2000 字符向量化，用向量相似度从分类体系中召回最相关的 5 个概念（相似度阈值 0.5，见 extractRAGContext）。这些概念被优先放入 LLM 提示词，显著提升概念匹配的准确率。

STEP 2 — LLM 完整增强带着"RAG 增强后的概念列表"调用 LLM。provider 选择遵循"配置 > CLI 参数 > 自动探测"的优先级：默认走本地 Ollama；若 Ollama 未运行或模型缺失，自动切换到 AI Gateway（Anthropic、OpenAI 等，实现见 src/services/Gateway.ts）。

STEP 3 — 新概念自动接纳LLM 可能提出分类体系中不存在的新概念（如education/spaced-repetition）。系统会：

1. 校验概念 ID 格式（必须是父类/短名结构，见 validateProposedConcepts）；
2. 对新概念做向量化，查找相似已有概念；
3. 若相似度高，再让 LLM 充当"裁判"判断是否重复（llmJudgeDuplicate，AutoTagger.ts）；
4. 确认是全新概念后自动加入分类体系并存储嵌入。

这意味着你的分类体系会随着文档的增加自动生长，而 LLM 重复概念会被去重拒绝。

🛟 降级策略：LLM 挂了怎么办

pdf-brain 设计了一个完整的启发式兜底：当 LLM 增强失败（网络错误、限流、JSON 解析失败）时，自动回退到纯规则方案（AutoTagger.ts）：

• 标题：从文件名清理而来
• 标签：从路径、文件名、正文关键词（TF-IDF 式打分）提取
• 分类：从目录结构推断

实际错误会被记录到日志供调试，但导入流程不会中断。因此即使断网，你的知识库依然可用——只是元数据"没那么聪明"。

💡 实用技巧与注意事项

• 速度：LLM 增强是 CPU 密集型操作，大批量导入建议挂过夜运行；追求速度可改用--auto-tag（启发式 + 轻量 LLM，更快）
• GPU 加速：Ollama 支持 GPU 时，增强速度会有质的提升
• 换模型：pdf-brain config set enrichment.model <模型名>可随时切换，Ollama 端点与模型选择逻辑见 src/services/Ollama.ts
• 自定义分类：编辑taxonomy.json后执行pdf-brain taxonomy seed --file data/taxonomy.json即可重建体系
• 数据库规模：500 万 chunk 时向量索引会相当大（约 48GB HNSW 邻居图），大规模使用建议先阅读 AGENTS.md 中的容量说明

✅ 总结

pdf-brain 的 AI 增强能力 =本地 LLM + RAG 概念召回 + 新概念自动治理 + 启发式兜底。它让"整理文档"这件事从手工打标签变成了自动流水线：标题、摘要、标签、概念一次生成，分类体系越用越准。全程本地运行，既保护了隐私，又零 API 成本——这正是本地优先（local-first）知识库工具的核心价值。

想深入更多设计背景，可参考 docs/ 目录下的 agentic-cli-roadmap.md 等文档。