企业官网建设流程全解析

最近整理会议录音的时候，我遇到一个特别头疼的问题：一段录音里三四个人在说话，有人提问有人补充，还有人插嘴打断，手动标注“这段是谁说的”“那几句是回答谁的”，光是听写就耗掉整个下午。后来我干脆把整段音频直接丢给 Whisper 转写，结果更乱，两个人同时开口的部分被揉成一团，出来的文字根本分不清哪句是哪个人说的。

折腾了几天之后，我定下来一套本地处理方案：Pyannote 负责把不同说话人从时间轴上分开，Whisper 负责把每一段声音转写成文字。两者一前一后串成管道，输入一个录音文件，输出就是带说话人标签和精确时间戳的逐字稿。实测下来，一小时左右的音频在普通显卡上十几分钟就能跑完，关键是完全本地运行，适合会议记录、访谈整理、播客后期这些场景。

这篇文章会把整套实现思路、完整可运行的代码、参数调优经验，以及我实际踩过的坑全部写下来。你不需要很强的音频基础，只要会装 Python 包、能看懂基本代码，就可以照着我这套流程复现。

1. 项目背景与方案选型

1.1 需求场景：当一段录音里有多个人说话

带说话人分离的语音转文字，跟普通的语音转文字完全是两个难度级别。普通转写字幕只需要做 ASR（自动语音识别），模型拿到音频后直接吐文字；但如果要在转写结果里区分“谁说了什么”，就必须先做说话人分离（Speaker Diarization），也就是“这一段是哪个人在说、那一段是哪个人在说”，然后再对每一段分别做语音识别。

实际使用中，这类需求最常见的就是会议纪要。公司内部讨论会、客户访谈、播客录音、法院庭审记录，甚至记者的采访录音，都会碰上一段声音文件里有多个人轮番发言的情况。如果只是想把录音变文字稿，那么任何一款语音转文字工具都能做到；但如果想直接生成一份“发言人A：内容”、“发言人B：内容”这样格式清晰的会议纪要，就绕不开说话人分离。

而且这里要澄清一个概念：说话人分离并不等于说话人识别。说话人识别要做的是“声纹比对”，告诉你这位发言人是张三还是李四；而分离只做“按声纹归类”，把相同音色的片段归为同一个标签，输出结果往往是 speaker_0、speaker_1 这样的代号。对大多数转写场景来说，先得到代号级别的分离，再由人来对照填写身份，已经足够用了。

1.2 技术方案对比：为什么选择 Pyannote + Whisper

市面上的说话人分离方案不算少，但我最终选择 Pyannote + Whisper 的组合，主要有三个原因。

第一个原因是Pyannote 是目前开源社区里效果最稳的说话人分离工具。它基于声纹嵌入（embedding）和聚类算法实现，背后是大量真实音频数据集训练出来的模型，在常见的中文会议录音上表现不错。官方提供的speaker-diarization-3.1模型，一行代码就能加载，不需要自己训练模型，大大降低了使用门槛。

第二个原因是Whisper 对中文的支持足够好。Whisper 是 OpenAI 开源的语音识别模型，训练数据覆盖了多种语言（包括中文），即使不用任何特殊微调，日常会议、访谈录音里的中文识别准确率也能达到实用水平。更重要的是它在长音频上不会像一些轻量模型那样出现严重漏字、错字的问题。

第三个原因是整套方案都可以本地运行。录音内容往往涉及隐私，直接上传到云端 API 转写有风险；而 Pyannote 和 Whisper 都可以完全离线运行，录音文件不出本机，对隐私保护更友好。

当然，Pyannote 也有替代方案，比如 Kaldi 体系的 diarization 工具，效果也不错，但配置复杂度高了一截；还有商业化的声纹分离 SaaS，按分钟计费，对高频用户来讲成本可观。Pyannote 的优势就是“零训练 + 开源 + 效果稳定”，和 Whisper 搭在一起，正好补足了 Whisper 没有说话人信息的短板。

1.3 核心处理流程总览

整个系统的处理流程可以理解为一条流水线：

