wavlab-speech/versa

🎧 什么是 VERSA？

VERSA（语音与音频的多功能评估）是一个开源 Python 工具包，允许研究人员和开发者使用 90 多个内置指标 对语音、音乐或任何音频信号的质量进行评分。这些指标涵盖感知质量（如 PESQ、POLQA）、可懂度（如 WER、STOI）、技术测量，甚至包括 Fréchet Audio Distance（FAD）等分布级分析。VERSA 作为原始实现的轻量级封装，负责处理模型下载、输入解析和分布式执行，让您专注于评估本身。

🚀 核心功能（如 README 所述）

庞大的指标目录 – 超过 90 个指标，包含多种变体，分为独立、依赖、非匹配和分布型组。
工具包集成 – 已在 ESPnet、Kaldi 风格流水线以及多个语音相关挑战中使用。
灵活的 I/O – 支持普通文件路径、Kaldi 风格的 SCP 列表或 ARK 归档。
可扩展执行 – 内置 Slurm 支持，用于多节点、多 GPU 运行；本地多进程模式支持 CPU。
可恢复评分 – JSONL 输出包含隐藏的完成记录，中断的任务可继续执行，无需重新计算已完成的语句。
可视化 – 提供交互式可视化工具和 CLI（versa-score）以探索指标结果。
可扩展性 – 可选的额外依赖组支持重型后端（如 Qwen2‑Audio、SongEval、MAPSS），按需安装。

📦 安装（快速开始）

# 克隆并安装核心包
git clone https://github.com/wavlab-speech/versa.git
cd versa
pip install .

# 仅在需要时安装可选组
pip install ".[audio,text,ml]"      # 需要大型模型堆栈的指标
pip install ".[songeval]"          # 仅 SongEval 指标
pip install ".[external]"         # 包装其他工具包的后端
pip install ".[dev]"              # 测试与 lint 工具

您也可以不克隆直接从仓库安装：

python -m pip install git+https://github.com/wavlab-speech/versa.git#egg=versa-speech-audio-toolkit --no-build-isolation

🛠️ 典型用法

单行评分（CPU，简单指标集）：

python versa/bin/scorer.py \
  --score_config egs/speech_cpu.yaml \
  --gt   test/test_samples/test1 \
  --pred test/test_samples/test2 \
  --output_file result.jsonl \
  --io dir

GPU 加速运行并显式选择指标：

python versa/bin/scorer.py \
  --score_config egs/speech_gpu.yaml \
  --gt test/test_samples/test1.scp \
  --pred test/test_samples/test2.scp \
  --output_file result.jsonl \
  --io soundfile \
  --use_gpu True \
  --scoring_mode metric   # 逐个加载指标以节省 GPU 内存

恢复长时间任务（例如集群被抢占后）：

python versa/bin/scorer.py ... --resume

探索可用指标：

versa-score --list-metrics                # 列出所有已安装的指标
versa-score --describe-metric pesq        # 查看依赖、论文引用等
versa-score --recommend-config --task tts --device gpu

使用 Slurm 进行分布式评估（提供启动脚本）：

./launch_slurm.sh <pred_scp> <gt_scp|None> <score_dir> <split_job_num>

该脚本会自动处理资源检查、作业数组创建和结果聚合。

📊 覆盖了哪些类型的指标？

类别	示例指标
独立型	PESQ、POLQA、MOS‑Net、DNS‑MOS（无需参考）
依赖型	STOI、WER、SI‑SDR（比较预测 vs. 真实值）
非匹配型	Audio‑LLM 感知评分、Qwen2‑Audio 摘要
分布型	Fréchet Audio Distance（FAD）、Kernel Inception Distance（KID）、MAPSS

完整列表（含变体名称）请见在线 指标目录 页面。

📚 文档与资源

网站与文档：https://wavlab-speech.github.io/versa/
交互式 Colab 演示（Interspeech 2024 教程）：https://colab.research.google.com/drive/11c0vZxbSa8invMSfqM999tI3MnyAVsOp?usp=sharing
论文：VERSA: A Versatile Evaluation Toolkit for Speech, Audio, and Music（NAACL 2025 系统演示）– 请引用提供的 BibTeX。
许可证：MIT（宽松，允许商业使用）。

🙋‍♀️ 谁应该使用 VERSA？

研究人员：需要为 TTS、VC、语音增强或音乐生成论文提供可复现、多指标评估的。
工程师：构建必须报告标准化音频质量数值的流水线（如产品 QA 或基准套件）的。
学生：学习语音质量指标的；CLI 可生成快速实验的初始 YAML 配置文件。

🤝 贡献指南

项目欢迎 Pull Request。请参阅在线 Contributing 指南了解风格、测试和文档期望。

TL;DR

VERSA 是一个维护良好、采用 MIT 许可证的 Python 库，整合了 >90 个语音/音频质量指标，支持分布式评分，并提供统一的 CLI 和基于 YAML 的配置系统。安装核心包，按需添加可选后端，运行 versa-score 或 versa/bin/scorer.py 即可为任意音频数据集生成可复现的指标报告。