模型与参考音色

1. 职责与边界

本模块负责准备 Worker 可复用的模型组件和参考音色条件，包括权重选择、缓存路径、可选组件与参考特征预计算。逐块调用顺序、上下文裁剪和后处理由流式转换流水线维护。

主要源码：models.py 中的 ModelFactory，以及 realtime_vc.py 的初始化与 _cal_reference()。两部分当前通过 RealtimeVoiceConversion 组合，不是独立的模型服务。

2. 输入与输出

项目	内容
加载输入	ModelConfig、音高开关、Worker 设备、缓存环境变量及模型路径
参考输入	reference_wav_path、max_prompt_length、模型采样率与已加载模型
模型输出	DiT/CFM、内容编码器、声码器、CAMPPlus、Mel 变换、VAD 和可选 F0 / 检索组件
参考输出	prompt_condition、prompt_mel、prompt_style 和可选参考音高中位数

模型工厂返回组件字典，转换实例持有字典与参考条件，在 Worker 内复用；连接自己的音频窗口和推理状态仍归 Session 所有。

3. 关键流程

3.1 权重与缓存

ModelFactory 先解析 Hugging Face 和 ModelScope 缓存路径，再加载模型。缓存相对路径按仓库根目录解析，环境变量入口见 .env.example。

当 dit_checkpoint_path 与 dit_config_path 均提供时加载自定义模型，否则使用 defalut_original_model 的映射。后者保留源码拼写；tiny、small、base 关联不同模型配置，不能仅修改名称就推断所有组件兼容。

默认权重通过 Hugging Face 获取；VAD 使用 FunASR / ModelScope，加载异常时尝试配置缓存目录中的本地模型路径。首次下载属于启动准备，应与推理耗时分开。

3.2 模型组件与可选分支

组件	在链路中的用途	加载条件
DiT/CFM 与长度调节器	条件长度对齐、目标特征生成	由所选模型配置决定
内容编码器	源音频和参考音频的内容特征	随模型配置加载对应编码器
声码器	目标特征转音频	随模型配置加载对应声码器
CAMPPlus 与 Mel 变换	参考风格特征、参考 Mel 与相关参数	初始化时准备
VAD	逐块语音检测	初始化时准备
RMVPE F0 提取器	源与参考音高处理	realtime_vc.is_f0 开启时加载
FAISS 索引及重建向量	语义特征近邻检索	models.is_retrieval 开启时加载

模型工厂为 CFM 安装线性或余弦 t_span_schedule 的推理实现；步数由逐块调用时的 diffusion_steps 决定。

启用检索时必须提供实际存在、与内容特征匹配的索引。prod.yaml 中的示例索引路径不表示仓库附带该资源。

3.3 参考音色预计算

每个 Worker 创建转换实例时读取参考音频，重采样到模型输出采样率，并按 max_prompt_length 截取。随后计算：

1. 将参考音频转为 16 kHz，提取内容特征；开启音高时另提取 F0 和有效音高的对数中位数。
2. 从 16 kHz 音频计算 fbank，并用 CAMPPlus 得到风格特征。
3. 从模型采样率下的参考音频计算 Mel。
4. 通过长度调节器将参考内容特征对齐到参考 Mel 长度，形成参考条件。

这些条件在 Worker 内固定复用。当前协议没有逐会话上传或替换参考音频的操作，修改参考路径或文件后需重启相应服务。多个固定音色可通过不同配置和端口的实例提供，运行文件隔离见数据记录与可观测性。

4. 约束与关联文档

服务初始化断言 SAMPLERATE_OUT 与模型采样率相等。更换模型时还需核对声码器、内容编码器、音高条件和窗口长度；默认 tiny 路径不代表上游所有模型能力都已通过本服务验证。协议输出采样率是后处理之后的转换，见音频约定。

当前 torch.compile 可选路径编译内容编码器和 DiT 推理函数，部分编码器内部使用半精度。这不等于统一且已验证的全链路 fp16 开关。调整模型、步数、检索和音高时，按评测指南记录有效配置、设备、输入与参考条件。

底层实现来自仓库固定提交的 Seed-VC 子模块。本仓库 LICENSE 说明项目代码许可，模型权重和音频素材的使用条款仍需分别依据其来源。