系列第 3 篇（共 3 篇）｜難度：L2-進階
前置：基本 Python 與命令列操作、已讀過本系列第 1、2 篇

一句話說明

IndexTTS2 是一個「把文字唸成語音」的 AI 模型，還能只用一小段參考音檔就模仿指定說話者的音色。

IndexTTS2 是什麼

用最白話講：你給它一段文字，它輸出一個音檔（wav）。

跟你手機內建的「文字轉語音（TTS）」比，IndexTTS2 多了兩個關鍵能力：

• 定位：偏「配音生成 / 語音克隆」工具，不是聊天機器人。
• 支援語言：中英文為主（含中英混讀），實際支援語言以官方 repo 為準。
• 跟一般 TTS 的差異：一般 TTS 只有固定幾個罐頭嗓音；IndexTTS2 的嗓音是「你丟什麼參考音檔，它就學那個音色」。

你是 Vibe Coder：這篇的重點不是教你訓練模型，而是**看懂 AI 幫你寫的那段呼叫程式在做什麼、怎麼驗收輸出的音檔對不對**。

30 秒範例

先把環境跟模型準備好（實際指令以官方 README 為準，這裡是最常見的樣子）：

# 1. 抓專案
git clone https://github.com/index-tts/index-tts.git
cd index-tts

# 2. 安裝依賴（用 uv 建立獨立環境）
uv sync

# 3. 下載模型權重（通常從 HuggingFace，會放到 checkpoints/）
uv run huggingface-cli download IndexTeam/IndexTTS-2 --local-dir checkpoints
Code language: PHP (php)

然後最小的合成程式長這樣：

from indextts.infer_v2 import IndexTTS2

# 1. 載入模型（把權重讀進記憶體，這步最慢）
tts = IndexTTS2(cfg_path="checkpoints/config.yaml", model_dir="checkpoints")

# 2. 合成：給文字 + 參考語者音檔 → 輸出 wav
tts.infer(
    spk_audio_prompt="ref_voice.wav",   # 參考語者：你要模仿誰的聲音
    text="你好，這是我用 IndexTTS2 合成的第一段語音。",
    output_path="output.wav",           # 輸出檔案
)
Code language: PHP (php)

這段代碼做了什麼：

1. 把模型權重從硬碟載入記憶體（IndexTTS2(...)）。
2. 傳入「要唸的文字」和「要模仿的聲音」。
3. 產出一個 output.wav，用播放器打開就能聽。

⚠️ 上面的 import 路徑、參數名稱（spk_audio_prompt、infer）**會隨版本改**。AI 給你程式時，實際名稱要對照你這版的官方 README。看到對不上不要慌，這是正常的，往下的「紅旗」段會教你怎麼處理。

核心概念翻譯

看 AI 寫的 IndexTTS2 程式時，你會反覆看到這幾個東西：

取樣率（sampling rate）是最容易踩雷的一個，先記住：模型輸出的 wav 有一個「正確的取樣率」，播放器要用同一個數字播，否則聲音會變得又尖又快（或又低又慢）。多數 TTS 模型輸出是 22050 或 24000 Hz。

AI 最常這樣用

用法 1：長文本分句合成

模型一次唸太長容易斷句怪、記憶體爆。AI 常把長文切成句子逐段合成，再接起來：

sentences = text.split("。")            # 用句號切成一句一句
for i, s in enumerate(sentences):
    if not s.strip():                   # 跳過空字串
        continue
    tts.infer(
        spk_audio_prompt="ref_voice.wav",
        text=s + "。",                  # 把句號補回去，斷句才自然
        output_path=f"part_{i}.wav",
    )
Code language: PHP (php)

翻譯：把長文章切成一句一句，每句各自合成一個小 wav，最後再合併。切太碎（例如逐字）反而會讓語氣斷斷續續。

用法 2：先做文字正規化再合成

text = "今天氣溫 25 度，CPU 使用率 80%。"
# 🚩 直接丟進去，模型可能把「25」「80%」「CPU」唸得亂七八糟

# 正規化：把數字、符號、英文轉成好唸的中文
normalized = "今天氣溫二十五度，CPU 使用率百分之八十。"
tts.infer(spk_audio_prompt="ref.wav", text=normalized, output_path="out.wav")
Code language: PHP (php)

翻譯：合成前先把「數字、百分比、英文縮寫」整理成模型唸得順的形式。有些版本內建正規化，有些要自己做——驗收時一定要試聽數字和英文那幾句。

用法 3：控制情感

tts.infer(
    spk_audio_prompt="ref.wav",
    text="太好了，我們成功了！",
    emo_audio_prompt="happy_sample.wav",  # 拿一段開心的語音當情緒範本
    emo_alpha=0.8,                        # 情緒強度 0~1，越大越誇張
    output_path="out.wav",
)
Code language: PHP (php)

