CleanS2S

英语 | 简体中文

CleanS2S 是一款语音到语音（S2S）原型代理，以单文件实现方式提供高质量、流式交互。该设计简洁明了，旨在打造类似 GPT-4o 风格的中文交互式原型代理。本项目希望让用户直接体验语言用户界面（LUI）的强大功能，并帮助研究人员快速探索和验证 S2S 流水线的潜力。

新增【主观行动判断】功能（详见 backend/README.zh.md），增强了代理在对话中主动发起行动的能力。

以下是 CleanS2S 的一些实时对话演示：

注意：请先打开视频的静音。

大纲

• 大纲
• 特性
• 开始使用
  • 后端（服务器）
  • 前端（客户端）
• 路线图
• 支持与参与
• 致谢
• 引用 CleanS2S
• 许可证

特性

📜 单文件实现

一种代理流水线的所有细节都被整合进一个独立的文件中。无需额外配置依赖或理解复杂的项目结构，因此对于希望快速了解 S2S 流水线并在此基础上直接验证新想法的人来说，这是一个极佳的参考实现。所有流水线组件都易于修改和扩展，用户可以迅速更换自己喜欢的模型（如 LLM）、添加新组件或自定义流水线。

🎮 实时流式交互界面

整个 S2S 流水线主要由 ASR（自动语音识别，即语音转文本）、LLM（大型语言模型）和 TTS（文本转语音）组成，同时包含两个 WebSocket 组件：接收器（内置 VAD）和发送器。该流水线专为实时流式交互设计，使用户能够像与真人对话一样与代理进行实时互动。所有音频和文本信息均通过 WebSocket 流式传输。

为此，我们采用了多线程和队列机制来确保流式处理的顺畅运行，避免阻塞问题。所有组件均为异步非阻塞设计，从输入队列获取数据并将其处理结果放入输出队列。

🧫 全双工交互与打断功能

基于 WebSockets 提供的强大机制，该流水线支持全双工交互，即用户可以在与代理交谈的同时进行发言和聆听。此外，流水线还支持打断功能——用户可在对话中的任何时刻通过新的语音输入打断代理，代理会立即停止当前处理任务，转而根据之前的对话内容及打断信息继续处理新输入。

值得一提的是，我们发现聊天机器人中常见的“助手式”和“轮次式”响应方式是阻碍人机对话自然流畅的主要原因之一。为此，我们为代理增加了更多有趣的策略，以提升对话的互动性和吸引力。

🌍 配备网络搜索和RAG功能

该流程进一步通过集成网络搜索能力和检索增强生成（RAG）模型而得到增强。 这些功能使智能体不仅能够实时处理并响应用户输入，还能访问并整合来自网络的外部信息到其回复中。 这为回答用户提出的各种实际问题提供了扩展性和灵活性。

• WebSearchHelper类负责根据用户查询进行在线搜索，或收集与对话相关的额外信息。这使得智能体能够引用最新或外部数据，从而提升其回复的丰富性和准确性。
• RAG类实现了检索增强生成方法，首先从数据库中检索相关信息，然后利用这些信息生成回复。这一两步流程确保了智能体的回答建立在相关、真实的数据基础上，从而实现更加知情且符合上下文的交互。

输出示例

注意：由于我们的计算资源限制，最大输出标记数被限制在一个较小的规模。

开始使用

后端（服务器）

安装

## 克隆仓库
git clone https://github.com/opendilab/CleanS2S.git
cd CleanS2S/backend
pip install -r requirements.txt

• 按照此处的说明安装 funasr (推荐1.1.6版本)，用于 paraformer-zh。
• 按照此处的说明安装 cosyvoice，用于 CosyVoice-300M。

下载模型

你需要下载4个必要的模型（3个ASR + 1个TTS），可以从以下链接下载，并将其放置在你自己的合适目录中。

• ASR: paraformer-zh, ct-punc, fsmn-vad
• TTS: CosyVoice-300M

对于LLM，默认使用LLM API，你也可以按照下面的说明自定义你本地的LLM模型（如DeepSeek-V2.5、Qwen2.5等）。

删除 --enable_llm_api 和 --lm_model_url 参数，并将 --lm_model_name 参数修改为你本地LLM模型的路径（例如：--lm_model_name /home/users/deepseek-v2.5）。

你还需要准备一个参考音频目录，其中包含用于韵律和音色迁移的参考音频。我们在这个仓库中提供了一个示例参考音频目录。 如果你想要使用自己的参考音频，需要保持与示例参考音频目录相同的格式。音频长度应在10~20秒之间，且发音清晰。

运行服务器

以下是使用默认设置运行服务器的示例：

