remsky/Kokoro-FastAPI 本機開源語音合成教學:Docker 一鍵架設相容 OpenAI 格式的高速 TTS

remsky/Kokoro-FastAPI 將輕量高效的 Kokoro 語音模型封裝為相容 OpenAI TTS 介面的 Docker 服務,支援 CPU、GPU 與串流播放,一篇教你本機部署與串接。

Share
Kokoro-FastAPI官方 GitHub 專案封面圖:Kokoro-FastAPI 教學
Kokoro-FastAPI官方開源專案視覺圖。 圖片來源:官方原文。

開發語音助理、有聲書工具或即時客服機器人時,文字轉語音 API 的帳單往往比大型語言模型推論還驚人。

一旦進入長篇文本朗讀或高頻率對話場景,商業語音服務的字元計費與網路延遲,很快就會成為專案上線的瓶頸。

remsky/Kokoro-FastAPI 是目前 GitHub 與 Docker Hub 上最熱門的本機語音合成封裝方案,每月映像檔拉取量突破 25 萬次。

它把僅有 8,200 萬參數的輕量級 Kokoro-82M 模型打包進 FastAPI 服務,並完整模擬 OpenAI、ElevenLabs 與 Cartesia 的 API 介面。

如果你需要隱私可控、零 API 授權費且低延遲的語音伺服器,這套專案非常適合你。但若你需要超高擬真度的商業級跨語種聲音複製,它目前僅支援微調而非完整複製,仍無法完全取代大型商業模型。

這篇 Kokoro-FastAPI 教學會帶你一次掌握架構特性、各硬體平台的 Docker 部署指令、OpenAI SDK 串接寫法、多角色混音與 SSML 進階語法。

Kokoro-FastAPI 是什麼?核心架構與多平台硬體支援

Kokoro-FastAPI 本質上是一個基於 FastAPI 打造的容器化推理伺服器,底層整合了 Kokoro-82M 語音合成模型與 Misaki 音素前端處理引擎。由於模型體積輕巧,它不需要高階資料中心顯示卡就能跑出極低的首字延遲。

根據官方實測數據,在啟用串流模式下,NVIDIA GPU 環境的首個音訊分塊延遲約 300 毫秒。即便是純 CPU 環境,在 Apple M3 Pro 筆電上也能壓在 1 秒以內,而在舊款 Intel i7 處理器上則約為 3.5 秒。

這套服務的強大之處在於「介面相容性」。它不只提供標準的 /v1/audio/speech 端點,還內建了 OpenAI Realtime 語音端點,以及相容 LiveKit 和 Pipecat 語音代理框架的 ElevenLabs 與 Cartesia WebSocket 路由。

這意味著你原本接商業語音服務的程式碼,幾乎只要改一行 base_url 就能無痛切換到本機端。

以下快速拆解幾個文件中常見的核心名詞:

  • TTS 文字轉語音:將輸入的純文字自動轉換為自然人聲波形與音訊檔案的技術。
  • Phoneme 音素:語言中能區分詞義的最小語音單位,透過精準控制音素可以修正專有名詞或破音字的唸法。
  • SSML 語音合成標記語言:一種基於 XML 格式的標籤語法,用來在文本中明確指定停頓秒數、語速變化或切換說話角色。
  • MPS 硬體加速:Apple Silicon 晶片內建的 Metal Performance Shaders 繪圖與運算架構,可讓 Mac 在沒有獨立顯卡的情況下加速模型推論。
Kokoro-FastAPI官方 GitHub 專案封面圖:Kokoro-FastAPI 教學
Kokoro-FastAPI官方開源專案視覺圖。 圖片來源:官方原文。

步驟教學:Docker 一鍵啟動與 Apple Silicon 本機運行

官方已經預先編譯好包含模型權重的多平台 Docker 映像檔,支援 linux/amd64 與 linux/arm64 架構,因此不需要手動下載龐大的模型檔就能直接啟動。

請依照你手邊的硬體設備,選擇對應的終端機啟動指令:

# 1. 純 CPU 環境:適合筆電或無獨立顯卡伺服器
docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest

# 2. NVIDIA 顯示卡:適用 GTX 900 系列至 RTX 40 系列,內建 CUDA 12.6
docker run --gpus all -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu:latest

# 3. NVIDIA RTX 50 系列 Blackwell 架構:內建 CUDA 12.8
docker run --gpus all -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu:latest-cu128

