107 lines
6.8 KiB
Markdown
107 lines
6.8 KiB
Markdown
# 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/](../../../../opt/1panel/www/sites/xk-api/index/xk-api/storage/maxkb_seed/) 下有 7 个 Markdown 文件 |
|
||
|
||
---
|
||
|
||
## 学习路径（按顺序看）
|
||
|
||
| 文档 | 做什么 | 预计耗时 |
|
||
|---|---|---|
|
||
| [01_部署MaxKB.md](./01_部署MaxKB.md) | 在服务器上装一个 MaxKB 平台 | 15 分钟 |
|
||
| [02_上传知识库.md](./02_上传知识库.md) | 把中医资料传到 MaxKB，让它能搜 | 10 分钟 |
|
||
| **[MaxKB创建内容.md](./MaxKB创建内容.md)** | **创建智能体时系统提示词/用户提示词/检索参数该怎么填**（直接复制版）| 5 分钟 |
|
||
| [03_创建应用拿密钥.md](./03_创建应用拿密钥.md) | 在 MaxKB 里建一个"应用"，拿到 API 钥匙 | 5 分钟 |
|
||
| [04_配置GoAgent.md](./04_配置GoAgent.md) | 改 Go Agent 配置文件，让它知道 MaxKB 在哪 | 5 分钟 |
|
||
| [05_打开PHP开关.md](./05_打开PHP开关.md) | 在数据库里把"启用知识库"的开关打开 | 5 分钟 |
|
||
| [06_修复检索词Bug.md](./06_修复检索词Bug.md) | ⚠️ **必做**：修复 PHP 不传检索词的 Bug | 10 分钟 |
|
||
| [07_验证与排错.md](./07_验证与排错.md) | 怎么测试接入是否成功？失败了怎么查？ | 按需 |
|
||
| **[08_本地知识库管理.md](./08_本地知识库管理.md)** | **MaxKB 免费版没有检索 API？改用本地知识库**（零部署、零成本） | 15 分钟 |
|
||
|
||
> **怎么选 MaxKB vs 本地知识库？**
|
||
>
|
||
> - 你的 MaxKB 是**专业版（Pro）** → 走 [01-07](./01_部署MaxKB.md)，体验最好（支持语义检索）
|
||
> - 你的 MaxKB 是**免费版** → 直接跳到 [08_本地知识库管理.md](./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 入口"，关联到一个或多个知识库。<br>⚠️ **注意版本差异**：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](./01_部署MaxKB.md)
|