export LLM_API_KEY=<your-deepseek-api-key>
python3 -u s2s_server_pipeline.py \
        --recv_host 0.0.0.0 \
        --send_host 0.0.0.0 \
        --stt_model_name <your-asr-path> \
        --enable_llm_api \
        --lm_model_name "deepseek-chat" \
        --lm_model_url "https://api.deepseek.com" \
        --tts_model_name <your-tts-path> \
        --ref_dir <ref-audio-path> \
        --enable_interruption

ℹ️ 支持自定义LLM：这里我们默认使用 deepseek-chat 作为LLM API，你也可以根据 OpenAI 接口更换为其他LLM API。（修改 --lm_model_name 和 --lm_model_url，并设置你自己的API密钥）

ℹ️ 支持 MiniMax：MiniMax 提供兼容 OpenAI 的 API，并支持长上下文模型。设置 MINIMAX_API_KEY（或 LLM_API_KEY）后，可以使用以下示例：

export MINIMAX_API_KEY=<your-minimax-api-key>
python3 -u s2s_server_pipeline.py \
        --recv_host 0.0.0.0 \
        --send_host 0.0.0.0 \
        --stt_model_name <your-asr-path> \
        --enable_llm_api \
        --lm_model_name "MiniMax-M2.7" \
        --lm_model_url "https://api.minimax.io/v1" \
        --tts_model_name <your-tts-path> \
        --ref_dir <ref-audio-path> \
        --enable_interruption

支持的模型：MiniMax-M2.7（204K上下文）、MiniMax-M2.7-highspeed（204K上下文，速度更快）。

ℹ️ 支持其他自定义：你可以参考后端管道文件（如 s2s_server_pipeline.py）中由 argparse 库实现的参数列表，根据自己的需求进行自定义。所有参数都在其帮助属性中进行了详细说明，易于理解。

pip install -r backend/requirements-rag.txt

git lfs install
git clone https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2

export LLM_API_KEY=''
export SERPER_API_KEY=''

python3 -u s2s_server_pipeline_rag.py \
        --recv_host 0.0.0.0 \
        --send_host 0.0.0.0 \
        --stt_model_name <your-asr-path> \
        --enable_llm_api \
        --lm_model_name "deepseek-chat" \
        --lm_model_url "https://api.deepseek.com" \
        --tts_model_name <your-tts-path> \
        --embedding_model_name <embedding-model-path> \
        --ref_dir <ref-audio-path> \
        --enable_interruption

前端（客户端）

我们建议使用 Docker镜像 来安装和运行客户端。具体步骤如下：

## 运行基础 Docker 镜像
docker run -it -p 3001:3001 amazonlinux:2023.2.20231011.0 sh

## 安装必要的软件包
dnf install vim git nodejs -y
npm install -g pnpm
git clone https://github.com/opendilab/CleanS2S.git
cd CleanS2S/frontend_nextjs
pnpm install

在 frontend_nextjs 目录下准备好合适的 .env.local 文件，可以参考 .env.example 文件来设置必要的环境变量。

## 运行客户端
pnpm dev --port 3001

然后你可以在浏览器中访问客户端页面 http://localhost:3001（推荐使用Chrome浏览器）。

附注：如果你想在本地运行客户端，需要先安装 node.js 和 pnpm，然后使用 pnpm 安装必要的软件包并运行客户端。

路线图

• 语音转换管道（ASR + TTS）（即 backend/vc_server_pipeline.py）
• WebUI优化（支持更多样化的交互和功能）
• 推理速度优化
• 后端多用户支持
• 对话中的长期记忆和主动意图机制
• 非文本交互机制，如表情包
• 更多提示词和RAG策略（serper + jina + LightRAG）
• 实际场景中的实用声纹检测机制
• 更多示例和评估工具
• 自定义示例角色
• 更有趣的交互和更具挑战性的机制
• e2e s2s模型训练和部署

支持与参与

我们非常感谢所有的反馈和贡献。欢迎随时提问，也欢迎在Github Issues和PR中提出讨论。

• 在Github上提交问题
• 在CleanS2S的Discord频道讨论
• 在OpenDILab的微信交流群讨论（请添加我们的微信号：ding314assist）

致谢

• 我们感谢 speech-to-speech 首次开源英语语音到语音的流水线。
• 我们感谢 funasr 和 CosyVoice 开源高质量的中文 ASR/TTS 模型。
• 我们感谢 HumeAI 开源了一系列前端组件。

引用 CleanS2S

@misc{lu2025cleans2s
      title={CleanS2S: 用于主动式语音到语音交互的单文件框架}, 
      author={Yudong Lu and Yazhe Niu and Shuai Hu and Haolin Wang},
      year={2025},
      eprint={2506.01268},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2506.01268}, 
}

