故障排查
1. 启动与依赖
| 现象 | 检查步骤 |
|---|---|
| 找不到 Seed-VC 模块 | 在仓库根执行 git submodule update --init --recursive |
| Opus / 音频库无法加载 | 检查快速开始列出的系统依赖，不只安装 Python 包 |
| 首次启动耗时较长 | 查看模型下载及缓存日志，确认下载完成，首次下载不计入推理性能 |
| CUDA 不可用或显存不足 | 检查驱动与 Torch 环境、device 列表及 Worker 数；每个 Worker 加载自己的模型 |
| 配置似乎未生效 | 显式使用 -c configs/prod.yaml 并核对日志；解析失败可能回退类默认值 |
| 找不到参考音频 / 索引 | 从仓库根启动；参考路径要存在，检索开启前准备匹配索引 |
模型和依赖版本以 pyproject.toml、uv.lock、子模块提交及模型配置为准，不用随意升级全部依赖替代定位。
2. 客户端与输出
快速开始使用简单协议客户端、PCM 输入和协议默认 16000 Hz 输出。该脚本虽然有 OPUS 命令行选项，但首条消息未传递 encoding，直接切到 OPUS 会与服务端默认 PCM 解释不一致；其输出写入也固定为 16000 Hz。不要据此判断服务本身不支持 Opus。
需要 Opus、显式输出采样率或并发时，使用快速开始中的标准客户端 Inputs 调用方式。ws_client.py 默认入口含环境相关输入配置，不能把直接执行默认入口当成通用演示；文档调用显式传入仓库资源，不依赖该配置。
检查客户端输出目录中的 WAV、日志中的错误及接收数据，不只看 Success 字样。当前客户端的完成判断不能替代协议完整性和音质验收。
3. 接口与测量
- 接收输出时按 16-bit 单声道 PCM 解码，采样率使用 sample_rate_out。
- 简单协议没有 ready，等待它会导致客户端挂起。
- 正常结束用对应协议的 end 消息；直接断开不保证处理剩余尾块。
- complete 返回后会话后台保存可能尚未完成，立即读取会话文件可能失败。
- 当前没有 /tools/performance-report 路由，使用离线评测入口。
- 非 16 kHz 输出下，当前服务端时间线的音频时长统计有偏差，见设计限制。
4. 提交问题
向 GitHub Issues 提供版本/提交、模型、有效配置、硬件、音频格式、复现步骤和经处理的日志。音频只附可公开的最小样例，清除凭据、机器路径和业务内容。进一步开发见贡献指南。