# https://github.com/bentoml/BentoChatTTS 项目说明书

生成时间：2026-06-18 00:42:42 UTC

## 目录

- [项目概览与快速开始](#page-1)
- [服务架构与 ChatTTS 集成](#page-2)
- [TTS 推理 API 与音频生成流水线](#page-3)
- [部署、构建配置与运维](#page-4)

<a id='page-1'></a>

## 项目概览与快速开始

### 相关页面

相关主题：[服务架构与 ChatTTS 集成](#page-2), [部署、构建配置与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/bentoml/BentoChatTTS/blob/main/README.md)
- [service.py](https://github.com/bentoml/BentoChatTTS/blob/main/service.py)
- [bentofile.yaml](https://github.com/bentoml/BentoChatTTS/blob/main/bentofile.yaml)
- [bento_constants.py](https://github.com/bentoml/BentoChatTTS/blob/main/bento_constants.py)
- [requirements.txt](https://github.com/bentoml/BentoChatTTS/blob/main/requirements.txt)
</details>

# 项目概览与快速开始

## 项目概述

BentoChatTTS 是一个将 [ChatTTS](https://github.com/2noise/ChatTTS) 文本转语音（TTS）模型封装为 [BentoML](https://docs.bentoml.com/) 微服务的示例项目。ChatTTS 是一种专为对话场景（如 LLM 助手）设计的语音合成模型，该项目演示了如何借助 BentoML 的服务抽象、容器化与部署能力，将该模型快速暴露为可通过 HTTP 调用的 API。

资料来源：[README.md:1-5]()

项目的核心定位是“示范与最小可用工程模板”，因此代码体量较小，逻辑清晰，适合作为学习 BentoML 集成 PyTorch 模型的参考实现。

## 架构与核心组件

BentoChatTTS 采用典型的 BentoML 单服务架构。整个工程由配置层、服务定义层、构建配置层和依赖声明层四部分组成。

```mermaid
flowchart LR
    Client[HTTP Client] -->|POST /tts| API[bentoml.api: tts]
    API --> ChatTTS[ChatTTS.Chat.infer]
    ChatTTS --> Tensor[torch.from_numpy wavs]
    Tensor --> Audio[torchaudio.save -> WAV bytes]
    Audio -->|audio/wav| Client
    Config[bento_constants.py] -.-> Service
    Build[bentofile.yaml] -.-> Service
    Req[requirements.txt] -.-> Service
```

**服务入口** 位于 `service.py` 中的 `Main` 类，类装饰器 `@bentoml.service(**CONSTANTS["service_config"])` 会读取 `bento_constants.py` 中的 YAML 常量，注入服务名、流量超时和 GPU 资源配置。

资料来源：[service.py:18-25]()、[bento_constants.py:1-7]()

**模型加载**：在 `__init__` 构造方法中，服务会通过 `sys.path.append(CHATTTS_PATH)` 把动态克隆下来的 ChatTTS 源码加入路径，并调用 `self.chat.load_models(compile=False)` 完成模型权重加载。

资料来源：[service.py:32-37]()

**部署钩子**：`@bentoml.on_deployment` 装饰的 `on_deployment` 静态方法在部署阶段执行，通过 `dulwich.porcelain.clone` 从环境变量 `CHAT_TTS_REPO` 指定的 Git 仓库拉取 ChatTTS 源码，确保运行环境中始终使用最新（或指定版本）的上游代码。

资料来源：[service.py:19-31]()

## 快速开始

### 环境准备

推荐使用 Python 3.11。在克隆项目后安装依赖前，需先通过系统包管理器安装 `libsox-dev`（音频编解码依赖），该要求同样会在 Docker 镜像构建阶段自动安装。

资料来源：[README.md:13-21]()、[bentofile.yaml:13-18]()

```bash
git clone https://github.com/bentoml/BentoChatTTS.git
cd BentoChatTTS
pip install bentoml
pip install -r requirements.txt
```

### 本地启动

通过环境变量指定 ChatTTS 上游仓库地址，然后使用 `bentoml serve` 启动服务。服务默认监听 `http://localhost:3000`，可通过 Swagger UI 发起交互式测试。

资料来源：[README.md:23-30]()

```bash
export CHAT_TTS_REPO=https://github.com/2noise/ChatTTS.git
bentoml serve
```

### 部署到 BentoCloud

完成 `bentoml login` 后，使用 `bentoml deploy .` 即可将当前目录构建为 Bento 并推送至 BentoCloud。构建配置由 `bentofile.yaml` 描述：服务入口为 `service:Main`，Python 版本固定为 3.11，容器镜像中预装 `libsox-dev`，并通过 `envs` 注入 `CHAT_TTS_REPO` 环境变量。

资料来源：[README.md:32-38]()、[bentofile.yaml:1-20]()

## 配置与依赖

| 配置项 | 取值 / 说明 | 来源文件 |
| --- | --- | --- |
| 服务名 | `chattts` | [bento_constants.py:3]() |
| 请求超时 | `300s` | [bento_constants.py:5]() |
| GPU 资源 | `1`（推理需 GPU） | [bento_constants.py:6]() |
| 容器 Python 版本 | `3.11` | [bentofile.yaml:13]() |
| 系统包 | `libsox-dev` | [bentofile.yaml:14-15]() |
| 环境变量 | `CHAT_TTS_REPO` | [bentofile.yaml:19-20]() |
| 锁包策略 | `lock_packages: true` | [bentofile.yaml:11]() |

主要 Python 依赖包括 `torch==2.3.0`、`torchaudio`、`transformers==4.41.0`、`omegaconf`、`vocos`、`vector_quantize_pytorch`、`WeTextProcessing`（含 `nemo-text-processing`）以及用于 Git 克隆的 `dulwich`。该组合基本对应 ChatTTS 上游运行所需的最小依赖集合。

资料来源：[requirements.txt:1-14]()

## 常见注意事项

- **GPU 必需**：服务在 `bento_constants.py` 中声明了 `gpu: 1`，本地或云端部署均需保证至少一块可用 GPU；CPU 模式会因模型尺寸与采样率导致推理极慢。
  资料来源：[bento_constants.py:5-6]()
- **speaker 参数**：`tts` 接口的 `speaker` 字段被当作十六进制字符串解析为随机种子，用于控制 `torch.manual_seed` 与 `cuda.manual_seed`，进而影响生成的 `rand_spk` 说话人向量。
  资料来源：[service.py:42-58]()
- **音频格式**：返回内容通过 `torchaudio.save` 序列化为 24 kHz 的 WAV，`ContentType("audio/wav")` 元数据帮助 BentoML 在响应中设置正确的 MIME。
  资料来源：[service.py:60-65]()

## See Also

- [ChatTTS 上游仓库](https://github.com/2noise/ChatTTS)
- [BentoML 示例项目列表](https://docs.bentoml.com/en/latest/examples/overview.html)
- [BentoCloud 访问令牌管理](https://docs.bentoml.com/en/latest/bentocloud/how-tos/manage-access-token.html)

---

<a id='page-2'></a>

## 服务架构与 ChatTTS 集成

### 相关页面

相关主题：[项目概览与快速开始](#page-1), [TTS 推理 API 与音频生成流水线](#page-3), [部署、构建配置与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [service.py](https://github.com/bentoml/BentoChatTTS/blob/main/service.py)
- [bento_constants.py](https://github.com/bentoml/BentoChatTTS/blob/main/bento_constants.py)
- [bentofile.yaml](https://github.com/bentoml/BentoChatTTS/blob/main/bentofile.yaml)
- [requirements.txt](https://github.com/bentoml/BentoChatTTS/blob/main/requirements.txt)
- [README.md](https://github.com/bentoml/BentoChatTTS/blob/main/README.md)
</details>

# 服务架构与 ChatTTS 集成

## 概述

`BentoChatTTS` 是基于 BentoML 框架构建的示例项目，演示如何将 [ChatTTS](https://github.com/2noise/ChatTTS)（专为对话场景设计的文本转语音模型）以 HTTP 服务形式进行部署与调用。项目的核心目标是把 PyTorch 推理代码与 BentoML 的服务编排、容器化、云端部署能力结合，使 ChatTTS 能作为 LLM 助手的语音输出后端。资料来源：[README.md:1-3]()。

## 整体架构与调用流程

下图展示了从客户端请求到音频返回的完整调用链：

```mermaid
sequenceDiagram
    participant Client as 客户端
    participant BentoML as BentoML 运行时
    participant Service as Main 服务
    participant ChatTTS as ChatTTS 模型
    Client->>BentoML: POST /tts (text, speaker)
    BentoML->>Service: 调用 tts() 入口
    Service->>Service: torch.manual_seed / 计算 rand_spk
    Service->>ChatTTS: chat.infer([text], params_infer_code)
    ChatTTS-->>Service: wavs (numpy 数组)
    Service->>Service: torchaudio.save → BytesIO
    Service-->>BentoML: 返回 audio/wav
    BentoML-->>Client: 200 OK (audio/wav)
```

服务在启动时会通过 `@bentoml.on_deployment` 钩子从 `CHAT_TTS_REPO` 环境变量指定的 Git 仓库克隆 ChatTTS 源码，并在 `__init__` 中加载预训练模型。资料来源：[service.py:27-44]()。

## 核心组件与服务定义

### 服务配置与部署钩子

`service.py` 中通过 `@bentoml.service(**CONSTANTS["service_config"])` 装饰 `Main` 类，将 `bento_constants.py` 中的 YAML 常量注入服务描述：

```yaml
project: chattts
service_config:
  name: chattts
  traffic:
    timeout: 300
  resources:
    gpu: 1
```

其中 `name` 标识服务，`traffic.timeout=300` 允许长文本推理耗时，`resources.gpu=1` 声明需要一块 GPU。资料来源：[bento_constants.py:1-9]()。

`on_deployment` 静态方法作为部署钩子，使用 `dulwich.porcelain.clone` 拉取 `CHAT_TTS_REPO` 仓库至本地 `CHATTTS_PATH`（即仓库根目录下的 `ChatTTS` 子目录），若目录已存在则先删除。资料来源：[service.py:27-39]()。该设计避免了在镜像中硬编码第三方依赖，使部署阶段始终使用与上游一致的源码。

### TTS API 实现

`tts` 是唯一的对外端点，由 `@bentoml.api` 装饰，其签名与返回类型如下：

```python
@bentoml.api
def tts(
    self,
    text: str = "PUT YOUR TEXT HERE",
    speaker: str = "2",
) -> Annotated[pathlib.Path, ContentType("audio/wav")]:
```

调用流程包含以下步骤，资料来源：[service.py:46-86]()：

1. **种子控制**：将 `speaker` 字符串按 16 进制解析为整数 seed，写入 `torch.manual_seed` 与 CUDA 版本的随机数生成器，从而保证同一 speaker 编号产生稳定的声纹。
2. **随机说话人嵌入**：从 `self.chat.pretrain_models["spk_stat"]` 切分出 `std` 与 `mean`，结合 GPT 首层 MLP 维度采样 `rand_spk`，作为推理时的说话人条件。
3. **推理参数**：`temperature=0.3`、`top_P=0.7`、`top_K=20`、`rhythm=True` 用于在稳定性与表现力之间取得平衡。
4. **推理与序列化**：`self.chat.infer(...)` 返回 numpy 波形数组，使用 `torchaudio.save` 以 24 kHz 采样率编码为 WAV 字节流，并以 `audio/wav` MIME 类型返回。

## 部署与运行配置

`bentofile.yaml` 描述了打包与容器化策略：

- `service: "service:Main"` 指向入口类，资料来源：[bentofile.yaml:1-2]()。
- `python.requirements_txt` 锁定 `requirements.txt` 中的依赖（`torch==2.3.0`、`transformers==4.41.0`、`vocos`、`WeTextProcessing` 等），并通过 `lock_packages: true` 生成可复现的锁文件。资料来源：[requirements.txt:1-14]()。
- `docker.python_version: "3.11"` 与 `system_packages: libsox-dev` 共同确保 `torchaudio` 的音频后端可用。资料来源：[bentofile.yaml:8-12]()。README 也明确指出，若宿主机缺少 `libsox-dev`，需先通过系统包管理器安装。资料来源：[README.md:13-15]()。
- 环境变量 `CHAT_TTS_REPO` 默认指向官方仓库 `https://github.com/2noise/ChatTTS.git`，可被用户覆盖以使用 fork 版本。资料来源：[bentofile.yaml:14-15]()。

运行时只需执行：

```bash
export CHAT_TTS_REPO=https://github.com/2noise/ChatTTS.git
bentoml serve
```

服务即在 `http://localhost:3000` 启动，Swagger UI 可用于调试。资料来源：[README.md:19-25]()。若要进一步部署至 BentoCloud，登录后执行 `bentoml deploy .` 即可。资料来源：[README.md:27-32]()。

## See Also

- [README.md](https://github.com/bentoml/BentoChatTTS/blob/main/README.md) — 安装、运行与部署说明
- [BentoML 官方文档](https://docs.bentoml.com/) — 服务定义与部署参考
- [ChatTTS 官方仓库](https://github.com/2noise/ChatTTS) — 上游模型与推理细节

---

<a id='page-3'></a>

## TTS 推理 API 与音频生成流水线

### 相关页面

相关主题：[服务架构与 ChatTTS 集成](#page-2), [部署、构建配置与运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [service.py](https://github.com/bentoml/BentoChatTTS/blob/main/service.py)
- [README.md](https://github.com/bentoml/BentoChatTTS/blob/main/README.md)
- [bento_constants.py](https://github.com/bentoml/BentoChatTTS/blob/main/bento_constants.py)
- [bentofile.yaml](https://github.com/bentoml/BentoChatTTS/blob/main/bentofile.yaml)
- [requirements.txt](https://github.com/bentoml/BentoChatTTS/blob/main/requirements.txt)
</details>

# TTS 推理 API 与音频生成流水线

## 概述

BentoChatTTS 是一个基于 [BentoML](https://github.com/bentoml/BentoML) 的服务端到端示例项目，用于将 [ChatTTS](https://github.com/2noise/ChatTTS) 对话式文本转语音模型封装为可独立部署的微服务。该项目通过单一 HTTP 端点接收文本输入并返回 WAV 格式音频字节流，核心由 `Main` 服务类与 `tts` 推理方法组成 资料来源：[service.py:1-16]()。

整体流水线涵盖三个阶段：部署期通过 Git 拉取上游 ChatTTS 仓库；服务初始化阶段加载预训练模型与说话人统计量；请求阶段根据 `speaker` 种子生成随机说话人嵌入，调用 ChatTTS 推理接口并将结果编码为 24 kHz 的 WAV 字节流返回客户端 资料来源：[service.py:19-78]()。

## 服务架构与初始化

### 部署期代码获取

服务在 `@bentoml.on_deployment` 钩子中读取环境变量 `CHAT_TTS_REPO`，并使用 `dulwich.porcelain.clone` 以 `depth=1` 的浅克隆方式拉取 ChatTTS 仓库到本地 `ChatTTS/` 目录；若目录已存在则先 `shutil.rmtree` 清空 资料来源：[service.py:18-33]()。该流程确保每次部署都使用最新的上游代码而无需手动同步。

### 模型加载

`__init__` 方法将 `ChatTTS/` 加入 `sys.path` 后导入 `ChatTTS.Chat`，调用 `chat.load_models(compile=False)` 加载预训练权重 资料来源：[service.py:36-42]()。禁用 `torch.compile` 可以缩短启动时间，源码注释提示将其设为 `True` 可获得更好的运行时性能 资料来源：[service.py:42]()。

## TTS 推理 API 详解

`tts` 方法以 BentoML 服务 API 暴露，签名如下 资料来源：[service.py:46-52]()：

| 参数 | 类型 | 默认值 | 作用 |
|------|------|--------|------|
| `text` | `str` | `"PUT YOUR TEXT HERE"` | 待合成的文本 |
| `speaker` | `str` | `"2"` | 十六进制字符串形式的随机种子，用于控制音色 |

返回类型为 `Annotated[pathlib.Path, ContentType("audio/wav")]`，BentoML 会自动附带正确的 `Content-Type: audio/wav` 响应头 资料来源：[service.py:51-52]()。

### 推理超参数

`rhythm`、`temperature`、`top_P`、`top_K` 在方法内部硬编码为 `True / 0.3 / 0.7 / 20`，分别控制韵律跳过精细化、采样温度、核采样概率与候选词数 资料来源：[service.py:53-57]()。这些值是 ChatTTS 推荐的“稳定生成”配置，未暴露为外部参数。

## 音频生成流水线

`tts` 方法内部的端到端流程可用下图概括：

```mermaid
flowchart TD
    A[接收 text 与 speaker] --> B[解析 speaker 种子]
    B --> C[设置 torch.manual_seed]
    C --> D[采样说话人嵌入 rand_spk]
    D --> E[调用 chat.infer]
    E --> F[torchaudio.save 编码 WAV]
    F --> G[返回音频字节流]
```

具体步骤如下：

1. **种子解析**：将 `speaker`（十六进制字符串）通过 `int(speaker, 16)` 转换为整数并写入 `torch.manual_seed`；当 CUDA 可用时同时设置 `cuda.manual_seed` 与 `manual_seed_all`，确保多 GPU 一致 资料来源：[service.py:60-67]()。
2. **说话人嵌入采样**：从 `self.chat.pretrain_models["spk_stat"]` 中按 `chunk(2)` 切分得到标准差 `std` 与均值 `mean`，再与 `gpt.layers[0].mlp.gate_proj.in_features` 维度的正态噪声结合生成 `rand_spk` 资料来源：[service.py:69-72]()。
3. **推理调用**：将 `rand_spk`、`temperature`、`top_P`、`top_K` 打包到 `params_infer_code`，并以 `skip_refine_text=rhythm` 跳过文本精细化步骤，调用 `self.chat.infer([text], ...)` 获得波形列表 资料来源：[service.py:74-80]()。
4. **WAV 编码**：使用 `torchaudio.save` 将 NumPy 数组形式的波形写入 `io.BytesIO`，采样率固定为 24 000 Hz，格式为 `wav`，最终通过 `.getvalue()` 返回字节内容 资料来源：[service.py:82-85]()。

## 配置与部署

### 服务常量

`bento_constants.py` 以内嵌 YAML 字符串声明服务级配置：服务名 `chattts`、流量超时 `300` 秒、GPU 资源数 `1` 资料来源：[bento_constants.py:1-9]()。这些字段会通过 `**CONSTANTS["service_config"]` 解包到 `@bentoml.service` 装饰器 资料来源：[service.py:14]()。

### Bento 构建文件

`bentofile.yaml` 指定入口服务 `service:Main`、Python 3.11 基础镜像、系统包 `libsox-dev`（用于音频 I/O），以及环境变量 `CHAT_TTS_REPO` 的默认值 资料来源：[bentofile.yaml:1-20]()。`lock_packages: true` 会在构建时锁定依赖版本，保证部署可复现 资料来源：[bentofile.yaml:12-13]()。

### 依赖与运行

运行所需的 Python 包由 `requirements.txt` 提供，包括 `torch==2.3.0`、`torchaudio`、`transformers==4.41.0`、`vocos`、`dulwich` 等 资料来源：[requirements.txt:1-13]()。本地启动只需在设置 `CHAT_TTS_REPO` 环境变量后执行 `bentoml serve` 即可监听 `http://localhost:3000` 并通过 Swagger UI 调试 资料来源：[README.md:21-31]()。生产环境可使用 `bentoml deploy .` 一键发布到 BentoCloud 资料来源：[README.md:33-41]()。

## 常见失败模式

- **未设置 `CHAT_TTS_REPO`**：`on_deployment` 中的 `assert` 会在导入阶段立即失败 资料来源：[service.py:21-22]()`。
- **缺失 `libsox-dev`**：因 `torchaudio.save` 依赖 sox 后端，缺少该系统包会导致 WAV 编码抛错 资料来源：[bentofile.yaml:16-17]()`。
- **GPU 资源不足**：`gpu: 1` 的资源声明意味着部署环境必须提供至少一张 CUDA 设备 资料来源：[bento_constants.py:7-8]()`。
- **说话人种子非法**：若 `speaker` 不是合法十六进制，`int(speaker, 16)` 会抛出 `ValueError` 资料来源：[service.py:61]()`。

## See Also

- [BentoML 官方示例列表](https://docs.bentoml.com/en/latest/examples/overview.html)
- [ChatTTS 上游仓库](https://github.com/2noise/ChatTTS)
- [BentoCloud 部署指南](https://docs.bentoml.com/en/latest/bentocloud/how-tos/manage-access-token.html)

---

<a id='page-4'></a>

## 部署、构建配置与运维

### 相关页面

相关主题：[项目概览与快速开始](#page-1), [服务架构与 ChatTTS 集成](#page-2), [TTS 推理 API 与音频生成流水线](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [bentofile.yaml](https://github.com/bentoml/BentoChatTTS/blob/main/bentofile.yaml)
- [bento_constants.py](https://github.com/bentoml/BentoChatTTS/blob/main/bento_constants.py)
- [service.py](https://github.com/bentoml/BentoChatTTS/blob/main/service.py)
- [README.md](https://github.com/bentoml/BentoChatTTS/blob/main/README.md)
- [requirements.txt](https://github.com/bentoml/BentoChatTTS/blob/main/requirements.txt)
</details>

# 部署、构建配置与运维

## 概述

BentoChatTTS 是基于 [ChatTTS](https://github.com/2noise/ChatTTS) 对话场景 TTS 模型的 BentoML 服务化示例。本页聚焦于该仓库中与**构建、打包、部署和运维**相关的全部配置与机制，涵盖 `bentofile.yaml` 构建清单、服务常量 `bento_constants.py`、运行时服务 `service.py`、运行说明 `README.md` 以及依赖清单 `requirements.txt`。

整体部署流程可以概括为：通过 `bentofile.yaml` 声明构建产物（Python 依赖、Docker 系统包、环境变量等），在部署阶段通过 `on_deployment` 钩子从远端仓库克隆 ChatTTS 源码，再由 `Main` 类加载模型并对外暴露 `/tts` 接口。运维人员既可以选择 `bentoml serve` 本地启动，也可以使用 `bentoml deploy .` 一键上云。

## 构建配置：bentofile.yaml

`bentofile.yaml` 是 BentoML 标准的构建清单，定义了如何把项目打包成可执行的 Bento 镜像。

| 配置项 | 取值 | 作用 |
|---|---|---|
| `service` | `service:Main` | 入口服务类，指向 `service.py` 中的 `Main` |
| `labels` | `owner: bentoml-team` 等 | 元信息标签，便于检索与分组 |
| `python.requirements_txt` | `./requirements.txt` | Python 依赖源 |
| `python.lock_packages` | `true` | 锁定精确版本以保证可复现构建 |
| `docker.python_version` | `3.11` | 容器内的 Python 版本 |
| `docker.system_packages` | `libsox-dev` | 系统级音频处理库，供 `torchaudio` 使用 |
| `envs` | `CHAT_TTS_REPO=...` | 注入到镜像中的环境变量 |

资料来源：[bentofile.yaml:1-25]()

## 服务运行配置：bento_constants.py 与 service.py

### 服务常量

`bento_constants.py` 通过内嵌 YAML 字符串向 `@bentoml.service` 装饰器提供关键配置：服务名为 `chattts`、流量超时为 300 秒、显式声明 `gpu: 1` 用于推理。这些参数会在 Bento 构建时被读取并写入服务的运行规格。

资料来源：[bento_constants.py:1-9]()

### 部署钩子（on_deployment）

`Main.on_deployment` 是一个静态方法，在部署阶段执行：先读取 `CHAT_TTS_REPO` 环境变量，若未设置则直接 `assert` 失败；随后使用 `dulwich.porcelain.clone` 以 `depth=1` 的浅克隆方式拉取 ChatTTS 仓库到 `ChatTTS/` 目录。运行时该目录会被加入 `sys.path`，从而可以 `import ChatTTS`。

资料来源：[service.py:18-31]()

### 运行时初始化与 API

`Main.__init__` 中调用 `self.chat.load_models(compile=False)` 加载模型。`tts` 端点的默认推理参数为 `temperature=0.3`、`top_P=0.7`、`top_K=20`，并以 `speaker`（十六进制字符串）作为随机种子生成 `rand_spk` 张量。输出为 24 kHz 单声道 WAV 字节流。

资料来源：[service.py:33-78]()

## 部署与运维流程

```mermaid
flowchart TD
    A[克隆 BentoChatTTS 仓库] --> B[设置 CHAT_TTS_REPO 环境变量]
    B --> C{bentoml serve / deploy}
    C --> D[on_deployment: 浅克隆 ChatTTS 源码]
    D --> E[加载预训练模型]
    E --> F[对外暴露 /tts API]
    F --> G[客户端 POST 请求]
    G --> H[返回 WAV 音频字节流]
```

### 本地运行

```bash
export CHAT_TTS_REPO=https://github.com/2noise/ChatTTS.git
bentoml serve
```

默认监听 `http://localhost:3000`，可通过 Swagger UI 调试。

资料来源：[README.md:14-24]()

### 部署到 BentoCloud

```bash
bentoml deploy .
```

需先在 [BentoCloud](https://www.bentoml.com/) 注册并登录。部署过程会沿用 `bentofile.yaml` 中声明的 GPU、`CHAT_TTS_REPO` 与系统包等配置。

资料来源：[README.md:26-35]()

## 依赖与系统要求

`requirements.txt` 锁定了核心推理栈：

- `torch==2.3.0`、`torchaudio`：PyTorch 与音频 IO；
- `transformers==4.41.0`：Hugging Face 模型加载；
- `omegaconf~=2.3.0`、`einops`、`vector_quantize_pytorch`、`vocos`：ChatTTS 模型结构与声码器；
- `nemo-text-processing`、`WeTextProcessing`：文本归一化；
- `dulwich`：在 `on_deployment` 中以纯 Python 方式克隆 Git 仓库，避免对系统 `git` CLI 的依赖。

系统层面需提前安装 `libsox-dev`（用于 `torchaudio.save` 的 WAV 编码），构建镜像时会以 `system_packages` 形式再次安装。

资料来源：[requirements.txt:1-13]()、[bentofile.yaml:15-19]()

## 常见运维注意事项

- 必须设置 `CHAT_TTS_REPO`，否则 `on_deployment` 会因 `assert` 失败而中断；
- `bentofile.yaml` 中 `gpu: 1` 与 300 秒超时意味着部署目标需具备至少一张 GPU，长音频合成可能接近超时；
- `load_models(compile=False)` 关闭了 `torch.compile`，在追求吞吐时可改为 `True`，但首次推理会有较长的编译等待；
- `python.lock_packages: true` 会让 `pip install` 阶段被锁版本替换，发布到生产时建议保留。

## See Also

- [README.md](https://github.com/bentoml/BentoChatTTS/blob/main/README.md) — 快速上手与运行指南
- [BentoML 官方文档](https://docs.bentoml.com/) — 部署与服务化框架参考

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：bentoml/BentoChatTTS

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

## 1. 身份坑 · 仓库名和安装名不一致

- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `bentochattts` 与安装入口 `bentoml` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 复现命令：`pip install bentoml`
- 证据：identity.distribution | https://github.com/bentoml/BentoChatTTS | repo=bentochattts; install=bentoml

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/bentoml/BentoChatTTS | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/bentoml/BentoChatTTS | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/bentoml/BentoChatTTS | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/bentoml/BentoChatTTS | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/bentoml/BentoChatTTS | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/bentoml/BentoChatTTS | release_recency=unknown

<!-- canonical_name: bentoml/BentoChatTTS; human_manual_source: deepwiki_human_wiki -->