原始音频 -> 预处理（格式转换、重采样） -> Pyannote 说话人分离 -> 得到多段带说话人标签的时间片段 -> Whisper 逐段转写 -> 合并结果输出

用生活里的话说，Pyannote 负责“分座位”，Whisper 负责“记笔记”。Pyannote 先把一整段音频切成不同说话人的片段，生成一个包含start_time / end_time / speaker的记录表；Whisper 拿到这些片段后，把每一小段音频转成文字；最后再做一个合并步骤，按照时间排序，把同一说话人的连续发言拼接起来，输出干净、可读的文字稿。

这个流程看起来简单，实际操作里涉及细节不少：比如 Pyannote 的时间戳精度如何控制、Whisper 一次转写多长时间的音频效果最好、两个工具之间如何互相传递音频数据，这些我都会在后面的代码解读里逐一说明。

2. 环境准备与依赖安装

2.1 基础环境与硬件建议

先说硬件。带说话人分离的语音转文字属于计算密集任务，有 NVIDIA 显卡会舒服很多。我的主力机器是一块 8GB 显存的 RTX 3060，跑 Pyannote 3.1 模型和 Whisper small 模型都没有压力；如果是 4GB 显存的老显卡，建议 Whisper 用 tiny 或 base 模型，或者干脆用 CPU 跑，多花点时间而已。

没有显卡也不用怕，CPU 完全可以运行，只是速度会慢几倍。实测下来，一段 40 秒的音频在 CPU 上用 Whisper small 模型转写大约需要 30 秒左右，勉强还能接受；一小时的录音就比较折磨人了，可能得跑半个小时以上。

操作系统上，Windows、Linux、macOS 都支持。我个人更推荐 Linux 或 WSL，因为在处理 ffmpeg 等依赖时更方便；但如果你已经习惯 Windows，装好对应依赖也能跑，后面会给出处理方法。

Python 版本建议 3.9 及以上，安装时最好用 conda 或 venv 新建一个独立的环境，避免和项目里的其他依赖打架。

conda create -n whisper_pyannote python=3.10 conda activate whisper_pyannote

2.2 安装 Pyannote、Whisper 与 ffmpeg

依赖安装是整个项目里最琐碎的环节，我按顺序一个个来。

先安装 PyTorch。如果你有 NVIDIA 显卡，要按你的 CUDA 版本安装对应的 PyTorch，例如 CUDA 12.1：

pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu121

这里提醒一句，PyTorch 和 CUDA 版本要匹配，不然后面的 CUDA out of memory、驱动版本报错会特别频繁。不确定自己 CUDA 版本的，在终端跑一下nvidia-smi，看右上角版本号就行。

接着安装 Pyannote：

pip install pyannote.audio

然后是 Whisper。这里我用的官方版openai-whisper：

pip install openai-whisper

最后是 ffmpeg。Whisper 依赖 ffmpeg 来解码音频文件，这一步很容易被忽略。Windows 上，我建议直接用包管理器安装，或者把 ffmpeg 的 exe 下载后放进 PATH；Linux/macOS 上用 apt/brew 一行搞定：

sudo apt update && sudo apt install ffmpeg

装完之后，在命令行里输入ffmpeg -version能正常输出版本号，说明解码环境没问题。

辅助工具这边，我还会用到pydub来切分音频片段，它底层还是依赖 ffmpeg，但接口更友好：

pip install pydub soundfile

soundfile用于直接读写 WAV 文件，对后面做音频切片很有帮助。

2.3 Hugging Face 模型授权与 Token 配置

Pyannote 的预训练模型托管在 Hugging Face 上，加载之前需要做两件事：注册一个 Hugging Face 账号，在模型页面同意使用条款，然后生成一个 Access Token 供本地代码读取。

具体步骤如下：

1. 访问 Hugging Face 官网并登录账号。
2. 打开pyannote/speaker-diarization-3.1和pyannote/segmentation-3.0两个模型页面，点击同意条款。
3. 在个人设置里创建一个 Access Token（Read 权限即可），复制保存。

拿到 Token 后，可以直接在代码里通过use_auth_token参数传入，也可以先用命令行登录：

huggingface-cli login

