NeuTTS-Air 微调实战指南:基于 Llasa 范式训练与定制你的端侧 TTS 模型
NeuTTS-Air 微调实战指南:基于 Llasa 范式训练与定制你的端侧 TTS 模型
本指南以仓库中的 TRAINING.md 为核心,系统讲解 NeuTTS-Air 的模型微调全流程:包括其遵循的 Llasa 训练/推理范式、基于 Hugging Face transformers 的微调脚本 examples/finetune.py 的逐段原理、微调配置文件 的每个参数,以及如何编码自有数据集、切换 Qwen2.5 骨干、扩展语音 token 词汇表并加入额外标签。读完本文,你将能够复现官方微调流程,并在自己的数据集上完成端侧 TTS 模型的定制训练。
一、微调范式与模型结构概览
NeuTTS-Air 的训练与推理设置遵循 Llasa 项目范式,其核心技术思想是:用一个小型自回归因果语言模型(LLM backbone)直接以自回归方式生成"语音 token 序列",再由神经音频编解码器把这些 token 解码为波形。整个仓库正是围绕这一"LLM + codec"架构组织起来的——README.md 将这一架构概括为 Simple LM + codec architecture。
从 neutts/neutts.py 的 NeuTTS 类初始化可以看出推理侧的关键常量:
- 采样率
sample_rate = 24_000(24kHz); - 上下文窗口
max_context = 2048token,约可容纳 30 秒音频(含参考音频 prompt); - codec 帧长
hop_length = 480(对应 50Hz 帧率,即每 20ms 一帧)。
语音 token 采用 <|speech_{idx}|> 形式(如 <|speech_0|>、<|speech_1|>),推理时由模型自回归生成,再由 NeuCodec 解码为波形——解码逻辑见 neutts/neutts.py 的 _decode 方法。这种设计意味着:微调本质上就是让 LLM 学会"文本 → 语音 token 序列"的映射。
训练数据形态:文本 + NeuCodec 码
微调所用的数据是已经过 NeuCodec 编码的音频。仓库内置的微调脚本默认加载 neuphonic/emilia-yodas-english-neucodec 数据集(Emilia-YODAS 语料的英文子集,音频已用 NeuCodec 编码)。从 examples/finetune.py 的 preprocess_sample 可以看到,每条样本就是一个字典,包含两个核心字段:
text:音频对应的文本;codes:NeuCodec 编码得到的整数码序列(VQ codes)。
训练时 codes 会被转换为 <|speech_0|><|speech_1|>... 这样的语音 token 串,与音素化后的文本一起组成模型的输入输出。因此,准备自有数据集的第一步就是把音频编码成与 Emilia-YODAS 相同格式(详见本文第五节)。
[!NOTE] 仓库维护者提到,关于微调存在一个持续讨论中的议题(GitHub issue #7),已有部分用户报告使用示例脚本微调取得成功。初次上手时若遇到问题,可关注该讨论。
二、环境准备与依赖
微调脚本运行在 transformers(Hugging Face)生态之上,首先安装项目基础包(详见 README.md 的 Get Started 部分):
pip install neutts
或克隆仓库后做本地可编辑安装:
pip install -e .
如果希望使用 GGUF 量化骨干做流式推理(llama-cpp-python)或 ONNX codec 解码器(onnxruntime),可分别安装可选依赖,或直接:
pip install neutts[all]
注意:微调脚本 examples/finetune.py 除项目基础依赖(
torch、transformers、phonemizer)外,还直接 import 了fire、omegaconf、loguru、datasets。从源码 import 结构看,运行脚本前需自行补充安装这些包:pip install fire omegaconf loguru datasets
三、官方微调脚本逐段解析
examples/finetune.py 是官方提供的微调入口,整个脚本只有约 170 行,逻辑非常集中。下面按执行顺序逐段拆解,帮助你理解它做了什么、以及改自己的数据时要动哪里。
3.1 入口与配置加载
脚本用 fire 库封装入口(examples/finetune.py),第一个位置参数就是配置文件的路径:
python examples/finetune.py examples/finetune_config.yaml
main 函数用 OmegaConf.load(config_fpath) 加载 YAML 配置(examples/finetune.py),并将 checkpoint 输出目录拼接为 save_root / run_name。也就是说,训练产物(日志与权重)会落在:
{save_root}/{run_name}/ # 例如 /data/neutts-finetune/
3.2 加载预训练骨干模型
配置中的 restore_from 决定微调的起点(examples/finetune.py):
tokenizer = AutoTokenizer.from_pretrained(restore_from)
model = AutoModelForCausalLM.from_pretrained(restore_from, torch_dtype="auto")
默认值为 neuphonic/neutts-air,即官方预训练好的 NeuTTS-Air 模型(约 3.6 亿激活参数,支持即时声音克隆)。若改为 Qwen/Qwen2.5-0.5B,则相当于从零开始训练一个基于 Qwen2.5 0.5B 骨干的 TTS 模型(详见第六节)。
3.3 文本到音素:EspeakBackend 与音素器定制
文本必须先音素化(phonemize)再送入模型。脚本在 examples/finetune.py 构造了 eSpeak 后端:
g2p = phonemizer.backend.EspeakBackend(
language="en-us",
preserve_punctuation=True,
with_stress=True,
words_mismatch="ignore",
language_switch="remove-flags",
)
这里的关键参数:
| 参数 | 取值 | 作用 |
|---|---|---|
language |
"en-us" |
音素化语言;换数据集/语言时必须修改 |
preserve_punctuation |
True |
保留标点,保证与分词器切分一致 |
with_stress |
True |
输出含重音标记的音素,有助于语调 |
words_mismatch |
"ignore" |
未登录词不报错,直接跳过 |
language_switch |
"remove-flags" |
去掉语言切换标记 |
仓库在 neutts/phonemizers.py 中对同一组参数做了封装,并额外提供了一个法语音素器子类 FrenchPhonemizer,它在 clean 阶段移除法语输出中常见的连字符音节标记。这就是官方文档"按数据集/任务检查和修改 phonemizer"所指的改造点:例如微调法语模型时,可参考 FrenchPhonemizer 的做法,为你的语言补充音素清洗逻辑,并把 language 改为对应 eSpeak 语言码。
3.4 数据加载与数据过滤
脚本将数据集仓库与切分硬编码在了 examples/finetune.py:
emilia_dataset = load_dataset(
"neuphonic/emilia-yodas-english-neucodec",
split="train[:2000]",
)
注意:使用自定义数据集时,这两处(仓库名、切分)必须改成你自己的数据源。
加载后首先经过 data_filter(examples/finetune.py)进行规则清洗,任何一条命中即丢弃该样本:
text为空;- 文本含数字(
\d); - 含缩略词——点号连写(如
U.S.、A.B.C.)或连续大写(如NASA),这类文本音素化易出错; - 不以
.、,、?、!结尾; - 含
£或$货币符号。
这套过滤规则与 TTS 数据特性强相关:缩略词、数字、货币符号都容易导致音素化与发音异常,微调自有数据时建议保留。
3.5 样本预处理与监督标签构造
核心函数是 preprocess_sample(examples/finetune.py),它把一条样本变成 transformers 需要的 input_ids / labels / attention_mask 三元组。过程如下:
-
音素化:
g2p.phonemize([text])得到音素串,若结果为空会打日志并丢弃该样本(安全校验)。 -
语音 token 化:把
codes整数序列拼接成<|speech_i|>字符串。 -
构造对话式模板(关键):
user: Convert the text to speech:<|TEXT_PROMPT_START|>{音素}<|TEXT_PROMPT_END|> assistant:<|SPEECH_GENERATION_START|>{语音token串}<|SPEECH_GENERATION_END|>这个模板与推理侧
NeuTTS._apply_chat_template(neutts/neutts.py)使用的user: Convert the text to speech:... assistant:...结构完全一致,保证微调所学模式在推理时可直接复用。 -
Padding:长度不足
max_seq_len时用pad_token_id补齐,超出则截断。 -
标签掩码:
labels初始全部为-100(LLaMA 惯例,表示该位置不参与损失计算),从<|SPEECH_GENERATION_START|>位置起才把input_ids复制为标签——也就是说模型只学习预测语音 token,不学习重建文本 prompt。 -
注意力掩码:非 pad 位置为 1。
理解这一点很重要:微调的目标函数只监督"语音 token 的生成",这正是让 LLM 变成语音生成器的关键设计。
3.6 TrainingArguments 与 Trainer
训练参数在 examples/finetune.py 中构造:
training_args = TrainingArguments(
output_dir=checkpoints_dir,
do_train=True,
learning_rate=config.lr,
max_steps=config.max_steps,
bf16=True,
per_device_train_batch_size=config.per_device_train_batch_size,
warmup_ratio=config.warmup_ratio,
save_steps=config.save_steps,
logging_steps=config.logging_steps,
save_strategy="steps",
ignore_data_skip=True,
dataloader_drop_last=True,
remove_unused_columns=False,
torch_compile=True,
dataloader_num_workers=64,
)
几个值得注意的实现细节:
bf16=True:依赖支持 bf16 的 GPU/硬件,降低显存占用;torch_compile=True:启用 torch 编译以加速训练(需 PyTorch 2.x 支持);ignore_data_skip=True:断点续训时从数据集开头重新取数,避免步数漂移;dataloader_drop_last=True:batch 不满时丢弃尾部,保证步数稳定;remove_unused_columns=False:保留原始列,配合自定义预处理;dataloader_num_workers=64:数据加载线程数较高,小机器上可酌情调低。
随后用 Trainer 装配模型、tokenizer、参数、数据集,数据整理用 default_data_collator,trainer.train() 完成后调用 trainer.save_model(checkpoints_dir) 保存 HF 格式的模型与 tokenizer(examples/finetune.py)。
3.7 启动命令
在仓库根目录下执行:
python examples/finetune.py examples/finetune_config.yaml
如需使用自己的配置,把第二个参数替换为你的配置文件路径即可。
四、微调配置文件逐字段详解
examples/finetune_config.yaml 是官方提供的完整微调配置。全部字段说明如下:
# run info
restore_from: "neuphonic/neutts-air" # 微调起点:预训练 NeuTTS-Air,或 "Qwen/Qwen2.5-0.5B"
save_root: "/data" # checkpoint 根目录
run_name: "neutts-finetune" # 子目录名,最终输出到 {save_root}/{run_name}/
# model info
codebook_size: 65536 # 语音 token 词汇量(单码本 16 bit)
max_seq_len: 2048 # 训练序列最大长度,与推理侧上下文窗口一致
lr: 0.00004 # 学习率(官方建议 1e-5 ~ 4e-5)
lr_scheduler_type: "cosine" # 学习率调度器:cosine
warmup_ratio: 0.00 # warmup 比例
# train info
per_device_train_batch_size: 2 # 每张卡/每个设备的 batch size
max_steps: 10000 # 最大训练步数
logging_steps: 100 # 每多少步打一次日志
save_steps: 20000 # 每多少步保存一次 checkpoint
seed: 1337 # 随机种子
各参数与源码的对应关系及官方经验建议:
restore_from:微调起点权重。保持neuphonic/neutts-air做领域/音色微调;改成Qwen/Qwen2.5-0.5B则从零训练(见第六节)。codebook_size = 65536:NeuCodec 单码本 16 bit 编码,即语音 token 为<|speech_0|>到<|speech_65535|>。从零训练时需据此批量扩充词汇表(见第六节代码)。注意:当前脚本本身未直接消费该字段,它主要用于"添加 token"的代码段(见 TRAINING.md 的示例代码)。max_seq_len = 2048:与NeuTTS.max_context(neutts/neutts.py)一致,对应约 30 秒音频(含参考 prompt)。lr:官方经验——学习率在1e-5到4e-5之间通常效果较好,具体取值取决于数据集规模。配置文件默认0.00004。- 步数:官方经验——微调通常不需要太多步数。例如 10 小时的数据集,1000~2000 步往往就足够。默认
max_steps: 10000是一个偏保守的上限。 warmup_ratio与调度器:官方建议可尝试不同的 warmup 比例 与 学习率调度器(如 cosine、linear),找到最适合自己数据集组合。seed、lr_scheduler_type:从源码结构看,examples/finetune.py 目前只消费了lr、max_steps、per_device_train_batch_size、warmup_ratio、save_steps、logging_steps等字段,seed与lr_scheduler_type尚未传入TrainingArguments。若需要,可在脚本中补充seed=config.seed与lr_scheduler_type=config.lr_scheduler_type。
五、在自己的数据集上微调:四步流程
官方文档给出四条步骤,结合源码细节展开如下:
第 1 步:用 NeuCodec 编码你的音频
将自有音频用 NeuCodec 编码成与 neuphonic/emilia-yodas-english-neucodec 相同的数据格式。仓库提供了独立的参考编码脚本 examples/encode_reference.py,其核心逻辑(L16-L26)展示了一条音频如何变成码序列:
from librosa import load
from neucodec import NeuCodec
import torch
codec = NeuCodec.from_pretrained("neuphonic/neucodec")
codec.eval().to("cpu")
wav, _ = load(ref_audio_path, sr=16000, mono=True) # 16kHz 单声道加载
wav_tensor = torch.from_numpy(wav).float().unsqueeze(0).unsqueeze(0) # [1, 1, T]
ref_codes = codec.encode_code(audio_or_path=wav_tensor).squeeze(0).squeeze(0)
批量准备微调数据时,需要对整个数据集逐条执行上述编码,产出包含 text 与 codes 两列的 Hugging Face datasets.Dataset(这正是 preprocess_sample 读取的字段),即可接入微调流程。
第 2 步:准备配置文件
参照 examples/finetune_config.yaml 复制一份自己的配置,重点修改:
save_root/run_name:输出目录;lr、max_steps:按第四节的经验区间设置;per_device_train_batch_size:按显存调整。
第 3 步:检查并修改 phonemizer 与 tokenizer
让两者适配你的数据集/任务:
- phonemizer:修改 examples/finetune.py 中的
language参数(例如德语de、法语fr-fr、西班牙语es,与 BACKBONE_LANGUAGE_MAP 的语言码体系一致);必要时参考 neutts/phonemizers.py 的FrenchPhonemizer,实现自己语言的音素后处理(如去除多余符号)。 - tokenizer:若使用 Qwen 骨干或要加自定义标签,需按第六节的代码扩充词汇表。
- 数据集:同时把 examples/finetune.py 硬编码的数据集名称与切分替换为自己的数据源。
第 4 步:运行微调脚本
在仓库根目录执行:
python examples/finetune.py examples/finetune_config.yaml
若使用自己的配置,替换第二个参数为对应路径。训练日志输出到 {save_root}/{run_name}/,最终模型权重也保存于此。
六、从零训练或引入额外标签
6.1 切换到 Qwen2.5 骨干
NeuTTS-Air 模型的 LLM 骨干基于 Qwen2.5 0.5B。若想从零训练(而非基于预训练 TTS 模型微调),只需把配置文件中的 restore_from 改为:
restore_from: "Qwen/Qwen2.5-0.5B"
6.2 扩展词汇表:语音 token 与自定义标签
使用 Qwen 骨干时,其原始词汇表不包含语音 token,必须把语音 token 标签加入模型词汇表。此外,无论 Qwen 还是 NeuTTS,都可以继续添加自定义标签来开启额外能力。这两步在加载模型后执行,完整代码(源自 TRAINING.md):
codec_special_tokens = [
# speech token tags to add if using Qwen
"<|TEXT_REPLACE|>",
"<|TEXT_PROMPT_START|>",
"<|TEXT_PROMPT_END|>",
"<|SPEECH_REPLACE|>",
"<|SPEECH_GENERATION_START|>",
"<|SPEECH_GENERATION_END|>",
# optional additional tags that you can add to enable features if you have the labels in your dataset
"<|EN|>",
"<|ZH|>",
"<|LAUGHING|>",
"<|WHISPERING|>",
]
codec_tokens = [f"<|speech_{idx}|>" for idx in range(config.codebook_size)]
new_tokens = codec_special_tokens + codec_tokens
n_added_tokens = tokenizer.add_tokens(new_tokens)
model.resize_token_embeddings(len(tokenizer), mean_resizing=False)
model.vocab_size = len(tokenizer)
这段代码的要点:
- 前三对特殊 token(
<|TEXT_REPLACE|>、<|TEXT_PROMPT_START/END|>、<|SPEECH_REPLACE|>、<|SPEECH_GENERATION_START/END|>)是推理模板必需的控制标记——其中TEXT_PROMPT_*与SPEECH_GENERATION_*出现在训练/推理的对话模板中,TEXT_REPLACE与SPEECH_REPLACE则被推理侧的_apply_chat_template(neutts/neutts.py)用于占位替换。 <|speech_{idx}|>共codebook_size个(默认 65536),与 NeuCodec 单码本容量一一对应,idx直接映射编码得到的整数码。tokenizer.add_tokens(new_tokens)后,model.resize_token_embeddings(len(tokenizer), mean_resizing=False)扩展 embedding 矩阵(mean_resizing=False表示新 token 用随机初始化而非均值填充),随后同步model.vocab_size。
示例中的 <|EN|>、<|ZH|>、<|LAUGHING|>、<|WHISPERING|> 是可选的自定义标签:只要你的数据集里有对应标注(语言、笑声、耳语等),就能通过标签让模型学会条件生成。
6.3 将额外标签注入模型输入
添加标签之后,需要把它们拼进模型的输入。官方文档给出的思路是:如果数据里有说话人 ID(speaker ID)或情感(emotion)标签,在把文本音素传给模型之前,将标签与音素 token 拼接在一起。落到 preprocess_sample(examples/finetune.py)中,即把标签 token 与 phones 一同放入对话模板的 TEXT_PROMPT_START/END 区间,例如:
phones = f"<|EN|> {phones}" # 语言标签前置
# 或加入说话人/情感标签,如 "<|SPK_ANDY|> <|HAPPY|> {phones}"
chat = f"""user: Convert the text to speech:<|TEXT_PROMPT_START|>{phones}<|TEXT_PROMPT_END|>\nassistant:<|SPEECH_GENERATION_START|>{codes_str}<|SPEECH_GENERATION_END|>"""
由于标签对模型而言与普通 token 无异,模型会在监督信号下自动学到"出现某标签 → 生成相应风格的语音 token",从而在推理时通过同样方式注入标签来控制输出。
七、验证微调结果与部署衔接
7.1 用测试用例验证推理链路
仓库的测试 tests/test_neutts.py 覆盖了骨干 + codec 的组合加载与推理验证:_QUICK_BACKBONES 中的 neuphonic/neutts-air 与 neuphonic/neutts-air-q4-gguf 会与 neuphonic/neucodec、neuphonic/distill-neucodec、neuphonic/neucodec-onnx-decoder 三种 codec 交叉测试(L17-L21),断言输出为非空、无 NaN 的 numpy 波形。微调完成后可用同款思路快速验证:加载新权重 → infer() → 检查波形有效。
安装开发依赖后运行全部测试:
pip install -r requirements-dev.txt
pytest tests/
7.2 训练模板与推理模板的一致性
微调脚本训练的是"文本音素 → 语音 token"的映射,而推理侧 NeuTTS 类通过 _apply_chat_template 与 _infer_torch(neutts/neutts.py)构造完全同构的 prompt,并让 LLM 自回归生成直到 <|SPEECH_GENERATION_END|>。因此微调产物可以直接接入 NeuTTS 的推理管线:trainer.save_model(checkpoints_dir) 保存的是 HF 格式 checkpoint,从源码结构看,NeuTTS._load_backbone 的 PyTorch 路径基于 AutoTokenizer.from_pretrained / AutoModelForCausalLM.from_pretrained(neutts/neutts.py),本地 checkpoint 目录原则上可直接作为 backbone_repo 传入。
需要注意:语言映射表 BACKBONE_LANGUAGE_MAP 只覆盖官方模型(en-us / de / fr-fr / es)。使用非官方或自定义微调模型时,NeuTTS 初始化必须显式传入 language 参数(否则会抛出 ValueError,见 neutts/neutts.py)。
7.3 端侧部署配套
微调完成后,如需部署到端侧,仓库还提供两条配套路径(详见 README.md 与 examples/README.md):
- GGUF 量化:基于
llama-cpp-python的量化骨干,支持流式推理(infer_stream),官方流式示例见 examples/basic_streaming_example.py; - ONNX codec 解码器:
neuphonic/neucodec-onnx-decoder可让推理时无需加载编码器,进一步降低延迟与内存(示例见 examples/onnx_example.py)。
结语
NeuTTS-Air 的微调链路非常"标准":基于 transformers 的 Trainer 训练自回归 LLM 生成 NeuCodec 语音 token,数据集只需"文本 + 编码后的码序列"两列即可接入。官方脚本的默认配置面向英文与 Emilia-YODAS,做自有数据微调时,需要修改的集中在四处:数据集加载、音素器语言、tokenizer 词汇表(如需自定义标签)、训练超参数。掌握了 examples/finetune.py 的数据过滤、标签掩码与对话模板设计,以及 finetune_config.yaml 的参数语义,你就可以按本文的流程训练出属于自己的端侧 TTS 模型,并平滑接入仓库的推理与部署体系。