Cecilia_srv

Cecilia_srv 是面向 Rockchip RK3588/RK3588S 的 C++ 推理项目。主服务运行 Ling-3.0-tiny,使用四个 Cortex-A76 大核和 RKNPU,提供 OpenAI Chat Completions 兼容的文本接口,以及缓存、分词、取消、暂停和流控接口。仓库另提供 MiniCPM-V 4.7 35B-A3B 的实验性文本运行时,以及专家权重硬盘卸载方案。

Cecilia是一个项目代号,是面向端侧设备的 LLM Agent 软硬协同框架计划,而 Cecilia_srv 在计划中承担推理服务的具体算力后端实现。

特性

  • Ling-3.0-tiny 的 RK3588 专用推理路径,默认使用 int8-v1:W4A8/W8A8 计算、INT8 MLA KV 和单份 INT8 历史缓存;bf16-v1 仅作为数值对照配方。
  • 纯开源 DRM/RKNPU 用户态后端,直接提交 NPU 作业,不需要厂商用户态运行库或 SDK。
  • OpenAI 风格 POST /v1/chat/completions,支持 JSON、SSE、Think/No-think、采样参数和 usage。
  • 精确前缀缓存、生成状态复用、会话快照、暂停/继续、取消和 ACK 流控;单份 INT8 KV 在同一 resident decoder 内支持 prompt/prefix/generated 命中,会话快照与跨 session fork 仍关闭,bf16-v1 保留完整缓存能力。
  • INT8 支持 4K、8K、16K、32K、64K、128K 和 256K;128K 为上游原生窗口,256K 使用官方 YaRN ×2,长窗口仍属实验功能。
  • Ling3 服务使用自包含 .l3r 文件,运行时不依赖 Python、PyTorch、外部 tokenizer 或父工作区。
  • 实验性专家卸载:Ling3 将路由专家保存在 eMMC/NVMe sidecar,通过有限的 NPU 槽位按需加载;主服务默认仍为全专家驻留。
  • 实验性 MiniCPM-V 4.7 35B-A3B 文本支持:提供独立 CPU+开源 NPU 全内存运行时和独立 CPU LES 卸载运行时。未接入主服务 API、视觉输入或投机解码。

支持范围

模型 / 路径 入口 状态
Ling-3.0-tiny,CPU+NPU、专家驻留 run.sh / HTTP 服务 主服务默认路径,单份 INT8 KV
Ling-3.0-tiny,eMMC/NVMe 专家卸载 主服务 --les-slots 64 --les-sidecar … 实验性,单份 INT8 KV;按需读取,预测预读另行测试
MiniCPM-V 4.7 35B-A3B,CPU+NPU、专家驻留 RAM experiments/minicpm47_npu/ 实验性,仅文本、F16 KV,独立命令行运行时
MiniCPM-V 4.7 35B-A3B,CPU LES 专家卸载 experiments/minicpm47_les/ 实验性,仅文本,支持按需读取和预测预读对照

两种 MiniCPM 运行时尚未合并为 CPU+NPU 硬盘卸载方案。MiniCPM 模型名中的 V 不代表本仓库已经支持图像输入;当前也未启用 DSpark 或其他投机解码。构建、参数和限制见实验功能指南。

目录

路径 内容
service/ HTTP 服务、配置和启动参数
core/ Ling3 解码器、分词、采样和 KV/状态管理
backend/ RKNPU 算子与后端实现
models/ 最终模型、模型卡和元数据
config/ 默认相对路径配置
tests/ 机制测试、HTTP smoke/benchmark 和长上下文脚本
converter/ 从上游 safetensors 进行 W4A8/W8A8 转换、校准、打包和精度对照
experiments/ MiniCPM 独立运行时补丁、构建与转换工具、固定提示和精选测量证据
docs/ 基线、设计、LES/INT8 KV 和 MiniCPM 研究记录,入口见 docs/README.md
build_portable.sh、tools/build_portable.py 在 aarch64/RK3588 板端生成自包含便携包
licenses/、NOTICES.md 组件来源和许可证

编译和启动

目标环境为 64 位 Linux RK3588/RK3588S,要求 CMake 3.20+、C++20 编译器、ICU、OpenMP、可用的 RKNPU 驱动和设备权限。服务不会替设备设置 CPU/NPU/DMC 频率。

启动前按模型说明获取实际 Ling3 权重;Git LFS 指针不能用于推理。

bash build.sh -DBUILD_TESTING=ON
ctest --test-dir build --output-on-failure
bash run.sh --check
bash run.sh

构建和运行只使用仓库内的 rk_npu_* DRM 提交层。设备仍需要 Linux RKNPU DRM 内核驱动、/dev/dri/renderD*(或对应的 NPU DRM 节点)及访问权限; 用户态不需要厂商 SDK、闭源运行库或图编译工具。

默认启动使用 int8-v1,并设置 LING3_MLA_KV_DTYPE=int8 与 LING3_INT8_KV_SINGLE=1。这里的“全 INT8”指默认推理和 KV 路径;模型权重仍按 W4A8/W8A8 分层执行,并非所有中间张量都强制为 INT8。

