Bug_Factory_w/chatterbox
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

Chatterbox 昇腾 NPU 迁移与推理部署指南

Chatterbox 是 Resemble AI 开源的生产级多语言 TTS(文本转语音)模型 (MIT 协议,0.5B 参数,Llama 3 骨干),支持 23 种语言 与 零样本语音克隆, 内置情绪夸张度控制与音频水印。本仓库将 Chatterbox 迁移适配到华为昇腾 NPU, 提供 HTTP 服务化推理 与完整测试用例。


1. 目录结构

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     #   适配过程截图

2. 环境要求

项目要求本机实测
硬件Ascend910 系列 (Atlas 800), ≥1 卡12x Ascend910 (61 GB HBM)
OSopenEuler / Ubuntu / KylinOS (aarch64)openEuler 22.03 SP4 aarch64
CANN≥ 8.08.5.1
Python3.10 – 3.113.11.14
PyTorch2.9.02.9.0
torch_npu与 PyTorch 配套2.9.0.post1+gitee7ba04
transformers≥ 5.0 (官方要求 5.2.0)5.2.0

2.1 环境初始化

# 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 资源

3. 模型结构与昇腾 NPU 迁移说明

3.1 模型架构

输入文本 (23 种语言)
  → MTLTokenizer (字素/音素编码 + pkuseg 中文分词 + pykakasi 日文)
  → T3 模型 (Llama 3 骨干, 自回归生成语音 token, 支持 CFG/温度/重复惩罚)
  → S3Gen 声码器 (flow matching + HiFi-GAN, 24kHz 音频)
  → Perth 水印 (可选)
  → 输出 wav 音频

3.2 适配点(使用 ascend-model-agent-plugin 的 ai4s-basic skill)

适配点问题修复方式
chatterbox/__init__.py源码树使用时 importlib.metadata.version("chatterbox-tts") 抛 PackageNotFoundErrortry/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。

4. 服务化推理

4.1 启动服务

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

4.2 接口定义

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)

5. 测试验证

5.1 一键运行全部测试

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

测试覆盖:

  1. 环境检查 — torch / torch_npu 版本、NPU 数量与显存
  2. 模块级英文 TTS — 生成英文语音,校验音频时长/非静音/采样率
  3. 模块级中文 TTS — 验证多语言支持(中文分词链路)
  4. HTTP 服务化推理 — 启动 Flask 服务,通过 POST /infer 端到端验证 (生成的音频保存至 output/ 目录)

5.2 本机实测结果(Ascend910, npu:0)

[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)
  • 中英文语音合成均正常输出非静音音频 ✓
  • 服务化推理端到端可用 ✓(HTTP 200)
  • NPU 显存占用 ~3.16 GB

6. 使用建议与已知限制

  1. 性能:短文本(约 40 字符)NPU 推理 2~4s(含自回归 token 生成 + 声码器)。 首次推理含算子编译会偏慢,后续稳定;transformers 的 KV cache 已启用。
  2. torch.istft CPU fallback:NPU 上 istft 算子(aclnnUnfoldGrad)暂不支持, 声码器最后一步在 CPU 执行。仅一次调用且数据量小(单帧频谱),对端到端耗时 影响 <5%,精度无损。
  3. 中文支持:中文分词依赖 spacy-pkuseg,首次使用会联网下载分词模型 (或预置到 ~/.pkuseg/),离线环境需提前准备。
  4. 语音克隆:audio_prompt_path 传参考音频路径即可零样本克隆音色; 参考语音语言与目标语言不一致时建议 cfg_weight=0(README 官方建议)。
  5. 水印:输出音频默认带 Perth 神经水印(用于溯源检测),如不需要可 修改 mtl_tts.py 中 watermarker 的使用。
  6. 多卡部署:单卡即可承载;多实例可通过多进程部署(每进程绑定一张卡, 不同端口)。

7. 引用

@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