企业官网建设流程全解析

• 人工智能
• 大模型
• 机器学习
• 深度学习
• 本地部署
• 模型推理服务

本篇技术指南以 candle-examples/examples/whisper-microphone/README.md 为骨架，围绕 Candle（Rust 极简机器学习框架）中基于 Whisper 模型、以麦克风作为实时输入源的语音识别（ASR）示例展开。读完本文，你将掌握该示例的启动命令与 feature 机制、输出日志的含义、全部命令行参数、底层"录音 → 重采样 → 梅尔频谱 → 解码"的数据流，以及语言检测、量化推理等进阶用法，并能直接在自己的机器上运行一套实时语音转写程序。

示例简介：从"音频文件"到"麦克风实时输入"

仓库中的常规 candle-whisper 示例 以.wav文件作为输入，而whisper-microphone则把输入源换成了计算机的默认麦克风：程序持续从音频输入设备采集 PCM 数据，经过重采样与梅尔频谱计算后，交给 Candle 实现的 Whisper 模型进行端到端推理，并把识别出的文本按时间分段打印到终端。它对应的源码位于 main.rs 与 multilingual.rs，音频特征计算复用的是 candle-transformers 的 whisper 模块。

值得注意的是，README 本身内容精炼，但源码非常完整——它同时封装了普通 FP32 模型与 GGUF 量化模型两条推理路径、多语言检测、温度回退（temperature fallback）等逻辑，这些都会在后续小节中逐一展开。

运行示例：一条命令开启实时转写

README 给出的启动命令如下：

$ cargo run --example whisper-microphone --features microphone

需要特别说明两点：

1. 必须启用microphonefeature。在 candle-examples/Cargo.toml 中定义：microphone = ["cpal", "rubato"]。cpal负责跨平台音频输入（在 Linux/macOS/Windows 上统一抽象麦克风设备），rubato负责采样率重采样。同时 Cargo.toml 中通过[[example]]声明whisper-microphone的required-features = ["microphone"]，因此不带 feature 直接运行会编译失败。
2. 默认模型是tiny.en（见下方--model参数），首次运行时程序会通过 candle-examples/src/hub.rs 中的Api（基于hf-hub）自动下载config.json、tokenizer.json、model.safetensors到本地缓存，之后启动会直接复用缓存。

README 给出了一个典型的运行输出：

> transcribing audio... > 480256 160083 > language_token: None > 0.0s -- 30.0s: Hello, hello, I don't know if this is working, but You know, how long did I make this? > 480256 160085

其含义为：

• transcribing audio...：麦克风音频流已启动，主循环开始阻塞等待音频数据（对应 main.rs）；
• 480256 160083：{缓冲的原始 PCM 样本数} {重采样后的 16kHz 样本数}。程序每累积约 10 秒（10 * in_sample_rate）原始样本才触发一次处理，重采样后变成 16 kHz 单声道样本；
• language_token: None：本次使用英文专用模型（tiny.en），不进行语言检测，因此语言 token 为空；
• 0.0s -- 30.0s: ...：当前音频段对应的时间区间与识别出的文本；
• 程序会持续循环，直到用户手动停止（Ctrl+C）。

命令行参数：完整控制推理行为

Args结构体定义在 main.rs，全部参数如下表：

支持的模型清单

WhichModel枚举定义于 main.rs，支持的模型与仓库/revision 对应关系如下（摘自model_and_revision，main.rs）：

• 多语言模型：tiny、base、small、medium、large、large-v2、large-v3、large-v3-turbo、distil-large-v2；
• 仅英文模型：tiny.en、base.en、small.en、medium.en、distil-medium.en。

多语言模型默认从openai/whisper-*仓库的特定 revision（如refs/pr/22）拉取权重，英文模型与较新版本则使用main。--quantized模式下默认仓库切换为lmz/candle-whisper，并约定文件名规则：config-{ext}.json、tokenizer-{ext}.json、model-{ext}-q80.gguf（ext取tiny或tiny-en），量化模式目前仅支持 tiny/tiny.en 两档（main.rs）。

数据流拆解：麦克风 PCM 如何变成识别文本

从源码可以完整还原整条实时流水线（对应 main.rs 的主流程）：

