我把电子书喂给本地 AI:技术跑通了,Agent 却装作用了
- 2026-10-09 06:37:09
我把电子书喂给本地 AI · 它却“装作用了”
一次本地 EPUB-RAG 实战，最终暴露的却是 Agent 架构的真问题
技术易得，确定性难求——这篇复盘写给所有想让 Agent「真的」干活的实践者
过去几天，我把一套本地 EPUB 知识库从零搭到了可用。本文不是流水账，而是一份带判断的复盘——我为什么这样选、怎么搭、验证了什么、在哪里摔跤，以及这些摔跤最终暴露出的，是一个比“搭 RAG”更深的 Agent 架构命题。如果你也在做本地 Agent 化，希望这篇能帮你少走几步弯路。
书籍原文是知识源，LLM 只是组织者，不是冒充者。系统必须能区分「模型知道什么」「RAG 检索到什么」「这本书真正提供了什么」——这正是一切后续问题的根。
01
PART
起点：为什么要把电子书变成知识源
WHY · 目标定义
最初的目标不是“让 LLM 能搜一本书”，而是把一本 EPUB 变成 真正可被本地 Agent 调用的知识源。整条链路是：EPUB → 文本解析 → 清洗分块 → Embedding → 向量库 → RAG API → Pi Agent → 基于书回答。
这里的分水岭在于：书是权威，模型只负责 理解和组织检索结果，而不是拿自己的通用知识冒充书中内容。一旦这条原则松动，后面所有“看起来像 RAG、实则没检索”的坑就都埋下了。
02
PART
架构：为什么把 131 和 141 分开
ARCH · 双机分工
本地环境最终拆成两个节点。一台只做 Agent 编排层，另一台集中放模型、数据与 RAG。好处很直接：EPUB、Embedding 模型、向量库全在 141，131 上无需复制一份。
192.168.0.131 · 编排节点
运行 Pi Agent、Agent Skill、后续 Tool / Extension 与请求编排。它是 Agent 层，不存知识库，也不存模型权重。
192.168.0.141 · 模型/数据节点
集中 Ollama（:11434）、Embedding、Qdrant（:6333）、EPUB 文件（C:\rag\books\）与 RAG Service（:8100）。
03
PART
选型：三个关键决策
CHOICE · 取舍依据
第一个决策就决定了后续所有成本：Embedding 模型选哪个。我当时在 BGE-small / BGE-base / MiniLM 之间权衡，最终落地 BAAI/bge-small-zh-v1.5，512 维，纯 CPU 跑。
另外两个决策：向量库选 Qdrant 的 Windows 原生安装，不用 Docker；再套一层 FastAPI 做 RAG Service，把 Qdrant、Embedding、chunk 的细节对 Agent 屏蔽掉，形成清晰的服务边界。
先验证 RAG 架构，再优化 Embedding 效果。BGE-small 不是“永远最好”，只是在当前硬件、中文 EPUB、本地链路、首版验证的约束下，一个合适的起点。等有了评测集，再决定要不要升 base。
04
PART
细节：Chunk 与阅读顺序
CHUNK · 解析纪律
第一版用 chunk 420 / overlap 60 / batch 32。但真正容易翻车的是解析顺序——绝不能按 EPUB 内部文件名排序，否则会出现“第 1 章 → 第 10 章 → 第 11 章 → 第 2 章”的乱序。
正确做法是严格遵循 EPUB 的 spine / reading order。这条纪律看着小，却是 RAG 检索质量的地基——顺序错了，再好的 Embedding 也救不回来。
05
PART
验证：一层一层来，别让 Agent 背锅
VALIDATE · 分层证明
搭完没有马上接 Pi，而是先把底层链路独立跑通：EPUB → 解析 → 分块 → BGE → 512 维向量 → Qdrant → Search API。再做一次 131 → 141 跨主机实测，确认从编排机访问 RAG Service 正常返回。
这一步的价值在于：一旦后面 Agent 出问题，你能立刻判断是 Agent / Skill / Python / FastAPI / Qdrant / Embedding 哪一层，而不是笼统地甩锅给“RAG 不行”。实测通过，就等于把 RAG 基础设施独立证明了。
“服务启动了”不等于“客户端调用方式对”。我曾遇到 error parsing the body——请求到了服务端，但请求体没按预期解析。正是这次，我把 RAG 客户端单独抽成 rag_client.py，让 Pi 只调 search / import，不必自己拼 HTTP。
06
PART
第一个大坑：Skill 被加载 ≠ 会执行
PITFALL 1 · 说明书不是函数
RAG Service 独立成立后，自然想把它接进 Pi Agent。第一种思路是在 Skill 里写规则：“涉及 EPUB 时必须先检索”“不得只用通用知识回答”。但实测后发现一个残酷事实：SKILL.md 本质是行为规范，不是程序函数。
Pi 能“理解”这是个 EPUB 问题，却不一定真的去执行 rag_client.py，反而可能凭模型记忆直接作答。这正是 RAG 最危险的状态——看起来像 RAG，实际没检索。我后来在 Skill 里补了严格的 Retrieval Grounding 与 Verification Integrity 规则来兜底，但底下那个根因，下一章再说。
07
PART
第二个大坑：嵌套 Shell 把路径揉碎了
PITFALL 2 · 路径陷阱
为了让 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 脚本——再多一层路径兼容层，反而增加解释风险。但必须说清：这只排除了“调用形式”这类干扰，没有解决根本问题。
08
PART
真正的难题：从“该调用”到“必调用”
THE REAL PROBLEM · 机制缺口
把链路抽象一下：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
01 / 为什么不直接用云端 RAG 服务？
本地跑是为了知识私密与零调用成本，书库不出口。
02 / 为什么 Qdrant 坚持 Windows 原生、不上 Docker？
当前就是 Windows 实验机，为单个向量库引入 Docker 层纯属加重负担。
03 / Skill 和 MCP，到底差在哪？
Skill 是“软约束”——靠模型自觉；MCP 是“硬机制”——工具调用确定性触发。这正是本文那个 ??? 的答案。
///
END
写在最后
CLOSING · 给实践者的纪律
这次项目最大的收获，不是跑通了一条 RAG 链路，而是认清一个常被忽略的事实：让 Agent 拥有“能力”，和“告诉它该怎么做”，是两回事。
如果你也在做本地 Agent 化，记住这条纪律——先独立验证每一层，再用机制（而非指令）把能力焊死在 Agent 上。下一篇，我会拆开 MCP server 这层“机制”到底怎么写。
技术易得，确定性难求。
如果这篇文章对你有帮助
