Instructions to use jj90/Kev-0.8B-RKNN3-RK1828 with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- llama.cpp
How to use jj90/Kev-0.8B-RKNN3-RK1828 with llama.cpp:
Install (macOS, Linux)
curl -LsSf https://llama.app/install.sh | sh # Start a local OpenAI-compatible server with a web UI: llama serve -hf jj90/Kev-0.8B-RKNN3-RK1828 # Run inference directly in the terminal: llama cli -hf jj90/Kev-0.8B-RKNN3-RK1828
Install from WinGet (Windows)
winget install llama.cpp # Start a local OpenAI-compatible server with a web UI: llama serve -hf jj90/Kev-0.8B-RKNN3-RK1828 # Run inference directly in the terminal: llama cli -hf jj90/Kev-0.8B-RKNN3-RK1828
Build from source code
git clone https://github.com/ggml-org/llama.cpp.git cd llama.cpp cmake -B build cmake --build build -j --target llama-app # Start a local OpenAI-compatible server with a web UI: ./build/bin/llama serve -hf jj90/Kev-0.8B-RKNN3-RK1828 # Run inference directly in the terminal: ./build/bin/llama cli -hf jj90/Kev-0.8B-RKNN3-RK1828
Use Docker
docker model run hf.co/jj90/Kev-0.8B-RKNN3-RK1828
- Llama new
- LM Studio
- Jan
- Ollama
How to use jj90/Kev-0.8B-RKNN3-RK1828 with Ollama:
ollama run hf.co/jj90/Kev-0.8B-RKNN3-RK1828
- Unsloth Desktop
- Pi
How to use jj90/Kev-0.8B-RKNN3-RK1828 with Pi:
Start the llama.cpp server
# Install llama.cpp: brew install llama.cpp # Start a local OpenAI-compatible server: llama serve -hf jj90/Kev-0.8B-RKNN3-RK1828
Configure the model in Pi
# Install Pi: npm install -g @earendil-works/pi-coding-agent # Add to ~/.pi/agent/models.json: { "providers": { "llama-cpp": { "baseUrl": "http://localhost:9931/v1", "api": "openai-completions", "apiKey": "none", "models": [ { "id": "jj90/Kev-0.8B-RKNN3-RK1828" } ] } } }Run Pi
# Start Pi in your project directory: pi
- Docker Model Runner
How to use jj90/Kev-0.8B-RKNN3-RK1828 with Docker Model Runner:
docker model run hf.co/jj90/Kev-0.8B-RKNN3-RK1828
- Lemonade
How to use jj90/Kev-0.8B-RKNN3-RK1828 with Lemonade:
Pull the model
# Download Lemonade from https://lemonade-server.ai/ lemonade pull jj90/Kev-0.8B-RKNN3-RK1828
Run and chat with the model
lemonade run user.Kev-0.8B-RKNN3-RK1828-{{QUANT_TAG}}List all available models
lemonade list
- Hermes Agent
How to use jj90/Kev-0.8B-RKNN3-RK1828 with Hermes Agent:
Start the llama.cpp server
# Install llama.cpp: brew install llama.cpp # Start a local OpenAI-compatible server: llama serve -hf jj90/Kev-0.8B-RKNN3-RK1828
Configure Hermes
# Install Hermes: curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash hermes setup # Point Hermes at the local server: hermes config set model.provider custom hermes config set model.base_url http://127.0.0.1:9931/v1 hermes config set model.default jj90/Kev-0.8B-RKNN3-RK1828
Run Hermes
hermes
- Atomic Chat
- OpenClaw
How to use jj90/Kev-0.8B-RKNN3-RK1828 with OpenClaw:
Start the llama.cpp server
# Install llama.cpp: brew install llama.cpp # Start a local OpenAI-compatible server: llama serve -hf jj90/Kev-0.8B-RKNN3-RK1828
Configure OpenClaw
# Install OpenClaw: npm install -g openclaw@latest # Register the local server and set it as the default model: openclaw onboard --non-interactive --mode local \ --auth-choice custom-api-key \ --custom-base-url http://127.0.0.1:9931/v1 \ --custom-model-id "jj90/Kev-0.8B-RKNN3-RK1828" \ --custom-provider-id llama-cpp \ --custom-compatibility openai \ --custom-text-input \ --accept-risk \ --skip-health
Run OpenClaw
openclaw agent --local --agent main --message "Hello from Hugging Face"
Download docs/DEPLOY.md from jj90/Kev-0.8B-RKNN3-RK1828: direct link, hf CLI and curl.
- Browser
- Download file 7.83 kB
-
https://huggingface.co/jj90/Kev-0.8B-RKNN3-RK1828/resolve/main/docs/DEPLOY.md
- Command line
-
hf download hf://jj90/Kev-0.8B-RKNN3-RK1828/docs/DEPLOY.md
-
curl -L -o DEPLOY.md https://huggingface.co/jj90/Kev-0.8B-RKNN3-RK1828/resolve/main/docs/DEPLOY.md
部署指南(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.txtexamples/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
三个必注意的点:
C:\cygwin64\bin必须在 PATH 最前面,否则cc1plus找不到cygwin1.dll,报一个和编译毫无关系的错。- 链接时直接给
.dll/.a的完整路径,Cygwin 的 ld 接受这种写法,不需要-L/-l。 - 编译产物
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,做不了更高精度的对照版本。