# 4. AMD 顯示卡:實驗性支援 ROCm,僅限 x86_64 架構
docker run --device=/dev/kfd --device=/dev/dri -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-rocm:latest

在正式環境部署時,官方建議將映像檔標籤固定在特定釋出版本,避免使用 :latest 造成意外升級。如果你想透過 Docker Compose 管理完整服務與網頁介面,可以先複製儲存庫並切換到對應資料夾建置:

git clone https://github.com/remsky/Kokoro-FastAPI.git
cd Kokoro-FastAPI
cd docker/gpu
docker compose up --build

要特別留意的是 Apple Silicon 用戶。由於 Docker 的 GPU 映像檔僅支援 NVIDIA CUDA,在 M1、M2 或 M3 晶片上若使用 Docker 只能跑 CPU 映像檔。

如果想發揮 Mac 原生的 MPS 顯示卡加速效能,官方建議直接複製專案並透過 uv 套件管理器啟動原生腳本:

./start-gpu_mac.sh

若你在 Linux 或一般 macOS 環境想從原始碼以 uv 啟動並開啟熱重載開發模式,也可以先執行模型下載腳本,再啟動對應的啟動檔:

python docker/scripts/download_model.py --output api/src/models/v1_0
./start-cpu.sh

服務順利跑起來後,瀏覽器打開 http://localhost:8880/web 就能進入內建的 Web 測試介面,打開 http://localhost:8880/docs 則可檢視完整的互動式 API 規格文件。

延伸閱讀:OpenAI 宣布 12 月 11 日退場 ChatGPT 舊版語音模式!全面轉向全雙工 GPT-Live 的技術差異與用戶影響

支援語言、輸出格式與串接模式比較表

在正式整合進應用系統前,先看清楚目前支援的輸出規格與語言能力。系統目前涵蓋美式英語、英式英語、西班牙語、法語、印地語、義大利語、日語、巴西葡萄牙語與現代標準漢語。

輸出格式則支援 mp3、wav、opus、flac、aac 與原始 pcm 串流。針對不同開發場景,三種主要的串接路由各有適用範圍:

串接介面 適用協定與端點 音訊規格與格式 典型應用場景
OpenAI Speech 相容介面 HTTP POST /v1/audio/speech 支援 mp3、wav、opus、flac、aac、pcm 批次生成有聲書、Podcast 配音或標準文字轉音檔
OpenAI Realtime 相容介面 WebSocket /v1/realtime 僅輸出 24000 Hz PCM 音訊 整合支援 OpenAI 即時語音協定的既有客戶端
ElevenLabs 與 Cartesia 介面 WebSocket multi-stream-input 與 /tts/websocket 8000 至 48000 Hz PCM,ElevenLabs 另支援 mp3 串接 LiveKit Agents 與 Pipecat 低延遲即時語音代理

如果你使用 OpenAI Python SDK 2.x 版本連線至本機 Realtime 端點,記得主動傳入 websocket_base_url="ws://localhost:8880/v1"。因為新版 SDK 預設會強制要求加密的 wss:// 協定,在本機未掛載憑證時會導致連線失敗。

實戰應用:OpenAI SDK 串流、雙聲線混音與多角色對話

Kokoro-FastAPI 最吸引開發者的地方,就是能直接沿用 openai 官方套件。下面這段程式碼示範如何把本機 8880 埠當成 OpenAI 伺服器呼叫,並直接將兩組內建聲線混音輸出成 MP3:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8880/v1",
    api_key="not-needed"
)

with client.audio.speech.with_streaming_response.create(
    model="kokoro",
    voice="af_sky+af_bella",
    input="Hello world! Welcome to local text to speech."
) as response:
    response.stream_to_file("output.mp3")

加權聲線混合與自訂別名

除了直接把兩個聲音相加,你還可以在括號中指定權重比例,系統會自動將比例正規化為 100%。例如 "af_bella(2)+af_sky(1)" 代表 67% 與 33% 的混音效果。

你甚至可以透過 /v1/audio/voices/combine 端點把混音結果下載成獨立的 .pt 語音包檔案,重複用於後續請求。若覺得長串的組合名稱不好寫在程式裡,還能搭配 voice_aliases 參數設定簡短別名:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8880/v1", api_key="not-needed")