1. 采集：通过cpal::default_host()获取默认主机，用default_input_device()找到默认麦克风，读取default_input_config()（打印采样率、声道数等配置）。回调函数按step_by(channel_count)抽取单声道，通过 mpsc 通道把 PCM 块发送给主线程（main.rs）。
2. 缓冲与重采样：主循环用buffered_pcm累积数据，不足 10 秒（10 * in_sample_rate）则继续等待；每 1024 个样本为一 chunk 交给rubato::Async多项式重采样器，目标采样率统一为 16000 Hz（resample_ratio = 16000. / in_sample_rate）。若输入产生非 1024 倍数的余数，则把余数搬到缓冲头部留到下一轮处理，避免数据丢失（main.rs）。
3. 梅尔频谱：调用audio::pcm_to_mel(&config, &pcm, &mel_filters)生成[1, num_mel_bins, frames]的梅尔频谱张量。底层实现在 candle-transformers/src/models/whisper/audio.rs：对加汉宁窗的样本做 FFT/DFT、计算功率谱、乘以梅尔滤波器组后取log10，并做归一化；FFT 计算按线程数拆分并行（最多 12 线程）。梅尔滤波器权重由melfilters.bytes/melfilters128.bytes按num_mel_bins（80 或 128）选择（main.rs）。
4. 语言检测（仅多语言模型）：首次迭代时若模型为多语言且未指定--language，调用multilingual::detect_language（multilingual.rs）：编码音频特征后，对 99 种语言的<|xx|>语言 token 打分并 softmax，打印概率最高的前 5 种语言，取最高者作为语言 token。语言代码表（en/zh/de/.../haw等 99 项）同样在 multilingual.rs。若指定了--language，则直接查 tokenizer 中的<|{language}|>token；英文专用模型则固定为None。
5. 解码：decoder.run(&mel, None)把 30 秒窗口的梅尔频谱切成最大 3000 帧（N_FRAMES，见 candle-transformers/src/models/whisper/mod.rs）的片段逐段处理，每段先经decode_with_fallback生成文本与no_speech_prob，再按需打印{start}s -- {end}s: {text}（main.rs）。每轮处理后调用reset_kv_cache()清空跨片段的 KV 缓存。

解码器与温度回退机制

Decoder::decode（main.rs）实现了一次标准的自回归解码：以<|startoftranscript|>（可选语言 token、任务 token、<|notimestamps|>）为起始 token，循环调用decoder_forward与decoder_final_linear，对 logits 施加suppress_tokens（把配置中的抑制 token 与 timestamps 模式下的<|notimestamps|>设为-inf），再按温度选择贪心（t=0）或加权随机采样（t>0），直到遇到<|endoftext|>或超过max_target_positions。

decode_with_fallback（main.rs）则复用了 whisper 模块的阈值常量（定义于 candle-transformers/src/models/whisper/mod.rs）：温度序列TEMPERATURES = [0.0, 0.2, 0.4, 0.6, 0.8, 1.0]，当compression_ratio > 2.4或avg_logprob < -1.0且no_speech_prob <= 0.6时，用更高温度重试，从而缓解重复文本与低置信度输出的问题。运行期间若no_speech_prob > 0.6且平均对数概率过低，则判定为无语音并跳过该段。

模型加载：普通权重与 GGUF 量化两条路径

Model枚举（main.rs）统一封装了两种后端，并对其暴露相同的encoder_forward/decoder_forward/decoder_final_linear接口：

• Normal：m::model::Whisper，权重来自model.safetensors，通过VarBuilder::from_mmaped_safetensors以内存映射方式加载，dtype 为F32（m::DTYPE）；
• Quantized：m::quantized_model::Whisper，权重来自 GGUF 文件，通过 candle-transformers 的 quantized_var_builder 加载并即时反量化。

两种模型均读取同一份config.json（Config结构含num_mel_bins、d_model、encoder_layers、vocab_size等字段，见 candle-transformers/src/models/whisper/mod.rs）。量化路径可以显著降低内存占用，适合无 GPU 的机器实时转写；选择何种路径由--quantized开关控制。

依赖与运行环境

运行本示例需要：

• 可用的音频输入设备（麦克风），且系统具有cpal支持的音频后端（ALSA/CoreAudio/WASAPI 等）；
• 首次运行联网下载模型权重（可由HF_HUB_CACHE等环境变量控制缓存位置，见 candle-examples/src/hub.rs）；
• 如需 GPU 加速，可在运行前用--features cuda（NVIDIA）或--features metal（Apple Silicon）构建，否则默认回退 CPU（candle-examples/src/lib.rs 会打印对应提示）。

小结与扩展

whisper-microphone是 Candle 生态中"实时音频输入 + ASR 推理"的完整参考实现：一条cargo run --example whisper-microphone --features microphone命令即可把默认麦克风变成实时语音转写器，支持多语言自动检测、翻译任务、量化部署与温度回退等生产级细节。对同一套 Whisper 实现的进一步研究，可阅读：

• 音频文件版示例说明：candle-examples/examples/whisper/README.md
• Whisper 模型定义与常量：candle-transformers/src/models/whisper/mod.rs
• 音频预处理（FFT/梅尔谱）：candle-transformers/src/models/whisper/audio.rs
• 普通模型网络结构：candle-transformers/src/models/whisper/model.rs
• 量化模型网络结构：candle-transformers/src/models/whisper/quantized_model.rs

• 人工智能
• 大模型
• 机器学习
• 深度学习
• 本地部署
• 模型推理服务