# 📊 MultiMetric-Eval

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

[![PyPI version](https://badge.fury.io/py/multimetric-eval.svg)](https://badge.fury.io/py/multimetric-eval)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🌟 核心功能

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

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

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

---

## 🚀 安装

### 1. 基础安装

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

### 2. 按需安装依赖

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

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

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

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

### 3. 安装 BLEURT (可选)

如果你需要使用 BLEURT 指标（PyTorch版），需手动安装：
```bash
pip install git+https://github.com/lucadiliello/bleurt-pytorch.git
```

---

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

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

### 快速开始

```python
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. 纯文本评测
```python
results = evaluator.evaluate_all(
    reference=["Reference translation."],
    source=["源文本。"],
    target_text=["My translation."],
)
```

#### 2. 纯语音评测 (ASR模式)
评估语音翻译模型的输出：
```python
evaluator = ModelEvaluator(use_comet=True, use_whisper=True)

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

#### 3. 双模式评测
同时评估文本翻译和语音翻译的一致性：
```python
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)**。
*   **混合文本**：混合处理。
> 无需用户手动分词，直接传入原始文本即可。

### 快速开始

```python
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 文件 (推荐)
最适合批量评测，避免文件乱序问题。

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

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

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

```python
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](https://github.com/tarepan/SpeechMOS/archive/refs/heads/main.zip)
2.  解压到服务器，例如 `/path/to/SpeechMOS-main`。
3.  下载权重文件：[utmos22_strong.pth](https://github.com/tarepan/SpeechMOS/releases/download/v1.0.0/utmos22_strong.pth)
4.  将权重放入缓存目录：`~/.cache/torch/hub/checkpoints/utmos22_strong.pth`

### 2. 准备 Whisper 模型 (解决权重下载慢)
Whisper 模型权重是单个 `.pt` 文件。
1.  下载权重 (以 medium 为例)：[medium.pt](https://openaipublic.azureedge.net/main/whisper/models/345ae4da62f9b3d59415adc6017195dc-medium.pt)
2.  上传到服务器目录，例如 `/path/to/whisper_weights/`。

### 3. 代码调用

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

### 4. 命令行调用 (CLI)

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

```bash
# 联网环境
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。手动指定方式如下：

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

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

或者使用环境变量：
```bash
CUDA_VISIBLE_DEVICES=1 python my_script.py
```

### 国内网络镜像
如果下载模型超时，请在代码开头设置 HF 镜像：
```python
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](https://github.com/sjtuayj/MultiMetric-Eval)