client.audio.speech.create(
    model="kokoro",
    voice="narrator",
    input="[voice:narrator] Once upon a time. [voice:villain] Never!",
    extra_body={
        "allow_voice_tags": True,
        "voice_aliases": {
            "narrator": "af_bella(2)+af_sky",
            "villain": "am_michael"
        },
    },
)

內嵌控制標籤與結構化多角色對話

在送出的 input 字串中,可以直接夾帶四種伺服器端解析的控制標籤,讓單次請求就能產生豐富的語氣變化:

  • 插入靜音停頓:使用 [pause:1.5s] 格式插入精確秒數的停頓,注意必須保留冒號與小寫字母 s,寫成等號或空白會被系統直接唸出來。
  • 強制英文音素發音:使用 [Worcester](/wˈʊstər/) 語法指定國際音標,解決生僻地名或專有名詞唸錯的問題。
  • 行內切換說話者:在請求參數加上 allow_voice_tags: true 後,可用 [voice:am_michael] 隨時切換語者。
  • 動態調整語速倍率:使用 [rate:1.5] 調整當前語者的講話速度,倍率範圍限制在 0.25 到 4.0 之間,直到下一個語速標籤或切換語者為止。

如果你正在製作訪談節目或雙人對話腳本,不想自己手動拼接標籤,可以直接呼叫 POST /dev/dialogue 端點,用 JSON 陣列傳入每一輪發言與 pause_between_turns 停頓秒數即可。

此外,標準端點也支援傳入 ssml: true 搭配 allow_voice_tags: true,讓系統自動把 <break>、<voice> 與 <prosody> 等標準 SSML 標籤翻譯成內部控制語法。如果想先預覽 SSML 翻譯後的控制標籤結果,也能單獨呼叫 POST /dev/ssml 進行檢查。

長文本自動斷句、音素除錯與語音代理串接

基礎模型單次推論上限為 510 個音素標記,大約對應 30 秒的語音,若強行塞入過長段落會導致語速突然變快或音質劣化。

為了解決這個問題,伺服器端內建了自然邊界偵測層,會在句號或自然斷點處自動切分並無縫拼接。系統透過 TARGET_MIN_TOKENS、TARGET_MAX_TOKENS 與 ABSOLUTE_MAX_TOKENS 三個環境變數控制切分長度,預設值分別為 175、250 與 450。

遇到專有名詞唸不準時,開發者也能利用 /dev/phonemize 端點先將文字轉換成國際音標,確認無誤或手動微調後,再透過 /dev/generate_from_phonemes 直接從音素生成高精準度的音檔。

若想整合進即時語音代理,例如在 LiveKit Agents 中直接取代商業 API,只需在初始化外掛時指向本機端點即可:

from livekit.plugins import cartesia, elevenlabs

tts_el = elevenlabs.TTS(base_url="http://localhost:8880/v1", api_key="x", voice_id="af_heart")
tts_ct = cartesia.TTS(base_url="http://localhost:8880", api_key="x", voice="am_michael")

憑藉著高度相容的介面,這套專案在開源社群已經累積了豐富的生態系支援。無論是智慧家庭平台 Home Assistant、開源對話介面 OpenWebUI、角色扮演前端 SillyTavern,或是電子書轉有聲書工具 epub_to_audiobook 與 Zotero-OpenReader,都能直接將它設為底層語音引擎。

部署完成後,如果你想快速驗證所有內建語音包是否運作正常,可以直接在專案根目錄執行官方附帶的檢查腳本 examples/assorted_checks/test_openai/test_openai_tts.py 測試 OpenAI 相容性,或執行 test_all_voices.py 一次掃描所有可用聲線。

如果專案需要直接從本機喇叭即時播放語音串流,只需將請求的 response_format 設為 pcm,再搭配 PyAudio 以 24000 Hz 單聲道格式讀取位元組串流,就能在模型邊合成的同時邊播放,大幅縮短互動式語音助理的體感等待時間。

另外,在 Kubernetes 叢集環境下,官方文件庫的 docs/deployment/kubernetes.md 也提供了完整的 Helm Chart 部署指南,方便維運團隊將語音服務水平擴展至多台 GPU 節點。

延伸閱讀:Apple 宣布 macOS 27.3 拆分裝置控制與資料存取權限:AI 代理時代的 Mac 資安新防線

安全邊界、機能限制與常見地雷