许可证

CleanS2S 代码库根据 Apache 2.0 许可证发布。

重要的第三方许可证声明：
本项目使用了 jinaai/jina-embeddings-v3 模型，该模型单独依据 知识共享署名-非商业性使用4.0国际许可协议（CC BY-NC 4.0） 授权。

Jina Embeddings 模型的主要限制：

• ✅ 允许：非商业用途及修改
• ❌ 禁止：将该模型用于商业用途
• 📝 要求：必须注明 Jina AI 的贡献

在使用本项目时，您必须：

1. 同时遵守两种许可证的要求
2. 确保对 Jina Embeddings 模型的任何使用均符合 CC BY-NC 4.0 的条款
3. 不得再授权或以商业方式分发 Jina 模型

完整条款请参阅：

• Apache 2.0 许可证
• CC BY-NC 4.0 许可证

CleanS2S 快速上手指南

CleanS2S 是一个单文件实现的语音到语音（S2S）原型智能体，支持高质量、低延迟的流式交互。它旨在让开发者快速体验类 GPT-4o 风格的中文语音交互，并验证 S2S 流水线的潜力。

环境准备

系统要求

• 操作系统: Linux (推荐) 或 macOS
• Python: 3.8+
• GPU: 推荐配备 NVIDIA GPU 以加速 ASR 和 TTS 模型推理（可选，但强烈推荐）

前置依赖

在开始之前，请确保已安装以下基础工具：

• git
• pip
• ffmpeg (用于音频处理)
• git-lfs (用于下载大模型文件)

# Ubuntu/Debian 示例
sudo apt-get update
sudo apt-get install -y git ffmpeg git-lfs
git lfs install

安装步骤

1. 克隆项目

git clone https://github.com/opendilab/CleanS2S.git
cd CleanS2S/backend

2. 安装 Python 依赖

pip install -r requirements.txt

3. 安装核心语音模型依赖

本项目依赖 FunASR (语音识别) 和 CosyVoice (语音合成)。请按以下官方指引安装：

• 安装 FunASR (推荐版本 1.1.6): 参考 FunASR 安装文档

• 安装 CosyVoice: 参考 CosyVoice 安装文档

国内加速提示: 如果访问 GitHub 或 HuggingFace 较慢，建议使用镜像源或配置代理。下载模型时可尝试使用 HuggingFace 镜像（如 hf-mirror.com）。

4. 下载必要模型

你需要下载 3 个 ASR 模型和 1 个 TTS 模型。建议将模型下载到本地指定目录。

参考音频准备: 项目自带示例参考音频目录 (backend/ref_audio)。若需自定义音色，请准备时长 10~20 秒、发音清晰的音频文件，格式需与示例目录一致。

基本使用

1. 配置 API Key

默认使用 DeepSeek 作为大语言模型（LLM），也可替换为 MiniMax 或其他兼容 OpenAI 接口的模型。

export LLM_API_KEY=<your-deepseek-api-key>

若使用 MiniMax:

export MINIMAX_API_KEY=<your-minimax-api-key>

2. 启动服务端

以下命令以 DeepSeek 为例启动服务。请替换 <your-asr-path>、<your-tts-path> 和 <ref-audio-path> 为你本地的实际路径。

python3 -u s2s_server_pipeline.py \
        --recv_host 0.0.0.0 \
        --send_host 0.0.0.0 \
        --stt_model_name <your-asr-path> \
        --enable_llm_api \
        --lm_model_name "deepseek-chat" \
        --lm_model_url "https://api.deepseek.com" \
        --tts_model_name <your-tts-path> \
        --ref_dir <ref-audio-path> \
        --enable_interruption

参数说明：

• --stt_model_name: ASR 模型路径（包含 paraformer-zh 等）。
• --tts_model_name: TTS 模型路径（CosyVoice-300M）。
• --ref_dir: 参考音频目录路径。
• --enable_interruption: 启用打断功能，支持全双工交互。
• --lm_model_name / --lm_model_url: 指定 LLM 模型名称和 API 地址。

注: 若需使用本地部署的 LLM（如 Qwen2.5, DeepSeek-V2.5 本地版），请移除 --enable_llm_api 和 --lm_model_url 参数，并将 --lm_model_name 改为本地模型路径。

3. 连接客户端

服务端启动后，前端客户端可通过 WebSocket 连接到 ws://<服务器 IP>:<端口> 进行语音交互。具体前端代码请参考项目中的 frontend 目录或自行开发 WebSocket 客户端。

如需启用联网搜索和 RAG 功能，请先安装 backend/requirements-rag.txt，配置 SERPER_API_KEY，并使用 s2s_server_pipeline_rag.py 脚本启动服务。