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 则不会静默用错版本:

set RK_RUNTIME=D:\somewhere\rknn3_110
start.cmd

2. 第一步:确认模型能加载

cd <REPO>\rknn
start.cmd

看到 server listening on 0.0.0.0:8888 就说明权重进了 NPU。

这一步只能证明"加载成功",不能证明"转换正确"。 Kev 不是对话模型, 用 /v1/chat/completions 问它问题一定得到胡言乱语——那是模型本身的行为,不是转换坏了。 真正的验收在 §4。

顺便看一眼占用:

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 指到就行),然后:

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,不用手动启动:

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)后:

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\"}}}}"

返回:

{"answers":{"team":{"type":"choice","answer":"billing","confidence":0.7638,"probabilities":{...}}}}

单项验收(不依赖数据集)

curl http://127.0.0.1:17890/healthz

整体验收(需要 decision-v2 数据集)

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

{
  "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,做不了更高精度的对照版本。