然后粘贴 Token 回车。很多问题，比如报401 Unauthorized或403 Forbidden，十有八九就是这一步没完成。我最初调试时就是漏掉了同意模型使用条款，卡了好一阵子。

Token 配置好之后，首次运行会从 Hugging Face 下载模型权重，体积大概几百 MB，视网速可能要点时间。网络状况不好的话，下载会比较痛苦；这时候可以考虑在国内镜像站点手动下载模型包，然后放到本地缓存目录。这个属于环境优化，会在常见问题部分再展开。

3. 完整代码实现与关键参数说明

3.1 用 Pyannote 提取说话人时间轴

核心第一步，是用 Pyannote 的Pipeline加载说话人分离模型，然后对音频文件做 diarization。

话不多说，先看代码：

import torch from pyannote.audio import Pipeline # 从 Hugging Face 加载预训练模型 pipeline = Pipeline.from_pretrained( "pyannote/speaker-diarization-3.1", use_auth_token="hf_你的token", ) # 如果有 GPU，使用 GPU 加速 pipeline.to(torch.device("cuda")) # 执行说话人分离 diarization = pipeline( "meeting.wav", min_speakers=2, max_speakers=4, ) # 遍历分离结果，拿到每个说话人的时间区间 for turn, _, speaker in diarization.itertracks(yield_label=True): print(f"start={turn.start:.1f}s stop={turn.end:.1f}s speaker={speaker}")

代码里几个要重点解释的参数：

min_speakers和max_speakers是给 Pyannote 的先验说话人数量范围。如果你提前知道这段录音里有多少人发言，设置范围之后分离准确率会明显提高。比如我知道这是一场两人对话，直接设min_speakers=2, max_speakers=2，模型就不会把一个人因为不同情绪的变化误分成两个说话人；如果完全不清楚人数，就设宽一点，比如min_speakers=1, max_speakers=8。

itertracks(yield_label=True)是 Pyannote 的遍历方式，返回的内容包含三个部分：turn是一个时间段对象（有start和end属性，单位秒）、_是轨道信息（这里不用）、speaker是说话人编号。

这里特别注意：Pyannote 的输出时间戳精度不是绝对的，即便模型对说话人切换很敏锐，在说话人重叠、有停顿、有环境噪声时，边界也可能有零点几秒的误差。如果拿来做字幕级别的精确时间轴，建议在代码里加入一个“边界扩展”的逻辑，让每段识别区间略微重叠一部分，避免把语音片段切断导致转写丢字。

接下来保存分离结果到本地，方便后续处理：

with open("diarization.txt", "w", encoding="utf-8") as f: for turn, _, speaker in diarization.itertracks(yield_label=True): f.write(f"{turn.start:.2f} {turn.end:.2f} {speaker}\n")

这一步生成的diarization.txt就是整个说话人分离的核心产物，每一行代表一段“某人在某个时间段内说话”。有了它，后面的 Whisper 转写就变成了一个“拿着时间轴去切音频、再逐段识别”的过程。

3.2 用 Whisper 逐段转写并合并结果

拿到说话人时间轴之后，下一步要做的是把原始音频按这些时间段切割出来，再交给 Whisper 逐段识别。这里有一个实现上的取舍：直接对整段长音频调用 Whisper 也可以，但我们已经在 Pyannote 阶段得到了时间信息，所以最好按片段分别传给 Whisper，这样既能避免长音频模型上下文长度限制，又方便把识别结果挂到一个具体的说话人下面。

我采用的方案是：先把整个音频读入内存，转换成 WAV 格式，然后用时间戳切片，这样比反复读写临时文件更快更稳。直接看代码：

