尧图网站建设 
在 mlx-audio 中运行 VoxCPM248kHz、无词表多语言 TTS 的 MLX 推理指南【免费下载链接】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-audioVoxCPM2 是 mlx-audio 提供的 2B 参数、多语言、tokenizer-free无离散音频词表TTS 模型输出 48kHz 录音室音质音频覆盖中英文、日语、韩语、印尼语等 30 种语言并原生支持零样本生成、文字描述设计音色Voice Design、语音克隆Voice Cloning与长语音续写Continuation。本文基于仓库内 VoxCPM2 模块文档结合 主实现文件、DiT/CFM 采样器 与 单元测试 的源码证据系统讲解其加载方式、五种生成模式、全部生成参数与底层架构帮助你在 Apple Silicon 上完整跑通并调优该模型。模型定位与能力概览VoxCPM2 的核心卖点来自其模块文档2B 参数、多语言、48kHz 输出且不使用离散音频 tokentokenizer-free而是直接对连续音频潜变量做自回归 扩散生成。原始模型来自 openbmb/VoxCPM2mlx-audio 将其移植到 Apple 的 MLX 框架提供 bf16 / 8-bit / 4-bit 三种量化档位模型参数格式大小mlx-community/VoxCPM2-bf162Bbf164.96 GBmlx-community/VoxCPM2-8bit2B8-bit3.23 GBmlx-community/VoxCPM2-4bit2B4-bit2.30 GB四种对外能力对应实现中的五种输入模式主实现 generate 方法 的 docstring 明确列出Zero-shot仅文本Voice design通过instruct参数提供文字音色描述Continuationprompt_textprompt_audio 文本从已有音频续写Reference cloningref_audio 文本克隆参考音色Combinedref_audioprompt_textprompt_audio 文本克隆音色并延续前文文档未提及但源码已实现。加载模型与基本生成模型通过 mlx-audio 统一的 TTS 加载入口获取模型类型voxcpm2在 mlx_audio/tts/utils.py 的MODEL_REMAPPING中注册因此load会自动路由到 voxcpm2.py 中的Model类from mlx_audio.tts.utils import load model load(mlx-community/VoxCPM2-8bit) result next(model.generate(Hello, this is VoxCPM2 on Apple Silicon.)) audio result.audio # mlx array, 48kHz几点值得注意的实现细节model.generate(...)是生成器因此用next(...)取出GenerationResultresult.audio的采样率由model.sample_rate决定而该属性返回 AudioVAEConfig.out_sample_rate即 48000。加载完成后post_load_hook 会用transformers.AutoTokenizer.from_pretrained从模型仓库加载文本 tokenizer所以运行环境需要安装transformers。GenerationResult携带了可观的运行时元数据音频时长audio_duration、实时率real_time_factor大于 1 表示比实时更快、每秒 token 数、每秒样本数、处理耗时与峰值内存peak_memory_usageGB在 generate 末尾的 yield 处一次性填好可直接用于性能分析。中文文本有一个专门的预处理_split_multichar_chinese_tokens 会把多字中文 token 拆成单字以匹配 OpenBMB 原始模型的 tokenize 行为保证中英文混合输入的一致性。五种生成模式详解1. 零样本生成只传文本即可属于文档中的默认路径。内部流程文本经_tokenize转成 token id 并追加audio_start_tokenid101文本与音频位置分别用text_mask/audio_mask加权融合成统一的 embedding 序列随后进入自回归循环。2. Voice Design文字描述造音色result next(model.generate( textHello, welcome to VoxCPM2., instructA young woman, warm and gentle voice, ))从源码看voxcpm2.py 第 443-448 行instruct的实现非常简单直接把描述拼到文本前面形成(A young woman, warm and gentle voice)Hello, welcome to VoxCPM2.。模型在训练中已学会解析这种(描述)正文格式。同时源码还做了一个针对 warmup 的微调描述本身已经提供了充分的发声上下文若warmup_patches 1会被自动压到 1减少无用的预热 patch。3. Voice Cloning参考音频克隆result next(model.generate( textThis text will be spoken in the reference voice., ref_audiospeaker.wav, ))参考音频的完整处理链在 _encode_wav 与 _make_ref_prefix文件经 audio_io.read 读入若是多声道会取均值转单声道采样率不等于 16kHz 时自动重采样到 16kHzVAE 编码端采样率若直接传入mx.array/numpy 数组则假定它是model.sample_rate48kHz并同样重采样到 16kHz。可选地做能量法 VAD 静音裁剪_trim_audio_silence_vad2048 帧长、512 跳步、-35dB 阈值保留首尾各 200ms 余量但默认关闭trim_silence_vadFalse。音频被补齐到 patch 对齐长度后经 AudioVAE 编码成潜变量reshape 为(num_patches, patch_size, feat_dim)的 patch 序列。构造参考前缀token 序列为[103(ref_audio_start), 0*ref_len, 104(ref_audio_end)]潜变量序列为[零 patch, ref_feat, 零 patch]前后各垫一个零 patch 作为边界。4. Continuation长语音续写面向有声书等长篇内容的核心模式result next(model.generate( text and this continues seamlessly from the previous sentence., prompt_textThe previous sentence spoken aloud, prompt_audioprevious.wav, ))实现上有三个关键机制generate 主体、L603-L618、L680-L685prompt_audio以padding_modeleft编码prompt_text text合并后统一 tokenize检测到序列末尾是音频audio_mask[0, -1] 1.0时进入续写状态取前streaming_prefix_len - 1默认 3个最近的 prompt patch 作为解码条件上下文保证续写的声学起点与上文平滑衔接续写模式下warmup_patches被强制归零上文本身就是上下文无需预热解码完成后会从输出头部裁掉decode_patch_len * (streaming_prefix_len - 1)个样本即把用于条件化的上文片段从最终音频中剔除——这正是「无缝续写」的实现来源。5. Combined克隆 续写组合模式同时提供ref_audio与prompt_text/prompt_audio时L461-L494参考前缀置于序列最前其后的文本段prompttext配零潜变量末尾放 prompt 音频潜变量。这样生成的音频既继承参考音色又从给定上文继续适合「用某音色朗读整本书、逐段续写」的场景。生成参数全解模块文档给出的参数表如下并补充源码中确认的取值细节ParameterDefaultDescriptioninference_timesteps10CFM diffusion steps. Lower faster, higher better qualitycfg_value2.0Classifier-free guidance strengthinstructNoneVoice description for voice design moderef_audioNoneReference audio path or array for voice cloningprompt_textNoneText of the prompt audio for continuation modeprompt_audioNonePrompt audio path or array for continuation modewarmup_patches0Extra patches to generate before output (for onset stability)max_tokens2000Maximum number of audio patches to generate源码层面还有几个文档没有明说的细节CFG 下限保护generate 开头 对cfg_value做了max(cfg_scale, 2.0)的钳制——即使传入更小的 guidance 值实际生效的也不会低于 2.0。这与 CFMConfig.inference_cfg_rate 的默认值 2.0 一致可以推断低于 2.0 会显著损害该模型的音质。CLI 别名cfg_scale会被映射到cfg_valueddpm_steps映射到inference_timesteps方便沿用其他 TTS 模型的参数习惯。max_tokens的语义是「音频 patch 数」而非 token 数每个 patch 由patch_size默认 4见 ModelArgs个潜变量帧组成循环上限是max_tokens warmup_patches。停止判定循环内每步用stop_projLinear SiLU stop_head2 类无偏置预测是否停止且只有在真实输出超过min_tokens默认 2个 patch 后才允许触发避免过短截断。warmup patch 不进输出if i warmup_patches才收集 patchwarmup 的作用是预热 LM/残差 LM 的 KV cache 与条件上下文消除起音伪影onset artifacts但会从结果中剔除。CLI 使用mlx-audio 提供统一的 TTS CLI 入口mlx_audio/tts/generate.py三个典型用法与模块文档一致# Zero-shot python -m mlx_audio.tts.generate \ --model mlx-community/VoxCPM2-8bit \ --text Hello world \ --play # Voice design python -m mlx_audio.tts.generate \ --model mlx-community/VoxCPM2-8bit \ --text Hello world \ --instruct A young woman, gentle voice \ --play # Voice cloning python -m mlx_audio.tts.generate \ --model mlx-community/VoxCPM2-8bit \ --text Hello world \ --ref_audio speaker.wav \ --ref_text placeholder \ --playCLI 侧值得展开的实现逻辑均在 generate_audio 函数为什么克隆示例要传--ref_text placeholder当--ref_audio给了而--ref_text没给时CLI 会检查模型generate签名是否接受ref_textVoxCPM2 接受于是 CLI 默认加载 Whisper STT 模型--stt_model默认mlx-community/whisper-large-v3-turbo-asr-fp16先转写参考音频。传一个占位文本即可跳过这次额外的 STT 加载与转写。参数透传--cfg_scale与--ddpm_steps非 None 时才注入gen_kwargs因此不传就完全使用模型默认2.0 / 10--ref_audio是append型参数可重复传入多段参考VoxCPM2 侧按单条处理。输出控制--play播放--stream--save可边生成边落盘--output_path/--file_prefix/--audio_format控制保存位置与格式--verbose打印时长、samples/sec、tokens/sec、实时率、耗时与峰值内存正是GenerationResult的字段。--text留空时会从 stdin 读取方便管道批量输入。架构解析五个组件如何协同模块文档的 Architecture 一节列出了五个组件下面结合源码逐一印证。MiniCPM 主干 LMMiniCPMModel 即主干语言模型。单元测试中解析真实模型 config 的结果印证了文档描述hidden_size2048、num_hidden_layers28、16 个注意力头配 2 个 KV 头GQA、kv_channels128、词表 73448、rope_scaling为 longrope 且original_max_position_embeddings32768。文本 embedding 在进入主干前会乘以 mup 缩放因子scale_embgenerate L575use_mup由 config 决定。残差 LM 与 V2 融合投影模型同时维护第二条较小的 LMresidual_lm层数取residual_lm_num_layers默认 8与文档一致vocab_size0表示无词表头真实配置开启no_rope即文档中的 no RoPE。V2 版的关键变化是 fusion_concat_proj残差 LM 的输入不再由简单相加得到而是把主干输出或 embedding与特征 embedding 沿最后一维拼接后经Linear(2H - H)投影。自回归循环中每一步主干隐状态与残差隐状态分别经lm_to_dit_proj、res_to_dit_proj投影后拼接成(1, 2*H)的 mu 送入 DiT——这就是文档所说的 multi-token mu。VoxCPMLocDiTV2 CFM 采样dit.py 中DiT 估计器本身也是一个MiniCPMModelvocab 0输入序列为[mu_tokens, t_token, cond_proj, x_proj]的拼接、以非因果is_causalFalse方式前向再切出目标位置输出经out_proj还原到潜变量维度cond是上一个 patch 的转置形式(B, D, P)充当时间条件。UnifiedCFM.sample 的完整采样流程从标准高斯噪声出发temperature1.0形状(B, feat_dim, patch_size)时间网格linspace(1, 0, n1)再做余弦 sway 变换t cos(πt/2) - 1 t把更多步数压向低噪声端solve_euler 以 Euler 法积分批内做条件/无条件成对前向后按 CFG 组合前max(1, 4%步数)步直接置零速度场对应 CFG zero-star 策略随后用st_star条件与无条件预测的正交投影系数做去相关的 CFG 组合cfg_value即乘在此处的引导强度。inference_timesteps10即这里的 Euler 步数也是每 patch 的 DiT 前向次数之一源码注释称 DiT 估计器占单步耗时约 54%。标量量化FSQ层ScalarQuantizationLayer 实现Linear(in-512) → tanh → round(·9)/9 → Linear(512-out)的标量量化scalar_quantization_latent_dim512、scalar_quantization_scale9定义在 ModelArgs。它把主干输出离散化成 9 个量化等级的隐表示——这正是 tokenizer-free 但仍带 token 压缩 的落点不引入离散词表与 VQ 码本却保留了近似离散信息的压缩与可预测性。前向时该层只在音频位置生效用audio_mask选择。AudioVAE V216kHz 编码 / 48kHz 解码的非对称设计AudioVAE 的默认配置AudioVAEConfig编码器下采样率[2, 5, 8, 8]、解码器上采样率[8, 6, 5, 2, 2, 2]、latent_dim64、sample_rate16000、out_sample_rate48000。chunk_size prod(encoder_rates)、decode_chunk_size prod(decoder_rates)分别定义编码/解码方向上每潜变量帧对应的样本数audio_vae.py L400-L402。样本率条件化sample-rate conditioning是其 V2 特性解码器持有_sr_boundaries缓冲默认[20000, 30000, 40000]见 audio_vae.py L339-L375把目标采样率映射为 bin 索引后过 embedding再以scale_bias方式注入各解码块cond_typescale_bias。因此解码器可以按out_sample_rate48000输出高频带完整的声音而编码端始终工作在 16kHz——编码路径被降规格换来更低计算量解码路径保留 48kHz 音质。其他工程细节sanitizevoxcpm2.py L315-L394负责权重形状修复矩阵转置校正、VAE 权重的独立 sanitize、sr_boundaries这类非参数缓冲的提取、缺失 RoPE buffer 的补算若主权重里没有audio_vae.*还会尝试从模型目录的audiovae.safetensors或audiovae.pth单独载入。compile_modelL166-L182用mx.compile编译热点路径CFM 估计器与主干/残差 LM/特征编码器的每一层self_attn、mlp用于进一步降低单步延迟。配置解析与注册机制模型 config 由 ModelArgs.from_dict 解析两个兼容点值得留意lm_config.rope_scaling嵌套字典会被展开为rope_scaling_type/rope_long_factor/rope_short_factor等平铺字段dit_config.mean_mode是dit_mean_mode的旧名别名mean_mode控制 CFM 是否向 DiT 传递真实 dt 值见 solve_euler L131-L135。test_from_dict_parses_real_config 用真实模型 config 验证了 2048/28 层主干、12 层 DiT、out_sample_rate48000等关键取值test_mean_mode_alias 则覆盖了别名映射。更完整的测试矩阵在 mlx_audio/tts/tests/test_models.py 第 7753 行起用小尺寸_tiny_voxcpm2_args配置分别覆盖 config 解析、VAE 编解码形状、MiniCPM 注意力、DiT 前向、_tokenize中文拆字、注册表映射等路径是理解各组件输入输出形状的最佳参考。适用前提与许可运行环境为 Apple Silicon MLX模型从 Hugging Face Hub 拉取mlx-community/VoxCPM2-*三种量化档位可按内存预算选择8-bit3.23 GB是文档推荐的默认档位。tokenizer 依赖transformers的AutoTokenizer从模型仓库目录加载。48kHz 输出为解码端固定行为out_sample_rate参考/prompt 音频任意采样率均可会被自动重采样到 16kHz 编码端。许可VoxCPM2 以 Apache License 2.0 发布见 模块文档 License 一节。小结VoxCPM2 在 mlx-audio 中是一个主干 LM 残差 LM CFM DiT 非对称 AudioVAE四段式流水线标量量化替代离散 token 保持 tokenizer-free 特性16kHz 编码 / 48kHz 解码的 VAE 以样本率条件化换取音质与计算量的平衡续写模式则靠前缀 patch 条件化与输出裁剪实现无缝长语音。对使用者而言loadgenerate两个接口即可覆盖零样本、音色设计、克隆与续写四类场景参数调优重点关注inference_timesteps、cfg_value不低于 2.0与warmup_patches三处即可。【免费下载链接】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 中运行 VoxCPM2：48kHz、无词表多语言 TTS 的 MLX 推理指南
在 mlx-audio 中运行 VoxCPM248kHz、无词表多语言 TTS 的 MLX 推理指南【免费下载链接】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-audioVoxCPM2 是 mlx-audio 提供的 2B 参数、多语言、tokenizer-free无离散音频词表TTS 模型输出 48kHz 录音室音质音频覆盖中英文、日语、韩语、印尼语等 30 种语言并原生支持零样本生成、文字描述设计音色Voice Design、语音克隆Voice Cloning与长语音续写Continuation。本文基于仓库内 VoxCPM2 模块文档结合 主实现文件、DiT/CFM 采样器 与 单元测试 的源码证据系统讲解其加载方式、五种生成模式、全部生成参数与底层架构帮助你在 Apple Silicon 上完整跑通并调优该模型。模型定位与能力概览VoxCPM2 的核心卖点来自其模块文档2B 参数、多语言、48kHz 输出且不使用离散音频 tokentokenizer-free而是直接对连续音频潜变量做自回归 扩散生成。原始模型来自 openbmb/VoxCPM2mlx-audio 将其移植到 Apple 的 MLX 框架提供 bf16 / 8-bit / 4-bit 三种量化档位模型参数格式大小mlx-community/VoxCPM2-bf162Bbf164.96 GBmlx-community/VoxCPM2-8bit2B8-bit3.23 GBmlx-community/VoxCPM2-4bit2B4-bit2.30 GB四种对外能力对应实现中的五种输入模式主实现 generate 方法 的 docstring 明确列出Zero-shot仅文本Voice design通过instruct参数提供文字音色描述Continuationprompt_textprompt_audio 文本从已有音频续写Reference cloningref_audio 文本克隆参考音色Combinedref_audioprompt_textprompt_audio 文本克隆音色并延续前文文档未提及但源码已实现。加载模型与基本生成模型通过 mlx-audio 统一的 TTS 加载入口获取模型类型voxcpm2在 mlx_audio/tts/utils.py 的MODEL_REMAPPING中注册因此load会自动路由到 voxcpm2.py 中的Model类from mlx_audio.tts.utils import load model load(mlx-community/VoxCPM2-8bit) result next(model.generate(Hello, this is VoxCPM2 on Apple Silicon.)) audio result.audio # mlx array, 48kHz几点值得注意的实现细节model.generate(...)是生成器因此用next(...)取出GenerationResultresult.audio的采样率由model.sample_rate决定而该属性返回 AudioVAEConfig.out_sample_rate即 48000。加载完成后post_load_hook 会用transformers.AutoTokenizer.from_pretrained从模型仓库加载文本 tokenizer所以运行环境需要安装transformers。GenerationResult携带了可观的运行时元数据音频时长audio_duration、实时率real_time_factor大于 1 表示比实时更快、每秒 token 数、每秒样本数、处理耗时与峰值内存peak_memory_usageGB在 generate 末尾的 yield 处一次性填好可直接用于性能分析。中文文本有一个专门的预处理_split_multichar_chinese_tokens 会把多字中文 token 拆成单字以匹配 OpenBMB 原始模型的 tokenize 行为保证中英文混合输入的一致性。五种生成模式详解1. 零样本生成只传文本即可属于文档中的默认路径。内部流程文本经_tokenize转成 token id 并追加audio_start_tokenid101文本与音频位置分别用text_mask/audio_mask加权融合成统一的 embedding 序列随后进入自回归循环。2. Voice Design文字描述造音色result next(model.generate( textHello, welcome to VoxCPM2., instructA young woman, warm and gentle voice, ))从源码看voxcpm2.py 第 443-448 行instruct的实现非常简单直接把描述拼到文本前面形成(A young woman, warm and gentle voice)Hello, welcome to VoxCPM2.。模型在训练中已学会解析这种(描述)正文格式。同时源码还做了一个针对 warmup 的微调描述本身已经提供了充分的发声上下文若warmup_patches 1会被自动压到 1减少无用的预热 patch。3. Voice Cloning参考音频克隆result next(model.generate( textThis text will be spoken in the reference voice., ref_audiospeaker.wav, ))参考音频的完整处理链在 _encode_wav 与 _make_ref_prefix文件经 audio_io.read 读入若是多声道会取均值转单声道采样率不等于 16kHz 时自动重采样到 16kHzVAE 编码端采样率若直接传入mx.array/numpy 数组则假定它是model.sample_rate48kHz并同样重采样到 16kHz。可选地做能量法 VAD 静音裁剪_trim_audio_silence_vad2048 帧长、512 跳步、-35dB 阈值保留首尾各 200ms 余量但默认关闭trim_silence_vadFalse。音频被补齐到 patch 对齐长度后经 AudioVAE 编码成潜变量reshape 为(num_patches, patch_size, feat_dim)的 patch 序列。构造参考前缀token 序列为[103(ref_audio_start), 0*ref_len, 104(ref_audio_end)]潜变量序列为[零 patch, ref_feat, 零 patch]前后各垫一个零 patch 作为边界。4. Continuation长语音续写面向有声书等长篇内容的核心模式result next(model.generate( text and this continues seamlessly from the previous sentence., prompt_textThe previous sentence spoken aloud, prompt_audioprevious.wav, ))实现上有三个关键机制generate 主体、L603-L618、L680-L685prompt_audio以padding_modeleft编码prompt_text text合并后统一 tokenize检测到序列末尾是音频audio_mask[0, -1] 1.0时进入续写状态取前streaming_prefix_len - 1默认 3个最近的 prompt patch 作为解码条件上下文保证续写的声学起点与上文平滑衔接续写模式下warmup_patches被强制归零上文本身就是上下文无需预热解码完成后会从输出头部裁掉decode_patch_len * (streaming_prefix_len - 1)个样本即把用于条件化的上文片段从最终音频中剔除——这正是「无缝续写」的实现来源。5. Combined克隆 续写组合模式同时提供ref_audio与prompt_text/prompt_audio时L461-L494参考前缀置于序列最前其后的文本段prompttext配零潜变量末尾放 prompt 音频潜变量。这样生成的音频既继承参考音色又从给定上文继续适合「用某音色朗读整本书、逐段续写」的场景。生成参数全解模块文档给出的参数表如下并补充源码中确认的取值细节ParameterDefaultDescriptioninference_timesteps10CFM diffusion steps. Lower faster, higher better qualitycfg_value2.0Classifier-free guidance strengthinstructNoneVoice description for voice design moderef_audioNoneReference audio path or array for voice cloningprompt_textNoneText of the prompt audio for continuation modeprompt_audioNonePrompt audio path or array for continuation modewarmup_patches0Extra patches to generate before output (for onset stability)max_tokens2000Maximum number of audio patches to generate源码层面还有几个文档没有明说的细节CFG 下限保护generate 开头 对cfg_value做了max(cfg_scale, 2.0)的钳制——即使传入更小的 guidance 值实际生效的也不会低于 2.0。这与 CFMConfig.inference_cfg_rate 的默认值 2.0 一致可以推断低于 2.0 会显著损害该模型的音质。CLI 别名cfg_scale会被映射到cfg_valueddpm_steps映射到inference_timesteps方便沿用其他 TTS 模型的参数习惯。max_tokens的语义是「音频 patch 数」而非 token 数每个 patch 由patch_size默认 4见 ModelArgs个潜变量帧组成循环上限是max_tokens warmup_patches。停止判定循环内每步用stop_projLinear SiLU stop_head2 类无偏置预测是否停止且只有在真实输出超过min_tokens默认 2个 patch 后才允许触发避免过短截断。warmup patch 不进输出if i warmup_patches才收集 patchwarmup 的作用是预热 LM/残差 LM 的 KV cache 与条件上下文消除起音伪影onset artifacts但会从结果中剔除。CLI 使用mlx-audio 提供统一的 TTS CLI 入口mlx_audio/tts/generate.py三个典型用法与模块文档一致# Zero-shot python -m mlx_audio.tts.generate \ --model mlx-community/VoxCPM2-8bit \ --text Hello world \ --play # Voice design python -m mlx_audio.tts.generate \ --model mlx-community/VoxCPM2-8bit \ --text Hello world \ --instruct A young woman, gentle voice \ --play # Voice cloning python -m mlx_audio.tts.generate \ --model mlx-community/VoxCPM2-8bit \ --text Hello world \ --ref_audio speaker.wav \ --ref_text placeholder \ --playCLI 侧值得展开的实现逻辑均在 generate_audio 函数为什么克隆示例要传--ref_text placeholder当--ref_audio给了而--ref_text没给时CLI 会检查模型generate签名是否接受ref_textVoxCPM2 接受于是 CLI 默认加载 Whisper STT 模型--stt_model默认mlx-community/whisper-large-v3-turbo-asr-fp16先转写参考音频。传一个占位文本即可跳过这次额外的 STT 加载与转写。参数透传--cfg_scale与--ddpm_steps非 None 时才注入gen_kwargs因此不传就完全使用模型默认2.0 / 10--ref_audio是append型参数可重复传入多段参考VoxCPM2 侧按单条处理。输出控制--play播放--stream--save可边生成边落盘--output_path/--file_prefix/--audio_format控制保存位置与格式--verbose打印时长、samples/sec、tokens/sec、实时率、耗时与峰值内存正是GenerationResult的字段。--text留空时会从 stdin 读取方便管道批量输入。架构解析五个组件如何协同模块文档的 Architecture 一节列出了五个组件下面结合源码逐一印证。MiniCPM 主干 LMMiniCPMModel 即主干语言模型。单元测试中解析真实模型 config 的结果印证了文档描述hidden_size2048、num_hidden_layers28、16 个注意力头配 2 个 KV 头GQA、kv_channels128、词表 73448、rope_scaling为 longrope 且original_max_position_embeddings32768。文本 embedding 在进入主干前会乘以 mup 缩放因子scale_embgenerate L575use_mup由 config 决定。残差 LM 与 V2 融合投影模型同时维护第二条较小的 LMresidual_lm层数取residual_lm_num_layers默认 8与文档一致vocab_size0表示无词表头真实配置开启no_rope即文档中的 no RoPE。V2 版的关键变化是 fusion_concat_proj残差 LM 的输入不再由简单相加得到而是把主干输出或 embedding与特征 embedding 沿最后一维拼接后经Linear(2H - H)投影。自回归循环中每一步主干隐状态与残差隐状态分别经lm_to_dit_proj、res_to_dit_proj投影后拼接成(1, 2*H)的 mu 送入 DiT——这就是文档所说的 multi-token mu。VoxCPMLocDiTV2 CFM 采样dit.py 中DiT 估计器本身也是一个MiniCPMModelvocab 0输入序列为[mu_tokens, t_token, cond_proj, x_proj]的拼接、以非因果is_causalFalse方式前向再切出目标位置输出经out_proj还原到潜变量维度cond是上一个 patch 的转置形式(B, D, P)充当时间条件。UnifiedCFM.sample 的完整采样流程从标准高斯噪声出发temperature1.0形状(B, feat_dim, patch_size)时间网格linspace(1, 0, n1)再做余弦 sway 变换t cos(πt/2) - 1 t把更多步数压向低噪声端solve_euler 以 Euler 法积分批内做条件/无条件成对前向后按 CFG 组合前max(1, 4%步数)步直接置零速度场对应 CFG zero-star 策略随后用st_star条件与无条件预测的正交投影系数做去相关的 CFG 组合cfg_value即乘在此处的引导强度。inference_timesteps10即这里的 Euler 步数也是每 patch 的 DiT 前向次数之一源码注释称 DiT 估计器占单步耗时约 54%。标量量化FSQ层ScalarQuantizationLayer 实现Linear(in-512) → tanh → round(·9)/9 → Linear(512-out)的标量量化scalar_quantization_latent_dim512、scalar_quantization_scale9定义在 ModelArgs。它把主干输出离散化成 9 个量化等级的隐表示——这正是 tokenizer-free 但仍带 token 压缩 的落点不引入离散词表与 VQ 码本却保留了近似离散信息的压缩与可预测性。前向时该层只在音频位置生效用audio_mask选择。AudioVAE V216kHz 编码 / 48kHz 解码的非对称设计AudioVAE 的默认配置AudioVAEConfig编码器下采样率[2, 5, 8, 8]、解码器上采样率[8, 6, 5, 2, 2, 2]、latent_dim64、sample_rate16000、out_sample_rate48000。chunk_size prod(encoder_rates)、decode_chunk_size prod(decoder_rates)分别定义编码/解码方向上每潜变量帧对应的样本数audio_vae.py L400-L402。样本率条件化sample-rate conditioning是其 V2 特性解码器持有_sr_boundaries缓冲默认[20000, 30000, 40000]见 audio_vae.py L339-L375把目标采样率映射为 bin 索引后过 embedding再以scale_bias方式注入各解码块cond_typescale_bias。因此解码器可以按out_sample_rate48000输出高频带完整的声音而编码端始终工作在 16kHz——编码路径被降规格换来更低计算量解码路径保留 48kHz 音质。其他工程细节sanitizevoxcpm2.py L315-L394负责权重形状修复矩阵转置校正、VAE 权重的独立 sanitize、sr_boundaries这类非参数缓冲的提取、缺失 RoPE buffer 的补算若主权重里没有audio_vae.*还会尝试从模型目录的audiovae.safetensors或audiovae.pth单独载入。compile_modelL166-L182用mx.compile编译热点路径CFM 估计器与主干/残差 LM/特征编码器的每一层self_attn、mlp用于进一步降低单步延迟。配置解析与注册机制模型 config 由 ModelArgs.from_dict 解析两个兼容点值得留意lm_config.rope_scaling嵌套字典会被展开为rope_scaling_type/rope_long_factor/rope_short_factor等平铺字段dit_config.mean_mode是dit_mean_mode的旧名别名mean_mode控制 CFM 是否向 DiT 传递真实 dt 值见 solve_euler L131-L135。test_from_dict_parses_real_config 用真实模型 config 验证了 2048/28 层主干、12 层 DiT、out_sample_rate48000等关键取值test_mean_mode_alias 则覆盖了别名映射。更完整的测试矩阵在 mlx_audio/tts/tests/test_models.py 第 7753 行起用小尺寸_tiny_voxcpm2_args配置分别覆盖 config 解析、VAE 编解码形状、MiniCPM 注意力、DiT 前向、_tokenize中文拆字、注册表映射等路径是理解各组件输入输出形状的最佳参考。适用前提与许可运行环境为 Apple Silicon MLX模型从 Hugging Face Hub 拉取mlx-community/VoxCPM2-*三种量化档位可按内存预算选择8-bit3.23 GB是文档推荐的默认档位。tokenizer 依赖transformers的AutoTokenizer从模型仓库目录加载。48kHz 输出为解码端固定行为out_sample_rate参考/prompt 音频任意采样率均可会被自动重采样到 16kHz 编码端。许可VoxCPM2 以 Apache License 2.0 发布见 模块文档 License 一节。小结VoxCPM2 在 mlx-audio 中是一个主干 LM 残差 LM CFM DiT 非对称 AudioVAE四段式流水线标量量化替代离散 token 保持 tokenizer-free 特性16kHz 编码 / 48kHz 解码的 VAE 以样本率条件化换取音质与计算量的平衡续写模式则靠前缀 patch 条件化与输出裁剪实现无缝长语音。对使用者而言loadgenerate两个接口即可覆盖零样本、音色设计、克隆与续写四类场景参数调优重点关注inference_timesteps、cfg_value不低于 2.0与warmup_patches三处即可。【免费下载链接】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），仅供参考