multimetriceval 0.4.1

多指标评测工具: 支持翻译 (sacreBLEU/COMET/BLEURT/chrF++)，延迟（ATD,StartOffset）与 语音 (UTMOS/WER)

📊 MultiMetric-Eval

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

🌟 核心功能

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

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

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

2. SpeechEvaluator (语音质量评测)

   • 场景: 语音合成 (TTS)、变声 (Voice Conversion)。
   • 指标: UTMOS (自然度), WER/CER (识别准确率)。
   • 特点: 关注声音听感自然度和发音准确性。

3. LatencyEvaluator (同传延迟评测)

   • 场景: 同声传译 (S2T / S2S)。
   • 指标: StartOffset, ATD (Average Token Delay)。
   • 特点:
     • 支持 计算感知 (Computation Aware) 延迟。
     • 支持 MFA 强制对齐，实现精确的 S2S 延迟测量。
     • 一键集成质量评测 (自动调用 ModelEvaluator/SpeechEvaluator)。

---

🚀 安装

1. 基础安装

# 基础版 (仅支持文本指标 + UTMOS)
pip install multimetriceval

2. 按需安装依赖

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

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

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

# [模块三] 启用同传可视化 (Matplotlib)
pip install "multimetriceval[viz]"

# 安装所有功能 (推荐)
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"
)

---

⏱️ 模块三：同传延迟评测 (LatencyEvaluator)

专为 Simultaneous Translation (同声传译) 任务设计，支持 S2T (Speech-to-Text) 和 S2S (Speech-to-Speech)。

核心理念：用户只需定义 Agent（读/写策略），本工具负责模拟流式环境、计算延迟并自动调用质量评测。

1. 编写你的 Agent

你需要创建一个 Python 文件（例如 my_agent.py），继承 GenericAgent 并实现 policy 方法。

# my_agent.py
from multimetriceval.latency import GenericAgent, ReadAction, WriteAction

class MyAgent(GenericAgent):
    def policy(self, states=None):
        # 策略示例：如果源端没读完，就请求更多音频 (Read)
        if not self.states.source_finished:
            return ReadAction()
        
        # 如果源端读完了，但还没输出，就输出翻译 (Write)
        if not self.states.target_finished:
            return WriteAction("Hello World", finished=True)
            
        return ReadAction()

2. 命令行一键评测

使用内置的 CLI 工具运行评测。支持同时计算 延迟指标 和 质量指标。

python -m multimetriceval.latency.cli \
    --source data/audio_list.txt \
    --target data/ref.txt \
    --agent-script my_agent.py \
    --agent-class MyAgent \
    --task s2t \
    --computation-aware \
    --quality

参数详解:

• --source: 音频文件路径列表。
• --target: 参考文本路径列表。
• --agent-script: 包含 Agent 类的 Python 文件路径。
• --agent-class: Agent 类名。
• --task: s2t 或 s2s。
• --computation-aware: 开启计算感知延迟（统计模型推理耗时）。
• --quality: (推荐) 跑完延迟后，自动调用 ModelEvaluator (S2T) 或 SpeechEvaluator (S2S) 计算 BLEU/WER/UTMOS。
• --visualize: 生成延迟阶梯图 (需安装 [viz])。

3. S2S 进阶：MFA 强制对齐

对于 Speech-to-Speech 任务，为了精确计算延迟（基于生成的音频内容而非切片），本工具支持调用 Montreal Forced Aligner (MFA)。

前置要求:

1. 安装 MFA: conda install -c conda-forge montreal-forced-aligner
2. 下载模型: mfa model download dictionary english_mfa & mfa model download acoustic english_mfa

使用方法: 只需在运行 S2S 任务时，脚本会自动检测 MFA 环境。如果环境就绪，会自动计算额外的对齐指标：

• StartOffset_SpeechAlign
• ATD_SpeechAlign

---

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

如果在无法连接 GitHub 或 HuggingFace 的服务器（如校园网 HPC）上使用，请按以下步骤操作。

1. 准备 UTMOS 模型

UTMOS 依赖 GitHub 源码加载。

1. 源码: 下载并解压 SpeechMOS 源码 到本地（例如 /path/to/SpeechMOS-main）。
2. 权重: 下载 utmos22_strong.pth 到本地任意位置（例如 /path/to/utmos22_strong.pth）。

2. 准备 Whisper 模型

1. 下载权重文件（如 medium.pt）。
2. 放入文件夹（例如 /path/to/whisper_weights/）。

3. 代码调用

通过参数显式指定路径，无需将文件放入系统缓存目录。

evaluator = SpeechEvaluator(
    device="cuda",
    # [新增] 指定本地源码路径
    utmos_model_path="/path/to/SpeechMOS-main",
    # [新增] 指定本地权重路径 (.pth)
    utmos_ckpt_path="/path/to/utmos22_strong.pth", 
    # 指定 Whisper 权重目录
    whisper_root="/path/to/whisper_weights/"
)

4. 命令行调用 (CLI)

python -m multimetriceval.speech_evaluator \
    --csv data.csv \
    --utmos_path /path/to/SpeechMOS-main \
    --utmos_ckpt /path/to/utmos22_strong.pth \
    --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	识别准确率	自动适配中英文
LatencyEvaluator	StartOffset	Start Offset	首字/首音延迟	反应速度
	ATD	Average Token Delay	平均 Token 延迟	综合延迟指标
	(Custom)	Custom ATD	在ATD基础上除去音频播放时长	支持扩展

---

❓ 常见问题 (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 依然可用。

Q: LatencyEvaluator 报错 matplotlib not found? A: 请运行 pip install "multimetriceval[viz]" 安装可视化依赖。

Q: S2S 任务中 ATD_SpeechAlign 没有结果？ A: 这通常是因为未安装 MFA 或未下载 MFA 模型。请参考模块三文档安装 montreal-forced-aligner。如果未安装，工具会自动跳过对齐指标，仅计算基础切片延迟。

Q: 如何在 Python 代码中手动调用同传评测？

from multimetriceval.latency import GenericAgent, LatencyEvaluator

# 定义 Agent
class MyAgent(GenericAgent): ...

# 运行评测
agent = MyAgent()
evaluator = LatencyEvaluator(agent)
instances = evaluator.run(src_files, ref_files, task="s2t")

# 计算分数
scores = evaluator.compute_latency(computation_aware=True)
print(scores)

---

📜 License

MIT License

🤝 Contributing

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