s2.cpp 源码分析
s2.cpp 是 Fish Audio S2 Pro Dual-AR 文本转语音模型的纯 C++17 推理引擎，构建于 ggml 之上，运行时完全不需要 Python，支持 CPU、Vulkan、CUDA、Metal 四种后端。它用 Slow-AR（36 层 4.13B Transformer，带持久 KV cache）逐帧预测语义 token，用 Fast-AR（4 层小 Transformer，无 KV cache）逐码本解码 10 个声学码，再经神经音频 codec（RVQ，10 × 4096，44.1 kHz）还原为波形，并提供 CLI、HTTP 服务和 C ABI 三种使用形态。
本项目从源码出发，逐模块拆解 s2.cpp 的核心机制。
文档
| # | 文档 | 内容 |
|---|---|---|
| 1 | 项目背景与概述 | s2.cpp 是什么、解决什么缺口、三种使用形态、模型与许可证 |
| 2 | 整体架构与数据流 | 对象关系、关键维度、一帧数据的完整旅程、图缓存策略 |
| 3 | 代码结构与构建系统 | 仓库布局、CMake 编排、ggml 子模块与两个本地补丁 |
| 4 | 模型加载与 GGUF | 元数据→hparams、张量绑定、权重放置、多 buffer 切分 |
| 5 | Slow-AR 计算图 | eval_cached、GQA、RoPE、KV cache、tied logits、分块 prefill |
| 6 | Fast-AR 与生成主循环 | fast_decode、sem_mask、generate 双 AR 循环、RAS、帧回调 |
| 7 | 采样器 | top-k/top-p/温度的实现与边界保护 |
| 8 | 音频编解码器 | 卷积 codec、layer-scale Transformer、余弦 VQ、缓存解码图 |
| 9 | 语音克隆与声音档案 | 参考音频编码、.s2voice 格式、对话模板构造 |
| 10 | 流水线与流式合成 | stride/holdback/context、窗口解码、codec 自动选型 |
| 11 | HTTP 服务 | /generate、503 单并发、分块传输、启动缓冲、分句合成 |
| 12 | 导出库 API | C ABI、Alloc/Release 三件套、回调式流式、多语言示例 |
快速开始
git clone --recurse-submodules https://github.com/chen3feng/s2cpp-analysis.git
cd s2cpp-analysis
源码通过 git submodule 引入，固定在文档生成时的 commit。在 VS Code 中打开，Cmd/Ctrl + 点击 代码引用即可跳转到对应行。
特点
- 精确行号：每个代码引用形如
[s2_model.cpp:860](../s2cpp/src/s2_model.cpp#L860)，可点击直接跳转 - 可验证：所有行号基于 submodule 中的固定 commit，不会溯源失效
- 架构图：ASCII 流程图和调用链，无需外部工具即可阅读
源码
源码分析基于 s2.cpp 项目，版本锁定在 commit 2c33261938da1a41d713768b1b391b4d368d7d2c。
License
文档：MIT。被分析项目：Fish Audio Research License（权重商业使用需 Fish Audio 授权）。