MaxKB 知识库接入教程（零基础版）
本教程面向没接触过 MaxKB / RAG / Go Agent 的同学，从 0 开始一步步带你把中医知识库接到 AI Agent 上。
跟着做完后，效果：医生开病历 / 开处方时，AI 会先去知识库里查"煎法 / 委托调剂 / 中医证候 / ICD-10 / 药品库"等固定资料，再生成回答，结果更准、幻觉更少。
这个东西是干嘛的？
打个比方：
- 现在的 AI：凭脑子里的训练知识回答（脑子里的知识可能过时、可能记错）
- 接入 MaxKB 后的 AI：回答前先去你的资料库翻书，把翻到的内容当作参考再回答（更准、更可控）
医生发起请求 ──▶ AI 先去 MaxKB 查相关资料 ──▶ 资料塞进提示词 ──▶ AI 结合资料生成答案
↑
你录入的知识库
（煎法、证候、药品、ICD-10…）
你需要准备什么
| 准备项 | 说明 |
|---|---|
| 一台能装 Docker 的服务器 | 推荐 Linux（你已经在用 1Panel，最简单） |
| 服务器至少 4G 内存 | MaxKB + 向量库吃内存，2G 会卡 |
| 服务器开放一个端口给 MaxKB | 比如 8081（不要用 8080，会和 Go Agent 冲突） |
| 知识库资料（已为你准备好） | storage/maxkb_seed/ 下有 7 个 Markdown 文件 |
学习路径（按顺序看）
| 文档 | 做什么 | 预计耗时 |
|---|---|---|
| 01_部署MaxKB.md | 在服务器上装一个 MaxKB 平台 | 15 分钟 |
| 02_上传知识库.md | 把中医资料传到 MaxKB，让它能搜 | 10 分钟 |
| MaxKB创建内容.md | 创建智能体时系统提示词/用户提示词/检索参数该怎么填（直接复制版） | 5 分钟 |
| 03_创建应用拿密钥.md | 在 MaxKB 里建一个"应用"，拿到 API 钥匙 | 5 分钟 |
| 04_配置GoAgent.md | 改 Go Agent 配置文件，让它知道 MaxKB 在哪 | 5 分钟 |
| 05_打开PHP开关.md | 在数据库里把"启用知识库"的开关打开 | 5 分钟 |
| 06_修复检索词Bug.md | ⚠️ 必做：修复 PHP 不传检索词的 Bug | 10 分钟 |
| 07_验证与排错.md | 怎么测试接入是否成功？失败了怎么查？ | 按需 |
| 08_本地知识库管理.md | MaxKB 免费版没有检索 API？改用本地知识库（零部署、零成本） | 15 分钟 |
怎么选 MaxKB vs 本地知识库？
- 你的 MaxKB 是专业版（Pro） → 走 01-07，体验最好（支持语义检索）
- 你的 MaxKB 是免费版 → 直接跳到 08_本地知识库管理.md，5 步搞定
全部做完总耗时：约 55 分钟
整体架构图（看一眼就懂）
┌──────────────────────────────────────────────────────────────────┐
│ 你的服务器 │
│ │
│ ┌──────────────┐ 检索 ┌──────────────────┐ │
│ │ MaxKB 平台 │ ◀───────────── │ Go Agent │ │
│ │ (端口 8081) │ ────────────▶ │ (端口 8080) │ │
│ │ │ 返回文档片段 │ │ │
│ │ 你的中医资料 │ │ - 拼 system 消息 │ │
│ │ (煎法/证候) │ │ - 调 DeepSeek │ │
│ └──────────────┘ └────────┬─────────┘ │
│ │ HTTP │
│ ▼ │
│ ┌──────────────────┐ │
│ │ PHP (xk-api) │ │
│ │ │ │
│ │ - 拼业务提示词 │ │
│ │ - 调 Go Agent │ │
│ │ - 写入数据库 │ │
│ └────────┬─────────┘ │
│ │ │
└────────────────────────────────────────────┼──────────────────────┘
│
▼
┌──────────────┐
│ 医生小程序 │
└──────────────┘
常见名词解释（小白专用）
| 名词 | 大白话解释 |
|---|---|
| MaxKB | 一个开源的"知识库 + AI"平台，你把资料扔进去，它帮你建索引、做检索，AI 调它就能"翻书" |
| RAG | Retrieval-Augmented Generation，检索增强生成。就是"先翻书再回答"的技术统称 |
| 知识库 | MaxKB 里的概念，相当于一个文件夹，装着一堆相关文档 |
| 应用 / 智能体 | MaxKB 里的概念，相当于"一个对外开放的 API 入口"，关联到一个或多个知识库。 ⚠️ 注意版本差异：MaxKB 老版（1.x/2.x）叫"应用"，新版（4.x）叫"智能体"。两个是同一个东西，底层 API 完全一样。如果你界面里看到的是"智能体"，把它当"应用"看就行。 |
| API Key | 一串密码，调 API 时带着它证明"我是合法用户"。老版以 application- 开头，新版可能是 application- 或 agent- 开头 |
| App ID | 应用 ID，类似"应用编号"，UUID 格式（8-4-4-4-12），调 API 时拼在 URL 里 |
| 向量化 | 把文字转成数字数组的过程，方便算相似度。MaxKB 自动做，你不用管 |
| TopK | 检索时返回"最相关的前 K 条"，K 一般填 5（既够用又不刷屏） |
下一步：开始 01_部署MaxKB.md