配置与部署
1. 运行入口与配置来源
从仓库根目录运行，先按快速开始安装依赖与初始化子模块。
配置优先级为 CLI --config / -c → 环境变量 CONFIG_PATH → Python 配置类默认值。.env.example 指定 configs/prod.yaml。配置文件读取或解析失败时，当前实现记录日志后回退类默认值；请检查启动日志的加载路径与有效参数。
uv run fast-vc serve -c configs/prod.yaml
uv run fast-vc status -p 8042
uv run fast-vc version类默认值不等同于 prod.yaml，例如音高开关、扩散步数、RMS 比例和参考音频路径存在差异。字段定义见 config.py，示例部署值见 prod.yaml。
2. 常用配置
以下值来自 prod.yaml，不是所有模型的通用推荐值。
| 配置 | 示例值 | 含义 |
|---|---|---|
| app.host / port / workers | 0.0.0.0 / 8042 / 2 | 监听和 Uvicorn 进程数 |
| app.receive_timeout | 120 | 初始化后逐次收包超时，秒 |
| buffer.prefill_time | 375 | 首个推理块预填充的静音时长，毫秒 |
| buffer.opus_frame_duration | 20 | 请求未指定时的 Opus 帧长，毫秒 |
| realtime_vc.device | [cuda:0] | Worker 设备列表 |
| realtime_vc.reference_wav_path | resources/refs/ref-24k.wav | Worker 启动时加载的参考音频 |
| realtime_vc.block_time | 0.5 | 推理块时长，秒 |
| realtime_vc.SAMPLERATE_IN / SAMPLERATE_OUT | 16000 / 22050 | 模型前端与模型后处理的采样率 |
| realtime_vc.extra_time_ce / extra_time_dit | 4.5 / 1.5 | 编码器与 DiT 上文，秒 |
| realtime_vc.sola_buffer_time / extra_time_right | 0.04 / 0.02 | 拼接区和右侧上下文，秒 |
| realtime_vc.is_f0 | false | 自适应音高开关 |
| realtime_vc.diffusion_steps / inference_cfg_rate | 5 / 0.7 | 扩散步数与引导率 |
| realtime_vc.max_prompt_length | 5.0 | 参考音频最大使用时长，秒 |
| realtime_vc.rms_mix_rate / is_sola | 0.9 / true | 音量包络混合与拼接 |
| realtime_vc.save_input / save_output / save_dir | true / true / outputs/ | 音频保存开关与目录 |
| models.is_retrieval / index_rate | false / 1.0 | 语义检索开关与混合比例 |
| models.t_span_schedule | cosine | CFM 时间步安排 |
| models.speech_noise_thres / decibel_thres | 0.8 / -50 | VAD 参数 |
| models.defalut_original_model | tiny | 未提供完整自定义模型路径时的选择 |
models.dit_checkpoint_path 和 models.dit_config_path 需成对提供；models.index_path 在启用检索时必须指向实际存在的匹配索引。仓库不附带 prod.yaml 所示的检索索引。
输出给客户端的采样率用请求中的 sample_rate_out 控制，详见 API，不要为调整网络输出而直接改模型采样率。
3. 环境、模型与参考音色
.env.example 提供 CONFIG_PATH、HF_HUB_CACHE、MODELSCOPE_CACHE。缓存相对路径在模型工厂中按仓库根目录解析；其他音频、输出和日志相对路径通常按进程工作目录解析，统一从仓库根启动可减少歧义。
Python 版本约束见 pyproject.toml，快速开始选用 3.10。默认配置为 NVIDIA CUDA，历史报告记录了 NVIDIA GPU 测试结果，但未保存完整的软件环境。代码包含 CPU 回退选择，但不是已验证的实时 CPU 运行承诺；Windows 原生路径还受 fcntl 等 Unix 依赖限制。
参考音色按服务配置固定，修改文件或配置后重启实例。首次启动会下载模型，请先确认下载完成，再进行请求与性能测试。
4. 多 Worker、多设备与多实例
Worker 按设备列表循环分配，每个进程加载模型。先以小并发测量，再增加 Worker；显存和吞吐需实测。
新增实例可复制配置，修改端口、设备、参考音色、日志和输出目录：
cp configs/prod.yaml configs/voice-b.yaml
# Edit voice-b.yaml: use port 8043 and separate log/output paths.
uv run fast-vc serve -c configs/voice-b.yaml当前连接统计使用同工作目录的公共文件。需要运行文件独立时采用分别克隆的仓库目录，并为实例配置不同端口；不能把不同端口表述为所有数据完全隔离。
5. 服务管理与访问边界
按目标端口停止服务：
uv run fast-vc stop -p 8042不带端口或配置的 stop 会尝试停止 CLI 已记录的所有实例。clean 要求明确指定 --logs 或 --outputs，显示文件后交互确认；当前没有 -y 选项，且清理的是仓库固定目录，并非任意配置中的自定义输出路径。
内置 api_key 校验是占位逻辑，HTTP 会话接口未鉴权。公开访问需由部署层提供认证、TLS 和访问控制；否则使用受控网络或仅监听回环地址。默认配置会保存音频与时间线，应按实际用途设置保存开关与保留策略。
仓库 Dockerfile 仍使用 Poetry，本轮未构建验证；当前指南以 uv 源码启动为准。容器流程的验证与更新需独立处理。