在标注数据上训练语音和音频模型

v2.14.0 新增

本教程在标注者于 Potato 中给出的答案上训练语音和音频模型，并把每个模型的输出作为预标签送回给标注者。本页面向已经在 Potato 中修正转写、说话轮次或动物叫声的研究负责人，他们想要一个能从这些修正中学习的模型。主线路径是导入说话人分离文件，让标注者修正说话轮次，在修正后的轮次上训练说话人分离模型，并把修正结果导出为 RTTM。随后三个较短的小节，分别在修正后的转写轮次上微调 Whisper，在声谱图上训练框检测器，以及在波形上训练声音事件标注器。关于一般的训练循环，请先读模型训练概览，从未启动过运行的话，再读训练你的第一个模型。

四个音频训练器

每个训练器只从一种方案学习，训练页面只为方案提供适合它的训练器：

每个音频训练器都从服务器磁盘上 soundfile 能打开的文件中读取录音，例如 WAV、FLAC 或 OGG，在较新的 libsndfile 下还有 MP3。像 /media/meet000.wav 这样的路径指的是任务目录的 media/ 文件夹里的文件，标注页面就是从这个文件夹播放录音的。录音是 http(s) URL 的条目会被排除在训练之外，并给出警告。请在训练之前把远程录音下载到 media/。训练器参考列出每个参数。

把训练器安装到运行 Potato 的环境中：

pip install "potato-annotation[train-audio]"

[train-audio] extra 会安装 PyTorch、transformers 和 soundfile。声谱图检测器改用 [train-vision]，或者用 pip install "potato-annotation[train]" 一次装齐全部文本、图像、音频和 LLM 训练器。缺少所需包的训练器会在训练页面上保留为“not installed”，并附上安装这些包的命令。

把说话人分离导入为 RTTM 文件

说话人分离按谁在说话把录音切分成轮次。pyannote 和 NeMo 把分离结果写成 RTTM，这是一种文本格式，每个轮次一行 SPEAKER，dscore 和 md-eval 用来给 RTTM 文件打分。每一行给出录音的文件 id、声道、轮次以秒为单位的起点和时长，以及说话人：

SPEAKER meet000 1 0.200 1.055 <NA> <NA> SPEAKER_01 <NA> <NA>
SPEAKER meet000 1 1.539 0.755 <NA> <NA> SPEAKER_00 <NA> <NA>

把 RTTM 文件和录音放进同一个文件夹，每段录音按其文件 id 命名（meet000 对应 meet000.wav），然后导入该文件夹：

potato import -f rttm -i diarization/ -o interviews \
  --speaker-map "SPEAKER_00=Interviewer,SPEAKER_01=Guest"

导入器为每段录音生成一个条目，把录音复制到 interviews/media/，并写出 config.yaml、data/diarization.jsonl 和一个 README。在本页所依据的 16 段录音的测试项目上，摘要行如下：

Imported 16 item(s), 1 question(s), 0 answer(s) from 0 annotator(s), and 16 model suggestion(s) on 16 item(s) from RTTM speaker diarization.

导入器有三个自己的标志：

• --rttm-scheme audio|tiered 选择轮次落在哪种方案上。默认的 audio 生成名为 speakers 的 audio_annotation 方案，标签就是各说话人。tiered 生成名为 tiers 的 tiered_annotation 方案，带一个 speaker 层。如果研究之后要逐轮次转写，请使用 tiered。
• --speaker-map 重命名说话人，映射中没有提到的说话人保留 RTTM 中的名字。只有当某个名字在每段录音里都指同一个人时，才使用映射。分离器在每个文件内部给说话人编号，一次访谈中的 SPEAKER_00 和下一次访谈中的 SPEAKER_00 可能是不同的人。
• --media-dir DIR 在录音不在 RTTM 文件旁边时，指明存放录音的文件夹。

导入器只读取 SPEAKER 行，并把其他行类型计为已跳过。零长度的轮次、起点为负的轮次、没有说话人名字（<NA>）的轮次，以及重复列出的轮次也会被跳过。RTTM 用空格分隔字段，导入器读取含空格的说话人名字时只读到空格处，并给出警告。导入项目完整介绍这种导入。

