2026/9/16 23:17:22
FEATURED · 精选文章 
mlx-audio 中的 Fun-ASR-Nano-2512 实战指南转换、推理、热词与语言约束【免费下载链接】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-audioFun-ASR-Nano-2512 是 FunAudioLLM 推出的紧凑型语音识别ASR模型本指南讲解它在 mlx-audio 仓库中的完整落地路径从 PyTorch 权重转换为 MLX 格式到 Python/CLI 双入口调用再到language、hotwords/context、itn等关键参数的底层行为。读完本文你将能够在 Apple Silicon 上独立完成该模型的转换、推理与领域热词校准并理解其 SenseVoice 风格编码器 Qwen3-0.6B 解码器的内部协作机制。模型概览一个编码器 语言模型的紧凑 ASR 架构Fun-ASR-Nano-2512 定位为轻量级语音转写模型整体约 0.8B 参数支持中文、英文、日文三种语言。它的结构可以拆成三段详见 fun_asr_nano.pySenseVoice 风格的音频编码器SenseVoiceEncoderSmall接收梅尔滤波器组特征经过 50 层 SANM 编码层与 20 层 TP 编码层输出语音表征音频适配器AudioAdaptorTransformer把编码器输出下采样并对齐到语言模型的嵌入维度llm_dim: 1024Qwen3-0.6B 文本解码器Qwen3CausalLM以语言条件提示词language prompt为前缀逐 token 自回归生成转写文本。这种设计的最大特点是用语言模型统一了听与写热词、语言约束、是否做文本规整ITN都被编码成提示词文本喂给 LLM而不是像传统 ASR 那样挂在解码图外部因此上下文偏置contextual biasing的实现非常直接——改提示词即可。权重转换从 model.pt 到可直接上传的 MLX 目录上游发布版只提供 PyTorch 权重model.pt需要使用模型专属转换器转换python -m mlx_audio.stt.models.fun_asr_nano.convert \ --hf-path FunAudioLLM/Fun-ASR-Nano-2512 \ --mlx-path Fun-ASR-Nano-2512-mlx转换器会完成以下工作对应 convert.py下载并解析检查点通过snapshot_download拉取上游仓库只保留model.pt、README.md、Qwen3-0.6B/*与example/*相关文件权重转换把 PyTorch tensor 转为 MLX 数组默认使用bfloat16精度。其中fsmn_block.weight这类形状为(C, 1, K)的卷积核会被转置为(C, K, 1)以匹配 MLX 卷积布局llm.lm_head.weight由于与嵌入层权重共享tied weights会被跳过运行时直接复用embed_tokens的权重矩阵生成运行时配置写入config.json包含前端参数、编码器与适配器结构以及直接从上游Qwen3-0.6B/config.json拷贝的文本模型配置拷贝配套文件将Qwen3-0.6Btokenizer 目录复制到输出目录post_load_hook会从这个子目录加载 tokenizer并生成一份带 front-matter 的README.md。转换器还提供几个可选参数参数默认值说明--dtypebfloat16稠密权重精度可选float16/bfloat16/float32--revision无指定上游 Hugging Face 仓库的 revision--no-examples关闭不拷贝上游 example 音频文件--no-overwrite关闭转换前不删除已存在的输出目录转换完成后输出目录结构为model.safetensorsconfig.jsonQwen3-0.6B/tokenizerREADME.md可直接整体上传为 Hugging Face 仓库例如mlx-community/Fun-ASR-Nano-2512之后就能按仓库 ID 加载。Python 使用三行代码完成转写通过统一的 STT 加载入口见 utils.py 的load_model/load内部通过MODEL_REMAPPING把fun_asr_nano路由到对应实现即可加载转换后的模型from mlx_audio.stt.utils import load_model model load_model(mlx-community/Fun-ASR-Nano-2512) result model.generate(audio.wav, languagezh, hotwords[开放时间]) print(result.text)generate返回一个STTOutput对象定义见 base.py除了text外还包含segments分段起止时间与文本、prompt_tokens/generation_tokens/total_tokenstoken 统计以及total_time、prompt_tps、generation_tps吞吐指标方便在脚本中做质量与性能观测。除了文档中的三个核心参数generate还暴露了完整的解码控制参数源码签名见 fun_asr_nano.pymax_tokens单段最大生成 token 数未指定时取配置中的default_max_tokens默认 512temperature/top_p/top_k/min_p/min_tokens_to_keep采样参数默认temperature0.0即贪心解码repetition_penalty/repetition_context_size重复惩罚chunk_duration/min_chunk_duration长音频自动分块参数默认 1200 秒一块prefill_step_size预填充步长默认 2048。CLI 使用命令行转写CLI 入口与 Python 等价适合批处理或脚本调用mlx_audio.stt.generate \ --model mlx-community/Fun-ASR-Nano-2512 \ --audio audio.wav \ --output-path transcript \ --language zh \ --context 开放时间, 地址--output-path指定结果保存位置--language与--context分别对应 Python 侧的language与热词参数--context是 CLI/服务端共享的字符串形式见 generate.py 中的参数定义。转写结果同样会返回text、segments与 token 统计。参数详解语言、热词与 ITNlanguageISO 语言提示与方言映射language接受 ISO 风格语言码当前 Nano 检查点支持的取值包括zh中文中文方言码yue粤语、wuu吴语、nan闽南语、hak客家话、gan赣语、hsn湘语、cjy晋语——这些代码统一映射到中文提示词en英文ja日文。传None或auto则省略语言约束。源码中完整的映射表ISO_TO_PROMPT_LANGUAGE还接受zh-cn、zh-tw、cmn、eng、jpn等别名fun_asr_nano.py_map_language会将其规范化为中文、英文或日文标签再拼入提示词——例如languagezh最终生成 语音转写成中文 形式的指令若传入不支持的语言码如ko会抛出ValueError并列出支持列表。hotwords 与 context领域热词偏置hotwords接受领域术语列表会被拼入上游提示词实现上下文偏置。其内部生成的提示词结构_prompt_text为请结合上下文信息更加准确地完成语音转写任务。如果没有相关信息我们会留空。 **上下文信息** 热词列表[开放时间, 地址] 语音转写成中文context是共享的字符串别名CLI 的--context与 OpenAI 兼容服务端POST /v1/audio/transcriptions的context字段都会走同一条路径。需要特别注意的是非空的hotwords与context互斥——_resolve_hotwords会先剔除空白项若两者同时非空则抛出ValueError(Pass either hotwords or context, not both.)。测试用例test_fun_asr_nano.py覆盖了各种空值组合、生成器惰性列表的物化以及分块时热词逐块复用的行为可据此验证自己的调用方式。itn是否做文本规整itnFalse时要求模型跳过逆文本规整inverse text normalization。从提示词构造逻辑可以看到关闭 ITN 会在语言指令后追加不进行文本规整修饰itn默认True适合需要保留口语原貌数字、金额按口述形式输出的场景result model.generate(audio.wav, languagezh, itnFalse)边界与限制转写之外的注意事项仅支持转写MLX 实现是 transcription-only。公开的FunAudioLLM/Fun-ASR-Nano-2512检查点不含时间戳头timestamp head权重因此该模型不输出词级时间戳VAD 与说话人分离是外置能力需要分段或区分说话人时请先调用 VAD / 分离工具处理音频再把切分结果送入本模型。源码级原理音频特征到提示词注入的完整链路为了让你更深入理解参数如何生效这里梳理一下前向链路audio.py fun_asr_nano.py特征提取prepare_audio先把输入统一重采样到 16kHz 单声道按FrontendConfigconfig.py计算 Kaldi 风格梅尔滤波器组——80 维 mel、25ms 帧长、10ms 帧移、Hamming 窗、0.97 预加重LFR 低帧率压缩apply_lfr以lfr_m7, lfr_n6做低帧率压缩把相邻 7 帧堆叠为 1 帧约 6 倍降帧并同步推算fake_token_length预估音频对应的 token 占位长度编码器与适配器特征经过SenseVoiceEncoderSmall与AudioAdaptorTransformerdownsample_rate1、ffn_dim2048、llm_dim1024、2 层 Transformer得到与 LLM 维度对齐的语音嵌入提示词注入_build_prompt_ids用 ChatML 格式拼接systemuser提示词含热词、语言、ITN 指令把语音嵌入插入到提示词 token 序列中间fbank_beg位置得到完整的inputs_embeds交给 Qwen3-0.6B 自回归解码解码与分段generate_step以{151643, 151645}为 EOS 停止条件超长音频通过split_audio_into_chunks自动分块每块独立转写后合并成完整结果测试test_fun_asr_nano.py验证了context会在每个音频块中被正确复用。理解这条链路后你就能解释所有参数的行为语言约束和热词本质上是提示词工程ITN 是提示词修饰而长音频分块则是特征侧的处理——这正是LLM 统一框架式 ASR 模型的典型实现思路。【免费下载链接】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 中的 Fun-ASR-Nano-2512 实战指南：转换、推理、热词与语言约束
mlx-audio 中的 Fun-ASR-Nano-2512 实战指南转换、推理、热词与语言约束【免费下载链接】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-audioFun-ASR-Nano-2512 是 FunAudioLLM 推出的紧凑型语音识别ASR模型本指南讲解它在 mlx-audio 仓库中的完整落地路径从 PyTorch 权重转换为 MLX 格式到 Python/CLI 双入口调用再到language、hotwords/context、itn等关键参数的底层行为。读完本文你将能够在 Apple Silicon 上独立完成该模型的转换、推理与领域热词校准并理解其 SenseVoice 风格编码器 Qwen3-0.6B 解码器的内部协作机制。模型概览一个编码器 语言模型的紧凑 ASR 架构Fun-ASR-Nano-2512 定位为轻量级语音转写模型整体约 0.8B 参数支持中文、英文、日文三种语言。它的结构可以拆成三段详见 fun_asr_nano.pySenseVoice 风格的音频编码器SenseVoiceEncoderSmall接收梅尔滤波器组特征经过 50 层 SANM 编码层与 20 层 TP 编码层输出语音表征音频适配器AudioAdaptorTransformer把编码器输出下采样并对齐到语言模型的嵌入维度llm_dim: 1024Qwen3-0.6B 文本解码器Qwen3CausalLM以语言条件提示词language prompt为前缀逐 token 自回归生成转写文本。这种设计的最大特点是用语言模型统一了听与写热词、语言约束、是否做文本规整ITN都被编码成提示词文本喂给 LLM而不是像传统 ASR 那样挂在解码图外部因此上下文偏置contextual biasing的实现非常直接——改提示词即可。权重转换从 model.pt 到可直接上传的 MLX 目录上游发布版只提供 PyTorch 权重model.pt需要使用模型专属转换器转换python -m mlx_audio.stt.models.fun_asr_nano.convert \ --hf-path FunAudioLLM/Fun-ASR-Nano-2512 \ --mlx-path Fun-ASR-Nano-2512-mlx转换器会完成以下工作对应 convert.py下载并解析检查点通过snapshot_download拉取上游仓库只保留model.pt、README.md、Qwen3-0.6B/*与example/*相关文件权重转换把 PyTorch tensor 转为 MLX 数组默认使用bfloat16精度。其中fsmn_block.weight这类形状为(C, 1, K)的卷积核会被转置为(C, K, 1)以匹配 MLX 卷积布局llm.lm_head.weight由于与嵌入层权重共享tied weights会被跳过运行时直接复用embed_tokens的权重矩阵生成运行时配置写入config.json包含前端参数、编码器与适配器结构以及直接从上游Qwen3-0.6B/config.json拷贝的文本模型配置拷贝配套文件将Qwen3-0.6Btokenizer 目录复制到输出目录post_load_hook会从这个子目录加载 tokenizer并生成一份带 front-matter 的README.md。转换器还提供几个可选参数参数默认值说明--dtypebfloat16稠密权重精度可选float16/bfloat16/float32--revision无指定上游 Hugging Face 仓库的 revision--no-examples关闭不拷贝上游 example 音频文件--no-overwrite关闭转换前不删除已存在的输出目录转换完成后输出目录结构为model.safetensorsconfig.jsonQwen3-0.6B/tokenizerREADME.md可直接整体上传为 Hugging Face 仓库例如mlx-community/Fun-ASR-Nano-2512之后就能按仓库 ID 加载。Python 使用三行代码完成转写通过统一的 STT 加载入口见 utils.py 的load_model/load内部通过MODEL_REMAPPING把fun_asr_nano路由到对应实现即可加载转换后的模型from mlx_audio.stt.utils import load_model model load_model(mlx-community/Fun-ASR-Nano-2512) result model.generate(audio.wav, languagezh, hotwords[开放时间]) print(result.text)generate返回一个STTOutput对象定义见 base.py除了text外还包含segments分段起止时间与文本、prompt_tokens/generation_tokens/total_tokenstoken 统计以及total_time、prompt_tps、generation_tps吞吐指标方便在脚本中做质量与性能观测。除了文档中的三个核心参数generate还暴露了完整的解码控制参数源码签名见 fun_asr_nano.pymax_tokens单段最大生成 token 数未指定时取配置中的default_max_tokens默认 512temperature/top_p/top_k/min_p/min_tokens_to_keep采样参数默认temperature0.0即贪心解码repetition_penalty/repetition_context_size重复惩罚chunk_duration/min_chunk_duration长音频自动分块参数默认 1200 秒一块prefill_step_size预填充步长默认 2048。CLI 使用命令行转写CLI 入口与 Python 等价适合批处理或脚本调用mlx_audio.stt.generate \ --model mlx-community/Fun-ASR-Nano-2512 \ --audio audio.wav \ --output-path transcript \ --language zh \ --context 开放时间, 地址--output-path指定结果保存位置--language与--context分别对应 Python 侧的language与热词参数--context是 CLI/服务端共享的字符串形式见 generate.py 中的参数定义。转写结果同样会返回text、segments与 token 统计。参数详解语言、热词与 ITNlanguageISO 语言提示与方言映射language接受 ISO 风格语言码当前 Nano 检查点支持的取值包括zh中文中文方言码yue粤语、wuu吴语、nan闽南语、hak客家话、gan赣语、hsn湘语、cjy晋语——这些代码统一映射到中文提示词en英文ja日文。传None或auto则省略语言约束。源码中完整的映射表ISO_TO_PROMPT_LANGUAGE还接受zh-cn、zh-tw、cmn、eng、jpn等别名fun_asr_nano.py_map_language会将其规范化为中文、英文或日文标签再拼入提示词——例如languagezh最终生成 语音转写成中文 形式的指令若传入不支持的语言码如ko会抛出ValueError并列出支持列表。hotwords 与 context领域热词偏置hotwords接受领域术语列表会被拼入上游提示词实现上下文偏置。其内部生成的提示词结构_prompt_text为请结合上下文信息更加准确地完成语音转写任务。如果没有相关信息我们会留空。 **上下文信息** 热词列表[开放时间, 地址] 语音转写成中文context是共享的字符串别名CLI 的--context与 OpenAI 兼容服务端POST /v1/audio/transcriptions的context字段都会走同一条路径。需要特别注意的是非空的hotwords与context互斥——_resolve_hotwords会先剔除空白项若两者同时非空则抛出ValueError(Pass either hotwords or context, not both.)。测试用例test_fun_asr_nano.py覆盖了各种空值组合、生成器惰性列表的物化以及分块时热词逐块复用的行为可据此验证自己的调用方式。itn是否做文本规整itnFalse时要求模型跳过逆文本规整inverse text normalization。从提示词构造逻辑可以看到关闭 ITN 会在语言指令后追加不进行文本规整修饰itn默认True适合需要保留口语原貌数字、金额按口述形式输出的场景result model.generate(audio.wav, languagezh, itnFalse)边界与限制转写之外的注意事项仅支持转写MLX 实现是 transcription-only。公开的FunAudioLLM/Fun-ASR-Nano-2512检查点不含时间戳头timestamp head权重因此该模型不输出词级时间戳VAD 与说话人分离是外置能力需要分段或区分说话人时请先调用 VAD / 分离工具处理音频再把切分结果送入本模型。源码级原理音频特征到提示词注入的完整链路为了让你更深入理解参数如何生效这里梳理一下前向链路audio.py fun_asr_nano.py特征提取prepare_audio先把输入统一重采样到 16kHz 单声道按FrontendConfigconfig.py计算 Kaldi 风格梅尔滤波器组——80 维 mel、25ms 帧长、10ms 帧移、Hamming 窗、0.97 预加重LFR 低帧率压缩apply_lfr以lfr_m7, lfr_n6做低帧率压缩把相邻 7 帧堆叠为 1 帧约 6 倍降帧并同步推算fake_token_length预估音频对应的 token 占位长度编码器与适配器特征经过SenseVoiceEncoderSmall与AudioAdaptorTransformerdownsample_rate1、ffn_dim2048、llm_dim1024、2 层 Transformer得到与 LLM 维度对齐的语音嵌入提示词注入_build_prompt_ids用 ChatML 格式拼接systemuser提示词含热词、语言、ITN 指令把语音嵌入插入到提示词 token 序列中间fbank_beg位置得到完整的inputs_embeds交给 Qwen3-0.6B 自回归解码解码与分段generate_step以{151643, 151645}为 EOS 停止条件超长音频通过split_audio_into_chunks自动分块每块独立转写后合并成完整结果测试test_fun_asr_nano.py验证了context会在每个音频块中被正确复用。理解这条链路后你就能解释所有参数的行为语言约束和热词本质上是提示词工程ITN 是提示词修饰而长音频分块则是特征侧的处理——这正是LLM 统一框架式 ASR 模型的典型实现思路。【免费下载链接】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），仅供参考 
