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。

三、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 目录中（部分整合包的环境独立，需手动复制或在该目录下执行安装命令）。
- 若上述方法均失败，可尝试更换网络环境（如手机热点），或检查防火墙 / 安全软件是否拦截了资源加载。