UIS-RNN

概述

这是用于*无界交错状态循环神经网络（UIS-RNN）*算法的库。UIS-RNN通过从示例中学习，解决了对序列数据进行分割和聚类的问题。

该算法最初在论文《完全监督的说话人日志》中提出（https://arxiv.org/abs/1810.04719）。

这项工作也曾在Google AI 博客上介绍过。

免责声明

由于依赖于一些内部库，此开源实现与我们用于生成论文（https://arxiv.org/abs/1810.04719）结果的内部实现略有不同。

我们无法分享论文中使用的说话人识别系统（d-vector 嵌入）的数据、代码或模型，因为该说话人识别系统高度依赖于 Google 的内部基础设施和专有数据。

本库并非 Google 官方产品。

我们欢迎社区对 uisrnn/contrib 文件夹的贡献（贡献指南）。但我们不对任何社区贡献的正确性负责。

依赖项

本库依赖于以下内容：

• Python 3.5+
• NumPy 1.15.1
• PyTorch 1.3.0
• SciPy 1.1.0（仅用于评估）

快速入门

安装包

无需下载仓库，您可以通过以下方式安装 package：

pip3 install uisrnn

或者

python3 -m pip install uisrnn

运行演示

要开始使用，只需运行以下命令：

python3 demo.py --train_iteration=1000 -l=0.001

这将使用 data/toy_training_data.npz 训练一个 UIS-RNN 模型，然后将其保存到磁盘，并在 data/toy_testing_data.npz 上进行推理，打印推理结果，并将平均准确率保存到文本文件中。

注：data/ 目录下的文件是手动生成的 玩具数据，仅用于演示目的。这些数据非常简单，因此我们应该能够在测试数据上获得 100% 的准确率。

运行测试

您还可以通过运行以下命令来验证本库的正确性：

bash run_tests.sh

如果您分叉了本库并进行了本地修改，请务必使用这些测试作为基本检查。

此外，这些测试也是学习 API 的绝佳示例，尤其是 tests/integration_test.py。

核心 API

术语表

通用机器学习	说话人日志
序列	发言段
观测值 / 特征	嵌入 / d-vector
标签 / 聚类 ID	说话人

参数

在您的主脚本中，调用以下函数以获取参数：

model_args, training_args, inference_args = uisrnn.parse_arguments()

模型构建

所有算法都实现为 UISRNN 类。首先，通过以下方式构造一个 UISRNN 对象：

model = uisrnn.UISRNN(args)

参数的定义在 uisrnn/arguments.py 中描述。请参阅 model_parser。

训练

接下来，通过调用 fit() 函数来训练模型：

model.fit(train_sequences, train_cluster_ids, args)

args 的定义在 uisrnn/arguments.py 中有说明，请参阅 training_parser。

fit() 函数接受两种类型的输入，如下所述。

输入为序列列表（推荐）

在此情况下，train_sequences 是一个观测序列的列表。每个观测序列是一个 2 维的 float 类型 NumPy 数组。

• 第一维是该序列的长度，不同序列的长度可以不同。
• 第二维是每个观测的维度，所有序列必须保持一致。对于说话人日志任务，观测可以是 d-vector 嵌入。

train_cluster_ids 同样是一个列表，其长度与 train_sequences 相同。train_cluster_ids 中的每个元素是一个 1 维字符串列表或 NumPy 数组，包含对应于 train_sequences 中相应序列的真实标签。对于说话人日志任务，这些标签是每个观测对应的说话人标识符。

以这种方式调用 fit() 时，请务必小心使用 --enforce_cluster_id_uniqueness 参数。

例如，假设：

train_cluster_ids = [['a', 'b'], ['a', 'c']]

如果两个序列中的标签 'a' 指的是整个数据集中同一个聚类，那么应设置 enforce_cluster_id_uniqueness=False；反之，如果 'a' 只是在第一个序列中用来区分 'b'，在第二个序列中用来区分 'c' 的局部标记，则应设置 enforce_cluster_id_uniqueness=True。

此外，请注意，以这种方式调用 fit() 时，我们会将所有序列和所有聚类标签拼接在一起，并交由下一部分处理。

输入为单个拼接后的序列

在此情况下，train_sequences 应该是一个 2 维的 float 类型 NumPy 数组，用于表示拼接后的观测序列。

例如，如果你有 M 个训练语音片段，每个片段包含 L 个嵌入向量，每个嵌入向量由 D 个数字组成，则 train_sequences 的形状为 N × D，其中 N = M × L。

train_cluster_ids 是一个 1 维字符串列表或 NumPy 数组，长度为 N，它是所有训练数据的拼接后真实标签。

由于我们正在拼接观测序列，需要注意的是，train_cluster_ids 中不同序列的真实标签应当是全局唯一的。

例如，如果第一个序列的标签集是 {'A', 'B', 'C'}，第二个序列的标签集是 {'B', 'C', 'D'}，那么在拼接之前，我们应该将它们重命名为类似 {'1_A', '1_B', '1_C'} 和 {'2_B', '2_C', '2_D'} 的形式，除非这两个序列中的 'B' 和 'C' 在语义上完全相同（在说话人日志任务中，这意味着它们代表的是跨语音片段的同一说话人）。这一部分通常会由前一部分的 --enforce_cluster_id_uniqueness 参数自动处理。

我们之所以要将所有训练序列拼接起来，是因为我们将对训练数据进行重采样和分块式打乱，作为一种数据增强手段，从而即使在训练序列数量不足的情况下，也能得到一个鲁棒的模型。

