上一篇文章介绍了 LLM-Wiki 与 Obsidian 的定位和整体架构。本文进入实际操作，使用一份工作文档演示从项目创建、模型配置、资料导入，到 Obsidian 阅读和 AI Agent 检索的完整流程。

本文的目标不是把所有功能一次讲完，而是先跑通一条最小可用链路：

创建 LLM-Wiki 项目
        ↓
配置 Chat / Ingest / Embedding 模型
        ↓
导入并解析原始文档
        ↓
生成结构化 Markdown Wiki
        ↓
使用 Obsidian 阅读和维护
        ↓
通过 AI Agent / MCP 检索知识

开始前的建议：先准备一份内容边界清晰、篇幅适中的 PDF、DOCX 或 Markdown 文档。首次测试不建议直接导入整个文件夹，这样更容易判断解析、生成和检索分别是否正常。

一、准备工作

开始之前，请确认已经完成以下准备：

安装 LLM-Wiki 和 Obsidian；
准备可用的 Chat 模型和 Ingest 模型；
如果需要语义检索，准备 Embedding 模型或兼容 OpenAI API 的 Embedding 服务；
如果需要提升 PDF 解析质量，准备可访问的 MinerU 服务或对应调用资源；
如果需要让外部 Agent 访问知识库，准备 Claude Code、Codex CLI 或其他支持 MCP 的 Agent 工具。

本文中的配置项和界面名称可能会随 LLM-Wiki、Obsidian 插件版本变化，实际操作时以当前版本界面和项目文档为准。

二、LLM-Wiki：创建项目并完成配置

LLM-Wiki 负责导入原始资料、调用模型完成内容分析、生成结构化 Wiki，并提供后续检索接口。

1. 创建项目

打开 LLM-Wiki 后，先创建一个新的知识库项目。创建时建议使用一个独立、稳定的本地目录，例如：

1	~/Documents/knowledge/my-wiki/

目录不要放在临时下载目录中，也不要随意移动。后续 LLM-Wiki、Obsidian 和 Agent 都需要指向这一个项目目录。

图 1：进入 LLM-Wiki 的项目创建入口。

根据界面提示填写项目名称，并选择项目目录。项目名称最好能够体现知识库的主题，例如“测试知识库”“团队业务知识库”，避免使用过于宽泛的名称。

图 2：填写项目名称并选择本地存储位置。

创建完成后，先不要急着导入文档。建议先检查项目目录和界面中的文件树，确认项目已经建立成功，并记住项目的实际路径。

图 3：项目创建完成后查看项目文件结构。原始资料、Wiki 页面和应用配置通常会分别存放。

目录建议：原始资料和生成的 Wiki 页面最好保留在同一个项目目录中，但不要把 API Key、Token 等敏感配置直接写进 Markdown 文件或提交到公开仓库。

2. 配置模型和解析能力

进入设置页面，先完成模型配置。建议区分以下几类能力：

配置项	主要作用	是否必须
Chat 模型	对话问答、总结和交互式处理	是
Ingest 模型	分析导入文档并生成 Wiki 内容	是
Embedding 模型	将文本转换为向量，支持语义检索	可选
MinerU	提升复杂 PDF、版面和表格的解析效果	可选
Web Search	补充外部网页搜索能力	按需

图 4：在设置中配置模型、解析器和检索相关能力。

MinerU PDF 解析

对于包含多栏排版、表格、图片或复杂版面的 PDF，普通文本提取可能会出现顺序错乱、表格丢失和图片信息缺失等问题。如果已经具备 MinerU 的本地服务或调用资源，可以在这里启用 MinerU，并先用一份复杂 PDF 做验证。

需要注意：启用 MinerU 不代表所有 PDF 都能完美解析，最终效果仍然取决于 PDF 本身、解析服务版本和文档版式。对于扫描版 PDF，还需要确认是否支持 OCR，以及 OCR 结果是否需要人工校对。

向量检索

LLM-Wiki 不是只能依赖向量检索的系统。开启向量搜索后，可以将关键词匹配、向量语义检索以及 Wiki 页面之间的关联结合起来；关闭向量搜索时，仍可以使用关键词或页面关系进行检索，但对同义表达、自然语言问题的召回能力可能会受到影响。

项目文档中的召回率数据属于特定版本、数据集和配置下的测试结果，不能直接当作所有场景的固定提升。实际效果还会受到 Embedding 模型、文档切分、查询内容和召回参数影响。

配置 Embedding 时，重点检查以下内容：

Embedding 服务地址和鉴权信息是否正确；
模型是否真的支持 Embedding，而不是只能进行文本生成；
向量维度是否与已有索引匹配；
更换 Embedding 模型后，是否需要重新建立索引；
测试文档和提问语言是否与 Embedding 模型匹配。

3. 导入并解析文档

配置完成后，进入文件导入页面，选择一份测试文档。可以从 PDF、DOCX、Markdown 等格式开始，先观察单份文档的处理结果，再逐步增加资料数量。

图 5：选择需要导入知识库的原始文档。

确认文件后，LLM-Wiki 会执行文档解析、内容分析和 Wiki 生成等步骤。处理时间会受到文档页数、图片数量、模型响应速度和是否启用外部解析服务等因素影响。

