按下生成之後,VoiceStudio 怎麼讓一堆 TTS 引擎輪流進記憶體
一個本機語音 app,設定頁裡能選的語音生成引擎有一長串,你按下「生成」的那一刻,它到底把哪個模型叫進記憶體?其他的又在哪裡?
這個問題對 VoiceStudio 特別有意思。它是 debpalash/VoiceStudio 這個 repo,2026 年 4 月 9 日建立,到 10 月 3 日我用 GitHub API 查的時候是 52,348 顆星、5,840 個 fork,最新 release 是 9 月 23 日的 v0.5.6。依它的 docs/feature-catalog.md(這個數字是轉述,我沒有自己打開那份檔案數),語音生成的條目有 17 個,轉錄引擎 10 個。這麼多模型,總不能全部同時載進記憶體。
所以它一定有一套「誰進來、誰出去」的規則。我讀了它後端的五個檔案和授權說明,沒有安裝,也沒有實際生成過任何一段音訊。下面的東西主要來自原始碼與授權文件,轉述二手整理的地方會另外註明。從最底層的介面往上拆。
每個引擎都只被允許做一件事
backend/services/tts_backend.py 開頭的說明寫得很乾脆:「A uniform protocol for every TTS engine」。它定義了抽象類 TTSBackend,介面刻意做得很窄,生成語音走的就是 generate(...)。
它收的參數不少,text、ref_audio、ref_text、instruct、language、description,還有 num_step=16、guidance_scale=2.0、speed=1.0 這幾個預設值。回傳卻只有一樣東西:一個 shape 為 (1, n_samples) 的單聲道 tensor。取樣率不在回傳值裡,是引擎自己的 sample_rate 屬性,因為每個引擎不一樣,註解舉的例子是 OmniVoice 24k、VoxCPM2 48k。
介面窄到什麼程度?串流直接不做。原話是「Streaming is left for a later pass — the dub generator consumes whole segments today」。不支援聲音設計的引擎拿到 description 參數,文件寫的是 ignore,也就是當沒看到。
照這個設計,「換引擎」對呼叫端來說,主要就是換掉 generate 背後的那個物件。後面每一層都踩在這件事上。
誰決定用哪一個,以及為什麼 import 不會把全部拖進來
用哪個引擎,由 active_backend_id() 決定。它只有一行邏輯,順序寫在註解裡:環境變數 > UI 裡存下來的選擇 > 預設值 "omnivoice"。環境變數排第一的理由也寫得很白,讓進階使用者可以釘死一個引擎,不會被設定頁的選單悄悄改回去。
真正有意思的是註冊表。下面是我從原始碼節錄、只留結構的版本:
1 | # 節錄自 backend/services/tts_backend.py(2026-10-03 main),只保留結構 |
註冊表裡每一筆只存兩個字串:模組路徑跟類別名稱。要等 get_backend_class(backend_id) 第一次被呼叫,才真的去 import 那個模組。
註解給了兩個理由。第一個是避開 services.subprocess_backend 跟 services.tts_backend 互相 import 的迴圈。第二個比較實際:import 的時候不要順手把 huggingface_hub 這類依賴整串拉進來。
換引擎的那一刻
拿到類別之後,get_active_tts_backend() 會快取一個實例,對應「目前設定的那個 id」。id 一變,它會先對舊實例呼叫 unload(),再建新的。卸載失敗不會擋住切換,只記一筆 warning。
到這裡都很直覺。麻煩在下一個問題:如果舊引擎還有工作在跑呢?
它的處理方式是記帳。_ENGINE_IN_USE 記每個引擎目前有幾件工作在用它,數字大於 0 的舊引擎不會立刻卸載,而是被放進 _RETIRED_ENGINES,等最後一件工作結束才 unload()。
另外還有一條閒置規則:引擎沒被用超過 600 秒就卸載,可以用 OMNIVOICE_ENGINE_IDLE_UNLOAD_SECONDS 改,下限 5 秒,亂填的值會被忽略並記 warning。計時用的是 monotonic 時鐘。註解解釋為什麼不用牆上時間:NTP 校時或筆電從休眠醒來,牆上時間會跳,一跳就被誤判成閒置了十分鐘。
40 分鐘的配音,看起來跟一個被遺忘的模型一模一樣
這是整份原始碼裡我最喜歡的一段註解。
閒置卸載要判斷「這個引擎多久沒被用」。最天真的做法是看「上次有人碰它是什麼時候」。問題是影片配音這種長工作,只在開頭碰一次快取,接著就埋頭生成。註解的原話是「a 40-minute dub looks exactly like an abandoned model」。光看時間,跑到第 11 分鐘的配音跟一個十分鐘沒人理的模型,長得完全一樣,閒置掃描會把正在工作的模型卸掉。
VoiceStudio 的解法是租約。跟圖書館借書一樣:書還在讀者手上,館員就不能把它下架,借期從「還書那天」才重新算。
程式上,包住一段工作的 engine_in_use(instance) 進去時 _ENGINE_IN_USE[cls] += 1,出來時減 1,並且用離開的時刻去更新 _ENGINE_LAST_USED。再透過 _lease_render 裝飾器把它包在方法外面。
包在哪一層,是我覺得這段設計最聰明的地方。呼叫端完全不用記得借書還書,TTSBackend.__init_subclass__ 會對每一個子類別自動把 generate、generate_batch、_ensure_loaded 包上租約。註解寫:「Enforce lifetime at the engine boundary so every caller is covered.」只要新引擎是 TTSBackend 的子類別,寫它的人就算完全不知道有租約這回事,也會被包到。
如果要我自己用最少的程式碼重寫這個想法,大概長這樣。下面是我寫的示意,不是 VoiceStudio 的原始碼:
1 | # 我寫的示意:租約計數 + 用「歸還時間」計算閒置 |
十幾行就寫完了。難的是一開始就想到「最後一次被碰」跟「最後一次被用完」是兩件事。
兩份快取互相不知道對方存在
原始碼裡有一份註解,說記憶體問題到這裡還沒解完。
backend/services/engine_memory.py 開頭寫著一個在 16 GB M2 上看到的情況(這是作者在註解裡寫的數字,不是我量的):OmniVoice 的核心模型常駐約 2.8 GB,接著再用 mlx-audio,記憶體從 3.9 GB 疊到 4.3 GB。原因是兩邊放在不同的快取裡,一個是 model_manager.model,一個是 engines._ENGINE_INSTANCES,彼此沒有協調。
所以有了第二層規則:同一時間只讓一個 TTS 引擎的模型留在記憶體。生成路徑決定好要用哪個引擎時,先呼叫 evict_other_tts_engines,把其他常駐的全部卸掉。OpenAI 相容路由的 openai_compat.py 在生成前就有這一行 await evict_other_tts_engines(backend.id)。這個行為預設開啟,OMNIVOICE_SINGLE_ENGINE_RESIDENT=0 可以關掉。代價是換引擎要重新載入,註解估 VoiceStudio 核心約 8 秒、較輕的引擎 1 到 2 秒,同樣是作者的數字。
這裡要說清楚我讀不出來的部分。「換 id 時卸載舊實例」跟「生成前趕走其他引擎」都在做換引擎時清記憶體的事,一個在 tts_backend.py,一個在 engine_memory.py。註解說它們處理的是不同快取,但兩層之間怎麼分工、會不會對同一個模型卸載兩次,我沒有查證。600 秒的閒置卸載跟單引擎常駐是兩種觸發條件,誰先誰後也一樣沒查證。
同一份 openai_compat.py 還留著另一個踩過的坑。新安裝的人第一次打 /v1/audio/speech,模型還沒下載,結果整個 300 秒的生成預算全花在下載好幾 GB 的 checkpoint 上,最後報出一個很誤導的訊息,說運算資源不夠跑這個模型(「too heavy for the available compute」)。後來把載入逾時獨立出來,OMNIVOICE_MODEL_LOAD_TIMEOUT 預設 1,200 秒,跟生成預算分開算。對應的 issue 是 #1033、#1037、#1014。
預設引擎 OmniVoiceBackend 本身也有兩段修過的痕跡。一個是 preprocess_prompt 參數,以前 API 收了卻沒往下傳,被 adapter 默默吃掉,後來才補上。另一個是 unload():舊版先釋放裝置快取、後丟掉模型參考,註解形容那個順序「frees nothing」(#1495)。現在的 unload() 除了丟參考,還要呼叫 model_manager.unload_shared_model() 清掉共用的單例,也會呼叫 clear_clone_prompt_cache() 清掉快取的 clone prompt 釋放 VRAM(#427)。卸載這件事,光是順序寫錯就等於沒做。
依賴打架的引擎,乾脆換一個 Python
有些引擎連 import 都進不了同一個程序。subprocess_backend.py 舉的例子是 IndexTTS 要 transformers<5,VoiceStudio 自己要 transformers>=5.3。MOSS-TTS v1.5 釘在 5.0.0、dots.tts 釘在 4.57.0,同樣跟主程序衝突(Issue #498)。
解法是讓這些引擎跑在自己的 venv,用 subprocess.Popen 開一個子直譯器,父子之間用「length-prefixed JSON over the child’s stdin/stdout」溝通,單一訊框上限 64 MB。文件特別寫明不用 multiprocessing,因為 multiprocessing 給你的是同一個直譯器,它要的偏偏是不同的。
子類別只要覆寫 venv_python() 跟 sidecar_script() 兩個方法。啟動、握手、請求回應、GPU slot 計帳、程式結束時清理、排掉 stderr、清掉整個 process group,都由基底類別負責。這幾個引擎在註冊表裡跟其他引擎一樣用 backend id 登記;子程序基底類別跟 TTSBackend 怎麼接起來,那段我沒讀到。
拆完了,反過來看它能拿來幹嘛
窄介面、延遲註冊、租約、單引擎常駐、子程序隔離,五層疊起來,結果是「後面接的是哪個模型」變成一個設定值。這時候再看它對外開的兩扇門,就知道為什麼開得出來。
一扇是 MCP。backend/mcp_server.py 用 FastMCP("VoiceStudio", …) 開了 9 個工具,包括 generate_speech、clone_voice、design_voice、transcribe、list_voices。整個 app 掛在 /mcp,所以它把 streamable HTTP 的路徑改成根目錄,不然會變成 /mcp/mcp。哪個 agent 用哪個聲音,是從請求標頭 x-omnivoice-client-id 讀的;stdio 客戶端讀不到這個標頭,就用後端預設的聲音。
檔案路徑另外有一道沙箱:OMNIVOICE_MCP_BASE_PATH 沒設,所有檔案路徑一律拒絕;設了就把路徑 realpath 之後檢查有沒有跑出那個目錄。讓 agent 直接丟檔案路徑給一個本機服務,這個預設拒絕是對的。
另一扇是 OpenAI 相容路由,openai_compat.py 裡有 POST /audio/speech、/audio/transcriptions、/audio/translations,以及 GET /models、/audio/voices。前綴 /v1 跟它能直接接 openai SDK、pipecat、LiveKit 這類框架的說法,我只看到二手整理,相容到什麼程度沒有驗證。
如果你要替自己的 agent 接一個本機 TTS,這個 repo 最值得抄的不是那張引擎清單,是租約加上「包在引擎邊界」的做法。清單會過時,引擎會換代,誰在用、用完了沒的帳,換了什麼模型都還用得上。反過來說,如果你從頭到尾只跑一個引擎、也不做長時間配音,上面這套對你幾乎沒意義,直接載一個模型常駐就好。
名字也是同一個問題
讀這份原始碼最容易卡住的,是「OmniVoice」這個字同時指好幾樣東西。它是 k2-fsa 團隊(Han Zhu)的 TTS 模型,也是這個 app 的預設引擎;它也是 app 的舊名,依二手整理,app 到 v0.4.2 為止都叫 OmniVoice Studio。所以環境變數全是 OMNIVOICE_*,logger 叫 omnivoice.engine_memory。backend id 裡又有 "omnivoice"、"omnivoice-gguf",加上一個放在可隔離崩潰的子程序裡的版本。這三個 id 之間是什麼關係,我沒有查證。
下面的版本節點,repo 建立日跟 v0.5.6 我用 GitHub API 對過,其他是從二手整理轉述的:
VoiceStudio 的幾個節點
2026-04-09 repo 建立
debpalash/VoiceStudio 的 created_at。
2026-04-23 v0.2.0
早期版本,當時還叫 OmniVoice Studio。
2026-07-21 v0.4.0
配音會先把 TTS 模型搬到 CPU、把 VRAM 讓給轉錄模型,取消或中斷後曾經沒搬回來(#1191)。CHANGELOG 把修正記在這版;效能文件寫的卻是 v0.3.23,而 GitHub 上沒有這個 release。
2026-08-14 v0.5.0
改名 VoiceStudio,程式內部大量沿用舊名。
2026-09-17 v0.5.3
桌面外殼從 Tauri 換成 Electron。
2026-09-23 v0.5.6
截至 10 月 3 日的最新 release。
名字混用,還一路連到授權。
LICENSE-NOTICE.md 寫得很清楚,app 本身是 AGPL-3.0-only,明文涵蓋商業與企業內部使用;你改了它、再透過網路給別人用,就得提供修改版的完整原始碼。想把 VoiceStudio 嵌進閉源產品的組織,可以另外買商業授權,細節請看官方的 plans 頁。
但同一份文件也寫了:模型權重不由 VoiceStudio 重新授權,「A commercial license for VoiceStudio-owned code does not replace any of those terms」。預設的 k2-fsa/OmniVoice,依這份文件轉述的模型卡,程式碼是 Apache-2.0、權重是 CC-BY-NC,audio_tokenizer 另外帶著 Boson Higgs Audio 2 跟 Meta Llama community 的條款。我沒有自己打開那張模型卡核對。
所以「OmniVoice」這個字,在授權上可能指 Apache-2.0 的 Python 套件,也可能指 CC-BY-NC 的權重。你買了 app 的商業授權,預設那顆模型的非商用限制還是在。其他引擎各自是什麼授權,我手上只有二手整理的表,沒有逐一回模型卡驗,這裡就不列了。
這時候前面拆的那套機制又派上用場。既然引擎是一個設定值,「換成一個權重可商用的模型」就從改程式變成改設定。
同樣的帳,在別的地方也要算
把 TTS 拿掉,這套東西剩下的骨架是:一個資源很貴、一次只能放一兩個;有人借、有人還;閒置太久要收回。
資料庫連線池、GPU 上的推論服務、縮到零的容器,都長這個樣子。它們都會遇到同一個陷阱:用「最後一次被碰」去判斷閒置,長工作就會被當成廢棄物。VoiceStudio 給的答案很便宜,借出去的時候記一筆、還回來的時候記時間,而且把記帳放在每個人都繞不過的那道門上。
那句「a 40-minute dub looks exactly like an abandoned model」,把 dub 換成一次批次匯出、一條跑很久的查詢,一樣成立。
參考來源
- VoiceStudio repo:https://github.com/debpalash/VoiceStudio(星數、fork、授權、release 為 2026-10-03 以 GitHub API 查詢的結果)
- 授權說明
LICENSE-NOTICE.md:https://github.com/debpalash/VoiceStudio/blob/main/LICENSE-NOTICE.md - 本文引用的原始碼:
backend/services/tts_backend.py、backend/services/engine_memory.py、backend/services/subprocess_backend.py、backend/mcp_server.py、backend/api/routers/openai_compat.py(皆為 2026-10-03 main 分支快照,之後可能變動) - 商業授權方案頁:https://voicestudio.sh/pro










