multimetriceval 0.5.2

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

📊 MultiMetric-Eval

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

🎯 适用范围与核心能力 (Capabilities)

本工具不仅仅是一个计算器，它是一个多模态 (Multimodal) 质量评测框架。它不负责翻译，而是负责对 “任意翻译/生成结果” 进行标准化打分。

1. 支持的任务方向 (Supported Tasks)

无论你的模型是文本还是语音，只要有参考答案 (Reference)，本工具均可评测：

任务类型	输入 -> 输出	关键指标	典型场景
机器翻译 (MT)	文本 -> 文本	BLEU, chrF++, COMET, BLEURT	文档翻译、聊天机器人
语音识别 (ASR)	语音 -> 文本	WER / CER	会议记录、字幕生成
语音合成 (TTS)	文本 -> 语音	UTMOS (自然度), ASR-WER (可懂度)	文本朗读、数字人
语音翻译 (S2T)	语音 -> 文本	BLEU, COMET, WER	端到端语音翻译
语音转语音 (S2S)	语音 -> 语音	UTMOS, ASR-BLEU, ASR-COMET	同声传译、变声器

2. 多语言支持 (Language Support)

本工具针对不同语系进行了深度优化，解决了传统评测脚本在 CJK (中日韩) 语言上分数失真的痛点。

• ✅ 第一梯队：深度优化 (CJK)

  • 语言: 中文 (zh), 日语 (ja), 韩语 (ko)
  • 特性: 内置智能路由，自动调用 Jieba / MeCab 进行特定分词。
  • 优势: 彻底解决 SacreBLEU 因无空格导致 BLEU=0 的问题；自动切换为 CER (字符错误率)。

• ✅ 第二梯队：标准支持 (印欧语系)

  • 语言: 英语 (en), 德语 (de), 法语 (fr), 西班牙语 (es) 等。
  • 特性: 使用国际标准的 13a 分词器，与 WMT 评测标准对齐。

• ✅ 第三梯队：广泛支持 (低资源语言)

  • 语言: 泰语、阿拉伯语、越南语等 100+ 种语言。
  • 特性: 依托 COMET (语义模型) 和 Whisper (ASR模型) 的强大能力，支持绝大多数互联网语言的语义与语音评测。

---

🌟 核心功能

本工具包含两个核心评测模块：

1. TranslationEvaluator (全能评测器)

   • 一站式解决方案: 同时支持 文本翻译 和 语音合成/转换 的评测。
   • 文本指标: BLEU, chrF++, COMET, BLEURT。
   • 语音指标: UTMOS (自然度), WER/CER (识别准确率)。
   • 特点: 智能判断输入类型（文本/语音），自动计算所有适用的指标。

2. LatencyEvaluator (同传延迟评测)

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

---

🚀 安装

1. 基础安装

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

2. 按需安装依赖

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

# [文本] 启用 COMET (语义评测)
pip install "multimetriceval[comet]"

# [语音] 启用 Whisper (ASR / WER / 语音转文本)
# *注意: 需要系统已安装 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

---

📖 模块一：全能评测 (TranslationEvaluator)

这是本库的核心类，能够处理从纯文本到纯语音，以及混合模态的所有评测需求。

⚡ 初始化配置 (Switches)

通过初始化参数，你可以精确控制要计算哪些指标：

from multimetriceval import TranslationEvaluator

evaluator = TranslationEvaluator(
    # --- 文本指标开关 ---
    use_bleu=True,      # 默认 True
    use_chrf=True,      # 默认 True
    use_comet=True,     # 默认 True (需安装 comnet)
    use_bleurt=False,   # 默认 False (需手动安装)
    
    # --- 语音指标开关 ---
    use_wer=True,       # 计算 WER/CER (需开启 whisper)
    use_utmos=False,    # 计算自然度 UTMOS (需下载模型)
    use_whisper=False,  # 启用 ASR 转写功能
    
    # --- 模型路径 (可选) ---
    device="cuda"       # 自动检测，可手动指定
)

