深入解析 Kyutai Speech-To-Text：Transformers 中基于 Mimi 编解码与流式解码的语音识别模型实战指南

深入解析 Kyutai Speech-To-TextTransformers 中基于 Mimi 编解码与流式解码的语音识别模型实战指南【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformersKyutai Speech-To-TextKyutai STT是 Kyutai 实验室于 2025 年 6 月正式并入 Hugging Face Transformers 的端到端语音识别模型系列其核心是把 Mimi 神经音频编解码器 的流式离散音频表征与Moshi 风格的自回归语言模型解码器组合成一套统一的双模态 token 体系。本文以 Kyutai Speech-To-Text 官方模型文档为主体结合仓库内该模型的完整实现梳理其工作原理、配置参数、特征提取管线与流式generate机制并给出可直接运行的单条与批量推理示例。通过本文你将掌握如何在 Transformers 中加载并运行kyutai/stt-2.6b-en-trfs等检查点完成英文/法文语音转写理解音频如何被实时切成 Mimi token 窗口并送入自回归解码器以及KyutaiSpeechToTextConfig、KyutaiSpeechToTextProcessor、KyutaiSpeechToTextFeatureExtractor与KyutaiSpeechToTextForConditionalGeneration各自承担的角色与关键参数。模型总览一套双模态的音频编解码 自回归解码架构根据模型文档与源码Kyutai STT 不是传统的编码器-注意力解码器式 ASR而是一条以音频 token 为第一公民的生成式语音转写链路前端编码Mimi codec 的流式离散化。模型内置一个 Mimi 编解码器在 HF Transformers 中另有独立模型支持见 Mimi 文档。Mimi 以流式方式把 24 kHz 的原始波形编码为离散 token 序列为自回归解码器提供逐帧音频表征。后端解码Moshi 风格自回归解码器。解码器是一个类似 Moshi见 Moshi 文档的自回归 Transformer逐帧预测文本 token 与 32 路 RVQ残差向量量化码本对应的音频 token。这种双模态 token 空间设计的直接收益是语音转写可以被建模为与 Moshi 一致的帧级对齐生成——每一帧同时包含文本与音频信息解码器在帧序列上自回归地前进从而实现低延迟的流式语音识别而无需像传统 ASR 那样等待整段音频编码完毕。官方文档声明当前发布了两档检查点kyutai/stt-1b-en_fr约 1B 参数支持英语与法语双语转写kyutai/stt-2.6b-en约 2.6B 参数专注英文、以最大化转写准确率为目标。本文所有示例与仓库测试均使用 HF 侧的镜像检查点kyutai/stt-2.6b-en-trfs见 集成测试 setUp。该模型于 2025-06-25 由 Eustache Le Bihan 贡献进入 Transformers。快速上手单条与批量推理单条语音转写模型文档给出的最小推理流程分为五步加载模型与处理器 → 载入音频 → 预处理 →generate→ 解码。以下代码可直接运行需要torch、datasets、transformersfrom datasets import Audio, load_dataset from transformers import KyutaiSpeechToTextForConditionalGeneration, KyutaiSpeechToTextProcessor # 1. 加载模型与处理器 model_id kyutai/stt-2.6b-en-trfs processor KyutaiSpeechToTextProcessor.from_pretrained(model_id) model KyutaiSpeechToTextForConditionalGeneration.from_pretrained(model_id, device_mapauto) # 2. 加载音频样本注意模型期望 24000 Hz 采样率 ds load_dataset( hf-internal-testing/librispeech_asr_dummy, clean, splitvalidation ) ds ds.cast_column(audio, Audio(sampling_rate24000)) # 3. 准备模型输入 inputs processor( ds[0][audio][array], ) inputs.to(model.device) # 4. 推理生成 output_tokens model.generate(**inputs) # 5. 解码生成的 token print(processor.batch_decode(output_tokens, skip_special_tokensTrue))几点实操细节采样率必须为 24000 Hz处理器内部的特征提取器默认sampling_rate24000源码见 feature_extraction_kyutai_speech_to_text.py。集成测试中加载 LibriSpeech 后同样通过cast_column(audio, Audio(sampling_rate24000))重采样见 test_modeling_kyutai_speech_to_text.py。device_mapauto依赖accelerate。若在 CPU 上运行可改传device_mapcpumodel.forward的 docstring 示例即采用此写法。该模型是条件生成任务inputs通常无需labels直接generate即可。批量推理自动 padding模型文档同时给出了批量推理版本核心区别是向处理器传入音频数组列表并开启 paddingfrom datasets import Audio, load_dataset from transformers import KyutaiSpeechToTextForConditionalGeneration, KyutaiSpeechToTextProcessor # 1. 加载模型与处理器 model_id kyutai/stt-2.6b-en-trfs processor KyutaiSpeechToTextProcessor.from_pretrained(model_id) model KyutaiSpeechToTextForConditionalGeneration.from_pretrained(model_id, device_mapauto) # 2. 加载音频样本 ds load_dataset( hf-internal-testing/librispeech_asr_dummy, clean, splitvalidation ) ds ds.cast_column(audio, Audio(sampling_rate24000)) # 3. 收集多条音频并做批处理返回 PyTorch 张量并按最长样本补零 audio_arrays [ds[i][audio][array] for i in range(4)] inputs processor(audio_arrays, return_tensorspt, paddingTrue).to(model.device) # 4. 推理生成 output_tokens model.generate(**inputs) # 5. 逐条解码 decoded_outputs processor.batch_decode(output_tokens, skip_special_tokensTrue) for output in decoded_outputs: print(output)从KyutaiSpeechToTextProcessorKwargs的默认值可以看到processing_kyutai_speech_to_text.py该处理器在音频侧默认注入sampling_rate24000、公共侧默认return_tensorspt这正是示例中可以不显式传这两个参数的原因。双模态 token 空间解码器到底在预测什么要正确理解generate的输出需要先明白模型的输入/输出 token 组织方式。这是全模型最反直觉但最核心的设计源码集中在两个位置可学习嵌入层按码本做偏移求和modeling 文件。词表维度定义为vocab_size num_codebooks * codebook_vocab_size 1默认即4001 32*2049 1。输入序列最后一维是1 num_codebooks 33第 0 列是文本 token其余 32 列分别对应 Mimi 的 32 个 RVQ 码本。嵌入前每个非 padding 的音频 token 都会加上自己所属码本的偏移量offsets[k] vocab_size k * codebook_vocab_size随后在最后一维上求和得到 (batch, seq, hidden) 的融合向量。生成阶段逐帧拼接prepare_inputs_for_generationmodeling 文件。解码器每个时间步的位置上input_ids会被构造成(batch, seq, 2)的形态——文本 token 列拼接上当前帧的 32 路音频 token当某帧使用起始标记时该帧 32 路音频 token 全部被替换为audio_bos_token_id。用配置文件中的默认 token id 可以更直观地理解这套体系configuration_kyutai_speech_to_text.py字段默认值含义vocab_size4001文本侧词表大小codebook_vocab_size2049单个码本的音频 token 词表大小num_codebooks32RVQ 码本数量与 Mimi 对齐audio_bos_token_id2048音频流起始标记每个码本内最后一个 idaudio_pad_token_id69569音频填充标记等于4001 32*2049同时充当嵌入层padding_idxbos_token_id48000文本/整体序列 BOS 标记pad_token_id3文本侧 padding 标记eos_token_idNone无显式 EOS靠帧数约束生成长度值得注意的一个推断正因为vocab_size、codebook_vocab_size与num_codebooks共同决定嵌入表大小和偏移计算这几个参数在加载官方检查点时不应随意改动否则 token 语义会发生偏移。解码器架构与生成机制源码解析主干为标准的深度 Transformer 解码器KyutaiSpeechToTextModel是一个以hidden_size2048、num_hidden_layers48、num_attention_heads32为主干的自回归解码器configuration 默认值并具备以下特征分组查询注意力GQAnum_key_value_heads默认None在__post_init__中会回退为num_attention_headsconfiguration。滑窗局部注意力sliding_window375配合max_position_embeddings750注意力被限制在较短的局部窗口内从而压低流式生成时的缓存与算力开销。RMSNorm SiLU 门控 MLP归一化采用KyutaiSpeechToTextRMSNormFFN 维度ffn_dim11264激活为hidden_actsilu的门控结构KyutaiSpeechToTextGatingMLP。旋转位置编码RoPEKyutaiSpeechToTextRotaryEmbedding支持rope_parameters中配置的rope_type与rope_theta默认实现遵循原始 RoPE 反频率公式见 modeling 的 compute_default_rope_parameters。多种注意力后端模型声明_supports_flash_attn、_supports_sdpa、_supports_flex_attnmodeling并支持梯度检查点。测试会对比 eager 与 sdpa / flash_attention_2 的输出等价性见 test 中的注意力实现对比。fp32 保精度的 codec 分支_keep_in_fp32_modules_strict [codec_model]而解码器主网络可安全地以 fp16/bf16 运行modeling。集成测试明确断言加载后codec_model保持 fp32、主干与lm_head为 fp16test。generate是如何把音频喂给自回归解码器的KyutaiSpeechToTextForConditionalGeneration重写了多条生成钩子构成了下图所示的流式链路_prepare_model_inputsmodeling根据输入波形的实际采样长度调用 codec 的get_encoded_length推算音频 token 窗口宽度audio_window_size初始化形状为(batch, audio_window_size, num_codebooks)的全零audio_tokens记录current_window窗口坐标并为 Mimi 编解码器准备dynamic cache与各层一维因果卷积的padding cacheKyutaiSpeechToTextConv1dPaddingCache。也就是说codec 与解码器都持有独立缓存是流式解码能够逐段推进的基础。prepare_inputs_for_generationmodeling当生成的文本帧推进到当前窗口末尾时以start * frame_size到(start audio_window_size) * frame_size为界切出新的波形片段调用codec_model.encode(...)在torch.no_grad()下产出该窗口的audio_codes写回audio_tokens并滑动current_window随后把当前帧对应的 32 路音频 token与文本 token 沿序列最后一维拼接后送入解码器。generate的自动长度约束modelingmax_audio_frames input_values.shape[-1] // codec_config.frame_size。若用户未显式给出max_new_tokens或给出的值超过了最大音频帧数会被自动钳制到音频帧总数——因此无需手动指定生成长度模型天然听多少、转写多少。from_pretrained/save_pretrained的重写modeling负责把codec_*前缀的生成配置在模型 GenerationConfig与内置 codec 的 GenerationConfig之间搬运保证 codec 的流式缓存初始化参数如sliding_window在存取后不丢失。上述流式生成属于实现层面的机制描述仓库未对 支持任意长度的实时流式音频输入 提供文档级承诺请以实际体验为准。另外测试注释指出与原始 moshi 代码库相比QKV 线性层的组织方式差异会使长上下文下的输出逐渐产生偏差因此集成测试刻意使用较短的输入验证见 test 注释。音频特征提取器从波形到模型的预处理契约KyutaiSpeechToTextFeatureExtractor继承自通用的SequenceFeatureExtractor负责把float32波形整理成模型的input_values与padding_maskfeature_extraction_kyutai_speech_to_text.py。其构造参数与语义如下参数默认值作用feature_size1特征维度1 表示单声道2 表示立体声sampling_rate24000音频数字化采样率Hzpadding_value0.0填充使用的常数值chunk_length_sNone若设置音频会按该秒数切片后再编码overlapNone相邻 chunk 的重叠比例用于计算chunk_stride int((1.0 - overlap) * chunk_length)audio_delay_seconds0.0在音频之后追加的延迟秒数右侧补零audio_silence_prefix_seconds0.0在音频之前追加的静音秒数左侧补零在调用管线__call__见 feature_extraction 源码内部还有几个容易被忽视但很重要的行为强制的采样率校验若显式传入sampling_rate且与self.sampling_rate不一致会直接抛出ValueError若未传则会打印日志警告。建议在调用处理器时始终带上 24 kHz 音频避免静默错误。默认开启 paddingpaddingNone时被解释为True补到 batch 内最长样本。若同时开启truncation会报错。输入形态约定单声道要求波形是(num_samples,)的一维数组立体声要求(2, num_samples)每条样本内部会做转置与 float32 转换非法维度会抛错。右侧至少补 1 秒零pad_right int((audio_delay_seconds 1.0) * sampling_rate)feature_extraction即默认对每条音频右侧补满 24000 个采样点左侧按audio_silence_prefix_seconds补零且padding_mask同步扩展。这解释了为何输入会被模型听到得比实际语音更长——这是与 Moshi/Mimi 对齐的约定解码器在这些帧上只产出空白或结束性文本。分块预处理当设置了chunk_length_s与overlap时max_length会被规整为 chunk 步长的整数倍边界(nb_step - 1) * chunk_stride chunk_length保证切片窗口对齐。仓库内还提供了chunk_length与chunk_stride两个动态属性feature_extraction它们基于采样率把秒级参数换算为采样点数并支持在运行时修改chunk_length_s后即时生效——设计意图正是服务于流式/分块场景。Processor 与 Config把部件粘合在一起KyutaiSpeechToTextProcessorKyutaiSpeechToTextProcessor是标准的ProcessorMixin组合processing 源码把一个feature_extractor音频与一个tokenizer文本绑在一起__call__时默认把音频侧的采样率设为 24000、统一返回 PyTorch 张量。因此你只需要processor KyutaiSpeechToTextProcessor.from_pretrained(model_id) # 之后 audio 波形会经由 feature_extractor 处理解码文本则交给内置 tokenizerbatch_decode(..., skip_special_tokensTrue)即走 tokenizer 路径把生成的 token id 还原为文本。KyutaiSpeechToTextConfigKyutaiSpeechToTextConfigconfiguration 源码是model_typekyutai_speech_to_text的配置类除前文已列的 token 与解码器超参外还需注意两点codec_config子配置声明为sub_configs {codec_config: AutoConfig}configuration。若未提供__post_init__会用AutoConfig.for_model(mimi)生成默认的 Mimi 音频编码器配置并把frame_size等字段回填到模型配置中configuration。也就是说Kyutai STT 在架构层面内嵌了一个完整的 codec 模型这也是为什么单个类名同时承载了编码与解码两套网络。架构约束校验strict装饰的validate_architecture要求ffn_dim必须为偶数否则抛错configuration。用配置类手工搭一个随机初始化模型的典型写法为from transformers import KyutaiSpeechToTextConfig, KyutaiSpeechToTextForConditionalGeneration configuration KyutaiSpeechToTextConfig() model KyutaiSpeechToTextForConditionalGeneration(configuration) configuration model.config # 通过模型访问已补全的配置代码结构导航从 modular 到生成文件的工程脉络该模型在仓库中的源码组织遵循 HF Transformers 的modular 单源生成模式modular_kyutai_speech_to_text.py真正的维护源文件所有手写改动应落在这里modeling_kyutai_speech_to_text.py由 modular 自动生成的主实现文件头有显式警告禁止手改configuration_kyutai_speech_to_text.py配置类feature_extraction_kyutai_speech_to_text.py音频特征提取器processing_kyutai_speech_to_text.py处理器组合convert_kyutai_speech_to_text_to_hf.py把原始 moshi/Kyutai 仓库权重含 Mimi codec 权重转换为 HF 格式的转换脚本write_model/write_processor分别产出模型权重与处理器配置。模型内的关键子模块按职责划分KyutaiSpeechToTextFlexibleLinear为每个码本各维护一份线性层权重、KyutaiSpeechToTextConv1dPaddingCache因果卷积流式缓存、KyutaiSpeechToTextEmbeddings双模态偏移求和嵌入、KyutaiSpeechToTextAttention/KyutaiSpeechToTextDecoderLayer带 RoPE 与滑窗的注意力解码层、KyutaiSpeechToTextModel主干、KyutaiSpeechToTextForConditionalGeneration组合解码器 lm_head 内嵌 codec 的顶层封装见 modeling 类定义。验证与测试依据想要验证本文描述的行为可以关注仓库中针对该模型的测试与 fixture单元/质量测试文件 tests/models/kyutai_speech_to_text/test_modeling_kyutai_speech_to_text.py覆盖 fp32 codec fp16 主干的精度保持、eager/sdpa/flash_attention_2 输出等价性、缓存复用下多次generate的一致性以及集成测试slow中针对 LibriSpeech dummy 样本的精确 token 级输出对齐见 EXPECTED_TOKENS 断言。该模型的配置与权重可从 HF Hub 的kyutai/stt-2.6b-en-trfs检查点直接获取处理器与模型共用同一个model_id加载。运行集成测试需slow标记与 GPU 加速器日常验证请优先使用 CPU/小样本的单元级测试路径。小结何时选择 Kyutai STT以及进一步阅读总结一下这套方案的关键画像基于 Mimi 流式离散音频编码 Moshi 风格双模态自回归解码输入约定为 24 kHz 单声道波形处理器默认右侧补 1 秒零、可配置 chunking 与 overlap解码器在 48 层、32 码本的深度维度上逐帧生成generate自动以音频帧数封顶生成长度。这套设计让语音转写天然具备流式、低延迟的自回归生成特性适合希望把 ASR 纳入端到端生成式建模管线的研究与工程场景。想进一步深入建议按以下顺序阅读仓库内资料本模型的模型卡片原文档 docs/source/en/model_doc/kyutai_speech_to_text.md前后端依赖的 Mimi 文档 与 Moshi 文档配置、建模、特征提取与转换脚本的源码路径见上文代码结构导航一节测试文件 test_modeling_kyutai_speech_to_text.py其中有真实检查点的集成验证示例。最终在代码侧你只需要记住一条最简用法inputs processor(audio, return_tensorspt, sampling_rate24000).to(cuda) tokens model.generate(**inputs) text processor.batch_decode(tokens, skip_special_tokensTrue)【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考