NeuTTS-Air 微调实战指南:基于 Llasa 范式训练与定制你的端侧 TTS 模型

原创2026-10-14 17:49:291,633 阅读
文章标签:语音音频处理本地部署大模型微调深度学习模型量化

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 = 2048 token,约可容纳 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)进行规则清洗,任何一条命中即丢弃该样本:

  1. text 为空;
  2. 文本含数字(\d);
  3. 含缩略词——点号连写(如 U.S.、A.B.C.)或连续大写(如 NASA),这类文本音素化易出错;
  4. 不以 .、,、?、! 结尾;
  5. 含 £ 或 $ 货币符号。

这套过滤规则与 TTS 数据特性强相关:缩略词、数字、货币符号都容易导致音素化与发音异常,微调自有数据时建议保留。

3.5 样本预处理与监督标签构造

核心函数是 preprocess_sample(examples/finetune.py),它把一条样本变成 transformers 需要的 input_ids / labels / attention_mask 三元组。过程如下:

  1. 音素化:g2p.phonemize([text]) 得到音素串,若结果为空会打日志并丢弃该样本(安全校验)。

  2. 语音 token 化:把 codes 整数序列拼接成 <|speech_i|> 字符串。

  3. 构造对话式模板(关键):

    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:... 结构完全一致,保证微调所学模式在推理时可直接复用。

  4. Padding:长度不足 max_seq_len 时用 pad_token_id 补齐,超出则截断。

  5. 标签掩码:labels 初始全部为 -100(LLaMA 惯例,表示该位置不参与损失计算),从 <|SPEECH_GENERATION_START|> 位置起才把 input_ids 复制为标签——也就是说模型只学习预测语音 token,不学习重建文本 prompt。

  6. 注意力掩码:非 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 模型,并平滑接入仓库的推理与部署体系。

登录后查看全文
neutts