Ling-3.0-tiny-RKNN

这是面向 RK3588/RK3588S 的 Ling-3.0-tiny 专用推理引擎和 W4A8/W8A8 转换模型。 本仓库同时提供 C++ 源码、转换工具、校准数据、测试报告和可选的 .l3r 部署模型。

Ling-3.0-rknn 是在 RK3588/RK3588S 上的专用 C++ 推理工程。

引擎使用 A76 CPU 和三核 RKNPU，提供终端对话与 OpenAI 兼容的 Chat Completions 接口。

支持 KV cache 命中；非连续缓存命中仍属于实验功能。

端侧知识库方案另见 mindnano-ling3-compass，该项目仍在实验阶段。

推理不依赖 RKLLM、llama.cpp 或 Python 服务。模型为纯文本 MoE，约 7.9B 总参数、每 token 约 1.3B 激活参数，当前未启用 MTP。

在16K以内上下文在可用范畴内，32K~256K均为测试，目前由于是专用推理引擎所以速度会随着上下文的增大而降低。

如果您有这方面的经验，或者可以优化这些请与我联系，非常感谢。

项目简介

本项目把 Ling-3.0-tiny 转换为 RK3588/RK3588S 可运行的专用 C++ 推理程序。模型是纯文本 MoE；权重采用 W4A8/W8A8 混合量化，推理由 A76 CPU 与 RKNPU 协同完成。程序提供终端模式和 OpenAI 风格的 Chat Completions HTTP 接口。公开源码使用设备上从 Rockchip 官方仓库安装的 RKNPU2 runtime，不需要 Python、RKLLM 或 llama.cpp 才能运行。

这是面向单板验证和端侧优化的工程。当前默认路径是单请求、无鉴权、无 TLS；部分 NPU MLA、FP8/INT8 KV 和非连续缓存仍属于实验功能。性能、内存和质量会随 RKNPU 驱动、频率、散热、后台服务及上下文长度变化。

目录与文件

路径	作用
src/、include/	canonical public C++ decoder, MoE, MLA/KDA, KV manager, service and RKNN backend
engine/source/	historical experimental snapshot; it is not included in this public repository and must not be mixed with the root build
CMakeLists.txt	根构建入口
tools/	量化、打包、部署和 benchmark 脚本
tests/	单元测试、模型测试和 API 测试
models/local-final/v6-board-test/	v6 发布包：最终模型、板端验证的便携二进制、manifest、许可声明和校验文件
calibration/	权重/激活量化使用的校准输入，不是运行时必需文件
docs/	文档索引：性能、KV 与数值误差报告；measurements/ 保留结果摘要、曲线和校验信息
deployment/notices/	第三方许可、来源链接和模型许可摘要

原始 BF16 模型不随本工作区保存。转换前请从上游仓库下载指定 revision；RKNN SDK/runtime 请从 Rockchip 官方仓库获取。发布模型时应同时提供 MODEL.json、SHA256SUMS.PUBLIC 和许可说明。

engine/source/ 是历史实验快照，不是第二个稳定入口；它包含板端探针和维护脚本，不能与根目录 src/ 混合编译，因此本公开仓库不包含该目录。部分历史性能报告引用当时使用的实验脚本；公开构建和测试入口以根目录 CMakeLists.txt、tools/ 和 tests/ 为准。

当前功能与限制

已实现的主要功能：

• 终端对话和 OpenAI 风格 POST /v1/chat/completions；
• 流式输出、thinking 开关、请求取消、暂停/恢复和流控；
• session_id 会话缓存、完整前缀命中和已生成状态复用；恢复 checkpoint 时可保留未覆盖的 NPU KV tile；
• --mla-backend auto|cpu|npu、性能指标日志和设备检查；
• --kv-cache bf16|fp16|fp8|int8。BF16 是默认且验证最充分的格式；FP8/INT8 只改变 MLA K/V 缓存，仍需按场景验证；
• 可选的 NPU MLA 预填充/解码路径和混合 W4A8/W8A8 权重。