翻譯：除了音色，還能指定「用什麼情緒唸」。emo_alpha 是強度旋鈕，太大會很浮誇、太小聽不出情緒，要試聽調整。

🚩 紅旗

AI 寫的 TTS 呼叫程式「跑得起來」不代表「聲音是對的」。以下四個最常見，跟本篇主題直接相關：

1. 參考音檔品質差還硬用

tts.infer(spk_audio_prompt="phone_recording_noisy.wav", ...)
# 🚩 參考音檔有雜音 / 有背景音樂 / 太短，克隆出來的音色會糊掉、忽大忽小
Code language: PHP (php)

為什麼危險：語音克隆的天花板就是參考音檔的品質。垃圾進、垃圾出。理想的參考音檔：乾淨無雜音、單一人聲、約 5～15 秒、講話自然。

跟 AI 這樣說：「幫我加一段檢查：參考音檔長度太短（<3 秒）或取樣率不符時先警告，並說明理想參考音檔的條件」

2. 文字沒正規化就合成

tts.infer(text="訂單 #12345 折扣 15% 由 GPT-4 處理", ...)
# 🚩 數字、#、%、GPT-4 這種，不同版本唸法天差地遠
Code language: PHP (php)

為什麼危險：畫面上文字沒錯，唸出來卻是「井字十二三四五」這種鬼東西，而你如果沒試聽就發布，錯的是你。

跟 AI 這樣說：「合成前先做文字正規化，把數字、百分比、符號、英文縮寫轉成中文唸法，並列出你做了哪些轉換」

3. 取樣率不符，聲音變尖變快

import soundfile as sf
sf.write("out.wav", audio, 16000)   # 🚩 模型其實輸出 24000，硬寫成 16000
Code language: PHP (php)

為什麼危險：存檔時填錯取樣率，播出來會像「花栗鼠」或「慢動作」。這是最典型、最容易被忽略的 bug，因為程式不會報錯。

怎麼發現：聲音明顯變尖變快（或變低變慢）就是它。用模型回傳的取樣率存檔，不要自己填一個數字。

跟 AI 這樣說：「存 wav 時用模型輸出的取樣率，不要寫死；並在 log 印出實際取樣率讓我確認」

4. 合成完沒試聽就當完成

tts.infer(text=article, output_path="final.wav")
print("完成！")    # 🚩 沒有任何人聽過這個檔案就宣告成功
Code language: PHP (php)

為什麼危險：TTS 的錯（唸錯字、斷句怪、音色不像、爆音）只有耳朵聽得出來，任何程式檢查都抓不到。

跟 AI 這樣說：「合成後印出音檔長度與取樣率，並提醒我一定要人工試聽再發布」

Vibe Coder 驗收檢查點

• [ ] 環境裝好了：uv run python -c "import indextts; print('ok')" 印出 ok（import 名稱以你這版為準）
• [ ] 模型權重下載完成：checkpoints/ 資料夾裡有檔案，不是空的
• [ ] 跑最小範例產出了 output.wav，而且檔案大小 > 0
• [ ] 實際用播放器聽 output.wav：發音正確、斷句自然、沒有爆音或雜訊
• [ ] 音色比對：把 output.wav 跟參考音檔 ref_voice.wav 一起聽，音色像不像
• [ ] 專門試聽「有數字 / 英文 / 百分比」那幾句，確認正規化有生效
• [ ] 問 AI：「這段合成程式的取樣率是寫死的還是用模型輸出的？會不會導致聲音變速？」

看不懂就這樣問 AI

「用白話一段一段解釋這段 IndexTTS2 的合成程式在幹嘛，每個參數（spk_audio_prompt、text、output_path、取樣率）分別是什麼意思，我是初學者。」

「這段程式合成完的 wav 取樣率是多少？存檔時有沒有可能填錯導致聲音變尖變快？」

「幫我把這段長文改成分句合成，並在合成前做中文文字正規化，最後告訴我要聽哪幾句來驗收。」

延伸：知道就好

這些進階功能，遇到再查：

• 批次合成：一次餵多段文字、多個語者，做整集有聲書。
• GPU 加速：device="cuda"，沒有顯卡就用 CPU（慢很多但能動）。
• 情感文字描述：部分版本支援用一句話（如「溫柔地說」）控制情緒，而非丟情緒音檔。
• 輸出格式轉換：模型多半輸出 wav，要 mp3 再用 ffmpeg 轉。

本系列到這裡告一段落：第 1、2 篇帶你認識多媒體 AI 工具的地圖，本篇把「文字 → 語音」這一段補齊。記住核心心法——**AI 的程式能跑不等於對，語音的驗收永遠要用耳朵。**