# CosyVoice2-Ex-GONGJI

**Repository Path**: jarod_lmn/CosyVoice2-Ex-GONGJI

## Basic Information

- **Project Name**: CosyVoice2-Ex-GONGJI
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-16
- **Last Updated**: 2025-10-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# CosyVoice2-Ex

CosyVoice2 功能扩充（预训练音色/3s极速复刻/自然语言控制/自动识别/音色保存/API），支持 Windows / Linux / MacOS

基于新一代生成式语音大模型，CosyVoice 将文本理解和语音生成技术深度融合，能够精准解析并诠释各种文本内容，将其转化为如同真人发声般的自然语音，带来高度拟人化的自然语音合成体验。

## 项目结构

```
CosyVoice2-Ex/
├── cosyvoice/                    # 核心模型代码
│   ├── bin/                      # 训练和推理脚本
│   ├── cli/                      # 命令行接口
│   ├── dataset/                  # 数据集处理
│   ├── flow/                     # 流式处理模块
│   ├── hifigan/                  # HiFi-GAN 声码器
│   ├── llm/                      # 大语言模型集成
│   ├── tokenizer/                # 分词器
│   ├── transformer/              # Transformer 架构
│   └── utils/                    # 工具函数
├── audios/                       # 示例音频文件
├── voices/                       # 预训练音色模型
├── asset/                        # 静态资源
├── docker/                       # Docker 相关配置
├── examples/                     # 示例和配置
├── runtime/                      # 运行时环境
├── tools/                        # 工具脚本
├── Dockerfile                    # 容器镜像构建文件
├── docker-compose.yml           # Docker Compose 配置
├── deploy.sh                    # Linux/macOS 部署脚本
├── deploy.bat                   # Windows 部署脚本
└── requirements.txt              # Python 依赖
```

## 可用 Docker 镜像

这些镜像可用于共绩算力平台部署：

- **`cosyvoice2-ex:latest`**: 基础镜像，包含完整的 CosyVoice2-Ex 环境
- **`cosyvoice2-ex:gpu`**: GPU 加速版本，支持 CUDA 推理
- **`cosyvoice2-ex:dev`**: 开发版本，包含调试工具

## API 规范

CosyVoice2-Ex 提供完整的 API 接口体系，支持通过编程方式实现语音合成全流程自动化。

### 输入格式

```json
{
  "input": {
    "tts_text": "需要合成的文本内容",
    "mode_checkbox_group": "预训练音色",
    "sft_dropdown": "default",
    "seed": 12345,
    "prompt_wav_upload": "base64_encoded_audio",
    "stream": "false",
    "speed": 1.0
  }
}
```

### 输出格式

```json
{
  "id": "sync-uuid-string",
  "status": "COMPLETED",
  "output": {
    "audio": {
      "filename": "synthesized_audio.wav",
      "type": "base64",
      "data": "iVBORw0KGgoAAAANSUhEUg..."
    }
  },
  "delayTime": 123,
  "executionTime": 4567
}
```

### 参数说明

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| tts_text | String | 是 | 需要合成的文本内容 |
| mode_checkbox_group | String | 是 | 合成模式（预训练音色/3s极速复刻/跨语种复刻） |
| sft_dropdown | String | 否 | 预训练音色名称 |
| seed | Number | 否 | 随机种子，用于控制生成结果的一致性 |
| prompt_wav_upload | String | 否 | Base64 编码的参考音频文件 |
| stream | String | 否 | 是否启用流式生成（"true"/"false"） |
| speed | Number | 否 | 语速控制（默认 1.0） |

## 使用方法

### 在共绩算力上部署

1. **获取 API 密钥**：在共绩算力控制台生成 API 密钥
2. **获取端点 ID**：在弹性部署服务页面找到您的端点 ID

#### 生成语音（同步示例）

向 `/runsync` 端点发送请求（等待完成）。替换 `<api_key>` 和 `<endpoint_id>`：

```bash
curl -X POST \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"input":{"tts_text":"你好世界","mode_checkbox_group":"预训练音色"}}' \
  https://api.gongjiyun.com/v2/<endpoint_id>/runsync
```

您也可以使用 `/run` 端点进行异步作业，然后轮询 `/status` 来查看作业完成情况。

### Python 客户端示例

```python
from gradio_client import Client, file

# 连接到部署的服务
client = Client("https://your-deployment-url.550c.cloud/")

# 生成随机种子
seed = client.predict(api_name="/generate_seed")[0]

# 生成音频
result = client.predict(
    tts_text="这里是需要合成的文本内容",
    mode_checkbox_group="预训练音色",
    sft_dropdown="default",
    seed=seed,
    stream="false",
    api_name="/generate_audio"
)
audio_path = result[0]  # 获取生成音频路径
```

## 本地部署

### Docker 部署（推荐）

**Windows 用户**：
```bash
# 双击运行
deploy.bat
```

**Linux/macOS 用户**：
```bash
# 添加执行权限并运行
chmod +x deploy.sh
./deploy.sh
```

**手动部署**：
```bash
# 构建并启动容器
docker-compose up -d

# 访问服务
# http://localhost:7865
```

### 传统部署

#### Windows

提供有 Windows 可用的一键包，解压后双击打开 `运行-CosyVoice2-Ex.bat` 即可运行

