MLX Audio 中的 Higgs-Audio v3 STTWhisper 风格音频编码器 × Qwen3 文本骨干的语音转写实战指南【免费下载链接】mlx-audioA text-to-speech (TTS), speech-to-text (STT) and speech-to-speech (STS) library built on Apples MLX framework, providing efficient speech analysis on Apple Silicon.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-audio导读Higgs-Audio v3 STT 是 Boson AI 推出的语音转文本Speech-to-Text模型它把 Whisper 风格的音频编码器与 Qwen3 文本骨干text backbone组合在一起在 Apple Silicon 上通过 MLX 框架实现高效转写。本文以 mlx_audio/stt/models/higgs_audio_3/README.md 为骨架结合其源码实现模型定义、配置、VAD 分块、特征提取与测试用例完整讲解该模型的 Python 与 CLI 用法、模型权重信息、架构细节、音频处理流水线以及generate的采样参数帮助你理解并直接使用 Higgs-Audio v3 STT 完成本地语音转写任务。模型概览Higgs-Audio v3 STTHuggingFace 仓库 IDbosonai/higgs-audio-v3-stt是一种纯转写transcription模型输入任意音频输出对应的文本。其设计思路是把语音理解交给音频编码器、文本生成交给大语言模型音频编码器Whisper 风格编码器32 层 Transformer1280 维隐藏层 AvgPool1d 时间下采样投影器Projectordepthwise 时间维 Conv1dstride 2 带 ReLU 的两层 MLP1280 → 2048文本骨干Qwen328 层2048 隐藏维以自回归方式逐 token 生成转写文本。在仓库中该模型被注册在 STT 模型的统一加载体系内mlx_audio/stt/utils.py的MODEL_REMAPPING中higgs_audio_3: higgs_audio_3因此可以和其他 STT 模型一样通过load_model/load加载。完整实现位于 higgs_audio_3.py核心类包括HiggsAudioEncoder、HiggsAudioFeatureProjector和最终的Model。快速开始Python API原文档给出的最小调用方式如下只需三行即可完成一次转写from mlx_audio.stt.utils import load_model model load_model(bosonai/higgs-audio-v3-stt) result model.generate(audio.wav) print(result.text)加载时会自动完成以下动作由 higgs_audio_3.py 的post_load_hook保证从模型目录用transformers.AutoTokenizer.from_pretrained(..., trust_remote_codeTrue)加载 Qwen3 分词器供后续把文本 prompt 编码为 token 序列使用同时Model.sanitize会把原始权重如audio_decoder_proj.text_lm_head.weight、embed_tokens.weight、norm.weight、layers.*重映射并转置为 MLX 模型需要的布局。除了load_model也可以使用 stt/utils.py 中的load函数二者等价均基于base_load_model自动识别模型类型。模型支持以 HuggingFace 仓库 ID 或本地模型目录路径传入。CLI 命令行用法原文档同时提供了命令行入口mlx_audio.stt.generate --model bosonai/higgs-audio-v3-stt --audio audio.wavCLI 与 Python API 共享同一套加载与生成逻辑适合快速验证模型效果或批量处理脚本化使用。--model接受仓库 ID 或本地目录--audio指定待转写的音频文件支持 wav/flac 等格式内部会统一重采样到 16kHz 单声道。模型权重信息原文档给出了官方模型的基础信息ModelSizeQuantizationHuggingFacehiggs-audio-v3-stt~5.35GBbf16bosonai/higgs-audio-v3-stt该权重为 bf16 精度、约 5.35GB 大小的官方 MLX 版本。从 config.py 可以看到完整的结构规模音频编码器128 个 mel 频带、32 层、20 个注意力头、FFN 维 5120、d_model1280、最大源位置 1500、帧率 25文本骨干Qwen3词表 151936、隐藏维 2048、中间维 6144、28 层、16 个头、8 个 KV 头、head_dim128、最大位置编码 32768、rope_theta1000000。架构深度解析音频编码器Whisper 风格特征提取HiggsAudioEncoderhiggs_audio_3.py的结构如下输入为 128 通道的 mel 频谱图16kHz两层 Conv1dconv1kernel 3、stride 1conv2kernel 3、stride 2加 GELU 激活把 128 维 mel 特征提升到d_model1280维叠加可学习的位置编码embed_positions最大 1500 帧经过 32 层AudioEncoderLayerLayerNorm → 自注意力 → 残差 → LayerNorm → FC1-GELU-FC2 → 残差其中自注意力使用mx.fast.scaled_dot_product_attention最后对时间维做 AvgPool1d相邻 2 帧取平均再做 LayerNorm将时间分辨率再次减半。投影器把音频特征映射到文本空间HiggsAudioFeatureProjectorhiggs_audio_3.py负责把音频编码器的输出对齐到 Qwen3 的隐藏维若projector_temporal_downsample 1先经过一个depthwise 时间维 Conv1dkernel 3、stride 2、groupsaudio_dim把时间帧数再减半两层线性投影1280 → 2048ReLU→2048 → text hidden size (2048)。音频编码器与投影器最终输出与文本 token 嵌入维度完全一致的向量序列从而可以直接拼接进 Qwen3 的输入嵌入。文本骨干Qwen3 自回归生成Model.__init__使用 config.py 中的TextConfig构造仓库自带的 Qwen3Model并挂一个不带 bias 的lm_head映射回词表。生成时通过KVCachecache.py缓存历史 KV配合mlx_audio.lm.generate.generate_step逐 token 解码。关键配置参数表以下参数来自 config.py 的ModelConfig可在加载时通过配置文件覆盖参数默认值含义chunk_size_seconds4.0单次送入模型的最大音频分块时长秒超长音频按此切块sample_rate16000音频采样率特征提取按 16kHz 计算vad_cutTrue是否用 Silero VAD 先切出语音区间再分块split_vadsFalse为 True 时仅保留 VAD 检测到的语音区间丢弃静音为 False 时合并为覆盖整段音频的连续块projector_temporal_downsample2投影器时间维下采样倍数audio_in_token_idx151672\|AUDIO\|占位符 token idaudio_bos_token_id/audio_eos_token_id151669 / 151670音频嵌入的起止标记pad_token_id151643填充 token id同时是 EOS 之一音频处理与生成流水线原文档描述了完整流程音频 → 128 通道 16kHz mel 频谱 → Silero VAD 切成不超过chunk_size_seconds的分块 → 每块编码 投影 → 合并到文本 prompt 的|AUDIO|占位位置 → 自回归生成。源码 higgs_audio_3.py 的get_input_embeddings精确实现了这一过程加载音频_load_audio把路径/mx.array/np.ndarray 统一转为 float32 单声道波形VAD 分块_chunk_waveform调用 vad.py 的vad_chunk_ranges——默认split_vadsFalse会把第一段语音起点钳到 0、最后一段延伸到音频末尾再按chunk_size_seconds二次切块若 VAD 不可用或检测失败则退化为固定长度切块特征提取AudioFeatureExtractoraudio.py用 Hanning 窗 STFTn_fft400、hop160计算幅度谱经 Slaney 归一化 mel 滤波器得到 128 通道频谱再做 log10、按最大值截断 8dB 动态范围并归一化到 [-1, 1] 区间逐块编码投影每个分块 pad 到统一长度后送入HiggsAudioEncoderHiggsAudioFeatureProjector得到音频嵌入序列嵌入合并文本 prompt 使用默认指令Transcribe the speech. Output only the spoken words in lowercase with no punctuation.模板为user\n{prompt}|audio_bos| N 个|AUDIO|占位 token |audio_eos|\nassistant\n每个占位 token 被替换为对应分块的音频嵌入与文本嵌入拼接成完整的inputs_embeds。VAD 细节SileroVADBackend 默认从mlx-community/silero-vad加载 VAD其关键参数为threshold0.5语音判定阈值、min_speech_duration_ms250最小语音段、min_silence_duration_ms100最小静音间隔、speech_pad_ms30语音边界填充。split_vadsTrue时只保留真实语音区间测试用例test_vad_chunk_ranges_respects_cuts验证了两种模式的分块结果差异。生成与后处理generatehiggs_audio_3.py的完整签名与默认值如下参数默认值说明max_tokens1024最大生成 token 数temperature0.0采样温度0 为贪心解码top_p1.0nucleus 采样阈值top_k0top-k 采样0 表示禁用min_p0.0min-p 采样阈值repetition_penaltyNone重复惩罚None 表示关闭repetition_context_size100重复惩罚考虑的上下文窗口prompt默认转写指令可自定义 prompt 引导输出格式prefill_step_size2048预填充步长生成以{151645, 151643}作为 EOS token 集合输出文本经过_parse_output清理去除 Qwen3 的think.../think推理块与所有|...|特殊标记。结果封装为 STTOutput除text外还包含prompt_tokens、generation_tokens、total_tokens、total_time、prompt_tps、generation_tps等性能统计字段便于评估转写速度。量化与内存控制模型规模约 5.35GBbf16在 Apple Silicon 上可通过量化降低内存占用。higgs_audio_3.py 的model_quant_predicate明确排除了audio_tower音频编码器与audio_encoder_proj投影器即量化只作用于 Qwen3 文本骨干音频编码器始终保留较高精度避免量化损伤语音特征提取质量。仓库的 STT 转换工具python -m mlx_audio.convert --model-domain stt --quantize --q-bits 4/8即可产出量化权重。测试与验证仓库在 test_higgs_audio_3.py 中提供了覆盖各模块的测试可用于理解与验证模型行为test_config_parses_nested嵌套配置音频编码器 文本配置解析test_feature_extractor_returns_mel_array特征提取输出形状(1, 128, T)test_encoder_halves_time_dim验证编码器经 conv2stride 2与平均池化后时间维约为输入的 1/4test_projector_downsamples_and_projects验证投影器时间下采样与维度对齐20 帧 → 10 帧test_get_input_embeddings_merges_audio验证音频占位 token 被替换为多行音频嵌入test_vad_chunk_ranges_*验证 VAD 分块与固定分块回退逻辑test_sanitize_*验证权重重映射与 Conv1d 转置test_real_model_transcribesrequires_weights标记设置环境变量HIGGS_AUDIO_3_PATH模型目录与HIGGS_AUDIO_3_TEST_AUDIOwav/flac 文件后可跑通真实模型端到端转写。总结Higgs-Audio v3 STT 是 MLX Audio STT 家族中Whisper 编码器 Qwen3 骨干路线的代表实现Whisper 风格编码器负责稳健的语音特征提取Qwen3 负责高质量文本生成Silero VAD 分块机制让任意长度音频都能被流式地切块处理。通过统一的load_model入口你可以像使用其他 STT 模型一样用三行 Python 或一条 CLI 命令在 Apple Silicon 上完成本地转写并通过自定义prompt、采样参数与量化选项进一步适配自己的场景。【免费下载链接】mlx-audioA text-to-speech (TTS), speech-to-text (STT) and speech-to-speech (STS) library built on Apples MLX framework, providing efficient speech analysis on Apple Silicon.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-audio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
MLX Audio 中的 Higgs-Audio v3 STT：Whisper 风格音频编码器 × Qwen3 文本骨干的语音转写实战指南
MLX Audio 中的 Higgs-Audio v3 STTWhisper 风格音频编码器 × Qwen3 文本骨干的语音转写实战指南【免费下载链接】mlx-audioA text-to-speech (TTS), speech-to-text (STT) and speech-to-speech (STS) library built on Apples MLX framework, providing efficient speech analysis on Apple Silicon.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-audio导读Higgs-Audio v3 STT 是 Boson AI 推出的语音转文本Speech-to-Text模型它把 Whisper 风格的音频编码器与 Qwen3 文本骨干text backbone组合在一起在 Apple Silicon 上通过 MLX 框架实现高效转写。本文以 mlx_audio/stt/models/higgs_audio_3/README.md 为骨架结合其源码实现模型定义、配置、VAD 分块、特征提取与测试用例完整讲解该模型的 Python 与 CLI 用法、模型权重信息、架构细节、音频处理流水线以及generate的采样参数帮助你理解并直接使用 Higgs-Audio v3 STT 完成本地语音转写任务。模型概览Higgs-Audio v3 STTHuggingFace 仓库 IDbosonai/higgs-audio-v3-stt是一种纯转写transcription模型输入任意音频输出对应的文本。其设计思路是把语音理解交给音频编码器、文本生成交给大语言模型音频编码器Whisper 风格编码器32 层 Transformer1280 维隐藏层 AvgPool1d 时间下采样投影器Projectordepthwise 时间维 Conv1dstride 2 带 ReLU 的两层 MLP1280 → 2048文本骨干Qwen328 层2048 隐藏维以自回归方式逐 token 生成转写文本。在仓库中该模型被注册在 STT 模型的统一加载体系内mlx_audio/stt/utils.py的MODEL_REMAPPING中higgs_audio_3: higgs_audio_3因此可以和其他 STT 模型一样通过load_model/load加载。完整实现位于 higgs_audio_3.py核心类包括HiggsAudioEncoder、HiggsAudioFeatureProjector和最终的Model。快速开始Python API原文档给出的最小调用方式如下只需三行即可完成一次转写from mlx_audio.stt.utils import load_model model load_model(bosonai/higgs-audio-v3-stt) result model.generate(audio.wav) print(result.text)加载时会自动完成以下动作由 higgs_audio_3.py 的post_load_hook保证从模型目录用transformers.AutoTokenizer.from_pretrained(..., trust_remote_codeTrue)加载 Qwen3 分词器供后续把文本 prompt 编码为 token 序列使用同时Model.sanitize会把原始权重如audio_decoder_proj.text_lm_head.weight、embed_tokens.weight、norm.weight、layers.*重映射并转置为 MLX 模型需要的布局。除了load_model也可以使用 stt/utils.py 中的load函数二者等价均基于base_load_model自动识别模型类型。模型支持以 HuggingFace 仓库 ID 或本地模型目录路径传入。CLI 命令行用法原文档同时提供了命令行入口mlx_audio.stt.generate --model bosonai/higgs-audio-v3-stt --audio audio.wavCLI 与 Python API 共享同一套加载与生成逻辑适合快速验证模型效果或批量处理脚本化使用。--model接受仓库 ID 或本地目录--audio指定待转写的音频文件支持 wav/flac 等格式内部会统一重采样到 16kHz 单声道。模型权重信息原文档给出了官方模型的基础信息ModelSizeQuantizationHuggingFacehiggs-audio-v3-stt~5.35GBbf16bosonai/higgs-audio-v3-stt该权重为 bf16 精度、约 5.35GB 大小的官方 MLX 版本。从 config.py 可以看到完整的结构规模音频编码器128 个 mel 频带、32 层、20 个注意力头、FFN 维 5120、d_model1280、最大源位置 1500、帧率 25文本骨干Qwen3词表 151936、隐藏维 2048、中间维 6144、28 层、16 个头、8 个 KV 头、head_dim128、最大位置编码 32768、rope_theta1000000。架构深度解析音频编码器Whisper 风格特征提取HiggsAudioEncoderhiggs_audio_3.py的结构如下输入为 128 通道的 mel 频谱图16kHz两层 Conv1dconv1kernel 3、stride 1conv2kernel 3、stride 2加 GELU 激活把 128 维 mel 特征提升到d_model1280维叠加可学习的位置编码embed_positions最大 1500 帧经过 32 层AudioEncoderLayerLayerNorm → 自注意力 → 残差 → LayerNorm → FC1-GELU-FC2 → 残差其中自注意力使用mx.fast.scaled_dot_product_attention最后对时间维做 AvgPool1d相邻 2 帧取平均再做 LayerNorm将时间分辨率再次减半。投影器把音频特征映射到文本空间HiggsAudioFeatureProjectorhiggs_audio_3.py负责把音频编码器的输出对齐到 Qwen3 的隐藏维若projector_temporal_downsample 1先经过一个depthwise 时间维 Conv1dkernel 3、stride 2、groupsaudio_dim把时间帧数再减半两层线性投影1280 → 2048ReLU→2048 → text hidden size (2048)。音频编码器与投影器最终输出与文本 token 嵌入维度完全一致的向量序列从而可以直接拼接进 Qwen3 的输入嵌入。文本骨干Qwen3 自回归生成Model.__init__使用 config.py 中的TextConfig构造仓库自带的 Qwen3Model并挂一个不带 bias 的lm_head映射回词表。生成时通过KVCachecache.py缓存历史 KV配合mlx_audio.lm.generate.generate_step逐 token 解码。关键配置参数表以下参数来自 config.py 的ModelConfig可在加载时通过配置文件覆盖参数默认值含义chunk_size_seconds4.0单次送入模型的最大音频分块时长秒超长音频按此切块sample_rate16000音频采样率特征提取按 16kHz 计算vad_cutTrue是否用 Silero VAD 先切出语音区间再分块split_vadsFalse为 True 时仅保留 VAD 检测到的语音区间丢弃静音为 False 时合并为覆盖整段音频的连续块projector_temporal_downsample2投影器时间维下采样倍数audio_in_token_idx151672\|AUDIO\|占位符 token idaudio_bos_token_id/audio_eos_token_id151669 / 151670音频嵌入的起止标记pad_token_id151643填充 token id同时是 EOS 之一音频处理与生成流水线原文档描述了完整流程音频 → 128 通道 16kHz mel 频谱 → Silero VAD 切成不超过chunk_size_seconds的分块 → 每块编码 投影 → 合并到文本 prompt 的|AUDIO|占位位置 → 自回归生成。源码 higgs_audio_3.py 的get_input_embeddings精确实现了这一过程加载音频_load_audio把路径/mx.array/np.ndarray 统一转为 float32 单声道波形VAD 分块_chunk_waveform调用 vad.py 的vad_chunk_ranges——默认split_vadsFalse会把第一段语音起点钳到 0、最后一段延伸到音频末尾再按chunk_size_seconds二次切块若 VAD 不可用或检测失败则退化为固定长度切块特征提取AudioFeatureExtractoraudio.py用 Hanning 窗 STFTn_fft400、hop160计算幅度谱经 Slaney 归一化 mel 滤波器得到 128 通道频谱再做 log10、按最大值截断 8dB 动态范围并归一化到 [-1, 1] 区间逐块编码投影每个分块 pad 到统一长度后送入HiggsAudioEncoderHiggsAudioFeatureProjector得到音频嵌入序列嵌入合并文本 prompt 使用默认指令Transcribe the speech. Output only the spoken words in lowercase with no punctuation.模板为user\n{prompt}|audio_bos| N 个|AUDIO|占位 token |audio_eos|\nassistant\n每个占位 token 被替换为对应分块的音频嵌入与文本嵌入拼接成完整的inputs_embeds。VAD 细节SileroVADBackend 默认从mlx-community/silero-vad加载 VAD其关键参数为threshold0.5语音判定阈值、min_speech_duration_ms250最小语音段、min_silence_duration_ms100最小静音间隔、speech_pad_ms30语音边界填充。split_vadsTrue时只保留真实语音区间测试用例test_vad_chunk_ranges_respects_cuts验证了两种模式的分块结果差异。生成与后处理generatehiggs_audio_3.py的完整签名与默认值如下参数默认值说明max_tokens1024最大生成 token 数temperature0.0采样温度0 为贪心解码top_p1.0nucleus 采样阈值top_k0top-k 采样0 表示禁用min_p0.0min-p 采样阈值repetition_penaltyNone重复惩罚None 表示关闭repetition_context_size100重复惩罚考虑的上下文窗口prompt默认转写指令可自定义 prompt 引导输出格式prefill_step_size2048预填充步长生成以{151645, 151643}作为 EOS token 集合输出文本经过_parse_output清理去除 Qwen3 的think.../think推理块与所有|...|特殊标记。结果封装为 STTOutput除text外还包含prompt_tokens、generation_tokens、total_tokens、total_time、prompt_tps、generation_tps等性能统计字段便于评估转写速度。量化与内存控制模型规模约 5.35GBbf16在 Apple Silicon 上可通过量化降低内存占用。higgs_audio_3.py 的model_quant_predicate明确排除了audio_tower音频编码器与audio_encoder_proj投影器即量化只作用于 Qwen3 文本骨干音频编码器始终保留较高精度避免量化损伤语音特征提取质量。仓库的 STT 转换工具python -m mlx_audio.convert --model-domain stt --quantize --q-bits 4/8即可产出量化权重。测试与验证仓库在 test_higgs_audio_3.py 中提供了覆盖各模块的测试可用于理解与验证模型行为test_config_parses_nested嵌套配置音频编码器 文本配置解析test_feature_extractor_returns_mel_array特征提取输出形状(1, 128, T)test_encoder_halves_time_dim验证编码器经 conv2stride 2与平均池化后时间维约为输入的 1/4test_projector_downsamples_and_projects验证投影器时间下采样与维度对齐20 帧 → 10 帧test_get_input_embeddings_merges_audio验证音频占位 token 被替换为多行音频嵌入test_vad_chunk_ranges_*验证 VAD 分块与固定分块回退逻辑test_sanitize_*验证权重重映射与 Conv1d 转置test_real_model_transcribesrequires_weights标记设置环境变量HIGGS_AUDIO_3_PATH模型目录与HIGGS_AUDIO_3_TEST_AUDIOwav/flac 文件后可跑通真实模型端到端转写。总结Higgs-Audio v3 STT 是 MLX Audio STT 家族中Whisper 编码器 Qwen3 骨干路线的代表实现Whisper 风格编码器负责稳健的语音特征提取Qwen3 负责高质量文本生成Silero VAD 分块机制让任意长度音频都能被流式地切块处理。通过统一的load_model入口你可以像使用其他 STT 模型一样用三行 Python 或一条 CLI 命令在 Apple Silicon 上完成本地转写并通过自定义prompt、采样参数与量化选项进一步适配自己的场景。【免费下载链接】mlx-audioA text-to-speech (TTS), speech-to-text (STT) and speech-to-speech (STS) library built on Apples MLX framework, providing efficient speech analysis on Apple Silicon.项目地址: https://gitcode.com/GitHub_Trending/ml/mlx-audio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考