说话人分离的配置

生成的配置已经把导入的轮次显示为预标注。在 config.yaml 的末尾添加管理员密钥和 model_training 块。下面这个完整文件能通过 python -m potato.validate_cli config.yaml --strict：

port: 8000
annotation_task_name: diarization (imported)
task_dir: .
output_annotation_dir: annotation_output/
data_files:
- data/diarization.jsonl
item_properties:
  id_key: id
  text_key: text
user_config:
  allow_all_users: true
  users: []
site_dir: default
pre_annotation:
  enabled: true
  field: predictions
  allow_modification: true
annotation_schemes:
- annotation_type: audio_annotation
  name: speakers
  description: Check and correct who speaks when.
  source_field: audio_url
  mode: label
  labels:
  - name: Guest
  - name: Interviewer
admin_api_key: "change-me"
model_training:
  enabled: true

导入器按字母顺序排列说话人标签，Guest 排在 Interviewer 之前。模型的回写默认进入条目字段 predictions，也就是导入时 pre_annotation 块所读取的同一个字段。已启用的 pre_annotation 块指明的字段与 writeback.field 不同时，Potato 拒绝启动，因为那样不会显示任何训练预标签。在第一次运行得到值得展示给标注者的留出得分之前，请不要在配置中写 writeback。

修正说话轮次

在项目文件夹中启动服务器：

cd interviews
potato start config.yaml -p 8000

每段录音打开时，分离器的轮次已经画在波形上。标注者可以移动轮次的边缘，更改轮次的说话人，删除噪声造成的轮次，并画出分离器漏掉的轮次。只有标注者保存条目之后，预标注才会被存储。没有人打开过的条目没有答案，也不会用于训练。说话人分离标注介绍波形控件和键盘快捷键。

diarization 训练器要求 train 划分里至少有 4 段已标注的录音，而默认划分把约 70% 的已标注录音放进 train。第一次运行之前请至少修正 8 段录音，要得到可信的留出得分则需要更多。

训练说话人分离模型

打开 http://localhost:8000/admin，输入管理员密钥，然后进入 /admin/training。把 diarization 选为训练器，把 speakers 选为方案。对于同一个方案，训练页面也提供 hf-audio-tagger。hf-audio-tagger 适合标签表示声音种类而不是说话人的情形。对于两人访谈，把 Parameters 字段设为：

{"max_speakers": 2}

点击 Train now。同一次运行也可以用管理员密钥通过脚本启动：

curl -X POST -H "X-API-Key: change-me" -H "Content-Type: application/json" \
  http://localhost:8000/admin/training/api/runs \
  -d '{"trainer": "diarization", "schemas": ["speakers"], "params": {"max_speakers": 2}}'

diarization 沿用 pyannote 分割模型的做法（Bredin and Laurent, 2021），但不依赖 pyannote 及其受限的权重，并用帧分类器微调 WavLM（microsoft/wavlm-base-plus），最多支持 max_speakers 位说话人。模型每次看到 chunk_s 秒的音频，默认为 10 秒。每个音频块的损失，是在模型的说话人输出与该块已标注说话人之间取最佳匹配之下计算的。匹配之所以重要，是因为同一个说话人名字在不同录音里指的是不同的人，针对名字的分类器就没有一致的目标。下面的参数决定预测轮次的形态：

远程训练会通过 ssh 把运行发送到 GPU 服务器，或发送到 SLURM 集群。

查看说话人分离得分

运行页面和 GET /admin/training/api/status 会报告运行在留出录音上的得分。对于 diarization，主得分是 diarization_accuracy，定义为 1 减去分离错误率（DER），下限为 0。DER 把漏掉的语音、误报和说话人混淆加起来，再除以已标注的语音量。Potato 在 10 ms 的网格上、不设容差区间，并在预测说话人与已标注说话人之间取最佳一对一映射的条件下测量 DER。运行还会分别报告这三类错误。读这三个数字，就能看出模型是漏掉了语音、凭空生成了语音，还是把说话人弄混了。DER 不管一个轮次叫 Interviewer 还是 SPEAKER_01，只计算说话人是否在正确的时间发生变化。