📂 数据输入方式详解

evaluate_all 方法非常灵活，支持 内存变量 (List) 和 文件路径 (Path) 混合输入。

1. 文本输入 (target_text&reference & source)

支持直接传入 Python 列表，或传入文件路径（工具会自动读取）。 一致性要求: 无论使用哪种方式，source 和 reference 的行数/条目数必须与评测目标严格对应。

• 格式 A: 纯文本文件 (.txt)
  • 要求：一行一句，数量必须与 reference 一致。

  Hello world
  This is a test
  

• 格式 B: JSON 文件 (.json)
  • 支持三种结构，工具会自动识别：
  1. 字典 (推荐): {"target_text": ["句1", "句2"]} 或 {"hypothesis": ["...", "..."]}
  2. 列表-字典: [{"target_text": "句1"}, {"target_text": "句2"}]
  3. 纯列表: ["句1", "句2"]

2. 语音输入 (target_speech)

支持直接传入音频路径列表，或传入文件夹路径。

• 方式 A: 文件夹路径 (推荐)
  • 传入字符串路径："./audio_output/"
  • 重要规则：工具会自动读取该文件夹下所有 .wav/.mp3/.flac 文件，并按文件名 (A-Z) 排序。请确保排序后的音频与 reference 文本顺序一一对应。
• 方式 B: 文件路径列表
  • 传入 List：["/data/1.wav", "/data/2.wav"]

---

🛠️ 使用场景示例

场景 1: 纯文本机器翻译 (MT)

计算 BLEU, chrF++, COMET。 注意： 如果目标语言是中文 (zh) 或日语 (ja)，请务必指定 target_lang，工具会自动切换分词器 (jieba/mecab)。

evaluator = TranslationEvaluator(use_comet=True)

# 示例：英日翻译 (English -> Japanese)
results = evaluator.evaluate_all(
    target_text=["猫はマットの上に座っている。"],  # 日语翻译结果
    reference=["猫はマットの上に座っています。"], # 日语参考译文
    source=["The cat sits on the mat."],       # 源文本
    target_lang="ja"                           # <--- 关键！指定目标语言为日语
)

# 工具会自动调用 'ja-mecab' 分词，计算准确的 BLEU
print(results)
# {'sacreBLEU': 45.2, 'chrF++': 62.1, 'COMET': 0.85}

场景 2: 语音合成 (TTS) / 变声 (VC)

计算 UTMOS (自然度) 和 WER/CER (准确率)。 注意：计算 WER 需要开启 use_whisper=True。

# 初始化: 开启语音相关功能
evaluator = TranslationEvaluator(
    use_utmos=True, 
    use_whisper=True, 
    use_wer=True,
    device="cuda"
)

results = evaluator.evaluate_all(
    target_speech="./generated_audio_folder/",  # 音频文件夹
    reference=["你好世界", "这是一个测试"],      # 对应的文本内容
    target_lang="zh"                            # <--- 指定中文，影响 ASR 后计算的 BLEU 分词
)

print(results)
# {
#   'UTMOS': 4.15,          # 自然度得分
#   'WER': 0.05,            # 字错误率 (中文自动转为 CER)
#   'sacreBLEU_ASR': 98.5   # ASR文本与参考文本的 BLEU (自动使用 zh 分词)
# }

场景 3: 语音翻译 (S2T / S2S) - 双模态评测

同时评估 “生成的文本” 和 “生成的语音”。常用于端到端语音翻译系统。

results = evaluator.evaluate_all(
    reference=["Ref sentence"], 
    source=["Src sentence"],
    target_text="./outputs/text_predictions.txt", # 文本结果文件
    target_speech="./outputs/audio_predictions/"  # 语音结果文件夹
)

# 返回结果将同时包含:
# 1. 文本指标 (基于 target_text): sacreBLEU, COMET
# 2. 语音指标 (基于 target_speech): UTMOS, WER, sacreBLEU_ASR, COMET_ASR

---

