Chatterbox 是 Resemble AI 开源的生产级多语言 TTS(文本转语音)模型 (MIT 协议,0.5B 参数,Llama 3 骨干),支持 23 种语言 与 零样本语音克隆, 内置情绪夸张度控制与音频水印。本仓库将 Chatterbox 迁移适配到华为昇腾 NPU, 提供 HTTP 服务化推理 与完整测试用例。
chatterbox-npu/
├── README.md # 本文档 (中文部署指引)
├── requirements.txt # 昇腾 NPU 运行环境依赖
├── inference.py # ★ 服务化推理脚本 (Flask HTTP 服务)
├── test_inference.py # ★ 测试用例 (英文/中文 TTS + HTTP 端到端)
├── example_tts.py # 官方示例脚本 (参考)
├── LICENSE # MIT 许可证
├── chatterbox/ # Chatterbox 源码 (已适配 NPU)
│ ├── mtl_tts.py # 多语言 TTS 主类 (from_local 已适配)
│ ├── models/
│ │ ├── t3/ # T3 文本模型 (Llama 3 骨干)
│ │ ├── s3gen/ # S3Gen 声码器 (hifigan._istft 已适配)
│ │ ├── s3tokenizer/ # 音频 tokenizer
│ │ └── tokenizers/ # 文本 tokenizer (23 语言)
├── scripts/
│ ├── gen_screenshots.py # 交付截图生成脚本
│ └── adaptation_log.txt # 适配过程记录
├── output/ # 测试生成的音频 (test_en.wav / test_zh.wav)
└── assets/ # 交付截图
├── npu_device_call.png # NPU 设备调用截图
├── model_result.png # 测试结果截图
└── agent_workflow.png # 适配过程截图| 项目 | 要求 | 本机实测 |
|---|---|---|
| 硬件 | Ascend910 系列 (Atlas 800), ≥1 卡 | 12x Ascend910 (61 GB HBM) |
| OS | openEuler / Ubuntu / KylinOS (aarch64) | openEuler 22.03 SP4 aarch64 |
| CANN | ≥ 8.0 | 8.5.1 |
| Python | 3.10 – 3.11 | 3.11.14 |
| PyTorch | 2.9.0 | 2.9.0 |
| torch_npu | 与 PyTorch 配套 | 2.9.0.post1+gitee7ba04 |
| transformers | ≥ 5.0 (官方要求 5.2.0) | 5.2.0 |
# 1) 加载 CANN 环境
source /usr/local/Ascend/ascend-toolkit/set_env.sh
# 2) 指定可见 NPU 卡
export ASCEND_RT_VISIBLE_DEVICES=0
# 3) 安装依赖 (建议使用华为镜像源)
pip install -r requirements.txt \
-i https://repo.huaweicloud.com/repository/pypi/simple/
# 4) 校验 NPU 可用
python3 -c "import torch; import torch_npu; \
a = torch.randn(3, 4).npu(); print(a + a)" # 输出 device='npu:0' 即正常⚠️ transformers 版本必须 ≥ 5.0:4.x 的
generate()接口与 Chatterbox 的T3HuggingfaceBackend不兼容(cache_position参数类型报错), 需升级到官方要求的 5.2.0。权重文件位置:
/mnt/old_data/whl/models/2/ResembleAI/chatterbox/
t3_mtl23ls_v3.safetensors— 多语言 T3 文本模型(V3,23 语言)s3gen_v3.safetensors/ve.pt— 声码器 / 说话人编码器conds.pt— 内置音色(无需参考音频即可合成)grapheme_mtl_merged_expanded_v1.json、Cangjie5_TC.json— tokenizer 资源
输入文本 (23 种语言)
→ MTLTokenizer (字素/音素编码 + pkuseg 中文分词 + pykakasi 日文)
→ T3 模型 (Llama 3 骨干, 自回归生成语音 token, 支持 CFG/温度/重复惩罚)
→ S3Gen 声码器 (flow matching + HiFi-GAN, 24kHz 音频)
→ Perth 水印 (可选)
→ 输出 wav 音频ascend-model-agent-plugin 的 ai4s-basic skill)| 适配点 | 问题 | 修复方式 |
|---|---|---|
chatterbox/__init__.py | 源码树使用时 importlib.metadata.version("chatterbox-tts") 抛 PackageNotFoundError | try/except 容错,缺省版本号 |
chatterbox/mtl_tts.py from_local() | device 为 npu:0 时 map_location=None,CUDA 设备权重无法反序列化 | 仅 cuda 传 None,其余一律 map_location=cpu 后 .to(device) |
models/s3gen/hifigan.py _istft() | torch.istft 在 NPU 不支持(aclnnUnfoldGrad 报错) | CPU fallback:复数频谱搬 CPU 完成 ISTFT 再搬回 NPU(单次调用,开销可忽略) |
| transformers 版本 | 4.57.6 的 generate() 与 T3HuggingfaceBackend 不兼容 | 升级 transformers 5.2.0 |
| 缺失依赖 | s3tokenizer/conformer/pykakasi/spacy-pkuseg/perth | 按官方 pyproject 补齐安装 |
详细适配过程见 scripts/adaptation_log.txt 与 assets/agent_workflow.png。
source /usr/local/Ascend/ascend-toolkit/set_env.sh
export ASCEND_RT_VISIBLE_DEVICES=0
python3 inference.py \
--ckpt_dir /mnt/old_data/whl/models/2/ResembleAI/chatterbox \
--t3_model t3_mtl23ls_v3.safetensors \
--port 8080 --device npu:0参数说明:
--ckpt_dir:本地权重目录--t3_model:多语言 T3 模型(v2/v3或 safetensors 文件名),默认 V3--device:推理设备,缺省自动选择npu:0(无 NPU 时回退 cuda/cpu)--port:HTTP 服务端口,默认 8080
GET /health — 健康检查
curl http://127.0.0.1:8080/health
# {"status":"ok","device":"npu:0","load_time":43.79,"sr":24000,"languages":["ar","da",...]}POST /infer — 文本合成语音
{
"text": "你好,这里是昇腾NPU上运行的Chatterbox语音合成系统。",
"language_id": "zh",
"exaggeration": 0.5,
"cfg_weight": 0.5,
"temperature": 0.8,
"audio_prompt_path": null
}输出:base64 编码的 wav 音频(16-bit PCM, 24kHz 单声道):
{
"status": "ok",
"wav_b64": "UklGRiQAAABXQVZF...",
"duration": 4.56,
"sr": 24000,
"elapsed": 3.042,
"total_elapsed": 3.05
}参数说明:
language_id:23 种语言代码之一(en/zh/fr/de/ja/ko 等)audio_prompt_path:参考音频路径(语音克隆),传 null 使用内置音色exaggeration:情绪夸张度 0~1(默认 0.5)cfg_weight:CFG 权重(默认 0.5;参考语音与目标语言不一致时建议设 0)
source /usr/local/Ascend/ascend-toolkit/set_env.sh
export ASCEND_RT_VISIBLE_DEVICES=0
python3 test_inference.py \
--ckpt_dir /mnt/old_data/whl/models/2/ResembleAI/chatterbox \
--device npu:0测试覆盖:
POST /infer 端到端验证
(生成的音频保存至 output/ 目录)[inference] Chatterbox 模型加载完成: 设备 npu:0, 耗时 43.79s, 采样率 24000Hz
[en] 推理耗时 : 4.040 s
[en] 音频时长 : 4.84s (sr=24000Hz) RMS 能量: 3882.87 (PASS)
[zh] 推理耗时 : 3.042 s
[zh] 音频时长 : 4.56s (sr=24000Hz) RMS 能量: 3202.08 (PASS)
[http] HTTP 状态 : 200
[http] 推理耗时 : 1.908 s
[http] 音频时长 : 2.52s (sr=24000Hz) RMS 能量: 3059.52 (PASS)transformers 的 KV cache 已启用。torch.istft CPU fallback:NPU 上 istft 算子(aclnnUnfoldGrad)暂不支持,
声码器最后一步在 CPU 执行。仅一次调用且数据量小(单帧频谱),对端到端耗时
影响 <5%,精度无损。spacy-pkuseg,首次使用会联网下载分词模型
(或预置到 ~/.pkuseg/),离线环境需提前准备。audio_prompt_path 传参考音频路径即可零样本克隆音色;
参考语音语言与目标语言不一致时建议 cfg_weight=0(README 官方建议)。mtl_tts.py 中 watermarker 的使用。@software{resemble_chatterbox,
title = {Chatterbox: Open Source TTS and Voice Conversion by Resemble AI},
author = {Resemble AI},
year = {2025},
url = {https://github.com/Resemble-AI/chatterbox}
}模型来源:HuggingFace: ResembleAI/chatterbox 许可证:MIT