【经验】ModelScope SamBERT-HiFiGAN TTS 在 Windows Python 3.12 上的安装踩坑全记录

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 kanttskantts是 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_requires3.7.0, 3.9Python 3.12 直接安装会报版本不兼容。解决解压 zip 后修改setup.py第 29 行# 修改前python_requires3.7.0, 3.9,# 修改后python_requires3.7.0,然后本地安装pipinstall.\KAN-TTS-main --no-deps注意--no-deps参数很重要避免自动安装不兼容的依赖版本。坑二kantts.models.hifigan目录缺失报错信息ModuleNotFoundError: No module named kantts.models.hifiganpip 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.signalPython 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 ttsfrdttsfrdTTS Frontend是阿里 KAN-TTS 的中文文本前端处理 C 扩展库仅支持 LinuxWindows 下没有任何可用的 whl 包或源码编译方案。同时SambertHifigan的__init__方法中直接调用了ttsfrd.TtsFrontendEngine进行初始化和语言类型设置不做处理根本无法通过模型加载# modelscope/models/audio/tts/sambert_hifi.py 中的初始化逻辑self.tfsttsfrd.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 _loglogging.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._initializedFalseself._langNonedefinitialize(self):self._initializedTrue_log.info(TtsFrontendEngine.initialize() stub called)returnTruedefset_lang_type(self,lang_typepinyinvg):self._langlang_type _log.info(fTtsFrontendEngine.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 的中文文本前端如pypinying2p等来替代ttsfrd的功能。4. 总结#问题解决方式1PyPI 上kantts是假包从 GitHub 源码安装 KAN-TTS2KAN-TTS 限制 Python 3.9修改 setup.py 放宽版本限制3hifigan 目录 pip 安装遗漏手动从源码复制4preprocess 目录 pip 安装遗漏手动从源码复制5scipy.signal.kaiser API 变更修改为 scipy.signal.windows.kaiser6ttsfrd 仅支持 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 服务器上以获得最佳体验。如果这篇文章对你有帮助欢迎点赞收藏~