摘要：llm-wiki 从本地 markdown 工具升级为企业级平台，4 个决策推翻了多次本能反应：架构边界、数据存储、Agent Loop 归属、数据权限。本文复盘取舍，并给出洞察：当客户端越来越强，服务端正从"业务承载"演化为"原子能力 + 数据治理"提供方 —— 所有面向 AI 的服务端都在经历这场变化。
上周有个同事问我：你们的 llm-wiki 能不能给我团队用一下?
我说可以，然后发现:知识库跑在本机、用 markdown 文件、没有权限、没有高可用、没有语义检索……
这就是个人工具和团队平台的差距 —— 不是功能差，是架构根本不支持。
LLM 知识库从个人版走向企业级，难点不是 RAG 选型，而是架构边界与数据治理:客户端 / 服务端 / 模型网关怎么分工、几十万节点怎么存怎么查、不同团队的知识资产怎么隔离 —— 每条决策都决定项目能不能从"我自己的工具"跑成"团队的平台"。 下面是这次升级里 4 个绕不过的关键决策。
一、起点:个人版 llm-wiki 是什么
个人版 llm-wiki 是一个本地跑的个人知识沉淀工具 —— 只有 markdown 文件，没有数据库。 工作方式很直接:用户喂进来文档(协作平台文档 / 本地 markdown),AI 蒸馏成三层笔记，全部以 markdown 落到本地目录:
| 目录 | 内容 |
|---|---|
| source | 来源页 —— 一篇原文档对应的笔记(摘要 / 核心观点 / 关联实体) |
| entity | 实体词条 —— 跨多篇文档凝聚的人 / 概念 / 决策 |
| topic | 主题综合页 —— 自动综合关联实体和来源 |
检索靠 markdown 文件名 + 全文扫描，AI 客户端直接读文件，跑 Agent Loop 自己规划多轮检索。 它验证了一件事:「文档 → 知识图谱」这条 LLM 蒸馏链路是可用的。但它有一个明显的边界 —— 它是"给我自己用的工具",不是"给团队用的平台"。
个人版的设计与实现细节见前作《Karpathy 的 LLM Wiki 模式——会自我进化的知识库》。本文聚焦从个人版走向企业版踩到的几个关键决策。
二、个人到企业:4 个绕不过的真实痛点
个人版好用，但要让它服务一个团队、再到一个组织，会立刻撞上四堵墙:
痛点 1:团队共享与高可用
- 知识库变成同事日常依赖的服务，不能挂在某个人的本机
- 磁盘坏了 / 换机器了，团队的知识资产不能一起没
痛点 2:文档量级上来后文件检索撑不住
- 个人版几百个 md 文件全文 grep 还能跑；上到几万节点 + 几十万条边，文件扫描秒级变分钟级
- 更要命的是 markdown 文件天然不支持语义检索（同义词 / 近义 / 语义相近完全靠不上）
痛点 3:数据权限隔离
- 不同团队的文档密级不同，A 团队的内容不能被 B 团队检索到
- 个人版没有"工作空间"概念，所有文档一锅炖
痛点 4:多客户端接入
- 用户同时在 Claude Code、Openclaw、Hermes 等多个 AI 客户端环境里用
- 要让同一份知识库在每个环境都可访问
四条痛点指向同一个结论:个人版必须升级为「客户端 + 服务端」的平台。 接下来是这次升级中四个最关键的决策。
三、决策一:架构边界怎么切
结论先行:客户端 / 服务端 / 模型网关三层切开，每层只持自己该持的东西。 个人版是单进程包圆 —— 身份 token、数据库、UX、AI 调用全在一个本地进程里。这种集中模式在团队场景里立刻就崩:身份 token 没法跨人共享，数据没法跨机访问，AI 调用配额无人统管。 平台版重新切了三层:
这一刀切下去解决了三件事:
- 用户身份 token 跟用户走，不进服务端 —— 多用户隔离的根基；服务端不持用户 token，永远不会出现"误用别人身份"的问题
- LLM key 集中服务端管理 —— 配额、限流、审计统一治理，不再是每个用户拿自己的 key 各跑各的
- 客户端只是 HTTP 调用方 —— Claude Code、Openclaw、Hermes 谁都能接，平台不绑死单一工具
这个边界一旦切下去，后面所有决策都是在这个骨架上做填充。
四、决策二:数据存储怎么选
结论先行:选 PostgreSQL 单库，扛起全文 + 向量 + 图三种检索。 痛点 2 决定了存储必须换。markdown 文件做检索在几百个文档量级还能撑，到了几万节点就崩 —— 全文扫描慢、语义检索完全没有、并发写要靠分布式锁。 桌面上摆着三个方案:
| 方案 | 优势 | 劣势 |
|---|---|---|
| 本地文件 / NAS(沿用个人版思路) | 零运维、迁移成本零、文档天然 markdown | 并发写要分布式锁、检索靠全量扫描、无 ACL、无语义检索能力 |
| MySQL + 向量库 + 图数据库(专业三件套) | 各司其职:关系 / 向量 / 图各自 SOTA | 运维成本 ×3、跨库事务难、3 套连接池 + 3 套备份 + 3 套监控 |
| PostgreSQL 单库(最终选择) | 全文索引 + 向量扩展 + 递归 CTE 图遍历，一库搞定 | 单项能力都不是 SOTA |
为什么不选三件套:
- 知识库的查询模式是"先召回再 1-2 跳",不是深度图算法 → 不需要图数据库的复杂表达力
- 数据量级是"几万到几十万节点",不是亿级 → 不需要专业向量库的规模
- 团队就 1-2 个后端，运维成本上限就是项目能不能活的上限
- PG 16+ 在三个能力上都"够用",事务 / 备份 / 监控只有一份
为什么不留 NAS:语义检索这一项就把它判了死刑。LLM 时代的知识库，没有语义召回基本等于残废。 一个隐藏教训:起步阶段为了快用过 SQLite 起步，但中文分词、向量、复合主键全都吃力，最后一刀切下线只留 PG。起步贪快，迁移成本最终会还 —— 早一点选定生产级数据库，比中途切换要划算得多。
五、决策三:Agent Loop 跑在哪
结论先行:默认让客户端跑 Agent Loop，服务端只暴露原子工具接口。 这个决策最反直觉。 个人版里 Agent Loop 天然跑在客户端 —— 用户在 AI 客户端里，本地直读 markdown，多轮检索 / 规划全是客户端自己跑。 平台化后第一反应:把 Agent Loop 搬到服务端，客户端只展示结果。这看起来更"平台化" —— 服务端控制所有逻辑，客户端只是个壳。 我们也确实试过这条路。在服务端用 Java 手写了一个 Agent Loop(叫 ask-deep)，跑下来效果一般:
- 模型版本跟不上:客户端用的是当前最新一代客户端模型，服务端走公司 LLM 网关绑定固定型号，差距越拉越大
- 规划逻辑写死在代码里:多轮策略想调一下就要发版，迭代速度被服务端发版周期拖住
- 客户端的工具调用框架反而更成熟:Claude Code / Openclaw / Hermes 在多轮规划上已经积累很深，服务端从零写一个循环很难追上
跑了一段时间我们才反应过来:这个本能反应是错的。客户端本身就是个完整的 AI 推理环境，让服务端再跑一遍 Agent Loop，等于平台跟客户端抢同一份事，且大概率抢不过。 最终决策:服务端保留一个兼容路径(ask-deep)，但默认 ask 走客户端 Agent Loop，客户端调服务端的原子接口(list / recall / pages)多轮自驱。 三维对比:
| 维度 | 服务端 Agent Loop | 客户端 Agent Loop(最终选) |
|---|---|---|
| 灵活性 | 模型固定、规划逻辑写死在服务端代码里，每次调整都要发版;多轮策略难快速迭代 | 客户端用什么模型、跑几轮、怎么规划全自主，跟着客户端能力一起升级 |
| 效果 | 服务端自己手写一个循环，很难比客户端原生 Agent 框架做得更好 —— Claude Code、Openclaw 在 Agent 工程上已经积累很深 | 直接复用客户端成熟的 Agent 能力，效果上限就是客户端 SOTA |
| 关注点分离 | 服务端既管数据又管推理，职责膨胀;任何一边的变更都互相牵连 | 服务端只暴露"工具",客户端只做"规划",各做各擅长的 |
架构层面的意义:Agent Loop 的本质是「规划 + 工具调用」。客户端是 AI 推理环境，已经把规划做到很好;服务端的优势在数据和工具暴露。正确的分工是:服务端收敛为"工具供应商",把规划权留给客户端。这是 LLM 时代分布式系统的一个普适设计 —— 不是所有逻辑都要往服务端搬，要看哪一边天然更擅长。
六、决策四:数据权限怎么隔离
结论先行:用 workspace + 角色把"团队边界"切出来，按需向"领域边界"演化。先做必要的，不做完备的。 很多人讨论企业级权限，第一反应是"鉴权"。但鉴权只是入场券 —— 它告诉系统"你是谁"。企业落地的真问题是更深一层:你这个身份能看哪些数据。 A 团队的内容不能被 B 团队检索到，研发方案不能被外部账号查到 —— 这才是数据权限隔离要解的事。
Phase 1:workspace + 角色(已落地)
把知识库按 workspace(工作空间)切成多个独立单元。设计要点:
| 设计点 | 做法 |
|---|---|
| 数据隔离 | 每条记录带 workspace_id，所有查询强制带 workspace 过滤(WHERE workspace_id = ?)，跨 workspace 访问必须显式切换并走 ACL 校验 |
| 用户挂载 | 通过 workspace_members 表，用户挂到一个或多个 workspace，每次挂载带角色 |
| 角色定义 | owner(管理)/ editor(写)/ viewer(只读)三档 |
| 鉴权来源 | 用户身份由企业鉴权 SDK 在 Filter 链统一解析(支持多种 token 来源),业务侧只关注"你属于哪些 workspace、在每个里能做什么" |
这一层做完，能解决 90% 的团队级隔离需求 —— 不同团队各起 workspace，互相看不到对方的数据。
Phase 2:按领域授权(按需推进)
workspace 粒度在更复杂的场景里还不够 —— 同一个 workspace 内的不同领域(如财务 / 研发 / 法务)也可能要分权。 设想:在 page 上打领域标签，角色加领域属性，查询时按领域 ACL 过滤。 这一层做不做、怎么做，关键看实际需求 —— 不要为了"看起来权限完整"提前做。 过度设计 ACL 的运维成本极高:每加一个领域，就是一轮组织映射 + 一轮历史数据回填 + 一轮策略评审。在用户没有真实诉求之前提前做，等于自己挖坑给自己跳。
核心思想
鉴权是入场券，数据权限隔离才是企业落地的硬骨头。
先用 workspace + 角色把"团队边界"切出来满足主流需求;按需向"领域边界"演化。
七、写在最后:服务端的角色正在变
回看这 4 个决策，有一个共同方向 —— 服务端的边界在重新定义:不再包揽所有，而是收敛到自己擅长的事，把编排和推理留给客户端 AI。
| 过去服务端做的事 | 新分工 |
|---|---|
| 持有用户身份 / 业务流程编排 / AI 推理 | 客户端 AI 接管 |
| 数据存储 / 原子工具暴露 / 鉴权治理 / 数据隔离 | 服务端继续做，且做扎实 |
把这次落地的三件事拼起来看:
- 决策一:客户端持身份 token，服务端不持
- 决策三:客户端跑 Agent Loop(编排),服务端只暴露原子接口(数据/工具)
- 决策四:服务端管 workspace 隔离(治理),规划与推理留给客户端
llm-wiki 的服务端实际上正在演化成一个"知识库 MCP server" —— 对外暴露原子工具集(list / recall / pages / ingest),管好数据治理和权限隔离，把"怎么用这些工具"交给客户端 AI 决定。 这不是 llm-wiki 一家的趋势。当 Claude Code / Openclaw / Hermes 这类 AI 客户端越来越强(更长上下文、更原生的工具调用、更成熟的 Agent 框架),服务端再去抢"编排"和"推理"已经没有优势 —— 这两件事本来就是 AI 客户端的主场。 服务端真正擅长的，是数据、工具、治理。
留一个开放问题:
所有面向 AI 设计的服务端，是不是都会逐步演化成"原子能力 + 数据治理"的提供方?
业务逻辑里 AI 擅长的部分 —— 多轮规划、上下文综合、工具选择 —— 上移到客户端;AI 不擅长但项目必须的部分 —— 鉴权、隔离、持久化、审计 —— 留在服务端。这是一种新的分工。 这不只是知识库服务考虑的事，所有面向 AI 设计的服务端，都面临同样的变化。
三条可执行的判断
如果你也在做企业级 LLM 应用:
- 先切架构边界再写代码 —— 客户端 / 服务端 / 模型网关三层各持各的，是稳定性的根基
- 平台化不应收回客户端已有的能力 —— 客户端有 AI 推理能力时，服务端应收敛为"原子能力 + 数据治理"的提供方
- 企业落地比的是治理，不是模型 —— 数据存储、权限隔离、客户端边界三件事不动，再好的 RAG 也只是 Demo
模型选型只是开胃菜，架构边界与数据治理才是主菜。
完整的部署脚本和踩坑手册，关注公众号「AI 纪元说」，后台回复 llmwiki 服务化 即可获取。