#### Linux & macOS

须通过 conda 环境运行：

```sh
conda create -n cosyvoice -y python=3.10
conda activate cosyvoice
conda install -y -c conda-forge pynini==2.1.5
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host=mirrors.aliyun.com

python webui.py --port 8080 --open
```

## Dockerfile 详解

我们的 Dockerfile 采用多阶段构建，确保镜像的轻量化和安全性：

```dockerfile
# 使用官方 Python 3.10 镜像作为基础镜像
FROM python:3.10-slim

# 设置工作目录
WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    git \
    build-essential \
    curl \
    wget \
    ffmpeg \
    unzip \
    git-lfs \
    sox \
    libsox-dev \
    nvidia-cuda-toolkit \
    && rm -rf /var/lib/apt/lists/*

# 初始化 git-lfs
RUN git lfs install

# 复制项目文件
COPY . /app/

# 安装 Python 依赖
RUN pip install --no-cache-dir -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host=mirrors.aliyun.com

# 安装 conda 和 pynini
RUN wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh \
    && bash miniconda.sh -b -p /opt/conda \
    && rm miniconda.sh

ENV PATH="/opt/conda/bin:$PATH"

RUN conda install -y -c conda-forge pynini==2.1.5

# 创建必要的目录
RUN mkdir -p /app/pretrained_models /app/voices /app/audios

# 设置环境变量
ENV PYTHONPATH=/app
ENV GRADIO_SERVER_NAME=0.0.0.0
ENV GRADIO_SERVER_PORT=7865

# 暴露端口
EXPOSE 7865

# 启动命令
CMD ["python", "webui.py", "--port", "7865", "--server-name", "0.0.0.0"]
```

### 镜像特性

- **多阶段构建**：优化镜像大小
- **GPU 支持**：集成 CUDA 工具包
- **安全配置**：最小化攻击面
- **性能优化**：预安装依赖，减少启动时间

## 配置说明

### 环境变量

| 变量名 | 默认值 | 描述 |
|--------|--------|------|
| PORT | 7865 | 服务端口号 |
| GRADIO_SERVER_NAME | 0.0.0.0 | 服务绑定地址 |
| GRADIO_SERVER_PORT | 7865 | Gradio 服务端口 |
| CUDA_VISIBLE_DEVICES | 0 | 可见 GPU 设备 |

### 资源要求

- **最低配置**：8GB RAM，单卡 GPU
- **推荐配置**：16GB RAM，RTX 4090 或更高
- **存储空间**：至少 20GB 可用空间（包含模型文件）

## 故障排除

### 常见问题

**Q: 服务启动失败**
A: 检查 GPU 驱动是否正确安装，确认容器镜像版本兼容性

**Q: 音频生成质量不佳**
A: 调整 speed 参数，确保参考音频质量，检查文本内容是否包含特殊字符

**Q: API 调用超时**
A: 增加请求超时时间，检查网络连接稳定性

**Q: 内存不足**
A: 减少并发请求数量或升级 GPU 配置

### 性能优化

- 使用 SSD 存储提升 I/O 性能
- 适当调整 batch_size 参数
- 启用 GPU 内存优化选项
- 定期清理临时文件

## 开发指南

### 本地开发环境

```bash
# 克隆仓库
git clone https://github.com/journey-ad/CosyVoice2-Ex.git
cd CosyVoice2-Ex

# 安装依赖
pip install -r requirements.txt

# 启动开发服务器
python webui.py --port 7865 --server-name 0.0.0.0
```

### 贡献指南

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 更新日志

### v2.0.0
- 新增容器化部署支持
- 优化 API 接口性能
- 增强跨语种合成能力
- 改进音色克隆精度

### v1.5.0
- 添加 3s 极速复刻功能
- 支持自然语言控制
- 优化预训练音色质量

## 免责声明

1. 本项目仅用于学习、研究和技术交流目的。使用者必须遵守中华人民共和国相关法律法规，尊重他人知识产权和合法权益。

2. 本项目基于 Apache 2.0 协议开源

3. 关于项目中的音频素材：
   - 项目中包含的示例音频仅用于技术测试和演示目的
   - 音频素材的版权归原作者所有，不适用于本项目遵循的 Apache 2.0 协议
   - 如果您是音频素材的版权所有者且不希望被使用，请联系我们删除

4. 关于 AI 生成语音：
   - 模型生成的语音内容可能存在版权风险
   - 生成的语音可能被用于制作误导性内容
   - 请谨慎使用和传播 AI 生成的语音内容
   - 建议在使用生成的语音内容时注明其 AI 生成的属性

5. 严禁将本项目用于以下用途：
   - 任何违法违规行为
   - 侵犯他人知识产权或其他合法权益
   - 传播不良或有害信息

6. 使用限制：
   - 请勿用于制作违法违规内容
   - 请勿用于制作虚假信息或误导性内容

7. 使用本项目所产生的一切后果由使用者自行承担，项目开发者不承担任何法律责任

8. 如果本项目有任何侵犯您权益的地方，请及时联系我们，我们将立即处理

使用本项目即表示您已阅读并同意以上声明

---

**注意**：本部署方案基于 Apache 2.0 协议开源，使用前请仔细阅读相关免责声明和使用条款。