图 6：观察文档导入和解析任务的执行状态。

导入过程中建议注意以下几点：

不要在任务进行中移动或重命名原始文件；
不要同时修改正在生成的 Wiki 页面；
如果任务失败，先查看错误信息，再决定是否重试；
首次导入建议记录模型、解析器和向量配置，便于复现问题；
对重要文档，保留原始文件，不要只保留模型生成的摘要。

4. 查看解析结果和知识图谱

处理完成后，先查看生成的 Wiki 页面，而不是直接把结果当作最终事实。重点检查：

标题和层级是否正确；
表格、代码块和图片是否完整；
实体名称、业务术语和专有名词是否被正确识别；
生成内容是否能够回溯到原始来源；
是否出现模型补写、张冠李戴或把推测当成事实的情况。

图 7：文档解析和 Wiki 生成完成后查看结果。

如果项目提供知识图谱视图，可以继续查看实体、概念和文档之间的关系。首次只导入少量文档时，图谱节点较少、结构比较简单是正常现象；只有当知识库中存在足够多的实体和交叉引用时，图谱才更容易体现出关联价值。

图 8：查看解析结果及当前知识库中的关联关系。

人工审核建议：先抽查原文中的关键结论、数字、日期和规则，再确认 Wiki 页面中的表述。知识图谱能够帮助发现关联，但不能替代事实核查。

5. 使用文本检索验证知识库

导入完成后，至少设计三类问题进行验证：

精确问题：原文中明确出现过的名称、编号或关键词；
语义问题：换一种说法询问原文中的同一概念；
跨文档问题：需要综合两份或多份资料才能回答的问题。

图 9：通过文本检索验证导入内容是否能够被找到。

验证时不要只看“有没有返回结果”，还要看结果是否真正支持答案。可以记录以下指标：

检查项	需要观察的内容
召回	相关页面是否出现在结果中
准确性	返回内容是否真的回答了问题
来源	是否能够定位到原始文档或 Wiki 页面
版本	新旧规则是否被正确区分
延迟	检索和生成是否能够接受

三、Obsidian：打开项目并进行日常管理

LLM-Wiki 负责知识摄入和生成，Obsidian 更适合进行人工阅读、编辑、链接、检索和可视化。两者配合使用时，最重要的是确认它们指向同一份本地 Markdown 知识。

1. 使用同一个 Vault

在 Obsidian 中选择“打开已有 Vault”，定位到 LLM-Wiki 实际生成 Markdown 内容的目录。通常应打开项目根目录；如果项目将 Wiki 单独放在某个目录，则以实际生成页面所在目录和项目配置为准。

图 10：在 Obsidian 中选择 LLM-Wiki 项目目录。

打开后，先确认左侧文件树中能够看到生成的 Markdown 页面，并随机打开一篇页面检查内容和内部链接。

图 11：在 Obsidian 中查看 LLM-Wiki 生成的知识页面。

如果 Obsidian 中看不到新生成的文件，可以先刷新文件列表，确认 Vault 路径是否正确，再检查 LLM-Wiki 是否把内容写入了另一个项目目录。

2. 安装 Terminal 插件

如果希望直接在 Obsidian 中调用本机的 AI Agent CLI，可以安装 Terminal 插件。常见流程是：

打开 Obsidian 设置；
进入“社区插件”；
关闭“受限模式”后搜索 Terminal 插件；
安装并启用插件；
按插件说明选择 Shell，或配置需要执行的终端命令。

图 12：进入 Obsidian 社区插件设置。

图 13：搜索并安装 Terminal 插件。

图 14：查看 Terminal 插件的安装和启用状态。

图 15：根据插件说明配置终端和命令执行方式。

图 16：确认 Terminal 插件能够调用本机 Shell。

安全提醒：社区插件和终端命令都具有较高权限。只安装自己信任的插件，不要把未知命令直接复制到终端执行；对包含工作资料的 Vault，建议先做好备份。

图 17：完成插件安装和启用后，返回 Obsidian 主界面。

3. 安装并使用 Agent CLI

在本机安装自己熟悉的 Agent CLI，例如 Claude Code、Codex CLI 或 Hermes Agent。安装方式和登录流程请以各工具的官方文档为准，不建议在文章中固定某一个版本的命令。

完成安装后，先在系统终端验证 CLI 是否可用，再通过 Obsidian Terminal 插件打开终端。建议先执行只读操作，例如查看当前目录、列出 Markdown 文件或读取单篇笔记，确认 Agent 访问的是正确的 Vault。

图 18：从 Obsidian 中打开 Terminal 面板。

图 19：在 Vault 对应目录中启动 Agent CLI。

图 20：确认 Agent 能够读取当前 Vault 中的 Markdown 内容。

建议给 Agent 明确以下约束：

默认只读，不要未经确认直接修改 Wiki 页面；
所有结论尽量附带来源文件和章节；
遇到冲突信息时列出不同版本，不要自行选择并覆盖；
批量修改前先给出计划和待修改文件清单；
不要读取与任务无关的隐私文件、密钥文件或系统目录。

