企业官网建设流程全解析

GPT-SoVITS 语音合成“hps未定义”报错快速修复完整指南

【免费下载链接】GPT-SoVITS1 min voice data can also be used to train a good TTS model! (few shot voice cloning)项目地址: https://gitcode.com/GitHub_Trending/gp/GPT-SoVITS

用 GPT-SoVITS 做少样本声音克隆语音合成时，点击开始合成后控制台抛出 NameError: name 'hps' is not defined，多半是 SoVITS 模型没加载成功，超参数变量 hps 一直没被赋值。按下面顺序排查，一般三步内解决。

这个报错长什么样

你运行 python webui.py 打开推理页面，选好 GPT 模型和 SoVITS 模型，点“开始合成”，页面卡在“模型加载中，请等待”，终端打出：

NameError: name 'hps' is not defined

有的环境里不会直接看到这一行，而是先报 torch.load 加载失败的 unpickle 相关错误——本质是同一条因果链：模型没读进来，hps 自然没值。

一句话说清它是什么

hps 是 inference_webui.py 里存模型超参数的变量，超参数指模型的采样率、帧长、说话人数量这类配置。程序的设计是“先读模型文件，再把配置赋给 hps”；一旦文件损坏、版本不匹配或 PyTorch 拒绝加载，hps 就是空的，后面算暂停时长等步骤一执行就抛未定义。

按顺序处理（从省事到费事）

第 1 步：确认模型文件与版本选择一致

做什么：在页面选同一批训练产出的 GPT 模型和 SoVITS 模型，版本要和代码匹配（v2 / v3 / v3Pro），不要混用不同版本的两个文件。

怎么判断做对了：点加载后控制台不再报错，页面脱离“模型加载中”状态，说明文件被正常读取。

第 2 步：升级到最新代码

做什么：旧版本存在 hps 赋值流程的已知 bug，拉到最新版即可，全新获取用：

git clone https://gitcode.com/GitHub_Trending/gp/GPT-SoVITS

已有目录直接更新到最新提交，然后重新运行 python webui.py。

怎么判断做对了：页面能正常进入推理界面，并且再次点合成时控制台不再出现该 NameError。

第 3 步：处理新版 PyTorch 的加载限制 ⚠️

做什么：PyTorch 2.6 起 torch.load 默认只允许加载纯权重，老模型文件会被拒绝，导致 hps 赋值那行根本执行不到。新版代码已在对应调用里加上 weights_only=False（允许加载附加对象），第 2 步升级即可覆盖；若你停留在旧代码，需在模型加载处手动补上这个参数。

怎么判断做对了：控制台模型加载日志走完，不再出现 pickle 或 unpickle 相关报错。

第 4 步：重新下载预训练模型

做什么：前三步都通过仍报错时，把 GPT_SoVITS/pretrained_models 目录下的旧文件清掉，用项目自带的下载方式重新拉取。

怎么判断做对了：GPT 与 SoVITS 两个模型文件都不为空、大小正常，页面能进入推理界面。

版本与环境对照表

修完又报别的错？

• 出现 ModuleNotFoundError: No module named 'text.LangSegmenter'：说明代码只升级了一半，别手动拼旧文件，直接重新获取最新完整代码。
• Mac M 系列、Windows 表现不一致：GPU 加载崩溃时先看官方文档 docs/cn/README.md 的环境配置部分，Mac M 系列可改用 MPS 设备跑。
• 切换 v1/v2/v3 后又报同类错：多半是 GPT 和 SoVITS 两个模型换得不一致，放回同一训练批次即可。

如果仍解决不了，把完整控制台日志、模型版本和 PyTorch 版本一起贴到项目 issue 区提问，响应会快很多；平时留意项目更新日志，这类错误通常在新版本里已经修掉，升级往往就是最短路径。

【免费下载链接】GPT-SoVITS1 min voice data can also be used to train a good TTS model! (few shot voice cloning)项目地址: https://gitcode.com/GitHub_Trending/gp/GPT-SoVITS