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 及其派生权重的上游条款。