pyannote.audio 说话人日志工具包完全指南

pyannote.audio 是一个基于 PyTorch 的开源 Python 工具包，专门用于说话人日志（Speaker Diarization）任务。它提供了最先进的预训练模型和管道，可以进一步微调以适应您的数据，从而获得更好的性能。

项目核心技术

• PyTorch 深度学习框架：用于构建和训练模型
• Hugging Face Transformers：用于加载和使用预训练模型
• PyTorch Lightning：简化训练过程，支持多 GPU 训练
• OpenTelemetry：提供可选的遥测功能

主要功能特性

• 语音活动检测（Speech Activity Detection）
• 说话人变化检测（Speaker Change Detection）
• 重叠语音检测（Overlapped Speech Detection）
• 说话人嵌入（Speaker Embedding）
• 多 GPU 训练支持
• Python 优先的 API 设计

安装准备

在开始安装之前，请确保满足以下要求：

1. Python 3.10 或更高版本
2. 如果使用 NVIDIA GPU，建议安装 CUDA 以加速训练和推理
3. 安装必要的 Python 依赖管理工具

详细安装步骤

步骤1：创建虚拟环境

首先创建一个虚拟环境来隔离项目依赖：

python3 -m venv pyannote-env
source pyannote-env/bin/activate

步骤2：安装 pyannote.audio

使用 pip 安装 pyannote.audio：

pip install pyannote.audio

步骤3：接受用户条件

在使用 pyannote.audio 之前，您需要接受用户条件。请访问以下链接并接受条件：

• pyannote/segmentation-3.0 用户条件
• pyannote/speaker-diarization-3.1 用户条件

步骤4：创建 Hugging Face 访问令牌

为了使用预训练模型，您需要在 Hugging Face 上创建一个访问令牌。请访问 Hugging Face 设置页面创建令牌。

步骤5：创建 pyannoteAI API 密钥（可选）

如果您想使用 premium 版本的说话人日志服务，可以在 dashboard.pyannote.ai 创建 API 密钥。

使用示例

社区版说话人日志

import torch
from pyannote.audio import Pipeline
from pyannote.audio.pipelines.utils.hook import ProgressHook

# 社区版开源说话人日志管道
pipeline = Pipeline.from_pretrained(
    "pyannote/speaker-diarization-community-1",
    token="HUGGINGFACE_ACCESS_TOKEN")

# 发送到 GPU（如果可用）
pipeline.to(torch.device("cuda"))

# 应用预训练管道（带进度钩子）
with ProgressHook() as hook:
    output = pipeline("audio.wav", hook=hook)

# 打印结果
for turn, speaker in output.speaker_diarization:
    print(f"start={turn.start:.1f}s stop={turn.end:.1f}s speaker_{speaker}")

Premium 版本说话人日志

from pyannote.audio import Pipeline

# Premium 版说话人日志服务
pipeline = Pipeline.from_pretrained(
    "pyannote/speaker-diarization-precision-2", token="PYANNOTEAI_API_KEY")

output = pipeline("audio.wav")  # 在 pyannoteAI 服务器上运行

# 打印结果
for turn, speaker in output.speaker_diarization:
    print(f"start={turn.start:.1f}s stop={turn.end:.1f}s {speaker}")

性能基准测试

根据最新基准测试数据（2025年9月），各版本在多个数据集上的表现：

数据集	社区版（community-1）	Premium版（precision-2）
AISHELL-4	11.7%	11.4%
AMI (IHM)	17.0%	12.9%
DIHARD 3	20.2%	14.7%
VoxConverse	11.2%	8.5%

注：数值为 diarization error rate（%，越低越好）

遥测功能配置

pyannote.audio 提供了可选的遥测功能，您可以选择发送匿名使用指标来帮助改进库。

环境变量配置

# 启用指标
export PYANNOTE_METRICS_ENABLED=1

# 禁用指标
export PYANNOTE_METRICS_ENABLED=0

Python 会话配置

from pyannote.audio.telemetry import set_telemetry_metrics

# 启用当前会话的指标
set_telemetry_metrics(True)

# 禁用当前会话的指标
set_telemetry_metrics(False)

开发环境设置

要设置 pyannote.audio 的开发环境，请运行以下命令：

pip install -e .[dev,testing]
pre-commit install

测试

运行测试套件以确保一切正常工作：

pytest

文档资源

项目提供了丰富的文档资源，包括：

• 变更日志（CHANGELOG.md）
• 视频教程和演示
• 博客文章和教程
• 社区贡献内容
• 常见问题解答（FAQ.md）

重要依赖

项目依赖于多个重要的 Python 包，包括：

• torch >= 2.8.0
• torchaudio >= 2.8.0
• lightning >= 2.4
• huggingface-hub >= 0.28.1
• pyannote-core >= 6.0.1
• pyannote-database >= 6.0.0

通过本指南，您应该能够成功安装和配置 pyannote.audio，并开始使用这个强大的说话人日志工具包。无论是学术研究还是工业应用，pyannote.audio 都提供了强大而灵活的工具来处理说话人日志任务。