指标名称带有划分，例如 val_der 或 test_diarization_accuracy。有已标注轮次却没有预测的录音算作错误，因此模型无法靠跳过难录音来抬高得分。

发布预测的轮次

等留出得分足以支持把模型的轮次展示给标注者之后，把该方案加入 writeback 并重启服务器：

model_training:
  enabled: true
  writeback:
    schemas: [speakers]
    include_unlabeled: true

include_unlabeled: true 还会在尚未有人修正的录音上做预测。没有该设置时，运行只在留出的 val 和 test 录音上预测。重启之后再训练一次。GET /admin/training/api/status 中的回写报告会给出数量。在测试项目上，针对 3 段 val 录音和 4 段未修正的录音，报告写的是“Published 7 prediction(s) as prelabels.”，train 划分里的录音保留了导入的 RTTM 轮次。

模型在每段录音内部按首次发言的顺序给说话人命名，先使用方案的标签，然后是 SPEAKER_00、SPEAKER_01，依此类推。因此在每段录音中最先听到的说话人，在这个项目里就是 Guest，无论这个人是不是客人。模型没有可据以识别人的声纹嵌入。一个在两个音频块的重叠部分保持沉默、之后又开口的说话人，会得到一个新名字。请告诉标注者检查每个预测轮次的说话人名字，而不只是检查轮次的边缘。循环中的模型介绍按置信度从低到高审核预标签，以及随着修正到来而重新训练。

把修正后的轮次导出为 RTTM

segments 导出会把修正后的轮次写回 RTTM，每位标注者一个文件：

python -m potato.export --config config.yaml --format segments --output ./export/

导出会写出 export/segments.jsonl（每个轮次一行）和 export/rttm/<annotator>.rttm。每个 RTTM 行中的文件 id 是去掉扩展名的录音名。之后 pyannote.metrics、dscore 或 md-eval 就能原样把分离器的原始输出与修正后的文件作对照打分。在测试项目上，export/rttm/ana.rttm 的前几行如下：

SPEAKER meet000 1 0.200 1.055 <NA> <NA> Guest <NA> <NA>
SPEAKER meet000 1 1.539 0.755 <NA> <NA> Interviewer <NA> <NA>

说话人层上的说话人分离

标注者要在同一条时间线上添加其他层（例如转写层）时，请用 --rttm-scheme tiered 导入：

potato import -f rttm -i diarization/ -o interviews --rttm-scheme tiered

导入会写出名为 tiers 的 tiered_annotation 方案，带一个 speaker 层。像上面那样添加 admin_api_key 和 model_training，并在 writeback 下写 schemas: [tiers]，配置就能通过 validate_cli --strict。diarization 在说话人层上训练，并把预测的轮次写回同一个层。训练器选择名为 speaker 或 speakers 的层。没有的话，训练器选择名字中含“speaker”的那个层，名为 non-speaker 的层不算。最后的退路是唯一带标签的那个层。有两个层符合条件，或者有几个层带标签而没有一个以说话人命名时，运行会排除这些录音，并给出点名这些层的警告。

在修正后的转写上微调 Whisper

whisper-asr 在标注者修正过的转写轮次上微调 Whisper，然后为没有人检查过的轮次建议修正。本节从一个没有转写的录音文件夹开始。

转写录音

把录音放进项目的 media/ 文件夹，并在服务器所在的机器上转写这些录音：

pip install "potato-annotation[transcribe]"
potato transcripts media --transcribe --asr-model small.en --asr-word-timestamps \
  --media-url-prefix /media -o data/interviews.json

potato transcripts --transcribe 在 WhisperX 已安装且能在该机器上运行时运行 WhisperX，否则运行 faster-whisper。[transcribe] extra 安装 faster-whisper，WhisperX 是单独安装的（pip install whisperx），并自带 PyTorch。WhisperX 缺失、无法导入、无法在该设备上运行，或无法加载模型时，Potato 会回退到 faster-whisper，摘要会给出每个文件所用的引擎。--asr-engine whisperx 或 --asr-engine faster-whisper 只运行一个引擎，不回退。--media-url-prefix /media 把每段录音的路径写成 /media/<file>，也就是标注页面播放该录音的地址。

