multimetriceval 0.3.0

多指标评测工具: 支持翻译 (sacreBLEU/COMET/BLEURT/chrF++) 与 语音 (UTMOS/WER)

📊 MultiMetric-Eval

全能型评测工具箱：一套工具，同时满足 机器翻译 (MT)、语音识别 (ASR)、语音合成 (TTS) 与 变声 (VC) 的评测需求。

🌟 核心功能

本工具包含两个独立的评测模块，按需导入：

1. ModelEvaluator (翻译与语义评测)

   • 场景: 机器翻译、语音翻译 (ST)、ASR。
   • 指标: BLEU, chrF++, COMET, BLEURT。
   • 特点: 关注语义一致性，支持文本和语音输入。

2. SpeechEvaluator (语音质量评测)

   • 场景: 语音合成 (TTS)、变声 (Voice Conversion)。
   • 指标:
     • UTMOS: 语音自然度/音质打分 (MOS 预测)。
     • WER / CER: 识别准确率。自动适配语言：英文计算词错误率 (WER)，中文计算字错误率 (CER)。
   • 特点: 关注声音听感自然度和发音准确性。

---

🚀 安装

1. 基础安装

# 基础版 (仅支持 BLEU, chrF++, UTMOS)
pip install multimetriceval

2. 按需安装依赖

根据你需要使用的功能安装额外的库：

# 启用 COMET (翻译评测)
pip install "multimetriceval[comet]"

# 启用 Whisper (语音评测 WER / ASR功能)
# *注意: 需要系统已安装 ffmpeg
pip install "multimetriceval[whisper]"

# 安装所有功能 (推荐)
pip install "multimetriceval[all]"

3. 安装 BLEURT (可选)

如果你需要使用 BLEURT 指标（PyTorch版），需手动安装：

pip install git+https://github.com/lucadiliello/bleurt-pytorch.git

---

📖 模块一：翻译评测 (ModelEvaluator)

用于评估翻译质量或语音识别的语义准确性。

快速开始

from multimetriceval import ModelEvaluator

# 初始化 (首次会自动下载模型)
evaluator = ModelEvaluator(use_comet=True)

# 评测
results = evaluator.evaluate(
    hypothesis=["The cat sits on the mat."],
    reference=["The cat is sitting on the mat."],
    source=["猫坐在垫子上。"]
)

print(results)
# Output: {'sacreBLEU': 45.2, 'chrF++': 62.1, 'COMET': 0.85}

三种输入模式

1. 纯文本评测

results = evaluator.evaluate_all(
    reference=["Reference translation."],
    source=["源文本。"],
    target_text=["My translation."],
)

2. 纯语音评测 (ASR模式)

评估语音翻译模型的输出：

evaluator = ModelEvaluator(use_comet=True, use_whisper=True)

results = evaluator.evaluate_all(
    reference=["Reference translation."],
    source=["源文本。"],
    target_speech="./my_audio_folder/",  # 自动转录后对比语义
)

3. 双模式评测

同时评估文本翻译和语音翻译的一致性：

results = evaluator.evaluate_all(
    reference=["Ref"], source=["Src"],
    target_text=["Trans text"],
    target_speech="./audio/"
)

---

🎧 模块二：语音质量评测 (SpeechEvaluator)

专为 TTS (语音合成) 和 VC (变声) 设计。

⚡️ 核心特性：WER/CER 智能适配

本工具内置了智能分词逻辑：

• 英文/印欧语系：保持空格分词，计算 WER (Word Error Rate)。
• 中文/日文：自动在字符间插入空格，计算 CER (Character Error Rate)。
• 混合文本：混合处理。

无需用户手动分词，直接传入原始文本即可。

快速开始

from multimetriceval import SpeechEvaluator

# 初始化 (自动加载 UTMOS 和 Whisper)
evaluator = SpeechEvaluator(device="cuda")

# 评测列表数据
audio_paths = ["/data/gen_en.wav", "/data/gen_zh.wav"]
ref_texts = ["Hello world", "你好世界"]

results = evaluator.evaluate(audio_paths, ref_texts)
print(results)
# Output: 
# {
#   'UTMOS': 4.15,  # 自然度 (1-5分)
#   'WER': 0.05     # 这里不仅包含英文WER，也包含中文CER
# }

数据输入方式

方式 A: CSV 文件 (推荐)

最适合批量评测，避免文件乱序问题。

wav_path,text
/exp/tts/001.wav,Hello world
/exp/tts/002.wav,你好世界