import whisper import soundfile as sf import numpy as np # 读取音频（soundfile 会把音频转为 numpy 数组） audio, sample_rate = sf.read("meeting.wav") # 如果音频是双声道，先取单声道（Whisper 会自己处理，单声道更保险） if audio.ndim > 1: audio = audio.mean(axis=1) # 加载 Whisper 模型 model = whisper.load_model("small") def transcribe_segment(start, end): start_sample = int(start * sample_rate) end_sample = int(end * sample_rate) segment_audio = audio[start_sample:end_sample] result = model.transcribe( segment_audio, language="zh", fp16=False, # CPU 跑必须 False；GPU 可开 True 加速 temperature=0.0, # 固定温度，减少随机性导致的文本飘忽 ) return result["text"].strip() # 假设这是上一步 Pyannote 输出的结果列表 segments = [ {"start": 0.0, "end": 5.2, "speaker": "speaker_0"}, {"start": 5.8, "end": 12.6, "speaker": "speaker_1"}, # ... ] transcript = [] for seg in segments: text = transcribe_segment(seg["start"], seg["end"]) if text: transcript.append((seg["speaker"], seg["start"], seg["end"], text)) for speaker, start, end, text in transcript: print(f"[{speaker}] {start:.1f}s - {end:.1f}s：{text}")

这里的核心参数解释一下：

• language="zh"：明确告诉 Whisper 识别中文，避免它在开始的几十秒里通过静默或语气词猜语言，浪费上下文窗口。
• temperature=0.0：Whisper 的采样温度。日常转写建议设为 0，让它每次都输出“最可能”的文本，而不是产生随机变体；遇到重复文本或幻觉严重的音频，再适当调高温度试试。
• fp16=False：如果跑在 CPU 上，必须设成 False，否则会报类型错误；GPU 上设为 True 能明显提速，显存占用也更小。

上一步的 Pyannote 输出格式和这里的segments列表结构是匹配的，实际使用时，你只需要把diarization.itertracks(yield_label=True)的循环结果塞进这个列表即可。

3.3 让结果更好用：导出带说话人标签的文本和 SRT

识别结果仅仅打印到终端还不够，实际项目里往往需要保存成文件。我会同时输出两种格式。

第一种是纯文本格式，适合直接放进会议纪要或作为邮件正文。实现时，同一个说话人的连续发言会被合并成一段，中间没有其他说话人打断：

from collections import OrderedDict def save_plain_text(transcript, output_path): merged = [] for speaker, start, end, text in transcript: if merged and merged[-1][0] == speaker: # 同一个说话人连续发言，直接拼接到上一段 merged[-1][2] = end merged[-1][3] += " " + text else: merged.append([speaker, start, end, text]) with open(output_path, "w", encoding="utf-8") as f: for speaker, start, end, text in merged: f.write(f"[{speaker}] ({start:.1f}s - {end:.1f}s)\n{text}\n\n")

第二种是 SRT 字幕格式。如果后续需要做视频字幕，或者想在播放器里同步显示说话人，这种格式更方便：

def save_srt(transcript, output_path): def format_ts(seconds): ms = int((seconds - int(seconds)) * 1000) s = int(seconds) m, s = divmod(s, 60) h, m = divmod(m, 60) return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}" lines = [] idx = 1 for speaker, start, end, text in transcript: lines.append(str(idx)) lines.append(f"{format_ts(start)} --> {format_ts(end)}") lines.append(f"{speaker}: {text}") lines.append("") idx += 1 with open(output_path, "w", encoding="utf-8") as f: f.write("\n".join(lines))

一个实际的处理建议：如果在导出时发现同一说话人的多个片段之间的间隔非常短（比如只有 0.2 秒），这往往是 Pyannote 把一句完整的、但中间有短暂停顿的话切成了多段。此时可以把间隔小于 0.3 秒的相邻片段合并，再交给 Whisper 转写，识别出来的中文会更连贯，不会出现一句话被硬生生从中间切开的别扭感。

我在实际使用时的经验是：把整段说话人分离结果先做一次“间隔合并”，再做 Whisper 转写，最后再合并同一个说话人的连续片段。这样经过两层合并之后，输出的文本质量明显要比直接按原始切分转写好很多。

到这里，最核心的代码逻辑已经完整了。你只需要把自己录音文件的路径替换到代码里，跑完就能得到带说话人的文字稿。

4. 实操测试与效果调优

4.1 一次真实会议录音的测试过程

为了验证整套流程，我拿了一段三人线上会议的测试音频，时长约 40 秒，内容是典型的“一人提问、两人回答”模式。测试环境是 RTX 3060 8GB、CUDA 12.1，Pyannote 3.1 + Whisper small。