--asr-word-timestamps 通过强制对齐为每个词计时，并让 WhisperX 在句末切分片段。在测试录音上，不带该标志时 WhisperX 为每段 10 秒的录音返回一个轮次，带该标志时每段录音三个轮次。更短的轮次为 whisper-asr 提供更多样本，而 Whisper 的输入窗口是 30 秒。转写格式和如何标注 Whisper 转写介绍转写选项、说话人标签和现有的 Whisper 输出。

转写配置

speech_transcript 方案显示转写的每个轮次，附带时间跨度和一个修正框。下面这个完整配置能通过 validate_cli --strict：

annotation_task_name: "Interview transcript correction"
task_dir: .
output_annotation_dir: annotation_output/
data_files:
  - data/interviews.json
item_properties:
  id_key: id
  text_key: conversation
admin_api_key: "change-me"
annotation_schemes:
  - annotation_type: speech_transcript
    name: transcript
    description: "Play each turn and type the right text wherever the transcript is wrong."
    segments_key: conversation
    error_types: [asr_error]
model_training:
  enabled: true
  trainer_params:
    whisper-asr:
      model_name: openai/whisper-small
      language: en

segments_key: conversation 指明 potato transcripts 写入转写所用的字段。error_types: [asr_error] 只保留一个错误标记，因为这项研究只涵盖转写错误。language: en 固定训练和预测所用的语言。不设置时，多语言 Whisper 会根据最多 16 个训练轮次检测一次语言，抽样的轮次中一致的不到四分之三时，运行日志会给出警告。

作为训练样本的修正轮次

每个修正过的轮次是一个样本，由按该轮次的起点和终点从录音中切出的音频，以及修正后的文本组成。没有人修正的轮次不是样本，因为方案只保存标注者动过的轮次，而没动过的轮次可能是对的，也可能没人读过。被标记但没有修正的轮次同样不是样本。长于 30 秒的轮次会被排除，并给出警告。train 划分里修正过的轮次少于 10 个时，训练器拒绝运行。

请修正你打开的录音上每个错误的轮次，因为留出得分是在修正过的轮次上计算的。在 12 段测试录音上，使用 tiny.en 的 WhisperX 在 36 个轮次中错了 11 个，错误包括把 Ypsilanti 写成“Epsilanti”，把 Kerrytown 写成“Cary Town”，以及轮次开头丢掉一个“I”。

训练并与转写对比

在训练页面上选择 whisper-asr 和 transcript 方案，然后点击 Train now。主得分是 word_accuracy，即 1 减去修正轮次上的词错误率（WER）。运行还会报告 wer_asr，即原始转写在同样轮次上的 WER，模型没有改动的轮次按转写的文本打分。发布任何内容之前，请先比较这两个数字。只有当模型的 WER 低于 wer_asr 时，微调后的模型才值得展示给标注者。

本页所依据的测试运行说明了这种比较为什么重要。train 里有 8 个修正轮次，min_instances 降到 4，openai/whisper-tiny 训练 3 个 epoch，运行在 test 上的 WER 为 0.31，而原始转写是 0.19。达到这一水平的模型会把正确的文本替换成错误的文本。请先收集更多修正，或者从更大的检查点开始，再训练一次，然后才添加 writeback。

发布建议的修正

等模型胜过转写之后，把方案加入 writeback，重启并再训练一次：

model_training:
  enabled: true
  trainer_params:
    whisper-asr:
      model_name: openai/whisper-small
      language: en
  writeback:
    schemas: [transcript]
    include_unlabeled: true

预测会转写每段留出录音和未标注录音的每个轮次。新文本与转写不同的轮次会成为建议的修正，标记为 asr_error，模型的平均 token 概率作为该建议的置信度。这些建议会填入修正框，标注者对每条建议选择保留、编辑或清除。

用微调后的模型转写新录音

