我把电子书喂给本地 AI:技术跑通了,Agent 却装作用了

技术易得，确定性难求——这篇复盘写给所有想让 Agent「真的」干活的实践者

过去几天，我把一套本地 EPUB 知识库从零搭到了可用。本文不是流水账，而是一份带判断的复盘——我为什么这样选、怎么搭、验证了什么、在哪里摔跤，以及这些摔跤最终暴露出的，是一个比“搭 RAG”更深的 Agent 架构命题。如果你也在做本地 Agent 化，希望这篇能帮你少走几步弯路。

最初的目标不是“让 LLM 能搜一本书”，而是把一本 EPUB 变成 真正可被本地 Agent 调用的知识源。整条链路是：EPUB → 文本解析 → 清洗分块 → Embedding → 向量库 → RAG API → Pi Agent → 基于书回答。

这里的分水岭在于：书是权威，模型只负责 理解和组织检索结果，而不是拿自己的通用知识冒充书中内容。一旦这条原则松动，后面所有“看起来像 RAG、实则没检索”的坑就都埋下了。

本地环境最终拆成两个节点。一台只做 Agent 编排层，另一台集中放模型、数据与 RAG。好处很直接：EPUB、Embedding 模型、向量库全在 141，131 上无需复制一份。

第一个决策就决定了后续所有成本：Embedding 模型选哪个。我当时在 BGE-small / BGE-base / MiniLM 之间权衡，最终落地 BAAI/bge-small-zh-v1.5，512 维，纯 CPU 跑。

另外两个决策：向量库选 Qdrant 的 Windows 原生安装，不用 Docker；再套一层 FastAPI 做 RAG Service，把 Qdrant、Embedding、chunk 的细节对 Agent 屏蔽掉，形成清晰的服务边界。

第一版用 chunk 420 / overlap 60 / batch 32。但真正容易翻车的是解析顺序——绝不能按 EPUB 内部文件名排序，否则会出现“第 1 章 → 第 10 章 → 第 11 章 → 第 2 章”的乱序。

正确做法是严格遵循 EPUB 的 spine / reading order。这条纪律看着小，却是 RAG 检索质量的地基——顺序错了，再好的 Embedding 也救不回来。

搭完没有马上接 Pi，而是先把底层链路独立跑通：EPUB → 解析 → 分块 → BGE → 512 维向量 → Qdrant → Search API。再做一次 131 → 141 跨主机实测，确认从编排机访问 RAG Service 正常返回。

这一步的价值在于：一旦后面 Agent 出问题，你能立刻判断是 Agent / Skill / Python / FastAPI / Qdrant / Embedding 哪一层，而不是笼统地甩锅给“RAG 不行”。实测通过，就等于把 RAG 基础设施独立证明了。

RAG Service 独立成立后，自然想把它接进 Pi Agent。第一种思路是在 Skill 里写规则：“涉及 EPUB 时必须先检索”“不得只用通用知识回答”。但实测后发现一个残酷事实：SKILL.md 本质是行为规范，不是程序函数。

Pi 能“理解”这是个 EPUB 问题，却不一定真的去执行 rag_client.py，反而可能凭模型记忆直接作答。这正是 RAG 最危险的状态——看起来像 RAG，实际没检索。我后来在 Skill 里补了严格的 Retrieval Grounding 与 Verification Integrity 规则来兜底，但底下那个根因，下一章再说。

为了让 Pi 真正驱动脚本，我开始测试 rag_client.py，结果踩进 Windows Shell 的坑。命令里出现 「python 后直接嵌套 Windows 路径双引号」这种写法，再叠一层 PowerShell 解析，Python 收到的路径被揉成了 C:\Users\Roy\.pi\UsersRoy.piagentskills…——文件明明存在（Get-Item 验证过），是多层 Shell 把参数解释错了。

powershell.exe -NoProfile -Command '& python "C:\Users\Roy\.pi\agent\skills\epub-rag\scripts\rag_client.py" search "当哲学家遇上心理医生"'

稳妥写法是 外层单引号、内部双引号，避开嵌套双引号。也别用 Bash / Git Bash 跑这种 Windows 脚本——再多一层路径兼容层，反而增加解释风险。但必须说清：这只排除了“调用形式”这类干扰，没有解决根本问题。

把链路抽象一下：Knowledge → Service → Client → Skill → ??? → Agent。前面每一格都验证成立了，唯独最后这一格没焊死。因为这两件事本质是分开的：

PIPELINE

从知识源到 Agent，缺口在最后一格

唯独没焊死的，是 Skill → Agent 之间的「触发机制」：Agent 会不会在需要时主动检索？

Skill 能“告诉 Agent 怎么做”已经基本解决；但 Skill 能保证 Agent 执行吗，仍是问题。这次项目最大的架构认识，是表面在搭 RAG，实则做了一回 Agent Architecture 实验——问题从“RAG 能不能工作”变成了“Agent 能不能可靠地调用 RAG”。

我的解法，是把 Skill 的“说明书”升级成“工具 / 函数调用”——也就是 用 MCP（Model Context Protocol）替代自然语言指令。让“需要 EPUB 知识 → 自动触发检索”从“靠模型自觉”变成“机制保证”：工具调用是确定性的，不像 SKILL.md 只是“你应该这么做”。这套系统后来确实改造成了 MCP server（stdio 接入），下一期拆开讲它到底怎么写。

COMMON QUESTIONS

这次项目最大的收获，不是跑通了一条 RAG 链路，而是认清一个常被忽略的事实：让 Agent 拥有“能力”，和“告诉它该怎么做”，是两回事。

如果你也在做本地 Agent 化，记住这条纪律——先独立验证每一层，再用机制（而非指令）把能力焊死在 Agent 上。下一篇，我会拆开 MCP server 这层“机制”到底怎么写。

如果这篇文章对你有帮助