如何零基础 5 分钟装好 pyannote.audio 并跑通说话人日志：从零到可用的实操教程-开发者社区

如何零基础 5 分钟装好 pyannote.audio 并跑通说话人日志：从零到可用的实操教程

【免费下载链接】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 是一个用于说话人日志（speaker diarization，即自动判定"录音里谁在什么时候说话"）的 Python 工具包，内置基于 PyTorch 的预训练模型，装好即可对一段音频输出"谁说了哪一段"。本文是 pyannote.audio 安装与配置的零基础实操教程：从环境自检、一行命令安装、领取访问令牌，到跑通预训练管道，全程跟着做就能得到第一个说话人日志结果。

先认识一下它

假设你有一段会议录音，想把它自动切成"说话人 A 从 6.7 秒说到 7.2 秒、说话人 B 接着说……"这样的时间轴，手工标注费时费力，这正是 pyannote.audio 要解决的事。它用 Python 编写，核心推理和建模构建在 PyTorch（主流深度学习框架）之上，预训练管道统一从 Hugging Face Hub（一个存放和共享模型的模型社区）拉取并缓存到本地，多 GPU 训练调度交给 PyTorch Lightning，而音频文件的解码则依赖系统级的 ffmpeg——少了它，库连 .wav 都打不开。

具体来说，它帮你做这些事：

语音活动检测：标出录音里哪些区间有人声、哪些是静音，让你不把算力浪费在空白段上
说话人变化检测与重叠语音检测：捕捉"换人说话"的节点，并标记两人抢话重叠的片段
说话人嵌入：为每个说话人生成一段向量"声纹"，用来区分同一个人还是另一个人，并据此聚类
开箱即用的预训练管道：几行代码直接调用，无需自己训练模型就能出日志结果

动手前的环境自检

安装前把下表过一遍，能避免 90% 的报错：

检查项	怎么查	不满足怎么办
✅ Python ≥ 3.10	终端执行`python --version`	pyannote.audio 4.x 硬性要求 3.10+，请用更新版本重建环境（conda 或 pyenv 均可）
⬜ 系统装有 ffmpeg	终端执行`ffmpeg -version`	用系统包管理器安装（如`apt install ffmpeg`或`brew install ffmpeg`），这是解码音频的底层依赖
⬜ 有模型社区的账号和访问令牌	能否登录并进入令牌管理页	免费注册账号；先在模型页接受用户条件，再创建带"读取"权限的令牌
⬜ 网络能访问模型下载源	浏览器能否打开模型仓库页	被墙或限速时设置 HTTP 代理，或改用可访问的镜像方式下载
⬜ NVIDIA GPU（可选）	终端执行`nvidia-smi`	不满足也能跑，CPU 推理只是慢一些，长音频建议配 GPU

分步安装 📦

一行命令装好 pyannote.audio

为什么：这个包的依赖很多（torch、torchaudio、lightning 等十几个），让包管理器一次性解析锁定版本，比自己逐个装能少走大量弯路。

uv add pyannote.audio

如果你不用 uv（一个更快的 Python 包管理工具），执行pip install pyannote.audio效果相同。

做对了长什么样：命令正常结束，终端执行pip show pyannote.audio能打印出包名、版本（4.x）和安装位置。

系统层装好 ffmpeg

为什么：pyannote.audio 用 torchcodec 解码音频，而 torchcodec 底层调用的是系统里的 ffmpeg，缺了它打开任何音频都会直接报错。

ffmpeg -version

做对了长什么样：第一行类似ffmpeg version 6.x ...。提示"找不到命令"就按自检表里的方式装系统 ffmpeg，装完重跑此命令确认。

接受用户条件并领取访问令牌

为什么：预训练管道存放在模型社区的"受控仓库"里——免费，但必须先登录账号、在模型页勾选接受用户条件，程序下载时也要靠访问令牌（一串账号凭据）证明你已同意。

登录 Hugging Face Hub（没有账号先免费注册）；
打开pyannote/speaker-diarization-community-1模型页，找到用户条件提示并点击同意；
在账号的令牌管理页创建一个"读取"权限的访问令牌，复制保存好。

做对了长什么样：浏览器里模型页能正常查看文件列表（如 config.yaml、模型权重文件），且你手头有一个刚创建、创建于同意条件之后的令牌。

一行验证 import 是否通过

为什么：import 失败往往是 Python 版本或依赖冲突，此时排查远比正式跑推理时排查快。

python -c "import pyannote.audio; print(pyannote.audio.__version__)"

做对了长什么样：打印出4.x.x这样的版本号，没有任何报错。

第一次运行 🚀

预训练管道本质上是托管在模型社区上的一组文件（配置 + 模型权重），首次运行会自动下载并缓存到本地，之后就走本地缓存：

用仓库自带的示例音频（一段两个人打电话的 .wav，位于src/pyannote/audio/sample/sample.wav）验证。如果手头没有克隆仓库，执行git clone https://gitcode.com/GitHub_Trending/py/pyannote-audio即可获得；有任意 .wav 也可直接替换路径。

from pyannote.audio import Pipeline pipeline = Pipeline.from_pretrained( "pyannote/speaker-diarization-community-1", token="hf_YOUR_ACCESS_TOKEN") output = pipeline("src/pyannote/audio/sample/sample.wav") for turn, speaker in output.speaker_diarization: print(f"{turn.start:.1f}s - {turn.end:.1f}s speaker_{speaker}")

首次运行会先下载管道文件，稍等片刻后应看到类似输出（两个人、时间轴基本吻合）：

6.7s - 7.2s speaker_0 7.6s - 8.2s speaker_1 8.4s - 8.9s speaker_0

看到按说话人分组、起止时间连续的时间轴，就说明 pyannote.audio 安装配置全部完成。有 NVIDIA GPU 的话，在pipeline(...)前加一行pipeline.to(torch.device("cuda"))可显著提速。

出错了先查这里 🩺

现象：pipeline(...)一开始就报错，提示找不到 ffmpeg 或 torchcodec 相关错误 →原因：系统 ffmpeg 缺失或版本过旧 →解法：按上文装好系统 ffmpeg，ffmpeg -version能打印版本号再重跑。
现象：下载时报 401 / GatedRepoError（受控仓库无权限）→原因：没在模型页接受用户条件，或令牌创建在同意条件之前 →解法：回到模型页点同意，随后新建一个"读取"权限令牌替换代码中的 token。
现象：ImportError或 torch / torchcodec 版本不匹配 →原因：环境是旧 Python（<3.10）或手动装过冲突版本的 torch →解法：用 Python 3.10+ 重建干净环境，再用pip install pyannote.audio一次装齐。