企业官网建设流程全解析

voxtral.c是一个零依赖的纯 C 推理引擎，可本地运行 Mistral 的 Voxtral Realtime 4B 语音识别模型（speech-to-text）。无需 Python 运行时、无需 CUDA 工具链，通过几行 C API 调用，你既可以做离线文件转写，也能做低延迟的实时流式语音识别，支持 Apple Silicon Metal GPU 加速。

为什么选择 voxtral.c 语音识别引擎 🎯

下面这个动图展示了它在终端中的流式转录效果（音频经 ffmpeg 管道送入，文字边听边出）：

第一步：下载模型并编译项目

先获取项目源码并下载约 8.9GB 的模型权重：

git clone https://gitcode.com/gh_mirrors/vo/voxtral.c cd voxtral.c ./download_model.sh # 下载到 ./voxtral-model/

然后按硬件选择后端编译（参考 Makefile）：

make mps # Apple Silicon Metal GPU（最快，macOS 专用） make blas # Intel Mac / Linux + OpenBLAS

Linux 上使用前先安装 OpenBLAS（如sudo apt install libopenblas-dev）。模型目录 voxtral-model/ 中会包含consolidated.safetensors、tekken.json分词器词表和params.json配置。

第二步：看懂核心 C API

整个 API 定义在 voxtral.h，实现位于 voxtral.c。构建应用只需认识下面这张接口表：

音频格式要求很简单：单声道 float32、16kHz、[-1, 1]。如果你手头是 WAV 文件，直接用 voxtral_audio.h 里的vox_load_wav()即可自动完成重采样与声道混合；内存中的 WAV 字节流则可用vox_parse_wav_buffer()解析。

第三步：离线文件转写（5 步完成）

最简单的场景：读入 WAV、喂入音频、收集文本。

#include "voxtral.h" #include "voxtral_audio.h" vox_ctx_t *ctx = vox_load("voxtral-model"); if (!ctx) return 1; int n_samples; float *samples = vox_load_wav("audio.wav", &n_samples); vox_stream_t *s = vox_stream_init(ctx); vox_stream_feed(s, samples, n_samples); /* 喂入全部音频 */ vox_stream_finish(s); /* 标记结束，冲刷尾部 */ const char *tokens[64]; int n; while ((n = vox_stream_get(s, tokens, 64)) > 0) for (int i = 0; i < n; i++) printf("%s", tokens[i]); printf("\n"); vox_stream_free(s); free(samples); vox_free(ctx);

💡 如果完全不需要流式控制，一行char *text = vox_transcribe(ctx, "audio.wav");就能拿到完整文本（记得free(text)）。

第四步：实时流式语音识别

实时场景（麦克风、网络流）的关键模式是：边喂音频、边取文本。

vox_stream_t *s = vox_stream_init(ctx); vox_stream_set_continuous(s, 1); /* 连续模式：EOS/KV 溢出时自动重启 */ while (have_more_audio()) { float chunk[4096]; int n_read = read_audio(chunk, 4096); /* 你的音频采集代码 */ vox_stream_feed(s, chunk, n_read); const char *tokens[16]; int n; while ((n = vox_stream_get(s, tokens, 16)) > 0) { for (int i = 0; i < n; i++) fputs(tokens[i], stdout); fflush(stdout); } } vox_stream_finish(s); while ((n = vox_stream_get(s, tokens, 16)) > 0) for (int i = 0; i < n; i++) fputs(tokens[i], stdout); vox_stream_free(s);

两个实时场景的要点：

• vox_stream_set_continuous(s, 1)：开启后解码器在序列结束（EOS）、KV 缓存溢出或长时间输出非文本 token 时会自动重启。有限文件不需要；无限长的直播/麦克风流必须开启，否则 KV 缓存会无限增长。
• vox_stream_flush(s)：检测到说话人停顿时调用，立即吐出缓冲的转录文本而不用结束流。这是做静音断句的推荐姿势。

第五步：调优延迟与置信度 ⚡

控制延迟/效率的权衡—— 用vox_set_processing_interval(s, seconds)设定编码器最小处理间隔（对应 CLI 的-I参数，默认 2.0 秒）：

vox_set_processing_interval(s, 1.0); /* 更响应，GPU 开销更高 */ vox_set_processing_interval(s, 3.0); /* 更省 GPU，出字更慢 */

实测建议：实时流式用1.0–2.0 秒；低于 0.5 秒会让大量 GPU 时间耗在每次调用的固定开销上。离线文件转写则无所谓。

获取候选 token（模型不确定时）：

vox_stream_set_alt(s, 3, 0.5); /* 最多 3 个候选，cutoff 0.5 */ const char *tokens[16 * 3]; while ((n = vox_stream_get_alt(s, tokens, 16, 3)) > 0) for (int i = 0; i < n; i++) { printf("%s", tokens[i * 3]); /* 最佳 token */ for (int a = 1; a < 3 && tokens[i * 3 + a]; a++) printf(" [alt: %s]", tokens[i * 3 + a]); }

调整转录延迟：vox_set_delay(ctx, delay_ms)（80–2400ms，默认 480ms）控制解码器相对音频的时间偏移，数值越小出字越即时。

常见问题与注意事项 ⚠️

1. 指针有效期：vox_stream_get()返回的字符串指针有效直到vox_stream_free()，需要保存请在之前复制。
2. 首段音频约需 3 秒：解码器 prompt 需要 312 帧 mel（约 3 秒音频）才开始出字，属正常现象。
3. 内存占用：权重 8.9GB（mmap 按需读取）；MPS 后端 GPU 权重缓存约 8.4GB；解码器 KV 缓存上限约 1.8GB。
4. 音频必须 16kHz 单声道：其他采样率请先用 ffmpeg 转换（-ar 16000 -ac 1），或用vox_load_wav自动重采样。
5. 一个 ctx 对应一个流：vox_stream_init会重置编码器 KV 缓存，多线程/多路音频请为每路创建独立上下文并做同步。

关键文件速查

• voxtral.h：全部公开 API 与模型常量定义
• voxtral.c：流式管线、上下文管理核心实现
• voxtral_audio.h：WAV 加载与 mel 频谱（含增量 mel，供流式使用）
• voxtral_encoder.c / voxtral_decoder.c：编码器（32 层）与 LLM 解码器（26 层）
• voxtral_mic_macos.c：macOS 麦克风采集示例
• main.c：CLI 入口，内含麦克风实时转写与 stdin 管道的完整参考用法
• MODEL.md：模型架构与权重格式详解

掌握以上 5 步，你就可以把 Voxtral Realtime 4B 语音识别能力像普通 C 库一样嵌入自己的应用了 🚀