Fay數字人如何使用GPT-SOVITS進行TTS轉換以及遇到的一些問題

一、GPT-SoVITS 簡介

GPT-SoVITS 是一款開源的語音合成（TTS）工具，結合了 GPT 模型的文本理解能力與 SoVITS（Sound of Voice In Text-to-Speech）的聲紋模擬技術，能夠實現高自然度、個性化的語音合成。它支持通過少量音頻樣本克隆特定音色，同時具備多語言合成、情感調節等功能，廣泛應用于語音助手、有聲內容創作等場景。用戶可通過網頁界面或 API 接口輸入文本，生成對應語音文件（如 WAV、MP3 等格式）。

二、使用 GPT-SoVITS 進行 TTS 轉換的流程

環境部署：下載項目源碼，安裝 Python 及相關依賴（如 PyTorch、FastAPI 等），部分版本需配置模型文件（如預訓練 GPT 模型、SoVITS 模型）。這里建議使用整合包，推薦使用V2版本的整合包。可參考https://blog.csdn.net/ergdfhgerty/article/details/149021178文章的內容。GPT-SoVITS 學習和v2版本下載地址為https://www.yuque.com/baicaigongchang1145haoyuangong/ib3g1e/dkxgpiy9zb96hob4#KTvnO

啟動服務：項目中的啟動腳本為api_v2.py，啟動本地服務（通常默認端口為 9880）。項目啟動的方法：復制go-webui.bat文件，重命名為api_v2.bat，將代碼修改為如下：

set "SCRIPT_DIR=%~dp0"
set "SCRIPT_DIR=%SCRIPT_DIR:~0,-1%"
cd /d "%SCRIPT_DIR%"
set "PATH=%SCRIPT_DIR%\runtime;%PATH%"
runtime\python.exe -I api_v2.py

啟動方式為雙擊api_v2.bat文件，但是一定要注意這里面不能傳入參數zh_CN，否則運行不通過，要在api_v2.py文件中指定text_lang和prompt_text的具體類型，如下所示：

@APP.get("/tts")
async def tts_get_endpoint(text: str = None,text_lang: str = "zh-CN",ref_audio_path: str = None,aux_ref_audio_paths: list = None,prompt_lang: str = "zh-CN",prompt_text: str = "",top_k: int = 5,top_p: float = 1,temperature: float = 1,text_split_method: str = "cut0",batch_size: int = 1,batch_threshold: float = 0.75,split_bucket: bool = True,speed_factor: float = 1.0,fragment_interval: float = 0.3,seed: int = -1,media_type: str = "wav",streaming_mode: bool = False,parallel_infer: bool = True,repetition_penalty: float = 1.35,sample_steps: int = 32,super_sampling: bool = False,
):

API 調用：若通過代碼調用，可使用 FastAPI 提供的接口http://127.0.0.1:9880/tts，傳入文本、語音參數等，獲取合成的音頻數據。

Fay數字人在調用時的設置：首先要在gptsovits_v3.py文件中指定參考音頻，和音頻的文本，注意要修改成正確的音頻路徑，音頻和音頻的文本要對應，同時音頻不能超過10秒，音頻使用格式為Windows PCM的wav，如下所示：

