我們會仔細閱讀每一則回饋，並非常重視您的意見。
這是 Mistral AI 的 Voxtral Realtime 4B 模型推論流程的 C 語言實作。除了 C 標準函式庫外，完全不依賴其他外部套件。MPS 推論速度相當不錯，而 BLAS 加速雖可用但較慢（因為持續將 bf16 權重轉換為 fp32）。
音訊處理採用分塊編碼器並使用重疊視窗，能限制記憶體使用量，不論輸入長度為何。音訊可透過標準輸入（--stdin）傳入，或從麥克風即時擷取（--from-mic，僅限 macOS），方便搭配 ffmpeg 即時轉碼與轉錄任何格式。提供串流 C API（vox_stream_t），可逐步餵入音訊並即時取得產生的文字標記。
本專案尚需更多測試：目前主要針對少數樣本進行測試，可能還需改進才能達到生產等級。不過最困難的部分——理解模型推論並重現推論流程——已完成，後續工作應較容易。測試長時間轉錄以壓力測試 KV 快取環狀緩衝區將是有益的任務。
感謝 Mistral 以開放權重方式釋出如此優秀的模型。然而，本專案作者認為若推論僅限於與 vLLM 合作，且未提供獨立的 Python 參考實作，將限制模型的實際普及與潛在效益。因此本專案誕生，提供純 C 推論引擎及簡單獨立的 Python 參考實作（python_simple_implementation.py），讓任何人都能輕鬆閱讀與理解，而無需深入 vLLM 程式碼庫。
推論時不需 Python 執行環境、CUDA 工具包、mistral_common 或 vLLM。
同時提供獨立 Python 實作，方便閱讀與理解模型：
此實作僅需 PyTorch 及少數標準函式庫。
文字標記會隨生成即時輸出至標準輸出。預設會將時間資訊輸出至標準錯誤，可用 --silent 或 --debug 控制詳細程度。
當模型對相似發音詞不確定時，使用 --alt <cutoff> 可內嵌顯示競爭候選詞：
cutoff（0.0–1.0）控制替代詞與最佳標記的接近程度。若 1 - prob[i]/prob[0] <= cutoff，該標記即符合條件。數值越低只顯示非常接近的替代詞，數值越高則較寬鬆。
-I <秒數> 參數控制編碼器處理累積音訊的頻率，這是延遲與效率的關鍵權衡：
預設為 2.0 秒。較低值讓串流更即時（語音後文字更快出現），但增加 GPU 開銷，因每次編碼器呼叫有固定啟動成本（約 50 毫秒）。較高值則將更多音訊批次處理，減少編碼器呼叫次數，提高 GPU 利用率。
開銷相當顯著：60 秒音訊片段中，批次模式編碼器約耗時 2.9 秒，而 -I 0.1 則約 15.8 秒（慢 5.4 倍），因為有數百次小批次編碼器呼叫，每次都付出固定成本。對即時串流而言，1.0 到 2.0 秒間的設定效果良好。低於 0.5 秒會浪費大部分 GPU 時間在呼叫開銷上。離線檔案轉錄則無此限制，因所有音訊一次取得。
--monitor 參數會在標準錯誤輸出非侵入式 Unicode 符號，與轉錄文字同時顯示，呈現引擎即時狀態。對診斷延遲問題或確認流程順暢非常有用。
健康的串流狀態會顯示 ▶·▪▪▶▪▪▶▪▪ —— 編碼器分塊與快速解碼批次交錯。若頻繁出現 ▸、▹、⚠ 或 ☠，表示解碼壓力過大。長時間連續串流中重啟符號正常，通常會看到成對符號如 ↺✂、⟳♻、↯♻ 或 ⌚♻。
--stdin 參數從標準輸入讀取音訊，格式自動偵測：若資料以 RIFF 標頭開頭則解析為 WAV，否則視為原始有號 16 位元小端格式，16 kHz，單聲道（s16le）。
這使得搭配 ffmpeg 即時轉碼任何音訊/影片格式變得簡單：
--from-mic 參數從預設麥克風擷取音訊（僅限 macOS，使用 AudioQueue Services）。按 Ctrl+C 停止。系統會自動偵測並剔除靜音，減少編碼器與解碼器負擔，僅處理實際語音。
若模型無法跟上即時速度，會顯示警告並跳過部分音訊以追趕進度。
--from-mic、--stdin 與 -i 參數互斥。
若要將檔案轉成 WAV 格式，只需使用 ffmpeg：
上述指令適用於多種檔案格式，不僅限於 OGG。samples 目錄下有兩個範例 WAV 檔案。
此函式庫提供串流 API（vox_stream_t），適用於離線與即時使用。您可餵入音訊樣本，並在可用時取得解碼文字標記。
離線轉錄——餵入全部音訊後收集結果：
即時串流——逐步餵入音訊，隨時取得文字標記：
feed() 會對可用資料執行梅爾頻譜、編碼器與解碼器，並排隊輸出標記。finish() 會加入填充並處理剩餘音訊。get() 取得待處理標記——可在每次 feed() 後或任何方便時呼叫。vox_stream_get() 回傳的標記字串指標在 vox_stream_free() 前有效。
vox_stream_flush(s) 強制編碼器處理緩衝中音訊，不論處理間隔，並加入右側填充使解碼器輸出延遲視窗內的標記。與 finish() 不同，串流保持開啟，後續仍可繼續餵入音訊。此功能對靜音偵測有用：當講者暫停時，flush 可取得待處理轉錄結果而不結束串流。
使用 vox_set_processing_interval(s, 秒數) 控制延遲與效率權衡（等同 CLI 的 -I 參數）。設定後，feed() 會累積音訊，僅在餵入指定秒數的新音訊後執行編碼器與解碼器。較低值提供更即時串流（文字更快出現），較高值則每次編碼器呼叫處理更多音訊，提高 GPU 利用率。預設為 2.0 秒。請參考上方 -I 參數說明選擇合適數值。
替代標記——當模型不確定時，可取得競爭候選詞：
vox_stream_get() 不受影響，始終只回傳最佳標記。
若不需串流，也提供一次性便利函式：
在 Linux 上使用 make blas 前，請先安裝 OpenBLAS。
可從 HuggingFace 下載模型權重（約 8.9GB）：
下載後存放於 ./voxtral-model/ 目錄，包含：
Apple M3 Max（40 核 GPU、128GB 記憶體、400 GB/s 頻寬）上的基準測試：
MPS 後端在每個標記使用單一 Metal 命令緩衝執行整個解碼器，並使用自訂 GPU 核心處理注意力機制、RoPE 與 KV 快取管理。所有權重在載入時預先轉換為 GPU 上的 f16。BLAS 後端使用 Accelerate 的多執行緒 sgemm，並即時將 BF16 轉為 F32。
解碼速度依序列長度而異：注意力機制每步掃描整個 KV 快取，轉錄越長每標記耗時越久。60 秒片段（約 760 步）平均約 31.6 毫秒/步。短片段（約 15 步）約 23.5 毫秒/步。無論如何，解碼器每約 80 毫秒音訊產生一標記，轉錄速度約為實時的 2.5 倍。
較長音訊的運算量線性隨編碼器（滑動視窗注意力為 O(n)）與解碼器（每 80 毫秒音訊產生一標記）增加。
Voxtral Realtime 4B 是一款約 40 億參數的串流語音轉文字模型：
純 C 語言實現 Mistral Voxtral Realtime 4B 語音轉文字模型推論。