四、通过 MCP 让 Agent 检索 LLM-Wiki

如果只使用 Terminal，Agent 看到的是文件系统中的 Markdown 文件；如果通过 LLM-Wiki 提供的 MCP 或 HTTP 接口，Agent 还可以调用知识库的检索、文件读取和关联分析能力。两种方式可以互补：

方式	更适合的场景	注意事项
直接读取文件	查看、编辑和批量整理 Markdown	需要 Agent 自己定位文件
LLM-Wiki MCP	混合检索、按语义查找、调用知识库能力	需要服务运行、鉴权和正确配置
HTTP API	自定义脚本或其他客户端接入	需要确认端口、Token 和访问范围

1. 配置 MCP 服务

在 LLM-Wiki 中找到 MCP 或外部服务相关设置，按照当前版本的项目文档生成或复制 Agent 所需的配置。不要直接套用其他版本的端口、字段名或配置格式。

配置时重点确认：

LLM-Wiki 应用或对应服务已经启动；
MCP 服务地址、端口和 Token 与 Agent 配置一致；
Agent 使用的是当前知识库项目，而不是另一个 Vault；
服务默认只监听本机地址，除非明确配置了安全的远程访问；
修改 MCP 配置后，重启 Agent CLI，使配置生效。

图 21：查看 LLM-Wiki 提供的 MCP 或外部调用配置。

2. 使用 Claude Code 进行知识检索

完成 MCP 配置后，可以从一个简单的只读问题开始，例如：

1	请在当前知识库中检索与“接口性能测试”相关的内容，列出最相关的 3 个页面，并为每个页面说明匹配原因和来源路径。

如果需要跨文档分析，可以进一步要求 Agent 对比多个来源，但要明确要求它列出引用页面，并区分“原文事实”和“模型推断”。

图 22：通过 Claude Code 调用知识库进行内容检索。

一次完整的检索链路通常可以理解为：

用户提出问题
    ↓
Agent 选择文件读取或 MCP 检索工具
    ↓
LLM-Wiki 返回相关 Wiki 页面和来源
    ↓
Agent 汇总、比较并生成答案
    ↓
用户回到 Obsidian 查看原文并人工确认

不要把 Agent 的回答直接当作最终结论。 最可靠的使用方式是让 Agent 负责缩小查找范围和整理线索，再回到原始文档或 Wiki 页面核对关键事实。

五、常见问题与排查方法

现象	可能原因	排查建议
文档导入失败	模型、解析器或文件权限配置错误	先查看任务错误信息，用小文件重新测试
PDF 内容顺序错乱	复杂排版、扫描版或 OCR 效果不佳	尝试 MinerU，检查 OCR 结果，并人工校对
搜索不到同义表达	未启用向量搜索或 Embedding 未生效	检查 Embedding 配置和索引是否已重新生成
更换模型后检索异常	新旧向量维度或索引不一致	清理或重建对应索引，避免混用不同模型的向量
Obsidian 看不到新页面	打开的 Vault 路径不对或文件列表未刷新	对照 LLM-Wiki 项目路径，刷新并重新打开 Vault
WikiLink 显示为普通文本	链接格式或文件名不符合 Obsidian 识别规则	检查 `[[页面名]]`、文件名和目录路径
MCP 无法连接	服务未启动、端口/Token 不一致或配置未加载	启动服务、核对配置并重启 Agent CLI
Agent 修改了不该修改的内容	权限范围过大，缺少只读约束	先备份，缩小工作目录和权限，修改前要求确认

六、隐私、安全与备份

本地知识库的“本地”主要指 Markdown 文件和项目目录保存在本机，并不代表所有处理都在本机完成。如果使用云端 Chat、Ingest、Embedding、重排或 Web Search 服务，文档内容或查询内容可能会发送到第三方服务。

建议至少落实以下措施：

导入敏感资料前，确认模型 Provider 的数据使用政策和日志策略；
不要在公开仓库中提交 API Key、Token 和包含敏感信息的原始资料；
MCP 或 HTTP 服务默认只开放给本机，确需远程访问时再配置鉴权和网络隔离；
对原始资料、Wiki 页面和配置目录分别制定备份策略；
使用 Git、Time Machine 或其他备份工具保留重要变更记录；
生成 Wiki 时尽量避免 Obsidian、LLM-Wiki 和 Agent 同时编辑同一文件。

七、总结

跑通这套方案后，三个工具的职责可以归纳为：

LLM-Wiki：负责原始资料摄入、内容分析、Wiki 生成和知识检索；
Obsidian：负责人工阅读、编辑、链接、检索和可视化；
AI Agent：负责跨文档分析、批量整理和自动化操作；
MCP：负责把 LLM-Wiki 的检索和文件能力暴露给外部 Agent。

这套方案的价值不在于让 AI 代替人类维护所有知识，而在于把“收集资料、整理知识、查找内容和人工审核”串成一条可重复的工作流。建议先从少量非敏感资料开始验证，再逐步扩展到团队规范、项目文档和长期经验沉淀。

Jean's Blog

LLM-Wiki 与 Obsidian 构建个人本地知识库实战