🌍 多语言支持：解决 SacreBLEU 分词问题

在评测 中文 (zh)、日语 (ja) 或 韩语 (ko) 时，传统的 BLEU 算法（默认以空格分词）会导致评分严重失真（通常接近 0 分）。

本工具内置了智能分词路由，你只需在 evaluate_all 中传入 target_lang 参数，工具会自动处理底层细节：

目标语言	target_lang	自动调用的 Tokenizer	依赖库
日语	"ja"	ja-mecab	mecab-python3, ipadic
中文	"zh"	zh	jieba
韩语	"ko"	ko-mecab	mecab-ko
英语/其他	"en", "fr"...	13a (默认)	无

使用方式：

# 日语评测 (必须指定，否则 BLEU 极低)
evaluator.evaluate_all(..., target_lang="ja")

# 英语评测 (默认可不写，或写 "en")
evaluator.evaluate_all(..., target_lang="en")

---

⚡️ 语音评测核心特性

1. WER/CER 智能适配

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

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

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

2. ASR 后文本指标联动

当 use_whisper=True 时，工具会计算 sacreBLEU_ASR。该指标同样受 target_lang 参数控制。例如设置 target_lang="ja"，不仅 WER 会按字符计算，sacreBLEU_ASR 也会自动使用 MeCab 分词。

3. 双轨制指标命名

当同时传入文本和语音时，结果字典中的 key 遵循以下规则：

• 标准指标 (如 sacreBLEU, COMET): 基于 target_text 计算。
• ASR 指标 (如 sacreBLEU_ASR, COMET_ASR): 先用 Whisper 将 target_speech 转写为文本，再基于转写结果计算。

---

⏱️ 模块二：同传延迟评测 (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: (推荐) 跑完延迟后，自动调用 TranslationEvaluator 计算质量指标。
• --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

---

🛡️ 离线 / 内网环境使用指南 (语音模型)

如果在无法连接 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 = TranslationEvaluator(
    use_utmos=True,
    use_whisper=True,
    # [新增] 指定本地源码路径
    utmos_model_path="/path/to/SpeechMOS-main",
    # [新增] 指定本地权重路径 (.pth)
    utmos_ckpt_path="/path/to/utmos22_strong.pth", 
    # 指定 Whisper 权重文件路径 (注意这里要带上 .pt 文件名或确保 load_model 能找到)
    whisper_model="medium", 
    # 或者通过环境变量控制 whisper 缓存路径
)

(注：Whisper 的 load_model 的 download_root 参数在 TranslationEvaluator 内部目前使用的是默认缓存或 ~/.cache/whisper，如需完全离线指定路径，建议提前设置环境变量或将模型放入默认缓存目录)

---

⚙️ 全局配置

GPU 设置

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

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

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

或者使用环境变量：

CUDA_VISIBLE_DEVICES=1 python my_script.py

国内网络镜像

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

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

---

📊 指标速查表

模块	指标	全称	用途	备注
TranslationEvaluator	sacreBLEU	Bilingual Evaluation Understudy	翻译 n-gram 匹配度	传统指标
	chrF++	Character n-gram F-score	字符级匹配度	适合形态丰富的语言
	COMET	Crosslingual Optimized Metric	基于神经网络的语义相似度	推荐
	BLEURT	Bilingual Evaluation Understudy with Representations	基于 BERT 的语义评分	Google 出品
	UTMOS	UTMOS22 Strong	语音自然度/MOS 预测	无需参考音频
	WER/CER	Word/Character Error Rate	识别准确率	自动适配中英文
LatencyEvaluator	StartOffset	Start Offset	首字/首音延迟	反应速度
	ATD	Average Token Delay	平均 Token 延迟	综合延迟指标

---

❓ 常见问题 (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: 评测日语时提示 ModuleNotFoundError: No module named 'MeCab'？ A: 评测日语 BLEU 需要依赖 MeCab。请运行 pip install mecab-python3 ipadic 安装所需依赖。同理，中文评测需要 pip install jieba。

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