# 部署指南(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. 布局 把仓库放到设备侧任意目录,建议: ``` \ ├── 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` 会自动在**两个位置**找运行时:`\runtime\rknn3_110`(本仓库下载后的布局) 和 `<包根>\runtime\rknn3_110`(放进 rk1828-console 的 `models\<模型>\` 时)。 两处都没有就报错并提示,不设 `RK_RUNTIME` 则不会静默用错版本: ```bat set RK_RUNTIME=D:\somewhere\rknn3_110 start.cmd ``` --- ## 2. 第一步:确认模型能加载 ```bat cd \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;\runtime\rknn3_110\lib;\runtime\rknn3_110\bin;%PATH% cd /d \examples\rknn3_session_test_demo "C:\cygwin64\bin\g++.exe" -std=c++11 -I. -Iutils -I\host -I\include ^ src\kev_daemon.cpp utils\rknn3_session_test_common.cpp -o daemon.exe ^ \runtime\rknn3_110\lib\librknn3_api.dll ^ \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=\rknn set KEV_DAEMON=\examples\rknn3_session_test_demo\daemon.exe python \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 \host\e2e_check.py ``` 期望 **23/26 = 0.885**(三题型混合抽样)。数字明显偏低时先看是不是抽样把题型抽偏了, 再用 KEV_DEV 指到正确路径。 --- ## 5. 接口 `POST /v1/systemone` ```json { "state": <任意 JSON:字符串 / 对象 / 数组,会按 YAML 风格渲染进 prompt>, "questions": { "": { "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` 前把 `\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**(`` 一次 + 每个 `` 一次)。图的输出固定 `[1,1,248320]`, 只保留最后一个位置;公开 API 没有 `num_logits_to_keep`,`clear_kvcache` 也没有 truncate。 这是硬下限,不是实现选择。 - 每次调用有约 **50 ms 固定开销**,与序列长度无关。延迟看**调用次数**,不是 token 数。 - 服务对整次决策加**全局锁**:并发是安全的,但会排队。`K+1` 次 prefill 共用一份 KV cache, 不加锁会串。 - 量化格式被工具链锁死为 `w4a16 + normal + group32`,做不了更高精度的对照版本。