將本機語音服務部署到團隊內網或生產環境時,有幾個技術細節與法規邊界必須提前掌握:

  • API 金鑰與高風險端點預設狀態:在預設啟動下,API 金鑰驗證是關閉的,若要對外開放存取務必設定 API_KEYS 環境變數。另外,參考音檔微調端點 POST /dev/tune 預設關閉,需設定 ENABLE_INNO_TUNER=true 才會開啟,若需將微調後的聲音檔持久化儲存,則須額外開啟 ALLOW_LOCAL_VOICE_SAVING=true。
  • 關閉不必要的 WebSocket 或標籤功能:若系統只需要單純的單聲線 HTTP 合成,可以設定 ENABLE_WEBSOCKET_TTS=false 關閉即時語音路由,或設定 ENABLE_VOICE_TAGS=false 停用行內切換語者功能,減少額外的攻擊面與資源消耗。
  • 聲音微調與聲音複製的落差:官方明確提醒,透過 Inno Clone-Tuner 提供的微調功能僅接收 3 至 30 秒的英語參考音檔,效果是「往該音色靠近的調校」,並非一比一的零樣本聲音複製。使用時也務必確認已取得該聲音擁有者的合法授權。

若你的團隊確實有客製化聲線需求,在開啟環境變數後呼叫 POST /dev/tune 端點時,除了直接合成音檔,也能透過 return_voice_pack 參數下載微調後的 .pt 權重包,或透過 save_voice 儲存在伺服器 VOICES_DIR 目錄以供後續重複呼叫,並可依需要微調 prosody_head 韻律開關與 fmax 音高上限,讓輸出音色更貼近特定角色設定或旁白需求。

  • 串流分塊過小的音質瑕疵:雖然調低串流分塊大小能縮短首字延遲,但官方文件特別註記,分塊過小容易增加語調斷裂或電子雜音的機率,實務上建議在延遲與聽感之間做壓測取捨。
  • SSML 安全防護上限:為防範 XML 外部實體攻擊與過深巢狀結構耗盡記憶體,系統強制拒絕任何包含 DTD 宣告的 SSML 文本,且巢狀深度超過預設上限 10 層時會直接回傳 400 錯誤。

常見問題

Kokoro-FastAPI 支援繁體中文或現代標準漢語嗎?

支援現代標準漢語。不過實務上英文語音的表現最成熟,音素級別的強制發音標記與參考音檔微調功能目前也明確標註僅支援英語語料。若要處理大量專業中文詞彙或特定口音,建議先用 WebUI 實測特定語音包的表現再決定是否導入。

在 Mac M 系列晶片上跑 Docker 為何感覺沒有用到 GPU?

因為官方釋出的 Docker GPU 映像檔底層綁定 NVIDIA CUDA,無法在 Apple Silicon 上進行硬體加速。在 Mac 上若使用 Docker 應選擇 kokoro-fastapi-cpu:latest,或者直接複製專案並執行 ./start-gpu_mac.sh,透過 uv 在本機原生啟用 MPS 加速。

為什麼請求裡寫了 [voice:am_michael] 卻被直接唸出字面文字?

這是安全機制預設行為。在呼叫 /v1/audio/speech 時,必須在請求主體中明確傳入 allow_voice_tags: true,且伺服器端的環境變數 ENABLE_VOICE_TAGS 不能被設為 false。若傳入 SSML 標籤時也必須同時開啟 ssml: true 與 allow_voice_tags: true,否則伺服器會回傳 400 錯誤或將標籤直接唸出。

要如何搭配系統環境產生未知詞彙的發音回退?

如果你選擇不透過 Docker,而是直接用 uv 在本機執行原始碼,官方建議事先在作業系統安裝 espeak-ng。這樣當模型遇到罕見單字或特殊符號時,才能有可靠的系統層級音素轉換作為後備支援。

結語

remsky/Kokoro-FastAPI 是目前將輕量級開源語音模型轉化為生產級微服務的最佳範例之一,兼顧了極低硬體門檻與完整的業界標準相容性。

它非常適合需要完全掌握語音資料隱私、想砍掉商業 TTS 高額帳單的個人開發者,以及正在串接 LiveKit、Pipecat、OpenWebUI 或 Home Assistant 的即時語音代理團隊。

相對地,如果你需要高度情感起伏的商用配音、或是跨語種一比一的名人聲線複製,它目前仍無法完全取代大型雲端商業方案。

想掌握更多這類能直接幫團隊省下大筆 API 費用的開源 AI 基礎設施教學,歡迎訂閱免費 AI 郵報,每週接收精選實戰工具拆解與部署指南。

資料來源