results = evaluator.evaluate_from_csv("data.csv", wav_col="wav_path", text_col="text")

方式 B: 文件夹 + 文本文件

适用于生成了一堆 wav 文件，且有一个对应的 txt 文件。 注意：音频文件将按文件名排序后与文本行对应。

results = evaluator.evaluate_from_folder(
    audio_folder="./outputs", 
    text_file="./scripts.txt"
)

---

🛡️ 离线 / 内网环境使用指南 (SpeechEvaluator)

如果在无法连接 GitHub 或 HuggingFace 的服务器（如校园网 HPC）上使用，请按照以下步骤手动加载模型。

1. 准备 UTMOS 模型 (解决 GitHub 连不通)

UTMOS 依赖 GitHub 源码加载。

1. 下载源码包：https://github.com/tarepan/SpeechMOS/archive/refs/heads/main.zip
2. 解压到服务器，例如 /path/to/SpeechMOS-main。
3. 下载权重文件：utmos22_strong.pth
4. 将权重放入缓存目录：~/.cache/torch/hub/checkpoints/utmos22_strong.pth

2. 准备 Whisper 模型 (解决权重下载慢)

Whisper 模型权重是单个 .pt 文件。

1. 下载权重 (以 medium 为例)：medium.pt
2. 上传到服务器目录，例如 /path/to/whisper_weights/。

3. 代码调用

evaluator = SpeechEvaluator(
    device="cuda",
    # 指定本地源码路径
    utmos_model_path="/path/to/SpeechMOS-main",
    # 指定权重存放目录
    whisper_root="/path/to/whisper_weights/"
)

4. 命令行调用 (CLI)

该库也支持在命令行直接运行评测：

# 联网环境
python -m multimetriceval.speech_evaluator \
    --folder ./wavs --text_file trans.txt --device cuda:0

# 离线环境
python -m multimetriceval.speech_evaluator \
    --csv data.csv \
    --utmos_path /path/to/SpeechMOS-main \
    --whisper_root /path/to/whisper_weights

---

⚙️ 全局配置

GPU 设置

所有模块均支持自动检测 GPU。手动指定方式如下：

# 指定第 0 号 GPU
evaluator = SpeechEvaluator(device="cuda:0")

# 强制使用 CPU
evaluator = SpeechEvaluator(device="cpu")

或者使用环境变量：

CUDA_VISIBLE_DEVICES=1 python my_script.py

国内网络镜像

如果下载模型超时，请在代码开头设置 HF 镜像：

import os
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"

---

📊 指标速查表

模块	指标	全称	用途	备注
ModelEvaluator	BLEU	Bilingual Evaluation Understudy	翻译 n-gram 匹配度	传统指标
	chrF++	Character n-gram F-score	字符级匹配度	适合形态丰富的语言
	COMET	Crosslingual Optimized Metric	基于神经网络的语义相似度	推荐，与人工打分相关性高
	BLEURT	Bilingual Evaluation Understudy with Representations	基于 BERT 的语义评分	Google 出品
SpeechEvaluator	UTMOS	UTMOS22 Strong	语音自然度/MOS 预测	无需参考音频，直接打分
	WER/CER	Word/Character Error Rate	识别准确率	自动适配中英文

---

❓ 常见问题 (FAQ)

Q: 为什么中文计算出的 WER 是 1.0 (100%)？ A: 这是因为传统 WER 算法以空格分词，中文没有空格会被当成一个词，错一个字就算全错。本工具已修复此问题，会自动给中文字符间插入空格，计算 CER，请放心使用。

Q: UTMOS 加载报错 HTTP 404 或 Connection Refused？ A: 这是因为服务器无法连接 GitHub 下载源码。请参考上文 “离线 / 内网环境使用指南”，手动下载 SpeechMOS 源码包并指定 utmos_model_path。

Q: 安装时提示 ffmpeg not found? A: Whisper 依赖系统级的 ffmpeg。请安装它：

• Ubuntu: sudo apt install ffmpeg
• Windows: 下载 ffmpeg.exe 并添加到环境变量 PATH 中。

Q: SpeechEvaluator 报错缺少 Whisper? A: 请运行 pip install "multimetriceval[whisper]"。如果不想用 WER 指标，可以忽略该错误，UTMOS 依然可用。

---

📜 License

MIT License

🤝 Contributing

欢迎提交 Issue 和 Pull Request！ GitHub: https://github.com/sjtuayj/MultiMetric-Eval