跑 Pyannote 分离时，我设置了min_speakers=2, max_speakers=4，因为会议中可能会出现第四个人的零星发言。分离结果如下：

start=0.8s stop=8.2s speaker=speaker_0 start=8.7s stop=15.1s speaker=speaker_1 start=15.8s stop=22.6s speaker=speaker_0 start=23.2s stop=34.5s speaker=speaker_2 start=35.1s stop=40.0s speaker=speaker_0

可以看到，三人分离效果基本正确。speaker_0 出现了三次发言，中间被 speaker_1 和 speaker_2 打断，这正是真实对话里常见的“轮换发言”模式。

紧接着用 Whisper small 逐段转写，温度设为 0，语言指定为中文。转写结果里只有 speaker_0 的最后一段出现了一个字的口误（“这个方案”被识别成“那个方案”），其余内容准确率很高。整段处理耗时大概 10 秒左右，速度还是让人满意的。

测试中也发现：如果直接把 40 秒音频整体丢给 Whisper 转写，虽然也能输出文字，但没有任何说话人信息，几个人轮流发言时，文字内容表面看起来连贯，实际串了多个人的话。经过 Pyannote 分离之后再逐段转，每个片段内部都是同一个人的声音，识别结果也更专注于单一说话风格和内容。

4.2 影响准确率的关键参数与调优经验

在使用过程中，我总结出几个影响最终输出质量的关键参数。

第一个是Pyannote 的说话人数量范围。这个参数直接决定聚类算法的行为。预设太窄，模型可能硬把两个混在一起的说话人归为一个人；预设太宽，模型可能把同一个人在不同情绪下的声音误拆成两个人。我的经验是：在能确定人数的情况下，把范围收窄到最小。比如知道是两人访谈，就min_speakers=2, max_speakers=2；不确定时，宁可放宽，也不要漏人。

第二个是Whisper 的模型大小。Whisper 提供 tiny、base、small、medium、large 多个档位。中文场景下，我实测 small 已经能覆盖绝大多数会议、访谈内容，准确率与 medium 差距不大但速度快很多；遇到专业术语、方言、背景噪声较大的音频，再换 medium 甚至 large。有一点要注意：模型越大，对显存要求越高，而且 large 在 8GB 显存上已经比较紧张，容易 OOM。

第三个是输入音频的质量。这可能听起来不是“参数”，但效果影响很大。Pyannote 和 Whisper 都对较干净、较少混响的音频更友好。如果是多人通过不同设备接入的线上会议录音，每个人的音量、音色差异大，反而是优势，分离更容易；但如果是单麦克风近距离录音、周围有风扇或电视噪声，建议先做降噪处理，否则分离边界会变模糊。

第四个是时间戳边界处理。前面提到过，Pyannote 的边界不一定完全贴着字边界，如果对时间要求严格，可以尝试在切分音频时前后各扩展 0.2 到 0.3 秒。比如 Pyannote 说是 8.0 秒到 12.0 秒，实际切片时切 7.8 秒到 12.3 秒，这样能避免语音开头和结尾被切掉。

4.3 长音频与批处理优化

处理完整的一小时会议录音时，直接把整个文件丢给 Pyannote 和 Whisper 虽然也能工作，但有几个隐藏问题：一是 Pyannote 在超长音频上处理时间会线性增加，二是 Whisper 的转写上下文有限，三是如果中途某个片段出错，就得全量重跑。

我建议在进入 Pyannote 之前，先用 ffmpeg 或 pydub 对音频做一个“静音切分”。具体做法是检测幅度低于某个阈值的静音区间，把长音频切成 5 到 10 分钟的块，然后逐块处理，最后合并结果。

