jj90's picture
Add model card, deployment guide and host-side code
a846b3d verified
|
Raw History Blame Contribute Delete
7.83 kB
# 部署指南(RK1828)
> 这份文档只讲"怎么把它跑起来"。为什么这么做、踩过哪些坑,见仓库根 `README.md`
> 与上游项目里的 `PITFALLS.md`。
---
## 0. 前置条件
| 项 | 要求 |
| --- | --- |
| Host | Windows PC(实测)/ RK3588 / RK3576 板。**x86 Linux 不行**——能转换、能跑模拟器,但不能直连模组 |
| 模组 | RK1828(RK1820 同 SDK) |
| 运行时 | RKNN3 **v1.1.0**,即 `runtime/rknn3_110`(`rkllm3-server.exe`、`librknn3_api.dll` 等) |
| 驱动/固件 | 与运行时同版本。版本不一致会 load 失败或静默退出 |
| 编译 daemon 额外需要 | Cygwin g++、RKNN3 SDK 的 `examples/rknn3_session_test_demo/{src,utils}`、`examples/3rdparty/tokenizer` |
| Python | 3.8+,`numpy` |
> 组件版本必须一致(toolkit / proxy / runtime / 固件)。混版本是最常见的"跑一半没反应"。
---
## 1. 布局
把仓库放到设备侧任意目录,建议:
```
<REPO>\
├── rknn\ # 本仓库的 rknn/ 目录
│ ├── Kev-0.8B.rknn
│ ├── Kev-0.8B.weight
│ ├── Kev-0.8B.embed.bin
│ ├── Kev-0.8B.tokenizer.gguf
│ └── start.cmd
├── host\
│ ├── kev_serve.py
│ ├── kev_daemon.cpp
│ ├── e2e_check.py
│ └── serve_assets\
└── runtime\rknn3_110\ # 从 SDK 拷来的运行时
```
`start.cmd` 会自动在**两个位置**找运行时:`<REPO>\runtime\rknn3_110`(本仓库下载后的布局)
和 `<包根>\runtime\rknn3_110`(放进 rk1828-console 的 `models\<模型>\` 时)。
两处都没有就报错并提示,不设 `RK_RUNTIME` 则不会静默用错版本:
```bat
set RK_RUNTIME=D:\somewhere\rknn3_110
start.cmd
```
---
## 2. 第一步:确认模型能加载
```bat
cd <REPO>\rknn
start.cmd
```
看到 `server listening on 0.0.0.0:8888` 就说明权重进了 NPU。
**这一步只能证明"加载成功",不能证明"转换正确"。** Kev 不是对话模型,
用 `/v1/chat/completions` 问它问题一定得到胡言乱语——那是模型本身的行为,不是转换坏了。
真正的验收在 §4。
顺便看一眼占用:
```bat
rknn-smi
```
`used` 应该在 **800 MB** 量级(含 34 MB 基线)。明显偏小说明权重没真正进 NPU。
> 加载期间**不要**去轮询 `rknn-smi`。查询会卡在 `Weight sync`,把 30 秒的加载拖成几分钟甚至失败。
---
## 3. 第二步:编译 daemon
`rkllm3-server` 只能返回文本,拿不到 logits,所以真实使用需要自己的 host 程序。
准备 SDK 里的两样东西(都来自 RKNN3 SDK,不在本仓库内):
- `examples/rknn3_session_test_demo/` —— 里面 `src/`、`utils/`、`CMakeLists.txt`
- `examples/3rdparty/tokenizer/` —— 头文件 + `lib/Windows/x86_64/libtokenizer.a`
把 `host/kev_daemon.cpp` 放进 demo 的 `src/`(或任意位置,`-I` 指到就行),然后:
```bat
set PATH=C:\cygwin64\bin;<REPO>\runtime\rknn3_110\lib;<REPO>\runtime\rknn3_110\bin;%PATH%
cd /d <SDK>\examples\rknn3_session_test_demo
"C:\cygwin64\bin\g++.exe" -std=c++11 -I. -Iutils -I<REPO>\host -I<TOK>\include ^
src\kev_daemon.cpp utils\rknn3_session_test_common.cpp -o daemon.exe ^
<REPO>\runtime\rknn3_110\lib\librknn3_api.dll ^
<TOK>\lib\Windows\x86_64\libtokenizer.a -lpthread
```
三个必注意的点:
1. **`C:\cygwin64\bin` 必须在 PATH 最前面**,否则 `cc1plus` 找不到 `cygwin1.dll`,报一个和编译毫无关系的错。
2. **链接时直接给 `.dll` / `.a` 的完整路径**,Cygwin 的 ld 接受这种写法,不需要 `-L`/`-l`。
3. 编译产物 `daemon.exe` **必须能加载到 `librknn3_api.dll`**。计划任务不继承 PATH,
这种情况下会以 `rc=3221225781`(`0xC0000135`)**一个字的输出都没有**地退出。见 §6。
---
## 4. 第三步:起服务并验收
`kev_serve.py` 会自己拉起 daemon,不用手动启动:
```bat
set KEV_MODEL_DIR=<REPO>\rknn
set KEV_DAEMON=<SDK>\examples\rknn3_session_test_demo\daemon.exe
python <REPO>\host\kev_serve.py
```
不设这两个环境变量时,它按"`<包根>\models\Kev-0.8B`"和"脚本同目录 `rknn3_session_test_demo\daemon.exe`"找,
放进现成的 rk1828-console 包里就不用设。
默认端口 **17890**,可用 `KEV_PORT` 覆盖。等它打印 ready(模型加载约 30 s)后:
```bash
curl -X POST http://127.0.0.1:17890/v1/systemone ^
-H "Content-Type: application/json" ^
-d "{\"state\":{\"ticket\":\"Checkout returns 500 for EU customers\"},\"questions\":{\"team\":{\"type\":\"choice\",\"instructions\":\"Which team?\",\"criteria\":{\"billing\":\"payments\",\"platform\":\"infra\"}}}}"
```
返回:
```json
{"answers":{"team":{"type":"choice","answer":"billing","confidence":0.7638,"probabilities":{...}}}}
```
### 单项验收(不依赖数据集)
```bash
curl http://127.0.0.1:17890/healthz
```
### 整体验收(需要 decision-v2 数据集)
```bash
set KEV_URL=http://127.0.0.1:17890
python <REPO>\host\e2e_check.py
```
期望 **23/26 = 0.885**(三题型混合抽样)。数字明显偏低时先看是不是抽样把题型抽偏了,
再用 KEV_DEV 指到正确路径。
---
## 5. 接口
`POST /v1/systemone`
```json
{
"state": <任意 JSON:字符串 / 对象 / 数组,会按 YAML 风格渲染进 prompt>,
"questions": {
"<name>": {
"type": "choice" | "noul" | "score",
"instructions": "...",
"criteria": {"<选项>": "<描述>"} // choice:对象
| ["<档位描述>", ...] // score:数组
}
}
}
```
| type | 返回 |
| --- | --- |
| `choice` | `answer` + `confidence` + `probabilities` |
| `noul` | `p_true`(上游 API 只回概率,不转布尔) |
| `score` | `score`(概率加权期望档位)+ `legend` + 各档概率 + `score_confidence` |
错误码:`400` 参数不合法、`405` 方法不对、`413` body 超过 1 MiB、`500` 内部错误(堆栈只写日志,不回给客户端)。
---
## 6. 一定会踩的坑
| 现象 | 原因 | 处理 |
| --- | --- | --- |
| daemon 起来就退,**没有任何输出**,`rc=3221225781` | `librknn3_api.dll` 找不到(计划任务不继承 PATH) | 在 `Popen` 前把 `<runtime>\lib` 和 `\bin` 塞进 `os.environ["PATH"]` |
| `READY_DAEMON` 永远等不到,但进程活着 | C 运行时把管道 stdout 全缓冲了 | `setvbuf(stdout, NULL, _IOLBF, 0)`(`kev_daemon.cpp` 里已加) |
| `model_init ret=-2`,日志 `core mask 0x00000000 is not contiguous` | `cfg.run_core_mask` 默认 0 | 传 `0xff`(8 核) |
| 反复拆建 proxy,模组从总线掉线 | proxy 全机唯一 | 复用同一个 proxy 进程,只启停模型 |
| 改了代码但行为没变 | 残留进程占着端口 / 旧 exe | 先 `taskkill /F /IM daemon.exe`,用随机端口自测 |
| 断电后设备认不到 | 进了 MaskROM(`2207:180B`) | 跑一次 `uf` 工具,约 2 秒恢复 |
| `.cmd` 里的中文把命令截断 | cmd 按 OEM 代码页(936)读文件 | `.cmd` / `.bat` / `.ps1` 一律**纯 ASCII + CRLF** |
完整清单见上游项目的 `PITFALLS.md`(更细,含每一步的日志与判据)。
---
## 7. 已知限制
- **一次请求 = K+1 次 prefill**(`<decide>` 一次 + 每个 `</opt>` 一次)。图的输出固定 `[1,1,248320]`,
只保留最后一个位置;公开 API 没有 `num_logits_to_keep`,`clear_kvcache` 也没有 truncate。
这是硬下限,不是实现选择。
- 每次调用有约 **50 ms 固定开销**,与序列长度无关。延迟看**调用次数**,不是 token 数。
- 服务对整次决策加**全局锁**:并发是安全的,但会排队。`K+1` 次 prefill 共用一份 KV cache,
不加锁会串。
- 量化格式被工具链锁死为 `w4a16 + normal + group32`,做不了更高精度的对照版本。