Cecilia_srv

Cecilia_srv 是面向 Rockchip RK3588/RK3588S 的 Ling-3.0-tiny 专用 C++ 推理后端。它使用四个 Cortex-A76 大核和 RKNPU，提供 OpenAI Chat Completions 兼容的文本接口，并提供缓存、分词、取消、暂停和流控等底层接口。

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

特性

• Ling-3.0-tiny 的 RK3588 专用推理路径，支持 int8-v1 和 bf16-v1 KV/attention 配方。
• OpenAI 风格 POST /v1/chat/completions，支持 JSON、SSE、Think/No-think、采样参数和 usage。
• 精确前缀缓存、生成状态复用、会话快照、暂停/继续、取消和 ACK 流控。
• INT8 支持 4K、8K、16K、32K、64K、128K 和 256K；128K 为上游原生窗口，256K 使用官方 YaRN ×2，长窗口仍属实验功能。
• 最终模型为自包含 .l3r 文件，不依赖 Python、PyTorch、外部 tokenizer 或父工作区。

目录

路径	内容
service/	HTTP 服务、配置和启动参数
core/	Ling3 解码器、分词、采样和 KV/状态管理
backend/	RKNPU 算子与后端实现
vendor/rknn/	RKNN 头文件和运行库
models/	最终模型、模型卡和元数据
config/	默认相对路径配置
tests/	机制测试、HTTP smoke/benchmark 和长上下文脚本
converter/	从上游 safetensors 进行 W4A8/W8A8 转换、校准、打包和精度对照
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 频率。

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

默认监听 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 记录

历史板端 benchmark 使用 RK3588、四个 A76（2.304/2.352GHz）、RKNPU 1GHz、DMC 2.4GHz。下面是旧 Decoder 在统一预留 64K、预热后、无前缀命中、greedy/no-think、每项生成 64 tokens 的完整曲线；这些数据不等同于 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/ 为本地测试产物，不应提交到源码仓库。长上下文脚本会启动独立服务，测试结束后应确认服务退出并清理临时 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，以及可选的 Rockchip RKNN Toolkit2。服务运行和普通引擎编译不依赖这些 Python 工具。

来源与许可证

代码和推理后端的许可证见 NOTICES.md 和 licenses/。仓库包含 AGPL-3.0-only 的 NPU 后端，整体程序不能表述为仅 Apache-2.0。转换模型资产按 CC BY-NC 4.0 发布，来源模型为 inclusionAI/Ling-3.0-tiny；使用和再分发必须同时遵守上游条款。完整模型说明见 models/MODEL-CARD.md。