边缘设备命令工作台 — 部署指南

套餐

RK3576 Kev RKLLM

此套餐在 RK3576 test platform 上部署已测试的 Kev RKLLM 路径。engine 导出容量为 8192 tokens，但该设备上的部署 guard 和 metadata 将请求限制为 2048 tokens，因为 8K 配置触发了全局 OOM。运行时、engine、head、tokenizer 和 metadata 均作为固定版本外部产物记录。

两台 RKLLM 设备的 500-token 可复现报告保存在 assets/evidence/context500-20261011/。每台设备包含 120 条 original 和 120 条 reverse fixture case；该 fixture 使用生成上下文，不能作为任意长请求的准确率结论。

1

部署 Kev 工作台

容器选择 DECISION_BACKEND=rkllm 和 MODEL_ID=kev。请准备包含 model.rkllm、kev_head.npz、tokenizer/tokenizer.json 以及固定版本运行时 runtime/librkllmrt.so 的模型目录。只有使用固定版本 RKLLM 1.3.1 头文件构建时，镜像才包含 C helper。

远程设备

填写 SSH 信息。RKLLM 首次准备至少需要 3GB 可用空间（实测新鲜产物峰值约 1.94GB，并保留 1GB 余量）。可选的 MODEL_SERVICES_JSON 可将其他模型系列映射到已有 HTTP 服务；当前容器只在本地加载 Kev。VOICE_SERVICE_URL 仅连接已有兼容语音服务，不会安装 ASR。

部署时需要填写（在 SenseCraft Solution 应用里填）
  • 设备 IP 或主机名*
  • SSH 用户名*
  • SSH 密码*
  • 远程模型配置 JSON（可选）

    将其他模型 ID 映射到已有 HTTP 模型服务；留空使用本地 Kev。

  • 已有本地语音服务地址（可选）
故障排查
现象处理
模型没有就绪检查提供的模型目录是否包含 model.rkllm、kev_head.npz、tokenizer/tokenizer.json 和 runtime/librkllmrt.so，然后重新部署。
健康接口返回了其他 backend 或 model ID检查部署字段，确认本套餐使用 DECISION_BACKEND=rkllm 和 MODEL_ID=kev。
部署完成后

打开 http://<设备 IP>:18768。验证要求 /api/health 返回 model_ready: true、backend: "rkllm" 和 model_id: "kev"。

2

打开 Kev 工作台

健康检查确认 Kev 模型就绪后，提交带候选命令的请求。

RK3576 第二轮验证

第二轮 RK3576 test platform 验证使用相同固定版本镜像，5 个 golden 请求全部 HTTP 200，5/5 选择结果正确。2069 词边界请求编码为 2088 tokens，在进入 NPU 前以 HTTP 422 拒绝。该轮使用镜像内置 helper，没有 external helper、RKNN runtime 或 GOMP mount。原始证据见 assets/evidence/rk3576-release-0.3.1-20261011/second-validation/。

故障排查
现象处理
工作台页面打不开先确认 18768 端口的健康接口已就绪，再打开页面。
请求返回 HTTP 422按套餐限制检查请求大小；文档中的边界请求会在进入 NPU 前被拒绝。