默认情况下，运行还会在运行的产物中写出 ct2/，即模型的 int8 CTranslate2 副本。该副本需要 ctranslate2 包，[transcribe] extra 会随 faster-whisper 一并安装它。把该副本的路径传给 potato transcripts，就可以用微调后的模型转写下一批录音：

potato transcripts media/batch2 --transcribe \
  --asr-model annotation_output/training/runs/<run_id>/artifacts/ct2 \
  --media-url-prefix /media/batch2 -o data/batch2.json

WhisperX 和 faster-whisper 都能加载该副本。运行页面会显示每次运行的 id，配置介绍运行文件夹。

在声谱图上检测叫声

spectrogram_annotation 方案让标注者围绕叫声画时频框。torchvision-detect 和 ultralytics-detect 把每段录音渲染成声谱图图像，渲染方式与组件绘制声谱图的方式相同，然后在这些框上训练。渲染把频率放在线性坐标轴上，范围是方案的 min_freq 到 max_freq，max_freq 未设置时到采样率的一半，高度 256 像素，每秒 100 像素。每个框变成一个图像框。时间和频率线性映射到像素，因此框在图像上的 IoU 等于它在秒乘赫兹空间中的 IoU。没有频率范围的框（例如 Audacity 标签或 BirdNET 行给出的）覆盖整个频带。41 秒或更长的录音渲染出至少 4,096 像素宽，会被切成窗口再拼接回来。

框通常来自导入。potato import 把 Raven 选择表、Audacity 标签轨道和 BirdNET-Analyzer 的输出读入 spectrogram_annotation 项目，详见 Potato 中的生物声学和在声谱图上核对 BirdNET 检测结果。训练器从标注者画出或修正过的框中学习，检测器读取的是声谱图像素，而不是 BirdNET 或 Perch 的嵌入。

下面的配置能通过 validate_cli --strict，并把检测器的 score_threshold 设为 0.5：

annotation_task_name: "Dawn chorus calls"
task_dir: .
output_annotation_dir: annotation_output/
data_files:
  - data/recordings.jsonl
item_properties:
  id_key: id
  text_key: id
admin_api_key: "change-me"
annotation_schemes:
  - annotation_type: spectrogram_annotation
    name: calls
    description: "Draw a box around each call and pick its type."
    source_field: audio_url
    max_freq: 8000
    labels:
      - name: whistle
      - name: chirp
model_training:
  enabled: true
  trainer_params:
    torchvision-detect:
      score_threshold: 0.5
  writeback:
    schemas: [calls]
    include_unlabeled: true

16 kHz 录音的频谱止于 8 kHz，max_freq: 8000 显示整个频带。默认的 score_threshold 为 0.25，会保留检测器更多的猜测。在 24 段录音的测试项目上，默认阈值下的 torchvision-detect 在 test 录音上为 10 个已标注的叫声预测了 34 个框，每个多出来的框都是标注者还要删除的又一个框。

每个数据行指明各自的录音，例如 {"id": "site_00", "audio_url": "/media/site_00.wav"}。检测器只在至少有一个框的录音上训练，因为没有框的录音看起来与没人检查过的录音相同。检测器默认要求 train 划分里有 20 段已标注的录音（min_instances）。

torchvision-detect 从 torchvision 的 COCO 权重微调 Faster R-CNN，ultralytics-detect 训练 YOLO 检测器。YOLO 检测器训练和运行都更快。Ultralytics 采用 AGPL-3.0 许可，用 Ultralytics 训练并分发的模型适用 AGPL 的条款。运行 ultralytics-detect 之前，训练页面会请你确认许可证，API 运行需要 "accept_licence": true。两个检测器都按渲染声谱图上 IoU 0.5 的 mAP 打分，并且都以 start_s、end_s、low_hz 和 high_hz 写回预测的框，标明为模型输出，用来预填组件。视觉模型介绍检测器的参数和分块。

用 hf-audio-tagger 标注声音事件

hf-audio-tagger 学习 audio_annotation 方案中带标签的时间片段，例如语音、音乐、叫声或咳嗽。该训练器微调语音编码器（默认为 facebook/wav2vec2-base），让它说出约每 20 ms 的每一帧里哪些标签处于活跃状态。每个标签单独打分。因此带不同标签的重叠片段会按标注的样子被学习。预测的片段作为可编辑的区域回到波形上。下面的配置能通过 validate_cli --strict：