默认监听 http://127.0.0.1:9091/v1,模型 ID 为兼容旧客户端而保留的 cecilia-ling3-tiny;服务产品名为 Cecilia_srv。等待日志出现 service_ready 后再发送请求。

# 局域网访问和上下文配置
bash run.sh --host 0.0.0.0 --context 64K

# 使用 BF16 对照配方
bash run.sh --profile bf16-v1 --context 8K

# 输出实际配置,不加载模型
bash run.sh --print-config

可用总窗口为 4K、8K、16K、32K、64K;当前源码额外提供 INT8 128K/256K。总窗口包含模板、输入和输出,没有额外的固定输入/输出截断。16GB RK3588 上的 256K 测试使用临时 swap 完成一次 262,080-token 输入,结果仅代表基本长上下文运行和三处取证通过,不能代表广泛长文质量或实用性能。

API 示例

curl -N http://127.0.0.1:9091/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"cecilia-ling3-tiny","messages":[{"role":"user","content":"请用中文简要介绍自己。"}],"stream":true,"max_tokens":128,"temperature":0,"enable_thinking":false}'

服务支持 temperature、top_p、top_k、seed、repeat_penalty、stop、max_tokens/max_completion_tokens 和 stream。messages 仅支持 system/user/assistant 字符串,单进程只允许一个活动生成任务;忙时返回 429。当前不支持工具调用、结构化输出、图像/音频、Responses API 或并发生成。

底层接口位于 /engine/v1/,包括:

  • status、capabilities、memory:服务、能力和内存状态;
  • tokenize、detokenize:使用同一聊天模板进行分词;
  • cache/probe、cache/status、cache/clear、cache/fork:查询和管理前缀/会话缓存;
  • generation/status、generation/pause、generation/resume、cancel、flow/ack:生成控制和流控。

Benchmark 记录

实验性硬盘卸载与 MiniCPM

Ling3 卸载将路由专家导出为 native .les sidecar,保留完整模型路由,通过每层 64 个 NPU 槽位减少常驻专家内存。它不卸载 KV,也不裁剪专家。默认专家读取使用 O_DIRECT;文件系统需要支持直接读取。主 .l3r 仍用于模型资产和非路由专家权重。

# 在目标存储上选择尚不存在的输出文件;先按上文完成构建
cmake --build build --target cecilia_srv-les-export
build/bin/cecilia_srv-les-export models/ling3-tiny-w4.l3r /path/on-nvme/ling3-tiny.native.les
build/bin/cecilia_srv-les-export --verify models/ling3-tiny-w4.l3r /path/on-nvme/ling3-tiny.native.les
bash run.sh --profile int8-v1 --context 8K \
  --les-slots 64 --les-io-workers 4 \
  --les-sidecar /path/on-nvme/ling3-tiny.native.les

2026-10-19 的当前开源构建使用单份 INT8 KV、8K 窗口、每层 64 槽,两个输入长度各重复三次。以下解码值为中位数,RSS 约 3.26–3.28 GiB:

存储 / 设备 调频策略 128/64 解码 1024/64 解码
PCIe 3.0 ×4 NVMe / 32 GB RK3588 原 ondemand 策略 14.44 tok/s 15.60 tok/s
eMMC / 16 GB RK3588 原 ondemand 策略 6.29 tok/s 6.56 tok/s
eMMC / 16 GB RK3588 CPU/NPU/DMC performance 8.20 tok/s 8.93 tok/s
PCIe 2.0 ×1 NVMe / 16 GB RK3588 2026-10-18 历史单次,旧构建 10.03 tok/s 10.74 tok/s

PCIe 3.0 ×4 的 TTFT 中位数为 1.24 / 4.51 s,填充为 103.68 / 227.11 tok/s。两块板的 DMC 上限分别为 2.112 / 2.4 GHz;eMMC 原策略下有明显 CPU 降频。旧 PCIe 2.0 ×1 使用不同构建且未记录当时频率,不能把上述差异全部归因于链路。32 GB 板另一次固定高频补测发生整板重启,未纳入正式性能结果;测试后已恢复原调频设置。完整范围、I/O 分解和复现命令见PCIe 3.0 ×4 / eMMC 实测。

历史同设备全驻留参考约 20.3 tok/s、5.19 GiB RSS;历史 LES64 为 3.40–3.41 GiB RSS,见旧版存储对照。这些旧数据不替代当前全驻留性能测试。

MiniCPM 使用单独的模型格式和构建入口,不能使用 Ling3 的 sidecar 或直接传给 run.sh:

MiniCPM 实验 实测解码 运行 RSS 条件与说明
CPU+开源 NPU,全专家驻留 RAM 4.15–4.21 tok/s 17.11 GiB 32 GB 板,128/64,后端单线程;CPU/DMC/NPU 上限 1.8/1.56/0.8 GHz
CPU、eMMC 卸载,按需 64 槽 2.05–2.06 tok/s 约 5 GiB 16 GB 板,512 窗口,Q3_K 专家,两个提示
CPU、NVMe 卸载,64 槽、预读 1 2.91 tok/s 约 5 GiB 同 16 GB 板,PCIe 2.0 ×1,一个提示