当前限制：一次只执行一个推理请求，忙时可能返回 429；接口没有用户鉴权和 TLS；KV 缓存是进程内资源，不是跨重启的持久聊天记录；128K/256K 只提供容量选项，尚未完成完整板端质量和性能认证；MTP 未启用。

板端性能

下表来自 NanoPi M6（RK3588、16GB）2026-09-22 实测。CPU、NPU、DMC 测试期间固定最高频率；模型为 ling3-tiny-w4.l3r，BF16 KV，32K 初始化，关闭 thinking，temperature=0，每次冷启动会话输入后生成 64 tokens，未命中 KV 缓存。TTFT 不包括服务启动时间。

输入/输出	TTFT	Prefill tok/s	解码计算 tok/s	峰值 RSS
128 / 64	753 ms	170.69	19.98	7197 MiB
512 / 64	2.759 s	185.75	18.26	7230 MiB
1024 / 64	5.691 s	180.03	16.86	7258 MiB
2048 / 64	12.754 s	160.64	13.85	7322 MiB
4096 / 64	29.043 s	141.06	11.21	7429 MiB
8192 / 64	76.447 s	107.17	8.37	7661 MiB
16384 / 64	226.045 s	72.49	6.06	8162 MiB

TTFT 随输入长度增加，解码速度也会因每个新 token 需要访问更长的历史 KV 而下降；因此 128/64 的结果不能代表长上下文表现。完整原始结果和测试环境见 BOARD_BENCHMARK_AND_INT4_20260922.md。频率、散热和后台负载改变时应重新测量。

量化与数值损失

当前发布模型不是全 W4：部分线性层和专家使用 W4A8，其他指定投影使用 W8A8。默认 KV 为 BF16，KDA 状态保留 FP32。量化存在损失，以下是固定 teacher-forcing 序列、4,322 个预测位置、完整 157,184 词表，以 BF16 为参考的 logits 分布指标：

路径	Logits MAE	RMSE	最大绝对差	平均 TV	平均 KL	Top1 一致率
官方 INT4（桌面重建）	0.281598	0.371417	8.390625	5.7605%	0.026054	92.6886%
板端 W4A8/W8A8 + NPU MLA	0.421164	0.549502	12.022694	8.9992%	0.061127	89.5187%

官方 INT4 一行是 group32 INT4 权重在桌面 CUDA BF16 参考实现中的重建计算，不是 RK3588 原生 INT4 速度测试。板端当前 MAE 约为官方 INT4 的 1.50 倍，RMSE 约 1.48 倍，Top1 一致率低 3.1699 个百分点。上述指标衡量 logits/概率分布保真，不等于问答正确率；完整口径见 INT4_BOARD_ACCURACY_20260922.md。

FP8 和 INT8 KV 选项仍是实验实现：它们可以降低缓存容量或改变 MLA 的 NPU 计算路径，但当前样本不足以证明长期生成质量优于默认 BF16。需要复现实验时，应记录 KV 格式、上下文长度、频率和 metrics.jsonl，不要只比较单条回复。

模型转换

转换前需要自行获取原始模型。上游仓库为 inclusionAI/Ling-3.0-tiny，本项目量化脚本固定的来源 revision 为 e3a47d5b986e7141b6efd62597d598ebb392060d。推荐使用 Hugging Face CLI 下载完整 BF16 权重、配置和 tokenizer：

hf download inclusionAI/Ling-3.0-tiny \
  --revision e3a47d5b986e7141b6efd62597d598ebb392060d \
  --local-dir ./work/Ling-3.0-tiny

转换需要该目录包含 model.safetensors.index.json、全部 safetensors 分片、config.json 和 tokenizer，还需要 Python、PyTorch、safetensors 以及对应的 RKNN 工具链。校准输入位于 calibration/dataset/calibration_v1.json；可选的激活校准 scale 由 --calibration-scales 提供。

