ModelScope SamBERT-HiFiGAN TTS 在 Windows Python 3.12 上的安装踩坑全记录
前言
最近想用 ModelScope（魔搭社区）的sambert-hifigan模型做一个中文文本转语音工具，于是在 Windows 上开启了折腾之旅。原以为pip install modelscope就万事大吉，结果踩了一堆坑，记录在此供大家参考避坑。
环境：Windows 10/11, Python 3.12, pip 最新版
1. 背景介绍
ModelScope 提供了多种 TTS 模型，其中damo/speech_sambert-hifigan_tts_zh-cn_16k是一款支持多种发音人（知甜、知言、知哲、知蓓）的中文语音合成模型，底层依赖阿里的KAN-TTS项目。
安装命令很简单：
pipinstallmodelscope但当你尝试加载模型时，真正的挑战才开始。
2. 踩坑全记录
坑一：kantts缺失
报错信息：
ModuleNotFoundError: No module named 'kantts'kantts是 KAN-TTS 项目中的核心包，PyPI 上存在一个名称为kantts的假包（大小仅 1.3KB，纯占位），安装它毫无意义。
解决方案：从 GitHub 源码安装真正的 KAN-TTS
# 先卸载假包pip uninstall kantts-y# 下载 KAN-TTS 源码pip download https://github.com/alibaba-damo-academy/KAN-TTS/archive/refs/heads/master.zip踩坑点：KAN-TTS 的setup.py中写死了python_requires=">=3.7.0, <3.9"，Python 3.12 直接安装会报版本不兼容。
解决：解压 zip 后修改setup.py第 29 行：
# 修改前python_requires=">=3.7.0, <3.9",# 修改后python_requires=">=3.7.0",然后本地安装：
pipinstall.\KAN-TTS-main --no-deps注意：--no-deps参数很重要，避免自动安装不兼容的依赖版本。
坑二：kantts.models.hifigan目录缺失
报错信息：
ModuleNotFoundError: No module named 'kantts.models.hifigan'pip installKAN-TTS 时，由于包结构问题，kantts/models/hifigan/子目录没有被包含进去。
解决方案：手动从源码复制
xcopy /E /I /Y KAN-TTS-main\kantts\models\hifigan ^ %PYTHON_PATH%\Lib\site-packages\kantts\models\hifigan坑三：kantts.preprocess目录缺失
报错信息：
FileNotFoundError: .../kantts/preprocess/...同理，preprocess目录（包含PhoneSet.xml等 50+ 配置文件）也被遗漏了。
解决方案：
xcopy /E /I /Y KAN-TTS-main\kantts\preprocess ^ %PYTHON_PATH%\Lib\site-packages\kantts\preprocess教训：对于非标准 pip 包，直接pip install .可能丢文件，务必核对MANIFEST.in或手动检查包完整性。
坑四：SciPykaiser函数 API 变更
报错信息：
ImportError: cannot import name 'kaiser' from 'scipy.signal'Python 3.12 下安装的 scipy 1.18 中，kaiser窗函数从scipy.signal移到了scipy.signal.windows，而 KAN-TTS 源码仍使用旧 API。
解决方案：修改pqmf.py
找到%PYTHON_PATH%\Lib\site-packages\kantts\models\pqmf.py，修改第 1 行：
# 修改前fromscipy.signalimportkaiser# 修改后fromscipy.signal.windowsimportkaiser坑五：ttsfrd—— 最大的拦路虎
报错信息：
ModuleNotFoundError: No module named 'ttsfrd'ttsfrd（TTS Frontend）是阿里 KAN-TTS 的中文文本前端处理 C++ 扩展库，仅支持 Linux，Windows 下没有任何可用的 whl 包或源码编译方案。
同时，SambertHifigan的__init__方法中直接调用了ttsfrd.TtsFrontendEngine进行初始化和语言类型设置，不做处理根本无法通过模型加载：
# modelscope/models/audio/tts/sambert_hifi.py 中的初始化逻辑self.tfs=ttsfrd.TtsFrontendEngine()self.tfs.initialize()self.tfs.set_lang_type('pinyinvg')解决方案：编写 stub 模块
在%PYTHON_PATH%\Lib\site-packages\ttsfrd\下创建__init__.py：
""" ttsfrd stub for Windows TtsFrontendEngine is a Linux-only C++ extension. This stub allows the ModelScope TTS pipeline to initialize on Windows, but actual Chinese text-to-phoneme conversion will not work. """importlogging _log=logging.getLogger(__name__)_log.warning("ttsfrd stub loaded - Chinese text frontend is NOT available on Windows")classTtsFrontendEngine:"""Stub implementation of Linux-only TtsFrontendEngine."""def__init__(self):self._initialized=Falseself._lang=Nonedefinitialize(self):self._initialized=True_log.info("TtsFrontendEngine.initialize() stub called")returnTruedefset_lang_type(self,lang_type='pinyinvg'):self._lang=lang_type _log.info(f"TtsFrontendEngine.set_lang_type('{lang_type}') stub called")returnTruedeftext_to_mel(self,text):_log.warning("text_to_mel() is not available in Windows stub")returnNonedefcompute_mel_style_embedding(self,text):_log.warning("compute_mel_style_embedding() is not available in Windows stub")returnNone坑六：依赖链长，版本兼容性差
整个依赖关系链如下：
modelscope → sambert_hifi → kantts → ttsfrd (Linux only) → kantts.models → hifigan (需手动复制) → kantts.preprocess (需手动复制) → scipy → kaiser (API 已变更)同时还需要安装的第三方依赖：
numpy, addict, datasets, scipy, simplejson, sortedcontainers, matplotlib建议使用批处理脚本一键安装所有依赖。
3. 最终效果
完成以上全部步骤后，模型可以成功加载：
[ModelScope] 加载模型 damo/speech_sambert-hifigan_tts_zh-cn_16k ... [ModelScope] 合成中: 你好，这是一个语音合成测试。 [ModelScope] 成功!注意：由于
ttsfrd在 Windows 上只是 stub，中文文本到音素的转换并未实际执行，生成的音频可能是静音或仅含文件头。如需在 Windows 上实现真正可用的语音合成，需要引入纯 Python 的中文文本前端（如pypinyin+g2p等）来替代ttsfrd的功能。
4. 总结
| # | 问题 | 解决方式 |
|---|---|---|
| 1 | PyPI 上kantts是假包 | 从 GitHub 源码安装 KAN-TTS |
| 2 | KAN-TTS 限制 Python < 3.9 | 修改 setup.py 放宽版本限制 |
| 3 | hifigan 目录 pip 安装遗漏 | 手动从源码复制 |
| 4 | preprocess 目录 pip 安装遗漏 | 手动从源码复制 |
| 5 | scipy.signal.kaiser API 变更 | 修改为 scipy.signal.windows.kaiser |
| 6 | ttsfrd 仅支持 Linux | 编写 Windows stub 模块 |
几条经验：
- PyPI 上名称相同的包不一定是你要的—— 先
pip show确认包内容再详细排查。 - GitHub 源码安装要核对完整性—— 非标准包容易丢子目录，建议检查
MANIFEST.in或直接比较目录。 - 跨平台 Python 项目要关注 C 扩展——
ttsfrd这种 Linux 专属库在 Windows 上无解，只能 stub 或用纯 Python 替代方案。 - Python 版本限制可以适当放宽—— 很多仓库只是"没测试过"高版本而非真的不兼容，修改
setup.py后大多能跑。
附录：一键安装脚本参考
@echo off echo ============================================ echo ModelScope TTS Windows 安装脚本 echo ============================================ REM 1. 安装基础依赖 pip install numpy addict datasets scipy simplejson sortedcontainers matplotlib REM 2. 安装 modelscope pip install modelscope REM 3. 下载并安装 KAN-TTS REM （需先手动下载、解压，修改 setup.py 中的 python_requires） pip install KAN-TTS-main --no-deps REM 4. 复制遗漏的目录 xcopy /E /I /Y KAN-TTS-main\kantts\models\hifigan ^ %PYTHON_PATH%\Lib\site-packages\kantts\models\hifigan xcopy /E /I /Y KAN-TTS-main\kantts\preprocess ^ %PYTHON_PATH%\Lib\site-packages\kantts\preprocess REM 5. 修复 scipy 兼容性 REM 修改 kantts/models/pqmf.py: from scipy.signal.windows import kaiser REM 6. 创建 ttsfrd stub REM 详见上文代码 echo [完成] 安装结束声明：本文为个人安装经验分享，环境不同可能遇到不同问题。建议将 ModelScope TTS 部署在 Linux 服务器上以获得最佳体验。
如果这篇文章对你有帮助，欢迎点赞收藏~
