wavlab-speech/versa

🎧 VERSA란 무엇인가요?

VERSA(Versatile Evaluation of Speech and Audio)는 연구자와 개발자가 음성, 음악 또는 어떤 음성 신호의 품질을 90개 이상의 내장 메트릭으로 평가할 수 있도록 해주는 오픈소스 파이썬 툴킷입니다. 이 메트릭은 지각적 품질(PESQ, POLQA 등), 이해도(WER, STOI 등), 기술적 측정, 그리고 Fréchet Audio Distance(FAD)와 같은 분포 수준 분석까지 포함합니다. VERSA는 원본 구현을 가볍게 감싸는 역할을 하며, 모델 다운로드, 입력 파싱, 분산 실행을 처리하여 사용자가 평가 자체에만 집중할 수 있도록 합니다.

🚀 핵심 기능 (README에 설명됨)

거대한 메트릭 카탈로그 – 90개 이상의 메트릭과 다양한 변형을 포함하며, 독립형, 종속형, 일치하지 않는, 분포형 그룹으로 분류됨.
툴킷 통합 – 이미 ESPnet, Kaldi 스타일 파이프라인 및 여러 음성 관련 챌린지에서 사용됨.
유연한 I/O – 단순한 파일 경로, Kaldi 스타일 SCP 목록, ARK 아카이브를 지원.
확장 가능한 실행 – 다중 노드, 다중 GPU 실행을 위한 내장 Slurm 지원; 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]"              # 테스트 및 린팅 도구

클론 없이 리포지토리에서 직접 설치할 수도 있습니다:

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 System Demo) – 제공된 BibTeX를 인용하세요.
라이선스: MIT (허용성 높음, 상용 사용 가능).

🙋‍♀️ VERSA를 사용해야 하는 사람

연구자: TTS, VC, 음성 강화, 음악 생성 논문에서 재현 가능한 다중 메트릭 평가가 필요한 분.
엔지니어: 제품 QA 또는 벤치마크 스위트에서 표준화된 음성 품질 수치를 보고해야 하는 파이프라인을 구축하는 분.
학생: 음성 품질 메트릭을 배우는 분; CLI는 빠른 실험을 위한 시작 YAML 설정 파일을 생성할 수 있음.

🤝 기여 방법

프로젝트는 풀 리퀘스트를 환영합니다. 스타일, 테스트, 문서 기대치는 온라인 Contributing 가이드를 참고하세요.

TL;DR

VERSA는 >90개의 음성/음악 품질 메트릭을 통합하고, 분산 스코어링을 지원하며, 통합된 CLI와 YAML 기반 구성 시스템을 제공하는 잘 관리되는 MIT 라이선스의 파이썬 라이브러리입니다. 코어를 설치하고 필요에 따라 선택적 백엔드를 추가한 후, versa-score 또는 versa/bin/scorer.py를 실행하여 어떤 음성 데이터셋에 대해서도 재현 가능한 메트릭 리포트를 얻을 수 있습니다.