示例流程如下，路径请替换为实际目录：

# 1. 从原始 BF16 模型生成 RKNN 资产和 manifest
python3 tools/quantize_model.py \
  --source ./work/Ling-3.0-tiny \
  --output build/ling3-assets \
  --max-context 32768 \
  --calibration-scales ./work/calibration-scales.safetensors

# 2. 将 manifest 和资产打包为运行时模型
python3 tools/pack_model.py \
  build/ling3-assets/manifest.json \
  build/ling3-tiny-w4.l3r

quantize_model.py 的默认布局对应本项目运行时的混合 W4A8/W8A8 方案；改变层范围、校准 scale 或上下文上限都应重新做数值和板端回归。完整部署包还需要把 .l3r、二进制、MANIFEST.json、MODEL.json 和校验文件放入独立目录；不要把中间 assets/ 当作板端模型。

编译与部署包

在 ARM64 构建机上安装 C++20 编译器、CMake、ICU 开发文件，以及 Rockchip 官方 rknn-toolkit2 和 rknpu2。RKNN_ROOT 应指向本地下载的 RKNPU2 目录，该目录需要包含 include/rknn_api.h 和目标平台的 librknnrt：

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DLING3_WITH_RKNN=ON \
  -DRKNN_ROOT=./vendor/rknpu2
cmake --build build -j4 --target mindnano-infer ling3-rknn

RKNN 头文件和运行库来自 Rockchip 官方仓库；RKNN_ROOT 既可以指向整理为 include/ 与 lib/ 的 SDK 目录，也可以直接指向官方 rknpu2 checkout，CMake 会搜索其 runtime/Linux/librknn_api/include 和 runtime/Linux/librknn_api/aarch64。构建时使用本地 SDK，便携打包时可按其许可随包转发匹配版本的 runtime。请按照 Rockchip 仓库中的许可、版本和硬件兼容性要求使用对应文件。

不带 RKNN SDK 时可以用 -DLING3_WITH_RKNN=OFF 构建主机检查和部分单元测试，但该二进制不能在 RK3588 上执行真实 NPU 推理。使用 tools/build_portable.py 可把引擎及其用户态依赖封装进便携启动器；模型文件仍单独放在发布目录：

python3 tools/build_portable.py \
  --engine build/mindnano-infer \
  --output release/mindnano-infer \
  --notices deployment/notices

# 将转换后的模型复制为 release/ling3-tiny-w4.l3r，
# 再生成 MANIFEST、MODEL.json、SHA256SUMS 等发布元数据。
python3 tools/finalize_release.py \
  --directory release \
  --model-source build/ling3-tiny-w4.l3r

build_portable.py 默认会把匹配版本的 librknnrt.so 和其他动态依赖写入启动器，并同时嵌入 deployment/notices/ 中的声明。若目标环境必须使用设备已有 runtime，可使用 --without-rknn-runtime；公开转发时仍须遵守 Rockchip rknpu2 仓库的许可、版本和硬件兼容性要求。

finalize_release.py 还会读取发布用 README 模板；如果源码包中没有该模板，需要先补齐模板或手动生成 MODEL.json、SHA256SUMS，不要把失败的中间目录当作发布包。

公开源码构建使用从 Rockchip 官方仓库获取的 RKNN 用户态库；便携启动器可将匹配版本的 librknnrt.so 一并分发。运行时仍要求 64 位 RK3588/RK3588S Linux 和可访问的 RKNPU 驱动（已按 0.9.8 版本验证）。公开发布前必须检查 MANIFEST.json、SHA256SUMS 和所有第三方 notices。 当前目录中的 v6 二进制已按当前源码和 NOTICE 在 ARM64 RK3588 板端重新构建，并通过 --check；重新构建任何变体后都必须同步生成新的 MANIFEST.json 和校验文件。

使用

进入部署包目录后先做设备检查，再选择上下文长度：

