pyannote.audio 实战入门：10 分钟安装并跑通说话人日志

pyannote.audio 实战入门：10 分钟安装并跑通说话人日志

【免费下载链接】pyannote-audioNeural building blocks for speaker diarization: speech activity detection, speaker change detection, overlapped speech detection, speaker embedding项目地址: https://gitcode.com/GitHub_Trending/py/pyannote-audio

pyannote.audio是一个基于 PyTorch 的开源说话人日志（Speaker Diarization）工具包，它回答"录音里谁在什么时候说话"这个问题。它自带开箱即用的预训练管道，你可以直接在本地运行，也可以用自己的数据继续微调以获得更好的效果。

能力速览

你最常用到的四项能力：

• 开箱即用的预训练管道：一行代码加载speaker-diarization-community-1，不用训练、不用调参，直接出说话人分割结果。
• 社区版 / 高级版双档位：社区版完全本地运行；高级版precision-2错误率更低、速度快约 2.2 倍，一行代码即可切换。
• Python 优先的 API：Pipeline对象可直接调用，说话人数等可选参数随调用传入，方便嵌入你自己的应用。
• 可持续微调：预训练模型支持基于 PyTorch Lightning 的多 GPU 训练，能适配你自己的领域数据。

环境准备与安装

把这 4 项准备好、装完包，你就具备跑通第一个示例的全部条件。

uv add pyannote.audio # 主推 pip install pyannote.audio # 备选

装完后在终端执行python -c "import pyannote.audio; print(pyannote.audio.__version__)"，能打印出版本号就说明安装成功。

使用社区版前还要做两件事：在 Hugging Face 上同意pyannote/speaker-diarization-community-1的用户条件，并创建一个个人访问令牌。

在模型页面点 Files 标签页就能看到config.yaml（管道的配置文件），模型权重会在首次运行时自动下载。

跑通第一个示例

用下面这段代码加载社区版管道，对一个 wav 文件跑完说话人日志，并打印每段语音的起止时间和说话人标签。把audio.wav换成你自己的文件即可；手头没有音频的话，可以先用仓库里的示例文件tests/data/tst00.wav。

import torch from pyannote.audio import Pipeline pipeline = Pipeline.from_pretrained( "pyannote/speaker-diarization-community-1", token="<你的TOKEN>") pipeline.to(torch.device("cuda")) # 送显卡，没有 GPU 就删掉这行 output = pipeline("audio.wav") # 在本地运行 for turn, speaker in output.speaker_diarization: print(f"{turn.start:.1f}s-{turn.end:.1f}s {speaker}")

输出长这样：

0.2s-1.5s speaker_0 1.8s-3.9s speaker_1 4.2s-5.7s speaker_0

每一行是一段连续的语音：开始时间、结束时间、说话人标签。相同标签代表同一个人，这正是说话人日志的完整输出。

场景化用法

下面两个场景都基于上一节的pipeline对象，按需取用。

已知说话人数：用 num_speakers 固定

会议录音这种场景，参与人数往往提前可知。把人数直接告诉管道，聚类会更稳，能明显减少"把一个人拆成两个标签"的错误。

output = pipeline("meeting.wav", num_speakers=4) # 或者给一个范围，让管道在区间内自行判断 output = pipeline("meeting.wav", min_speakers=2, max_speakers=10)

对会议、访谈、播客这类人数固定的内容，固定人数意味着你可以把"多估计一个说话人"这类错误基本消除。

追求更高准确率：切换到高级版 precision-2

当你想要更低的错误率、又不想自己占 GPU 时，把Pipeline.from_pretrained的第一个参数换成pyannote/speaker-diarization-precision-2，token 换成 pyannoteAI 的 API key（新账号有免费额度）。调用会在 pyannoteAI 服务器上运行，返回的说话人标签形如SPEAKER_00、SPEAKER_01。

其余调用代码完全不变，pipeline("audio.wav")返回同样的speaker_diarization结构，你可以拿同一段音频对比两个版本的准确率再决定长期用哪个。

效果验证

选版本前，先看两档的真实说话人日志错误率（Diarization Error Rate，% 越低越好，官方 benchmark 数据更新于 2025-09）：

结论很直接：干净录音上两者接近，但在会议、电话等复杂数据（AMI、DIHARD 3）上高级版领先 4~5 个百分点——你的数据越嘈杂，越值得用高级版。

可选配置速查

想调整遥测（匿名使用指标）行为，只需要下面三处之一，全部列在表里：

遥测只记录模型名称、音频时长这类无法识别个人身份的信息；默认是开启的，不想参与就把环境变量设为0。

项目地图与下一步

想深入源码或教程，从这几个位置入手：

• src/pyannote/audio/pipelines/：说话人日志、语音活动检测等管道实现
• src/pyannote/audio/models/：分割、说话人嵌入等模型定义
• tutorials/：应用预训练管道、用自有数据微调等官方 notebook
• FAQ.md：常见问题汇总

到这里你已经能对一个音频文件产出完整的说话人日志结果；下一步建议打开tutorials/adapting_pretrained_pipeline.ipynb，把社区版管道微调到你自己的标注数据上，进一步压低错误率。

【免费下载链接】pyannote-audioNeural building blocks for speaker diarization: speech activity detection, speaker change detection, overlapped speech detection, speaker embedding项目地址: https://gitcode.com/GitHub_Trending/py/pyannote-audio