def to_sample(self, text, style) :    url = "http://127.0.0.1:9880/tts"data = {"text": text,                   # str.(required) text to be synthesized"text_lang": "zh",              # str.(required) language of the text to be synthesized"ref_audio_path": "D:/GPT-SoVITS-v2pro-20250604/111.wav",         # str.(required) reference audio path."prompt_text": "迅捷音頻轉換器是一款專業級軟件，集音頻格式轉換、視頻提取音頻、音頻剪輯",            # str.(optional) prompt text for the reference audio"prompt_lang": "zh",            # str.(required) language of the prompt text for the reference audio"top_k": 5,                   # int.(optional) top k sampling"top_p": 1,                   # float.(optional) top p sampling"temperature": 1,             # float.(optional) temperature for sampling"text_split_method": "cut5",  # str.(optional) text split method, see text_segmentation_method.py for details."batch_size": 1,              # int.(optional) batch size for inference"batch_threshold": 0.75,      # float.(optional) threshold for batch splitting."split_bucket": True,         # bool.(optional) whether to split the batch into multiple buckets."speed_factor":1.0,           # float.(optional) control the speed of the synthesized audio."fragment_interval":0.3,      # float.(optional) to control the interval of the audio fragment."seed": -1,                   # int.(optional) random seed for reproducibility."media_type": "wav",          # str.(optional) media type of the output audio, support "wav", "raw", "ogg", "aac"."streaming_mode": False,      # bool.(optional) whether to return a streaming response."parallel_infer": True,       # bool.(optional) whether to use parallel inference."repetition_penalty": 1.35    # float.(optional) repetition penalty for T2S model.}

這里音頻處理軟件可使用cool edit pro軟件，這是一款專業的音樂編輯軟件，軟件擁有非常強大的功能，幫助用戶進行各種各樣的音頻編輯繪制，玩法多種多樣帶給用戶非常舒適的體驗，下載鏈接：https://www.365xiazai.com/soft/12050.html。

相關參考視頻：

GPT-SoVITS教程6-新增自動選取參考音頻和保存音頻歷史功能

三、API 調用 GPT-SoVITS 相關內容總結

1. 參考教程

B 站教程地址：GPT-SoVITS 教程 5 - 如何調用 API

2. API 調用核心步驟與參數說明

（1）api.py 文件參數解析

文件頂部明確了運行腳本時可傳入的執行參數，主要包括：

模型路徑：-s（SoVITS 模型路徑）、-g（GPT 模型路徑），可在 config.py 中預設；
默認參考音頻參數（調用請求缺少參考音頻時使用）：
- -dr：默認參考音頻路徑；
- -dt：默認參考音頻文本；
- -dl：默認參考音頻語種（支持 “中文”“英文”“日文” 及縮寫 “zh”“en”“ja”）；
運行配置：
- -d：推理設備（“cuda” 或 “cpu”）；
- -a：綁定地址（默認 “127.0.0.1”）；
- -p：綁定端口（默認 9880，可在 config.py 中指定）；
- -fp/-hp：覆蓋 config.py 使用全精度 / 半精度推理；
輸出與文本處理：
- -sm：流式返回模式（默認不啟用，可選 “close”“normal”“keepalive” 及縮寫 “c”“n”“k”）；
- -mt：音頻編碼格式（流式默認 ogg，非流式默認 wav，支持 “wav”“ogg”“aac”）；
- -cp：文本切分符號（默認空，需以 “,.，。” 字符串形式傳入）；
模型組件路徑：-hb（cnhubert 路徑）、-b（bert 路徑）。

（2）啟動 API 服務

運行腳本：在終端中執行?python api.py?或?runtime\python.exe api.py，可直接運行（后續推理時指定參數），或啟動時傳入參數（如指定默認參考音頻、設備等）。
驗證啟動：出現網址即代表接口開啟（默認如http://127.0.0.1:9880）。

（3）內網共享設置

獲取本機 IPv4 地址：打開新終端輸入ipconfig，找到 “無線局域網適配器 WLAN” 項下的 IPv4 地址；
替換地址：用 IPv4 地址替換默認網址中的 “0.0.0.0”，同一內網設備可通過該地址調用接口（例如http://10.10.9.169:9880）。

（4）查看 API 文檔

在啟動的網址后添加/docs，即可查看 FastAPI 自動生成的接口文檔（包含請求格式、參數說明等）。

3. 請求格式（GET 與 POST）

（1）使用預設參考音頻

GET 請求：
http://127.0.0.1:9880?text=待合成文本&text_language=語種
（示例：http://127.0.0.1:9880?text=先帝創業未半而中道崩殂...&text_language=zh）

POST 請求（JSON 格式）：

{  "text": "待合成文本",  "text_language": "語種"  
}

（2）使用預設參考音頻并指定分割符號

GET 請求：
http://127.0.0.1:9880?text=待合成文本&text_language=語種&cut_punc=切分符號
（示例：http://127.0.0.1:9880?text=先帝創業未半...&text_language=zh&cut_punc=，。）

POST 請求（JSON 格式）：

{  "text": "待合成文本",  "text_language": "語種",  "cut_punc": "切分符號"  
}

（3）手動指定當次推理的參考音頻

GET 請求：
http://127.0.0.1:9880?refer_wav_path=音頻路徑&prompt_text=參考文本&prompt_language=參考語種&text=待合成文本&text_language=文本語種
（示例：http://127.0.0.1:9880?refer_wav_path=123.wav&prompt_text=一二三。&prompt_language=zh&text=先帝創業未半...&text_language=zh）

POST 請求（JSON 格式）：

{  "refer_wav_path": "音頻路徑",  "prompt_text": "參考文本",  "prompt_language": "參考語種",  "text": "待合成文本",  "text_language": "文本語種"  
}

（4）更換默認參考音頻（endpoint：`/change_refer`）

GET 請求：
http://127.0.0.1:9880/change_refer?refer_wav_path=新音頻路徑&prompt_text=新參考文本&prompt_language=新語種

POST 請求（JSON 格式）

{  "refer_wav_path": "新音頻路徑",  "prompt_text": "新參考文本",  "prompt_language": "新語種"  
}

4. 響應說明

成功：
- 合成請求：直接返回音頻流（http code 200）；
- 更換參考音頻請求：返回 JSON（http code 200）。
失敗：返回包含錯誤信息的 JSON（http code 400）。

5. 拓展與改良方案

原生 API 功能不足時，可參考改良版接口：
- CSDN 博客：《GPT-SoVITS 項目的 API 改良與使用》；
- 支持動態切換模型和情緒的改良代碼：《針對 GPT-SoVITS 項目的 API 接口改進》（可直接覆蓋原 api.py，新增切換模型、情緒的接口，支持 GET/POST）。

相關參考文章：https://blog.csdn.net/ergdfhgerty/article/details/149021178https://blog.csdn.net/Polo_fang/article/details/140521946

四、常見問題及解決方法（針對 FastAPI 頁面空白問題）

問題：訪問 FastAPI 頁面（如 docs 文檔頁）時顯示空白，鏈接正確但無內容

核心原因：頁面依賴的 CSS 和 JavaScript 資源（通常來自國外 CDN）加載失敗，導致界面無法渲染。

解決方法：

方法一：使用網絡加速工具
- 若有 “魔法” 工具（網絡加速工具），開啟后重新訪問頁面，通常可解決 CDN 資源加載問題。
方法二：安裝?fastapi_cdn_host?庫替換 CDN
- 步驟 1：安裝庫
  打開終端（CMD 或 PowerShell），進入項目的?runtime\Lib\site-packages?目錄（或項目虛擬環境目錄），執行命令：
```
pip install fastapi_cdn_host  
```
  ?
  （注：若項目使用獨立 runtime 環境，需確保庫安裝到該環境的?site-packages?中，而非系統全局 Python 環境。?如果安裝在全局Python環境中，需要把fastapi_cdn_host庫復制到runtime\Lib\sitepackages里，一共有兩個文件夾的內容fastapi_cdn_host和fastapi_cdn_host-0.9.2.dist-info，可以根據文件生成時間確定哪些是需要復制的文件夾，整合包bat運行的環境庫不是主機的，而是runtime里的。）
- 步驟 2：修改代碼
  打開項目中的?api_v2.py?文件，在代碼中添加以下內容：
  - 在文件頂部（約 123 行后）添加導入語句：
```
import fastapi_cdn_host  
```
  - 在 FastAPI 實例化后（約 147 行后，通常是?APP = FastAPI(...)?之后）添加：
```
fastapi_cdn_host.patch_docs(APP)  
```
- 步驟 3：重啟服務
  保存文件后，重新運行啟動腳本（雙擊api_v2.bat），再次訪問頁面即可。
方法三：使用 Steam++ 等工具加速
- 下載并安裝 Steam++ 工具，啟動后選擇 “加速 Steam 社區” 等模式，利用其網絡加速功能間接解決 CDN 資源加載問題。
注意事項
- 若安裝庫后仍無效，需確認?fastapi_cdn_host?已正確放置在項目 runtime 的?site-packages?目錄中（部分整合包的環境獨立，需手動復制或在該目錄下執行安裝命令）。
- 若上述方法均失敗，可嘗試更換網絡環境（如手機熱點），或檢查防火墻 / 安全軟件是否攔截了資源加載。