cd models/local-final/v6-board-test
sha256sum --ignore-missing -c SHA256SUMS
./mindnano-infer --check
./mindnano-infer --context 8K

支持的上下文选项为 4K、8K、16K、32K、64K、128K 和 256K。程序会输出内存估算和不足提示，但当前是告警模式，不会替用户做内存保证；256K 超出原生 128K 位置范围，属于未经验证的外推。--list-contexts 可查看估算值。

启动 HTTP 服务（仅在可信局域网使用）：

./mindnano-infer --context 8K --host 0.0.0.0 --port 9092 \
  --no-console --log metrics.jsonl

发送 OpenAI 风格请求：

curl --noproxy '*' -N http://127.0.0.1:9092/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"mindnano-ling3-tiny","session_id":"demo","messages":[{"role":"user","content":"你好"}],"stream":true,"max_tokens":128,"enable_thinking":false}'

常用接口为 GET /health、GET /v1/models、POST /v1/chat/completions 和 POST /v1/cancel。响应中的 request_id 可用于取消请求，流式事件中的 mindnano_metrics 包含 TTFT、解码速度和缓存状态。终端模式下 /reset 清空当前会话，/quit 退出；模型加载和预热只在进程启动时进行。

可选运行参数：

--mla-backend auto|cpu|npu
--kv-cache bf16|fp16|fp8|int8
--session-cache-mib N
--prefix-checkpoints N

--kv-cache bf16 是默认推荐值；fp8 和 int8 需要重新测量精度和性能。session_id 只用于进程内缓存复用，客户端仍应在每轮发送完整 messages；缓存不等于持久化聊天记录。服务未提供鉴权、TLS 或稳定并发保证。

性能测试

部署包内的 benchmark.py 会启动本机服务、预热并测量短请求；端口冲突时使用其他端口：

python3 benchmark.py --port 19092 --output board-test-result.json

测试指标中，TTFT 是首 token 前的时间，Prefill tok/s 是输入处理速度，解码计算 tok/s 是模型生成阶段速度，RSS 是进程峰值常驻内存。长上下文专项和 KV 容量测试见 KV_CACHE_BENCHMARK_20260922.md；NPU/CPU 占用分析见 KV_UTILIZATION_16K_20260922.md。数值损失复现入口和数据说明见 INT4_BOARD_ACCURACY_20260922.md。

Hugging Face 发布边界

当前工作区的模型、元数据和已通过板端检查的便携二进制保存在 models/local-final/v6-board-test/；发布独立 Hugging Face 模型仓库时，可将其中的 ling3-tiny-w4.l3r、MODEL.json、SHA256SUMS.PUBLIC 和部署用 README 平铺到模型仓库根目录。SHA256SUMS 是包含当前二进制的部署包清单；如果公开上传 mindnano-infer，应同时保留匹配的 MANIFEST.json 和全部第三方 notices。

来源与许可

本仓库中的 C++ 源码、转换脚本、测试工具和文档（第三方组件除外）采用 Apache-2.0 许可，完整资产边界见 LICENSES.md。 本项目发布的转换/打包模型资产 ling3-tiny-w4.l3r 标注为 CC BY-NC 4.0，仅限非商业、学术研究和教育用途；该标注不改变上游基模型的权利或许可边界。商业使用或商业集成请先取得相应授权。 文件顶部的 Hugging Face 自定义许可元数据以转换模型资产为主，许可链接指向模型 CC BY-NC 4.0；本仓库源码仍按根目录 LICENSE 使用 Apache-2.0，完整资产边界见 LICENSES.md。

转换模型的基模型为 inclusionAI/Ling-3.0-tiny，来源 revision 为 e3a47d5b986e7141b6efd62597d598ebb392060d。原始 BF16 权重和完整上游模型卡不随本仓库分发；使用者仍须遵守上游模型条款。Rockchip RKNN SDK/runtime 是独立的第三方组件，来源和许可链接见 deployment/notices/BUILD-AND-LICENSES.md。