性能与效果评测
1. 范围与复现条件
性能、音色相似度和音频质量分别测量。本目录统一维护评测方法与报告，历史结果见评测报告索引；本指南整理现有工具和测量限制，没有新增 GPU 测试或音质结论。
每次评测记录：
- 仓库提交、包版本、Seed-VC 子模块提交、模型权重与配置标识。
- GPU、驱动、Torch、操作系统、Worker 数、并发数与部署方式。
- 完整有效配置，尤其扩散步数、块长、预填充、上下文、VAD、音高和检索。
- 源音频与参考音频标识、时长、采样率、编码及可公开的获取方式。
- 客户端发送节奏、输入/输出采样率、计时位置、热身方式、样本量与统计方法。
分别记录首次模型下载、首次请求和热身后的请求，不能将三者混成推理时延。
2. 现有性能工具与指标
标准客户端可通过 Inputs 设置源文件列表、max_workers、worker_delay、real_time 与 save_timeline，见快速开始。它会保存输出并可记录客户端时间线；这不是完整的自动压力测试报告。
TimelineAnalyzer 支持单文件和批量离线分析。以下为当前实现中的指标含义：
| 指标 | 当前计算方式 / 边界 |
|---|---|
| first_token_latency_ms | 首次接收事件时间减首次发送事件时间；不是麦克风到扬声器的全链路时延 |
| end_to_end_latency_ms | 最后接收事件减最后发送事件；是尾部收发差值，不是整个请求总耗时 |
| chunk_latency_stats | 接收累计音频时长减预填充后，与发送累计音频对齐得到时差 |
| real_time_factor | 上述逐块时差除以对应音频时长；不等同于纯模型计算耗时 / 音频时长 |
| 路由 E2E 日志 | 取块、转换和发送的执行段，未计入此前输入累积和之后播放 |
使用实际生成的时间线文件路径替换下例占位符：
uv run python -m fast_vc_service.tools.timeline_analyzer analyze \
--timeline-file outputs/example-001_timeline.json \
--prefill-time 375prefill-time 必须对应实际配置。工具会在时间线所在目录输出分析结果；批量命令为同模块的 batch（对应 Python 函数 batch_analyze）。历史报告当时的完整运行条件并未全部保存，不能仅凭当前工具定义重新解释所有旧数字。
3. 时间线有效性与当前限制
标准客户端开启 save_timeline 后的文件包含 session_id 和 merged_timeline，可供分析。简单客户端当前不提供同等的时间线文件保存入口。
当前服务路由按 16000 Hz 记录输出累计音频时长，因此非 16 kHz 输出的服务端时间线存在偏差。使用标准客户端并设置正确的 samplerate_out 可记录客户端所接收到的音频时长；比较前还应核对预填充、尾块补零和网络计时位置。
VC_SLOW 路径存在秒计时与毫秒阈值比较问题；SLOW 标记不作为单独验收依据。上述限制见数据记录与可观测性。
对于面向实时播放的验收，应另记录采集、发送、首个可播放样本、播放缓冲和丢包/断流情况；不能以 RTF < 1 单独证明整个应用已满足时延要求。
4. 音色与质量工具
tools/eval.py 提供参考音频与转换结果的说话人嵌入相似度，以及 DNSMOS 的 SIG、BAK、OVRL 分数。主函数接收非空的参考/结果路径对列表和报告路径；脚本默认入口含占位路径，需显式配置。
GPU 评测依赖为可选 extra：
uv sync --locked --extra eval-gpu还需检查 DNSMOS 模型文件和运行时 Provider。该 extra 不意味着所有评测环境已验证。评测模块导入时就会初始化模型，不应用导入检查代替轻量语法检查。
SECS 在实现中是嵌入向量内积，不能当作百分比准确率；DNSMOS 是模型预测分数，不能当作人工主观评分。保留逐样本结果，与源/参考/转换音频对照试听，关注内容完整性、音色、噪声、静音恢复和拼接边界。固定同一批输入再比较参数方案。
5. 结果保存与发布
原始音频、日志、时间线和运行报告默认作为运行产物保留，不纳入版本控制。公开结论应附复现条件、样本数、统计口径及局限；只发布可公开的素材。任务验收记录进入 Spec，简短事实进入 changelog，不把一次效果比较表述成普遍质量保证。
经整理、可公开的评测报告统一收录在 reports，目录按时间组织，具体命名见报告归档规则。