这些结果来自不同设备和量化路径,不能作为同配置加速比。全内存 NPU 路径将 Q3_K 专家有损再量化为 W4A8;原频率下 CPU/NPU 都发生过整板重启,根因未定位。全部结果均未使用投机解码,不代表模型质量等价或长期稳定性。详见 MiniCPM NPU 报告、MiniCPM 卸载报告及实验功能指南。

Ling3 历史完整曲线

历史板端 benchmark 使用 RK3588、四个 A76(2.304/2.352GHz)、RKNPU 1GHz、DMC 2.4GHz。下面是旧 Decoder 在统一预留 64K、预热后、无前缀命中、greedy/no-think、每项生成 64 tokens 的完整曲线;这组记录来自移除厂商 SDK 之前的历史版本,不能作为当前纯开源路径的完整性能证明,也不等同于 HTTP 服务的时延承诺。65472/64 的总窗口正好为 65536 tokens。

KV 配方 输入/输出 tokens TTFT (ms) 填充 (tok/s) 解码 (tok/s)
BF16 128/64 788.37 162.41 18.38
INT8 128/64 523.51 244.62 20.75
BF16 1024/64 4547.82 225.18 17.18
INT8 1024/64 4053.11 252.66 19.99
BF16 2048/64 9169.62 223.35 16.33
INT8 2048/64 8245.27 248.39 18.78
BF16 4096/64 19267.55 212.59 15.15
INT8 4096/64 17460.35 234.59 17.87
BF16 8192/64 43311.17 189.14 12.33
INT8 8192/64 39046.09 209.80 15.98
BF16 16384/64 107692.89 152.14 9.99
INT8 16384/64 94136.82 174.05 13.86
BF16 32768/64 295053.14 111.06 6.90
INT8 32768/64 250812.59 130.65 11.05
BF16 65472/64 916708.80 71.42 4.23
INT8 65472/64 760182.12 86.13 7.70

上表是统一的旧 Decoder 曲线;测试细节、量化误差和 HTTP 服务短请求结果分别见 docs/BASELINE.md 和 docs/BENCHMARK.md。INT8 的 logits 对 BF16 有量化误差;仓库不作无损承诺。

128K/256K 极限上下文

配置窗口 BF16 KV 容量(估算) INT8 KV 容量(估算) 实测状态
128K 7.5 GiB 3.75 GiB 仅容量估算,未独立完成完整模型吞吐测试
256K 15 GiB 7.5 GiB 完整输入诊断通过;使用 YaRN ×2 和 32 GiB 临时 swap

256K 实测输入/输出为 262080/25,TTFT 12,279,620.51 ms,填充 21.34 tok/s,解码 1.61 tok/s,峰值 RSS 14,976.53 MiB,swap 峰值 15,204.93 MiB,MLA NPU 调用 12438、CPU fallback 0。该结果只证明极限窗口的基本读取和取证样本通过,换页影响很大,不能作为实用长文性能承诺。详细过程见 docs/LONG_CONTEXT.md。

运行 benchmark:

python3 tests/http_smoke.py --base-url http://127.0.0.1:9091 --with-thinking --output results/http-smoke.json
python3 tests/http_benchmark.py --base-url http://127.0.0.1:9091 --output results/http-benchmark.json

根目录 results/ 为本地测试产物,不应提交到源码仓库。experiments/*/results/ 中的精选摘要、正确性日志和压缩采样用于核验文档结论,随实验源码保留。长上下文脚本会启动独立服务,测试结束后应确认服务退出并清理临时 swap。

便携部署

仓库不附带旧版便携二进制。需要自包含部署包时,在 aarch64/RK3588 构建机上重新编译和打包;生成物会写入 portable/:

bash build.sh
bash build_portable.sh
./portable/cecilia_srv-server --check
./portable/cecilia_srv-server --config config/cecilia_srv.json

模型文件为 models/ling3-tiny-w4.l3r,SHA256: 80f0086247328fe77b2f939df460b4955287b6f75f6aaada85512c56e652f435。

如果需要从原始模型重新生成 .l3r,使用 converter/README.md。该目录包含转换、激活校准、精度对照脚本和校准数据;需要另外安装 PyTorch、safetensors、Transformers 和 NumPy。服务运行和普通引擎编译不依赖这些 Python 工具。

来源与许可证

代码和推理后端的许可证见 NOTICES.md 和 licenses/。仓库包含 AGPL-3.0-only 的 NPU 后端,整体程序不能表述为仅 Apache-2.0。随仓库提供的 Ling3 转换模型资产按 CC BY-NC 4.0 发布,来源模型为 inclusionAI/Ling-3.0-tiny;使用和再分发必须同时遵守上游条款。完整模型说明见 models/MODEL-CARD.md。MiniCPM 实验单独获取上游运行时和模型,来源、固定版本及转换方式见对应实验说明;Ling3 模型许可不代替 MiniCPM 及其派生权重的上游条款。

Downloads last month

-

Downloads are not tracked for this model. How to track
Inference Providers NEW
This model isn't deployed by any Inference Provider. 🙋 Ask for provider support