from pydub import AudioSegment from pydub.silence import split_on_silence audio = AudioSegment.from_wav("long_meeting.wav") chunks = split_on_silence( audio, min_silence_len=800, # 静音持续 800ms 以上视为断点 silence_thresh=-40, # 低于 -40dBFS 视为静音 keep_silence=500, # 保留边缘 500ms 静音，防止切断说话 ) for i, chunk in enumerate(chunks): chunk.export(f"chunk_{i}.wav", format="wav")

切出来的块数如果偏多，还可以用faster-whisper替换官方 Whisper。faster-whisper 是 Whisper 模型的 CTranslate2 实现，推理速度通常是官方版本的两到四倍，显存占用也更低，接口基本兼容。切换方法很简单：

from faster_whisper import WhisperModel model = WhisperModel("small", device="cuda", compute_type="float16") segments, info = model.transcribe("segment.wav", language="zh", beam_size=5) text = " ".join(seg.text.strip() for seg in segments)

我自己在长音频批处理场景下已经切换到了 faster-whisper，速度提升非常明显，唯一的代价是输出格式和官方版本略有差异，需要多写几行代码拼接结果。如果只是偶尔处理几个文件，官方版也完全够用。

5. 常见问题排查与经验总结

5.1 高频报错速查表

这几天调试下来，我整理了开发中最高频的报错及对应排查手段，放在下面这张表里，基本能覆盖 90% 的启动阶段问题。

其中401 Unauthorized是新手最容易踩的坑。很多人以为注册了 Hugging Face 账号、生成了 Token 就万事大吉，实际上 Pyannote 的模型是 gated model，必须在模型页面上单独点击同意条款，否则模型文件下载没权限。这个坑比较隐蔽，因为报错往往不会提示“你同意一下协议”，只会说“Unauthorized”。

5.2 避坑心得与使用建议

最后分享几个实际项目里磨出来的使用建议。

一是先跑小模型验证整套流程，再换大模型。第一次复现时，先用 Whisper tiny 跑通 30 秒的测试音频，确认 Pyannote 分离、音频切片、Whisper 转写、结果导出每个环节都没问题，再切换到 small 或 medium 处理长音频。这样能极大减少调参和排错的成本。

二是音频格式统一转成 16kHz 或 22kHz 的单声道 WAV。Pyannote 和 Whisper 内部都有重采样逻辑，但前置步统一转好，可以减少不确定性。在这方面，ffmpeg 是万能的：

ffmpeg -i input.m4a -ac 1 -ar 16000 output.wav

-ac 1表示单声道，-ar 16000表示 16kHz 采样率。录音文件是 m4a、mp3、ogg 都没关系，提前转成标准 WAV 能省掉很多后续兼容问题。

三是同一段录音不要反复跑分离，把时间轴缓存下来。Pyannote 分离的时间轴结果本身就是文本，保存下来之后，后续更换 Whisper 模型、调整转写参数时，不需要重新跑分离，直接复用这份时间轴即可。我在批量处理系列录音时，通常会把每段录音的 diarization 结果存成一个 JSON 或 TXT，下次再处理就是纯文本加载，大幅缩短迭代时间。

四是如果内容里有大量专业术语（人名、产品名、代码关键词），通过initial_prompt提示 Whisper。Whisper 支持一个初始提示参数，可以在转写前把“可能会出现的词汇”塞进去，帮助模型在解码时倾向输出这些词。示例：

result = model.transcribe( segment_audio, language="zh", initial_prompt="以下是一些专有名词：Whisper、Pyannote、Transformer、CUDA、gated model。", )

这个技巧尤其适合技术会议和产品评审录音，能明显减少人名和术语的错字率。

五是我个人的经验：处理长录音时，不要试图一次性转写所有片段，先看 Pyannote 的分离结果里有没有异常（比如单个 speaker 时间占比高得不正常、某段音频时长超过 30 秒还没切换）。如果发现异常，优先处理这些有问题的片段，再跑全量。这套预处理习惯帮我避免过很多次“跑了一晚上，最后发现结果串人”的尴尬局面。

现在我的日常流程已经固定成一套脚本，输入一个文件夹路径，脚本自动查找所有录音文件，依次做格式转换、说话人分离、分段转写、导出文本和 SRT。跑完一小时的会议录音，通常十几分钟后就有一份干净、带说话人标签的初稿，剩下的工作就是人工核对一遍时间和错字。如果你经常处理多人录音，这套组合方案值得花半小时搭一下，后续的效率提升完全是值得的。