大规模数据集上的训练

对于大规模数据集，数据通常无法一次性全部加载到内存中。在这种情况下，需要多次调用 fit() 函数。

以下是我们的一些建议：

1. 不要将不同的数据集分别传入不同的 fit() 调用中。相反，每次调用 fit() 时，输入应涵盖来自不同数据集的序列。
2. 每次调用 fit() 函数时，尽量使输入大小大致相同，但也不要过小。

预测

训练完成后，我们可以使用训练好的模型对新序列进行推理，方法是调用 predict() 函数：

predicted_cluster_ids = model.predict(test_sequences, args)

这里，test_sequences 应该是一个 2 维 float 类型 NumPy 数组的列表，对应于用于测试的观测序列。

返回的 predicted_cluster_ids 是一个与 test_sequences 大小相同的列表。predicted_cluster_ids 中的每个元素是一个整数列表，其长度与相应的测试序列相同。

你也可以只使用一个测试序列作为 test_sequences，此时返回的 predicted_cluster_ids 将是一个单独的整数列表。

args 的定义同样在 uisrnn/arguments.py 中说明，请参阅 inference_parser。

引用

我们的论文引用如下：

@inproceedings{zhang2019fully,
  title={Fully supervised speaker diarization},
  author={Zhang, Aonan and Wang, Quan and Zhu, Zhenyao and Paisley, John and Wang, Chong},
  booktitle={International Conference on Acoustics, Speech and Signal Processing (ICASSP)},
  pages={6301--6305},
  year={2019},
  organization={IEEE}
}

参考文献

基线日志系统

如需了解更多基于无监督聚类算法的基线日志系统，请访问此网站。

本文中使用的谱聚类算法的 Python 重新实现版本可在此处找到。

NIST SRE 2000 数据集（Disk6 和 Disk8）的真实标签可在此处找到：https://github.com/google/speaker-id/tree/master/publications/LstmDiarization/evaluation/NIST_SRE2000。

更多关于说话人日志的公开资源，请参阅 awesome-diarization。

说话人识别器/编码器

如需了解更多关于我们说话人嵌入系统的相关信息，请访问此网站。

我们了解到有几款第三方实现了这项工作：

• Resemblyzer：resemble-ai 提供的 PyTorch 实现
• Janghyun1230 提供的 TensorFlow 实现
• HarryVolek 提供的 PyTorch 实现，并集成了 UIS-RNN
• SV2TTS 项目中的 PyTorch 实现

请根据自己的判断决定是否使用这些实现。

我们不对任何第三方实现的正确性负责。

变体

这里列出了基于 UIS-RNN，但集成了其他技术或进行了一些改进的仓库。

链接	描述
taylorlu/Speaker-Diarization	使用 UIS-RNN 和 GhostVLAD 进行说话人日志分割。一种更简便的方式来支持开放集说话人识别。
DonkeyShot21/uis-rnn-sml	UIS-RNN 的一个变体，用于论文《面向多领域数据的带样本均值损失的监督在线日志分割》。

UIS-RNN 快速上手指南

UIS-RNN（Unbounded Interleaved-State Recurrent Neural Network）是一种用于序列数据分割和聚类的算法，最初应用于全监督说话人日记化（Speaker Diarization）任务。本指南将帮助你快速在本地环境中部署并运行该工具。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：3.5 及以上
• 核心依赖：
  • numpy >= 1.15.1
  • pytorch >= 1.3.0
  • scipy >= 1.1.0 (仅用于评估环节)

提示：国内开发者建议使用国内镜像源安装依赖，以提升下载速度。例如使用清华源或阿里源。

安装步骤

你可以通过 PyPI 直接安装预编译包，无需克隆仓库。

方式一：使用默认源安装

pip3 install uisrnn

方式二：使用国内镜像源加速安装（推荐）

python3 -m pip install uisrnn -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

安装完成后，你可以直接运行官方提供的演示脚本来验证安装并体验完整流程（包含训练、模型保存、推理及结果评估）。

运行演示 Demo

在项目根目录或任意位置执行以下命令：

python3 demo.py --train_iteration=1000 -l=0.001

脚本执行流程说明：

1. 数据加载：自动加载 data/toy_training_data.npz 中的玩具数据（Toy Data）。
2. 模型训练：使用指定参数训练 UIS-RNN 模型。
3. 模型保存：将训练好的模型保存到磁盘。
4. 推理预测：对 data/toy_testing_data.npz 进行测试数据推理。
5. 结果输出：打印推理结果，并将平均准确率保存为文本文件。

注意：Demo 使用的数据是人工生成的简单玩具数据，理论上在测试集上应达到 100% 的准确率。此脚本主要用于展示 API 调用流程和验证环境正确性。

代码集成示例

若需在自有项目中集成，核心调用逻辑如下：

import uisrnn

# 1. 解析参数
model_args, training_args, inference_args = uisrnn.parse_arguments()

# 2. 构建模型
model = uisrnn.UISRNN(model_args)

# 3. 训练模型
# train_sequences: 观察序列列表 (List of 2-dim numpy arrays)
# train_cluster_ids: 对应的真实标签列表 (List of 1-dim lists/arrays)
model.fit(train_sequences, train_cluster_ids, training_args)

# 4. 进行预测
# test_sequences: 测试观察序列列表
predicted_cluster_ids = model.predict(test_sequences, inference_args)

对于大规模数据集无法一次性载入内存的情况，可以分批次多次调用 model.fit() 方法进行增量训练。