annotation_task_name: "Dawn chorus events"
task_dir: .
output_annotation_dir: annotation_output/
data_files:
  - data/recordings.jsonl
item_properties:
  id_key: id
  text_key: id
admin_api_key: "change-me"
annotation_schemes:
  - annotation_type: audio_annotation
    name: events
    description: "Mark every call on the waveform and pick its type."
    source_field: audio_url
    mode: label
    labels:
      - name: whistle
      - name: chirp
model_training:
  enabled: true
  writeback:
    schemas: [events]
    include_unlabeled: true

标注器把录音中任何没有被标注者标记的片段视为“这里没有标签”。这个假设适合标注者标记每个事件的研究，上面方案的描述要求的就是“每个叫声”。标注者只标记部分事件时，模型会学会漏掉其余的事件。主得分是片段 F1，预测片段与带同一标签的已标注片段在 IoU 至少为 0.5 时算作匹配，运行还会报告匹配片段的平均 IoU。该训练器默认要求 train 划分里有 10 段已标注的录音。

对于 audio_annotation 方案，训练页面同时提供 hf-audio-tagger 和 diarization。标签表示一种声音，并且在每段录音里含义相同时，请选择 hf-audio-tagger。标签是说话人，且说话人的名字只在每段录音内部有效时，请选择 diarization。

本页背后的运行

本页的命令和配置都是在笔记本电脑上，用下面所说的较小模型，针对 Potato 2.14.0 运行过的。说话人分离路径从头到尾都运行过：从导入 16 段合成的两人录音的 RTTM（其中 20% 的轮次被赋予错误的说话人），到修正 12 段录音，再到一次 diarization 运行和回写，直至 segments 导出。这次运行用的是单层的测试编码器，而不是 WavLM。因此这次运行的得分对真实语音没有任何说明意义。Whisper 一节用了 12 段合成语音的录音，由使用 tiny.en 的 WhisperX 转写，并从 openai/whisper-tiny 微调。声谱图和标注器两节用了 24 段 3 kHz 和 6 kHz 音调的合成录音。每个配置块都能通过 python -m potato.validate_cli --strict。

延伸阅读

• 模型训练概览介绍训练循环、训练页面和留出得分。
• 训练器列出每个训练器及其方案、安装和参数。
• 配置记录每个 model_training 键、回写和路由。
• 循环中的模型介绍审核预标签和自动重新训练。
• 音频标注介绍如何搭建分类、事件、转写和说话人分离任务。
• 转写格式列出 Potato 读取的每种转写格式。
• 上游参考逐个参数记录了 diarization、whisper-asr、hf-audio-tagger和声谱图。

参考文献

• Bain, M., Huh, J., Han, T., and Zisserman, A. (2023). WhisperX: Time-Accurate Speech Transcription of Long-Form Audio. Interspeech 2023, 4489–4493. doi:10.21437/Interspeech.2023-78
• Bredin, H., and Laurent, A. (2021). End-To-End Speaker Segmentation for Overlap-Aware Resegmentation. Interspeech 2021, 3111–3115. doi:10.21437/Interspeech.2021-560
• Chen, S., Wang, C., Chen, Z., Wu, Y., Liu, S., Chen, Z., Li, J., Kanda, N., Yoshioka, T., Xiao, X., Wu, J., Zhou, L., Ren, S., Qian, Y., Qian, Y., Wu, J., Zeng, M., Yu, X., and Wei, F. (2022). WavLM: Large-Scale Self-Supervised Pre-Training for Full Stack Speech Processing. IEEE Journal of Selected Topics in Signal Processing. doi:10.1109/JSTSP.2022.3188113
• Radford, A., Kim, J. W., Xu, T., Brockman, G., McLeavey, C., and Sutskever, I. (2023). Robust Speech Recognition via Large-Scale Weak Supervision. Proceedings of the 40th International Conference on Machine Learning, PMLR 202, 28492–28518. proceedings.mlr.press