README.md

---
license: other
license_name: apache-2.0-source-cc-by-nc-4.0-model
license_link: https://creativecommons.org/licenses/by-nc/4.0/
base_model: inclusionAI/Ling-3.0-tiny
pipeline_tag: text-generation
library_name: ling3rknn
tags:
- rk3588
- rknn
- edge-inference
- custom-format
language:
- zh
---

# 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](https://huggingface.co/Sariel00/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/` | [文档索引](docs/README.md)：性能、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 未启用。

MTP 仅作为实验保留，编译开关为 `LING3_EXPERIMENTAL_MTP`，默认 `OFF`。默认构建不包含 MTP 前向实现、实验 API 和 `mtp-benchmark` 命令，不初始化 MTP 权重或 KV。即使显式编译为 `ON`，终端对话和 OpenAI API 也不自动启用 MTP；只有实验探针调用 `EnableMtp()` 后才初始化。实验模型不加入正常部署流程，启用方法见 [MTP 实验说明](docs/MTP_LATEST_20261002.md)。

## 板端性能

下表来自 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](docs/BOARD_BENCHMARK_AND_INT4_20260922.md)。频率、散热和后台负载改变时应重新测量。

2026-10-02 保留最新混合模型＋MTP 的[实验驻留前向测试](docs/MTP_LATEST_20261002.md)：统一 32K 初始化，主模型约 18.69 token/s；MTP 每步追加约 10.54 ms，驻留 RSS 增加约 497 MiB。四条不同序列的下一 token Top1 命中为 17/252，尚未证明投机加速。这些 MTP 指标只适用于显式启用的实验探针，不是默认引擎的开销。实验模型位于 `models/local-experimental/mtp/`，正式 v6 模型、便携发布二进制和默认服务未替换。

## 量化与数值损失

当前发布模型不是全 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](docs/INT4_BOARD_ACCURACY_20260922.md)。

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

## 模型转换

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

```bash
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` 提供。

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

```bash
# 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](https://github.com/airockchip/rknn-toolkit2) 和 [rknpu2](https://github.com/airockchip/rknpu2)。`RKNN_ROOT` 应指向本地下载的 RKNPU2 目录，该目录需要包含 `include/rknn_api.h` 和目标平台的 `librknnrt`：

```bash
cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DLING3_WITH_RKNN=ON \
  -DLING3_EXPERIMENTAL_MTP=OFF \
  -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` 可把引擎及其用户态依赖封装进便携启动器；模型文件仍单独放在发布目录：

```bash
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](https://github.com/airockchip/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` 和校验文件。

## 使用

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

```bash
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 服务（仅在可信局域网使用）：

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

发送 OpenAI 风格请求：

```bash
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` 退出；模型加载和预热只在进程启动时进行。

可选运行参数：

```text
--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` 会启动本机服务、预热并测量短请求；端口冲突时使用其他端口：

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

测试指标中，TTFT 是首 token 前的时间，Prefill tok/s 是输入处理速度，解码计算 tok/s 是模型生成阶段速度，RSS 是进程峰值常驻内存。长上下文专项和 KV 容量测试见 [KV_CACHE_BENCHMARK_20260922.md](docs/KV_CACHE_BENCHMARK_20260922.md)；NPU/CPU 占用分析见 [KV_UTILIZATION_16K_20260922.md](docs/KV_UTILIZATION_16K_20260922.md)。数值损失复现入口和数据说明见 [INT4_BOARD_ACCURACY_20260922.md](docs/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](LICENSE) 许可，完整资产边界见 [LICENSES.md](LICENSES.md)。
本项目发布的转换/打包模型资产 `ling3-tiny-w4.l3r` 标注为 [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0)，仅限非商业、学术研究和教育用途；该标注不改变上游基模型的权利或许可边界。商业使用或商业集成请先取得相应授权。
文件顶部的 Hugging Face 自定义许可元数据以转换模型资产为主，许可链接指向模型 CC BY-NC 4.0；本仓库源码仍按根目录 [LICENSE](LICENSE) 使用 Apache-2.0，完整资产边界见 [LICENSES.md](LICENSES.md)。

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