[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"tool-opendilab--CleanS2S":3,"similar-opendilab--CleanS2S":117},{"id":4,"github_repo":5,"name":6,"description_en":7,"description_zh":8,"ai_summary_zh":8,"readme_en":9,"readme_zh":10,"quickstart_zh":11,"use_case_zh":12,"hero_image_url":13,"owner_login":14,"owner_name":15,"owner_avatar_url":16,"owner_bio":17,"owner_company":18,"owner_location":18,"owner_email":19,"owner_twitter":15,"owner_website":18,"owner_url":20,"languages":21,"stars":38,"forks":39,"last_commit_at":40,"license":41,"difficulty_score":42,"env_os":43,"env_gpu":44,"env_ram":45,"env_deps":46,"category_tags":56,"github_topics":62,"view_count":71,"oss_zip_url":18,"oss_zip_packed_at":18,"status":72,"created_at":73,"updated_at":74,"faqs":75,"releases":116},6392,"opendilab\u002FCleanS2S","CleanS2S","High-quality and streaming Speech-to-Speech interactive agent in a single file.  只用一个文件实现的流式全双工语音交互原型智能体！","CleanS2S 是一个仅需单个文件即可运行的高质量、流式语音对语音（Speech-to-Speech）交互智能体原型。它旨在模拟类似 GPT-4o 的自然对话体验，让用户能直接感受语言用户界面（LUI）的魅力，并帮助研究者快速验证语音交互流水线的潜力。\n\n传统语音交互系统往往架构复杂、配置繁琐且难以实时响应。CleanS2S 通过极简的单文件设计解决了这一痛点，将自动语音识别（ASR）、大语言模型（LLM）和语音合成（TTS）完整集成，无需复杂的环境配置即可启动。其核心技术亮点在于实现了真正的全双工实时流式交互：基于 WebSocket 和多线程机制，用户不仅可以与智能体像真人一样自然对话，还能在智能体播报过程中随时打断并插入新指令，系统会立即响应。\n\n这款工具非常适合希望快速探索 S2S 技术的研究人员、想要低成本验证新想法的开发者，以及需要参考实现来构建自定义语音应用的技术团队。由于代码结构清晰且易于修改，用户也可以轻松替换其中的大模型组件或添加新功能。无论是用于学术实验还是原型开发，CleanS2S 都提供了一个干净、高效且功能强大的起点。","# CleanS2S\n\nEnglish | [简体中文(Simplified Chinese)](https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S\u002Fblob\u002Fmain\u002FREADME.zh.md) \n\n**CleanS2S** is a Speech-to-Speech (**S2S**) prototype agent that provides high-quality and streaming interactions in the single-file implementation. This design is simple and clean, aiming to provide a \nChinese interactive prototype agent like the GPT-4o style. This project wants to let users directly experience the power of Linguistic User Interface (**LUI**) and quickly explore\u002Fvailidate the potential of the S2S pipeline for researchers.\n\nAdd [Subjective Action Judgement](https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S\u002Fblob\u002Fmain\u002Fbackend\u002FREADME.zh.md), enhanced the agent's ability to proactively initiate actions during conversations.\n\nHere are some live conversation demos of CleanS2S:\n\n> Note: please unmute the video first.\n\n\n\u003Ctable>\n\u003Ctr>\n\u003Ctd align=\"center\">\n\n**投资话题1**\n\n\u003C\u002Ftd>\n\u003Ctd align=\"center\">\n\n**投资话题2**\n\n\u003C\u002Ftd>\n\u003Ctd align=\"center\">\n\n**心情话题**\n\n\u003C\u002Ftd>\n\u003Ctd align=\"center\">\n\n**高考志愿话题**\n\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd align=\"center\">\n\n[投资话题1](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F65333528-b07c-42ab-9cb5-660b68b404c4)\n\n\u003C\u002Ftd>\n\u003Ctd align=\"center\">\n\n[投资话题2](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Ff6ee3bad-ddd0-404f-9995-088ac1902b11)\n\n\u003C\u002Ftd>\n\u003Ctd align=\"center\">\n\n[心情话题](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F40d20126-9c6b-45db-8ee9-ce768fee5b3f)\n\n\u003C\u002Ftd>\n\u003Ctd align=\"center\">\n\n[高考志愿话题](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fe86c1cad-ca49-4145-8c22-8d9de59f44b4)\n\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftable>\n\n\n\u003Cbr>\n\u003Cdetails>\n\u003Csummary>\u003Cstrong style=\"font-size: 1.5em;\">More Conversation Demos\u003C\u002Fstrong>\u003C\u002Fsummary>\n\u003Cbr>\n\n\u003Ctable>\n\u003Ctr>\n\u003Ctd align=\"center\">\n\n**胃病话题**\n\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd align=\"center\">\n\n[胃药话题](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F84d27040-52b5-478e-8796-48ea7f468dc9)\n\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftable>\n\n\u003C\u002Fdetails>\n\n\n## Outline\n\n- [Outline](#outline)\n- [Features](#features)\n- [Get Started](#get-started)\n  - [Backend (Server)](#backend-server)\n  - [Frontend (Client)](#frontend-client)\n- [Roadmap](#roadmap)\n- [Support and Get Involved](#support-and-get-involved)\n- [Acknowledgements](#acknowledgements)\n- [Citing CleanS2S](#citing-cleans2s)\n- [License](#license)\n\n\n## Features\n\n### 📜 Single-file implementation\n\nEvery detail about a kind of agent pipeline is put into a single standalone file. There is no extra burden to configure the dependencies and understand the project file structure.\nSo it is a great reference implementation to read for folks who want to quickly have a glance at the S2S pipeline and directly vailidate novel ideas on top of it.\nAll the pipeline implementations are easy to modify and extend, and the user can quickly change the model (e.g. LLM) they like, add new components, or customize the pipeline.\n\n### 🎮 Real-time streaming interface\n\n![](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fopendilab_CleanS2S_readme_6dc4c45ae690.png)\n\nThe whole S2S pipeline is mainly composed of `ASR` (Automatic Speech Recognition, or named Speech to Text), `LLM` (Large Language Model), and `TTS` (Text to Speech), together with two `WebSockets` components Receiver (contains VAD) and Sender.\nThe pipeline is designed to be real-time streaming, which means the user can interact with the agent in real-time like a human-to-human conversation. All the audio and text information is streamed sent and received through the WebSocket.\nTo achieve this, we utilize multi-threading and queueing mechanisms to ensure the streaming process and avoid the blocking issue. All the components are designed to be asynchronous and non-blocking, processing the data from input queue and output result into another queue.\n\n### 🧫 Full-duplex interaction with interruptions\n\nBased on the powerful mechanisms provided by [WebSockets](https:\u002F\u002Fwebsockets.readthedocs.io\u002Fen\u002Fstable\u002F), the pipeline supports full-duplex interaction, which means the user can speak and listen to the agent at the same time.\nFurthermore, the pipeline supports interruptions, which means the user can interrupt the agent at any time during the conversation with a new sppech input. The agent will stop current processing and start to process the new input with the context of the previous conversations and interruptions.\nBesides, we find the \"assistant-style\" and \"turned-based\" response usually used in chatbot is one of the most important drawbacks for human-like conversation. We add more interesting strategies for the agent to make the conversation more interactive and engaging. \n\n### 🌍 Complemented with Web Search and RAG\n\nThe pipeline is further enhanced by the integration of web search capabilities and the Retrieval-Augmented Generation (RAG) model. \nThese features provide the agent with the ability to not only process and respond to user inputs in real-time but also to access and incorporate external information from the web into its responses. \nThis provides room for expansion and agility in answering various practical questions raised by users.\n  - The WebSearchHelper class is responsible for conducting online searches based on user queries or to gather additional information relevant to the conversation. This allows the agent to reference up-to-date or external data, enhancing the richness and accuracy of its responses.\n  - The RAG class implements a retrieval-augmented generation approach, which first retrieves relevant information from a database and then uses that information to generate responses. This two-step process ensures that the agent's replies are grounded in relevant, factual data, leading to more informed and contextually appropriate interactions.\n\n#### output examples\n> Note: Due to our computing resource limitations, the maximum token output is limited to a small size.\n\u003Ctable>\n  \u003Ctr>\n    \u003Cth>Case\u003C\u002Fth>\n    \u003Ctd>\n      \u003Cstrong>LanguageModelHandler\u003C\u002Fstrong>\u003Cbr>\n      \u003Cspan style=\"color: grey; font-size: smaller;\">\u003C\u002Fspan>\n    \u003C\u002Ftd>\n    \u003Ctd>\n      \u003Cstrong>RAGLanguageModelHelper\u003C\u002Fstrong>\u003Cbr>\n      \u003Cspan style=\"color: grey; font-size: smaller;\">\u003C\u002Fspan>\n    \u003C\u002Ftd>\n  \u003C\u002Ftr>\n  \u003Ctr>\n    \u003Ctd>1\u003C\u002Ftd>\n    \u003Ctd>芭比波朗虫草粉底液产品口播文案\\n\\n大家好，我是你们的美妆达人小美，今天我要向大家介绍一款我最近发现的宝藏产品——芭比波朗虫草粉底液。首先，让我们来看看这款粉底液的\n产品特性。它采用三重持色科技，能够均匀分散，贴肤不结块，让你的妆容持久不暗沉。同时，它还拥有面霜级的质地，特别适合干性肌肤使用，能够提供长时间的滋润和保湿效果，使肌肤在上妆的同时得到滋养。其次，>让我们来看看这款粉底液是如何满足用户需求的。它含有37种护肤精粹，包括冬虫夏草与人参提取物，这些成分能够激发肌肤能量，提供抗老效果，同时积雪草与圣保罗草有助于紧致肌肤。此外，它还含有透明质酸与稻米>提取物，确保了粉底液的高保湿效果，使用后肌肤不会感到干燥紧绷。\n    \u003Ctd>天啊，我太恨芭比布朗了，为什么这么晚才让我知道还有这么好用的产品！芭比布朗，你不营销你的虫草粉底液你糊涂啊！\\n\\n你知道吗。我之前用的那些粉底液，不是卡粉就>是脱妆，冬天用还特别干，简直让人抓狂。直到我遇到了芭比波朗的虫草粉底液，我的天，简直是干皮救星！它的质地就像面霜一样，滋润得不得了，上妆后皮肤感觉水润润的，完全没有紧绷感。而且，它的粉质超级细腻>，用三重持色科技，上妆后均匀分散，贴肤不结块，简直就是自然无瑕的代名词。更别提\u003C\u002Ftd>\n  \u003C\u002Ftr>\n  \u003Ctr>\n    \u003Ctd>2\u003C\u002Ftd>\n    \u003Ctd>MAC无暇粉底液二代\\n\\n## 产品特性\\n\\nMAC无暇粉底液二代是一款专为油皮星姐妹打造的粉底液。它具有以下特点：\\n\\n- 持久控油：能够24小时持妆，即使到了晚上也能保持妆容>不花。- 全新科技：采用PRO流体黑科技，使得粉底液能够均匀覆盖肤色，同时保持轻薄服帖。- 不脱妆：妆效持久，不卡粉、不斑驳，不拔干，适合长时间保持完美妆容。- 控油成分：含有糖海带精粹，有助于控油，使油\n性皮肤能够全天保持雾面效果。- 高遮瑕力：能够有效遮盖痘痘、痘坑和毛孔，提供高遮瑕效果，即使近距离观察也不怕。- 养肤成分：含有80%的养肤精粹，成分温和，有助于抵抗外界刺激，同时长效平衡水油。- 专为亚洲肌肤定制：提供三大明星色号，适合亚洲人的肤色，更容易找到匹配自己肤色的粉底液。## 用户需求对接\\n\\n油皮星姐妹常常苦恼于粉底液经常脱妆，容易氧化，假白等问题。而MAC无暇粉底液二代正是为了解决这些问>题而生。它能够持久控油，不脱妆，不卡粉，不斑驳，不拔干，适合爱夜生活的晚8人们。同时，它还能够遮盖痘痘、痘坑和毛孔，提供高遮瑕效果，让油皮姐妹们在任何场合都能保持完美妆容。\n    \u003Ctd>嘿，油皮姐妹们，是不是常常为脱妆、氧化、假白这些问题烦恼。别担心，MAC无暇粉底液二代来拯救你们啦！这款粉底液简直就是油皮的救星，24小时持妆，晚8点出门也不怕>花妆，整夜都能保持无暇状态。全新PRO流体黑科技，让你的肤色匀净，轻薄服帖，妆效持久不卡粉、不斑驳，不拔干。更厉害的是，它含有糖海带精粹，一抹就能控油，大油皮全天都能保持雾面效果。痘痘、痘坑、毛孔统\n统不在话下，高遮瑕力让你不怕怼脸看。而且，80%的养肤精粹\u003C\u002Ftd>\n  \u003C\u002Ftr>\n\n\u003C\u002Ftable>\n\n\n## Get started\n\n### Backend (Server)\n\n#### Installation\n```bash\n## clone the repository\ngit clone https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S.git\ncd CleanS2S\u002Fbackend\npip install -r requirements.txt\n```\n\n- Install `funasr (1.1.6 recommended)` for paraformer-zh according to the instructions [here](https:\u002F\u002Fgithub.com\u002Fmodelscope\u002FFunASR?tab=readme-ov-file#installation)\n- Install `cosyvoice` for CosyVoice-300M according to the instructions [here](https:\u002F\u002Fgithub.com\u002FFunAudioLLM\u002FCosyVoice?tab=readme-ov-file#install)\n\n#### Downloading models\nHere are 4 necessary models you need to download (3 ASR + 1 TTS), you can download them from the following links and put them in your own proper directory.\n- ASR: [paraformer-zh](https:\u002F\u002Fhuggingface.co\u002Ffunasr\u002Fparaformer-zh), [ct-punc](https:\u002F\u002Fhuggingface.co\u002Ffunasr\u002Fct-punc), [fsmn-vad](https:\u002F\u002Fhuggingface.co\u002Ffunasr\u002Ffsmn-vad)\n- TTS: [CosyVoice-300M](https:\u002F\u002Fgithub.com\u002FFunAudioLLM\u002FCosyVoice?tab=readme-ov-file#install)\n\nFor LLM, we use LLM API by default, you can also follow the instructions below to customize your own local LLM (such as DeepSeek-V2.5, Qwen2.5, etc.).\n\n> delete the `--enable_llm_api` and `--lm_model_url` parameters, and modify the `--lm_model_name` parameter to your local LLM model path (e.g., `--lm_model_name \u002Fhome\u002Fusers\u002Fdeepseek-v2.5`).\n\nYou also need to prepare a reference audio directory, which contains the reference audios for the prosody and timbre transfer. Here we prepare a [sample reference audio directory](https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S\u002Ftree\u002Fmain\u002Fbackend\u002Fref_audio) in this repository.\nIf you want to use your own reference audio, you need to keep it in the same format as the sample reference audio directory. And the audio should be 10~20 seconds long with clear pronunciation.\n\n\n#### Running the server\n\nHere is an example of running the server with the default settings:\n```bash\nexport LLM_API_KEY=\u003Cyour-deepseek-api-key>\npython3 -u s2s_server_pipeline.py \\\n        --recv_host 0.0.0.0 \\\n        --send_host 0.0.0.0 \\\n        --stt_model_name \u003Cyour-asr-path> \\\n        --enable_llm_api \\\n        --lm_model_name \"deepseek-chat\" \\\n        --lm_model_url \"https:\u002F\u002Fapi.deepseek.com\" \\\n        --tts_model_name \u003Cyour-tts-path> \\\n        --ref_dir \u003Cref-audio-path> \\\n        --enable_interruption\n```\n> ℹ️ **Support for customized LLM**: Here we use deepseek-chat as the default LLM API, you can also change to other LLM API follow the OpenAI interface. (modify the `--lm_model_name` and `--lm_model_url`, set your own API key)\n\n> ℹ️ **Support for MiniMax**: [MiniMax](https:\u002F\u002Fwww.minimaxi.com) provides an OpenAI-compatible API with long-context models. Set `MINIMAX_API_KEY` (or `LLM_API_KEY`) and use the example below:\n> ```bash\n> export MINIMAX_API_KEY=\u003Cyour-minimax-api-key>\n> python3 -u s2s_server_pipeline.py \\\n>         --recv_host 0.0.0.0 \\\n>         --send_host 0.0.0.0 \\\n>         --stt_model_name \u003Cyour-asr-path> \\\n>         --enable_llm_api \\\n>         --lm_model_name \"MiniMax-M2.7\" \\\n>         --lm_model_url \"https:\u002F\u002Fapi.minimax.io\u002Fv1\" \\\n>         --tts_model_name \u003Cyour-tts-path> \\\n>         --ref_dir \u003Cref-audio-path> \\\n>         --enable_interruption\n> ```\n> Supported models: `MiniMax-M2.7` (204K context), `MiniMax-M2.7-highspeed` (204K context, faster).\n\n> ℹ️ **Support for other customizations**: You can refer to the parameters list implemented by the `argparse` library in the backend pipeline file (e.g. `s2s_server_pipeline.py`) to customize it according to your own needs.\nAll the parameters are well-documented in their help attributes and easy to understand.\n\n\u003Cbr>\n\u003Cdetails>\n\u003Csummary>\u003Cstrong style=\"font-size: 1.5em;\">Running the server w\u002F Websearch+RAG\u003C\u002Fstrong>\u003C\u002Fsummary>\n\u003Cbr>\n  \nYou should install the dependencies which Websearch and RAG needed first.\n  \n```bash\npip install -r backend\u002Frequirements-rag.txt\n```\n\nSecond, choose an embedding model for embedding websearch result in RAG.\nlike the followinging embedding model:\n\n```bash\ngit lfs install\ngit clone https:\u002F\u002Fhuggingface.co\u002Fsentence-transformers\u002Fall-MiniLM-L6-v2\n```\n\nThen, provide tokens for Websearch and RAG module, in `s2s_server_pipeline_rag.py` we use [Serper](https:\u002F\u002Fserper.dev) as Websearch tool and [Deepseek](https:\u002F\u002Fdeepseek.com) for RAG.\n\n```bash\nexport LLM_API_KEY=''\nexport SERPER_API_KEY=''\n```\n\nFinally, replace `s2s_server_pipeline.py` with `s2s_server_pipeline_rag.py` in the example code given in running the server. and add an arguments `--embedding_model_name`.\n\nHere is an example of running the server with the default settings with Webseach+RAG:\n\n```bash\npython3 -u s2s_server_pipeline_rag.py \\\n        --recv_host 0.0.0.0 \\\n        --send_host 0.0.0.0 \\\n        --stt_model_name \u003Cyour-asr-path> \\\n        --enable_llm_api \\\n        --lm_model_name \"deepseek-chat\" \\\n        --lm_model_url \"https:\u002F\u002Fapi.deepseek.com\" \\\n        --tts_model_name \u003Cyour-tts-path> \\\n        --embedding_model_name \u003Cembedding-model-path> \\\n        --ref_dir \u003Cref-audio-path> \\\n        --enable_interruption\n```\n\u003C\u002Fdetails>\n\n\n### Frontend (Client)\n\nWe recommend using the `Docker image` for install and run the client. Here is the specific steps:\n\n```bash\n## run the basic docker image\ndocker run -it -p 3001:3001 amazonlinux:2023.2.20231011.0 sh\n```\n\n```bash\n## install the necessary packages\ndnf install vim git nodejs -y\nnpm install -g pnpm\ngit clone https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S.git\ncd CleanS2S\u002Ffrontend_nextjs\npnpm install\n```\n\nPrepare the proper `.env.local` file in the `frontend_nextjs` directory, you can refer to the `.env.example` file for the necessary environment variables.\n\n```bash\n## run the client\npnpm dev --port 3001\n```\n\nThen you can visit the client at `http:\u002F\u002Flocalhost:3001` in your browser (Chrome is recommended).\n\nP.S.: If you want to run the client locally, you should install node.js and pnpm first, then use pnmp to install the necessary packages and run the client.\n\n## Roadmap\n- [x] Voice Conversion Pipeline (ASR + TTS) (i.e., backend\u002Fvc_server_pipeline.py)\n- [x] WebUI optimization (support more diverse interactions and functions)\n- [ ] Inference speed optimization\n- [x] Multi-user support for backend\n- [x] Long-term memory and proactive intent mechanism in dialogue\n- [x] Non-textual interaction mechanisms such as emoji packs\n- [x] More prompts and RAG strategies (serper + jina + LightRAG)\n- [ ] Practical voiceprint detection mechanism in real scenes\n- [ ] More examples and evaluation utilities\n- [ ] Customized example characters\n- [ ] More interesting interraction and challenging mechanism\n- [ ] e2e s2s model training and deployment\n\n## Support and get involved\n\nWe appreciate all the feedbacks and contributions. Feel free to ask questions. Posting in Github Issues and PRs are also welcome.\n\n- [File an issue](https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S\u002Fissues\u002Fnew\u002Fchoose) on Github\n- Discuss on CleanS2S [discord channel](https:\u002F\u002Fdiscord.gg\u002FdkZS2JF56X)\n- Discuss on OpenDILab's WeChat group (i.e. add us on WeChat: ding314assist)\n\n\n## Acknowledgements\n- We thank [speech-to-speech](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fspeech-to-speech) for first open-sourcing the English speech-to-speech pipeline.\n- We thank [funasr](https:\u002F\u002Fgithub.com\u002Fmodelscope\u002FFunASR) and [CosyVoice](https:\u002F\u002Fgithub.com\u002FFunAudioLLM\u002FCosyVoice) for open-sourcing high-quality Chinese ASR\u002FTTS models.\n- We thank [HumeAI](https:\u002F\u002Fgithub.com\u002FHumeAI) for open-sourcing a series of frontend components.\n\n## Citing CleanS2S\n```latex\n@misc{lu2025cleans2s\n      title={CleanS2S: Single-file Framework for Proactive Speech-to-Speech Interaction}, \n      author={Yudong Lu and Yazhe Niu and Shuai Hu and Haolin Wang},\n      year={2025},\n      eprint={2506.01268},\n      archivePrefix={arXiv},\n      primaryClass={cs.AI},\n      url={https:\u002F\u002Farxiv.org\u002Fabs\u002F2506.01268}, \n}\n```\n\n## License\n\nCleanS2S codebase is released under the Apache 2.0 license.\n\n**Important Third-Party License Notice:**  \nThis project uses the [jinaai\u002Fjina-embeddings-v3](https:\u002F\u002Fhuggingface.co\u002Fjinaai\u002Fjina-embeddings-v3) model which is separately licensed under [Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0)](https:\u002F\u002Fcreativecommons.org\u002Flicenses\u002Fby-nc\u002F4.0\u002F). \n\nKey restrictions for the Jina Embeddings model:\n- ✅ **Allowed**: Non-commercial use and modification\n- ❌ **Prohibited**: Commercial use of the model\n- 📝 **Requirement**: Attribution must be given to Jina AI\n\nWhen using this project, you must:\n1. Comply with both licenses simultaneously\n2. Ensure any use of the Jina Embeddings model follows CC BY-NC 4.0 terms\n3. Not sublicense or commercially redistribute the Jina model\n\nFor full terms:\n- [Apache 2.0 License](LICENSE)\n- [CC BY-NC 4.0 License](https:\u002F\u002Fcreativecommons.org\u002Flicenses\u002Fby-nc\u002F4.0\u002Flegalcode)","# CleanS2S\n\n英语 | [简体中文](https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S\u002Fblob\u002Fmain\u002FREADME.zh.md) \n\n**CleanS2S** 是一款语音到语音（**S2S**）原型代理，以单文件实现方式提供高质量、流式交互。该设计简洁明了，旨在打造类似 GPT-4o 风格的中文交互式原型代理。本项目希望让用户直接体验语言用户界面（**LUI**）的强大功能，并帮助研究人员快速探索和验证 S2S 流水线的潜力。\n\n新增【主观行动判断】功能（详见 [backend\u002FREADME.zh.md](https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S\u002Fblob\u002Fmain\u002Fbackend\u002FREADME.zh.md)），增强了代理在对话中主动发起行动的能力。\n\n以下是 CleanS2S 的一些实时对话演示：\n\n> 注意：请先打开视频的静音。\n\n\u003Ctable>\n\u003Ctr>\n\u003Ctd align=\"center\">\n\n**投资话题1**\n\n\u003C\u002Ftd>\n\u003Ctd align=\"center\">\n\n**投资话题2**\n\n\u003C\u002Ftd>\n\u003Ctd align=\"center\">\n\n**心情话题**\n\n\u003C\u002Ftd>\n\u003Ctd align=\"center\">\n\n**高考志愿话题**\n\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd align=\"center\">\n\n[投资话题1](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F65333528-b07c-42ab-9cb5-660b68b404c4)\n\n\u003C\u002Ftd>\n\u003Ctd align=\"center\">\n\n[投资话题2](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Ff6ee3bad-ddd0-404f-9995-088ac1902b11)\n\n\u003C\u002Ftd>\n\u003Ctd align=\"center\">\n\n[心情话题](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F40d20126-9c6b-45db-8ee9-ce768fee5b3f)\n\n\u003C\u002Ftd>\n\u003Ctd align=\"center\">\n\n[高考志愿话题](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fe86c1cad-ca49-4145-8c22-8d9de59f44b4)\n\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftable>\n\n\n\u003Cbr>\n\u003Cdetails>\n\u003Csummary>\u003Cstrong style=\"font-size: 1.5em;\">更多对话演示\u003C\u002Fstrong>\u003C\u002Fsummary>\n\u003Cbr>\n\n\u003Ctable>\n\u003Ctr>\n\u003Ctd align=\"center\">\n\n**胃病话题**\n\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd align=\"center\">\n\n[胃药话题](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F84d27040-52b5-478e-8796-48ea7f468dc9)\n\n\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftable>\n\n\u003C\u002Fdetails>\n\n\n## 大纲\n\n- [大纲](#outline)\n- [特性](#features)\n- [开始使用](#get-started)\n  - [后端（服务器）](#backend-server)\n  - [前端（客户端）](#frontend-client)\n- [路线图](#roadmap)\n- [支持与参与](#support-and-get-involved)\n- [致谢](#acknowledgements)\n- [引用 CleanS2S](#citing-cleans2s)\n- [许可证](#license)\n\n\n## 特性\n\n### 📜 单文件实现\n\n一种代理流水线的所有细节都被整合进一个独立的文件中。无需额外配置依赖或理解复杂的项目结构，因此对于希望快速了解 S2S 流水线并在此基础上直接验证新想法的人来说，这是一个极佳的参考实现。所有流水线组件都易于修改和扩展，用户可以迅速更换自己喜欢的模型（如 LLM）、添加新组件或自定义流水线。\n\n### 🎮 实时流式交互界面\n\n![](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fopendilab_CleanS2S_readme_6dc4c45ae690.png)\n\n整个 S2S 流水线主要由 `ASR`（自动语音识别，即语音转文本）、`LLM`（大型语言模型）和 `TTS`（文本转语音）组成，同时包含两个 WebSocket 组件：接收器（内置 VAD）和发送器。该流水线专为实时流式交互设计，使用户能够像与真人对话一样与代理进行实时互动。所有音频和文本信息均通过 WebSocket 流式传输。\n\n为此，我们采用了多线程和队列机制来确保流式处理的顺畅运行，避免阻塞问题。所有组件均为异步非阻塞设计，从输入队列获取数据并将其处理结果放入输出队列。\n\n### 🧫 全双工交互与打断功能\n\n基于 [WebSockets](https:\u002F\u002Fwebsockets.readthedocs.io\u002Fen\u002Fstable\u002F) 提供的强大机制，该流水线支持全双工交互，即用户可以在与代理交谈的同时进行发言和聆听。此外，流水线还支持打断功能——用户可在对话中的任何时刻通过新的语音输入打断代理，代理会立即停止当前处理任务，转而根据之前的对话内容及打断信息继续处理新输入。\n\n值得一提的是，我们发现聊天机器人中常见的“助手式”和“轮次式”响应方式是阻碍人机对话自然流畅的主要原因之一。为此，我们为代理增加了更多有趣的策略，以提升对话的互动性和吸引力。\n\n### 🌍 配备网络搜索和RAG功能\n\n该流程进一步通过集成网络搜索能力和检索增强生成（RAG）模型而得到增强。\n这些功能使智能体不仅能够实时处理并响应用户输入，还能访问并整合来自网络的外部信息到其回复中。\n这为回答用户提出的各种实际问题提供了扩展性和灵活性。\n  - WebSearchHelper类负责根据用户查询进行在线搜索，或收集与对话相关的额外信息。这使得智能体能够引用最新或外部数据，从而提升其回复的丰富性和准确性。\n  - RAG类实现了检索增强生成方法，首先从数据库中检索相关信息，然后利用这些信息生成回复。这一两步流程确保了智能体的回答建立在相关、真实的数据基础上，从而实现更加知情且符合上下文的交互。\n\n#### 输出示例\n> 注意：由于我们的计算资源限制，最大输出标记数被限制在一个较小的规模。\n\u003Ctable>\n  \u003Ctr>\n    \u003Cth>案例\u003C\u002Fth>\n    \u003Ctd>\n      \u003Cstrong>语言模型处理器\u003C\u002Fstrong>\u003Cbr>\n      \u003Cspan style=\"color: grey; font-size: smaller;\">\u003C\u002Fspan>\n    \u003C\u002Ftd>\n    \u003Ctd>\n      \u003Cstrong>RAG语言模型助手\u003C\u002Fstrong>\u003Cbr>\n      \u003Cspan style=\"color: grey; font-size: smaller;\">\u003C\u002Fspan>\n    \u003C\u002Ftd>\n  \u003C\u002Ftr>\n  \u003Ctr>\n    \u003Ctd>1\u003C\u002Ftd>\n    \u003Ctd>芭比波朗虫草粉底液产品口播文案\\n\\n大家好，我是你们的美妆达人小美，今天我要向大家介绍一款我最近发现的宝藏产品——芭比波朗虫草粉底液。首先，让我们来看看这款粉底液的\n产品特性。它采用三重持色科技，能够均匀分散，贴肤不结块，让你的妆容持久不暗沉。同时，它还拥有面霜级的质地，特别适合干性肌肤使用，能够提供长时间的滋润和保湿效果，使肌肤在上妆的同时得到滋养。其次，>让我们来看看这款粉底液是如何满足用户需求的。它含有37种护肤精粹，包括冬虫夏草与人参提取物，这些成分能够激发肌肤能量，提供抗老效果，同时积雪草与圣保罗草有助于紧致肌肤。此外，它还含有透明质酸与稻米>提取物，确保了粉底液的高保湿效果，使用后肌肤不会感到干燥紧绷。\n    \u003Ctd>天啊，我太恨芭比布朗了，为什么这么晚才让我知道还有这么好用的产品！芭比布朗，你不营销你的虫草粉底液你糊涂啊！\\n\\n你知道吗。我之前用的那些粉底液，不是卡粉就>是脱妆，冬天用还特别干，简直让人抓狂。直到我遇到了芭比波朗的虫草粉底液，我的天，简直是干皮救星！它的质地就像面霜一样，滋润得不得了，上妆后皮肤感觉水润润的，完全没有紧绷感。而且，它的粉质超级细腻>，用三重持色科技，上妆后均匀分散，贴肤不结块，简直就是自然无瑕的代名词。更别提\u003C\u002Ftd>\n  \u003C\u002Ftr>\n  \u003Ctr>\n    \u003Ctd>2\u003C\u002Ftd>\n    \u003Ctd>MAC无暇粉底液二代\\n\\n## 产品特性\\n\\nMAC无暇粉底液二代是一款专为油皮星姐妹打造的粉底液。它具有以下特点：\\n\\n- 持久控油：能够24小时持妆，即使到了晚上也能保持妆容>不花。- 全新科技：采用PRO流体黑科技，使得粉底液能够均匀覆盖肤色，同时保持轻薄服帖。- 不脱妆：妆效持久，不卡粉、不斑驳、不拔干，适合长时间保持完美妆容。- 控油成分：含有糖海带精粹，有助于控油，使油\n性皮肤能够全天保持雾面效果。- 高遮瑕力：能够有效遮盖痘痘、痘坑和毛孔，提供高遮瑕效果，即使近距离观察也不怕。- 养肤成分：含有80%的养肤精粹，成分温和，有助于抵抗外界刺激，同时长效平衡水油。- 专为亚洲肌肤定制：提供三大明星色号，适合亚洲人的肤色，更容易找到匹配自己肤色的粉底液。## 用户需求对接\\n\\n油皮星姐妹常常苦恼于粉底液经常脱妆，容易氧化，假白等问题。而MAC无暇粉底液二代正是为了解决这些问>题而生。它能够持久控油，不脱妆，不卡粉，不斑驳，不拔干，适合爱夜生活的晚8人们。同时，它还能够遮盖痘痘、痘坑和毛孔，提供高遮瑕效果，让油皮姐妹们在任何场合都能保持完美妆容。\n    \u003Ctd>嘿，油皮姐妹们，是不是常常为脱妆、氧化、假白这些问题烦恼。别担心，MAC无暇粉底液二代来拯救你们啦！这款粉底液简直就是油皮的救星，24小时持妆，晚8点出门也不怕>花妆，整夜都能保持无暇状态。全新PRO流体黑科技，让你的肤色匀净，轻薄服帖，妆效持久不卡粉、不斑驳、不拔干。更厉害的是，它含有糖海带精粹，一抹就能控油，大油皮全天都能保持雾面效果。痘痘、痘坑、毛孔统\n统不在话下，高遮瑕力让你不怕怼脸看。而且，80%的养肤精粹\u003C\u002Ftd>\n  \u003C\u002Ftr>\n\n\u003C\u002Ftable>\n\n\n## 开始使用\n\n### 后端（服务器）\n\n#### 安装\n```bash\n\n## 克隆仓库\ngit clone https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S.git\ncd CleanS2S\u002Fbackend\npip install -r requirements.txt\n```\n\n- 按照[此处](https:\u002F\u002Fgithub.com\u002Fmodelscope\u002FFunASR?tab=readme-ov-file#installation)的说明安装 `funasr (推荐1.1.6版本)`，用于 paraformer-zh。\n- 按照[此处](https:\u002F\u002Fgithub.com\u002FFunAudioLLM\u002FCosyVoice?tab=readme-ov-file#install)的说明安装 `cosyvoice`，用于 CosyVoice-300M。\n\n#### 下载模型\n你需要下载4个必要的模型（3个ASR + 1个TTS），可以从以下链接下载，并将其放置在你自己的合适目录中。\n- ASR: [paraformer-zh](https:\u002F\u002Fhuggingface.co\u002Ffunasr\u002Fparaformer-zh), [ct-punc](https:\u002F\u002Fhuggingface.co\u002Ffunasr\u002Fct-punc), [fsmn-vad](https:\u002F\u002Fhuggingface.co\u002Ffunasr\u002Ffsmn-vad)\n- TTS: [CosyVoice-300M](https:\u002F\u002Fgithub.com\u002FFunAudioLLM\u002FCosyVoice?tab=readme-ov-file#install)\n\n对于LLM，默认使用LLM API，你也可以按照下面的说明自定义你本地的LLM模型（如DeepSeek-V2.5、Qwen2.5等）。\n\n> 删除 `--enable_llm_api` 和 `--lm_model_url` 参数，并将 `--lm_model_name` 参数修改为你本地LLM模型的路径（例如：`--lm_model_name \u002Fhome\u002Fusers\u002Fdeepseek-v2.5`）。\n\n你还需要准备一个参考音频目录，其中包含用于韵律和音色迁移的参考音频。我们在这个仓库中提供了一个[示例参考音频目录](https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S\u002Ftree\u002Fmain\u002Fbackend\u002Fref_audio)。\n如果你想要使用自己的参考音频，需要保持与示例参考音频目录相同的格式。音频长度应在10~20秒之间，且发音清晰。\n\n\n#### 运行服务器\n\n以下是使用默认设置运行服务器的示例：\n```bash\nexport LLM_API_KEY=\u003Cyour-deepseek-api-key>\npython3 -u s2s_server_pipeline.py \\\n        --recv_host 0.0.0.0 \\\n        --send_host 0.0.0.0 \\\n        --stt_model_name \u003Cyour-asr-path> \\\n        --enable_llm_api \\\n        --lm_model_name \"deepseek-chat\" \\\n        --lm_model_url \"https:\u002F\u002Fapi.deepseek.com\" \\\n        --tts_model_name \u003Cyour-tts-path> \\\n        --ref_dir \u003Cref-audio-path> \\\n        --enable_interruption\n```\n> ℹ️ **支持自定义LLM**：这里我们默认使用 deepseek-chat 作为LLM API，你也可以根据 OpenAI 接口更换为其他LLM API。（修改 `--lm_model_name` 和 `--lm_model_url`，并设置你自己的API密钥）\n\n> ℹ️ **支持 MiniMax**：[MiniMax](https:\u002F\u002Fwww.minimaxi.com) 提供兼容 OpenAI 的 API，并支持长上下文模型。设置 `MINIMAX_API_KEY`（或 `LLM_API_KEY`）后，可以使用以下示例：\n> ```bash\n> export MINIMAX_API_KEY=\u003Cyour-minimax-api-key>\n> python3 -u s2s_server_pipeline.py \\\n>         --recv_host 0.0.0.0 \\\n>         --send_host 0.0.0.0 \\\n>         --stt_model_name \u003Cyour-asr-path> \\\n>         --enable_llm_api \\\n>         --lm_model_name \"MiniMax-M2.7\" \\\n>         --lm_model_url \"https:\u002F\u002Fapi.minimax.io\u002Fv1\" \\\n>         --tts_model_name \u003Cyour-tts-path> \\\n>         --ref_dir \u003Cref-audio-path> \\\n>         --enable_interruption\n> ```\n> 支持的模型：`MiniMax-M2.7`（204K上下文）、`MiniMax-M2.7-highspeed`（204K上下文，速度更快）。\n\n> ℹ️ **支持其他自定义**：你可以参考后端管道文件（如 `s2s_server_pipeline.py`）中由 `argparse` 库实现的参数列表，根据自己的需求进行自定义。所有参数都在其帮助属性中进行了详细说明，易于理解。\n\n\u003Cbr>\n\u003Cdetails>\n\u003Csummary>\u003Cstrong style=\"font-size: 1.5em;\">运行带有Web搜索+RAG的服务器\u003C\u002Fstrong>\u003C\u002Fsummary>\n\u003Cbr>\n  \n首先，你需要安装 Websearch 和 RAG 所需的依赖项。\n  \n```bash\npip install -r backend\u002Frequirements-rag.txt\n```\n\n其次，选择一个嵌入模型，用于将 Websearch 结果嵌入到 RAG 中。\n例如以下嵌入模型：\n\n```bash\ngit lfs install\ngit clone https:\u002F\u002Fhuggingface.co\u002Fsentence-transformers\u002Fall-MiniLM-L6-v2\n```\n\n然后，在 `s2s_server_pipeline_rag.py` 中为 Websearch 和 RAG 模块提供令牌，我们使用 [Serper](https:\u002F\u002Fserper.dev) 作为 Websearch 工具，使用 [Deepseek](https:\u002F\u002Fdeepseek.com) 作为 RAG。\n\n```bash\nexport LLM_API_KEY=''\nexport SERPER_API_KEY=''\n```\n\n最后，将运行服务器示例代码中的 `s2s_server_pipeline.py` 替换为 `s2s_server_pipeline_rag.py`，并添加一个参数 `--embedding_model_name`。\n\n以下是使用默认设置运行带有 Webseach+RAG 的服务器的示例：\n\n```bash\npython3 -u s2s_server_pipeline_rag.py \\\n        --recv_host 0.0.0.0 \\\n        --send_host 0.0.0.0 \\\n        --stt_model_name \u003Cyour-asr-path> \\\n        --enable_llm_api \\\n        --lm_model_name \"deepseek-chat\" \\\n        --lm_model_url \"https:\u002F\u002Fapi.deepseek.com\" \\\n        --tts_model_name \u003Cyour-tts-path> \\\n        --embedding_model_name \u003Cembedding-model-path> \\\n        --ref_dir \u003Cref-audio-path> \\\n        --enable_interruption\n```\n\u003C\u002Fdetails>\n\n\n### 前端（客户端）\n\n我们建议使用 `Docker镜像` 来安装和运行客户端。具体步骤如下：\n\n```bash\n## 运行基础 Docker 镜像\ndocker run -it -p 3001:3001 amazonlinux:2023.2.20231011.0 sh\n```\n\n```bash\n## 安装必要的软件包\ndnf install vim git nodejs -y\nnpm install -g pnpm\ngit clone https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S.git\ncd CleanS2S\u002Ffrontend_nextjs\npnpm install\n```\n\n在 `frontend_nextjs` 目录下准备好合适的 `.env.local` 文件，可以参考 `.env.example` 文件来设置必要的环境变量。\n\n```bash\n## 运行客户端\npnpm dev --port 3001\n```\n\n然后你可以在浏览器中访问客户端页面 `http:\u002F\u002Flocalhost:3001`（推荐使用Chrome浏览器）。\n\n附注：如果你想在本地运行客户端，需要先安装 node.js 和 pnpm，然后使用 pnpm 安装必要的软件包并运行客户端。\n\n## 路线图\n- [x] 语音转换管道（ASR + TTS）（即 backend\u002Fvc_server_pipeline.py）\n- [x] WebUI优化（支持更多样化的交互和功能）\n- [ ] 推理速度优化\n- [x] 后端多用户支持\n- [x] 对话中的长期记忆和主动意图机制\n- [x] 非文本交互机制，如表情包\n- [x] 更多提示词和RAG策略（serper + jina + LightRAG）\n- [ ] 实际场景中的实用声纹检测机制\n- [ ] 更多示例和评估工具\n- [ ] 自定义示例角色\n- [ ] 更有趣的交互和更具挑战性的机制\n- [ ] e2e s2s模型训练和部署\n\n## 支持与参与\n我们非常感谢所有的反馈和贡献。欢迎随时提问，也欢迎在Github Issues和PR中提出讨论。\n\n- 在Github上[提交问题](https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S\u002Fissues\u002Fnew\u002Fchoose)\n- 在CleanS2S的[Discord频道](https:\u002F\u002Fdiscord.gg\u002FdkZS2JF56X)讨论\n- 在OpenDILab的微信交流群讨论（请添加我们的微信号：ding314assist）\n\n## 致谢\n- 我们感谢 [speech-to-speech](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Fspeech-to-speech) 首次开源英语语音到语音的流水线。\n- 我们感谢 [funasr](https:\u002F\u002Fgithub.com\u002Fmodelscope\u002FFunASR) 和 [CosyVoice](https:\u002F\u002Fgithub.com\u002FFunAudioLLM\u002FCosyVoice) 开源高质量的中文 ASR\u002FTTS 模型。\n- 我们感谢 [HumeAI](https:\u002F\u002Fgithub.com\u002FHumeAI) 开源了一系列前端组件。\n\n## 引用 CleanS2S\n```latex\n@misc{lu2025cleans2s\n      title={CleanS2S: 用于主动式语音到语音交互的单文件框架}, \n      author={Yudong Lu and Yazhe Niu and Shuai Hu and Haolin Wang},\n      year={2025},\n      eprint={2506.01268},\n      archivePrefix={arXiv},\n      primaryClass={cs.AI},\n      url={https:\u002F\u002Farxiv.org\u002Fabs\u002F2506.01268}, \n}\n```\n\n## 许可证\n\nCleanS2S 代码库根据 Apache 2.0 许可证发布。\n\n**重要的第三方许可证声明：**  \n本项目使用了 [jinaai\u002Fjina-embeddings-v3](https:\u002F\u002Fhuggingface.co\u002Fjinaai\u002Fjina-embeddings-v3) 模型，该模型单独依据 [知识共享署名-非商业性使用4.0国际许可协议（CC BY-NC 4.0）](https:\u002F\u002Fcreativecommons.org\u002Flicenses\u002Fby-nc\u002F4.0\u002F) 授权。\n\nJina Embeddings 模型的主要限制：\n- ✅ **允许**：非商业用途及修改\n- ❌ **禁止**：将该模型用于商业用途\n- 📝 **要求**：必须注明 Jina AI 的贡献\n\n在使用本项目时，您必须：\n1. 同时遵守两种许可证的要求\n2. 确保对 Jina Embeddings 模型的任何使用均符合 CC BY-NC 4.0 的条款\n3. 不得再授权或以商业方式分发 Jina 模型\n\n完整条款请参阅：\n- [Apache 2.0 许可证](LICENSE)\n- [CC BY-NC 4.0 许可证](https:\u002F\u002Fcreativecommons.org\u002Flicenses\u002Fby-nc\u002F4.0\u002Flegalcode)","# CleanS2S 快速上手指南\n\nCleanS2S 是一个单文件实现的语音到语音（S2S）原型智能体，支持高质量、低延迟的流式交互。它旨在让开发者快速体验类 GPT-4o 风格的中文语音交互，并验证 S2S 流水线的潜力。\n\n## 环境准备\n\n### 系统要求\n- **操作系统**: Linux (推荐) 或 macOS\n- **Python**: 3.8+\n- **GPU**: 推荐配备 NVIDIA GPU 以加速 ASR 和 TTS 模型推理（可选，但强烈推荐）\n\n### 前置依赖\n在开始之前，请确保已安装以下基础工具：\n- `git`\n- `pip`\n- `ffmpeg` (用于音频处理)\n- `git-lfs` (用于下载大模型文件)\n\n```bash\n# Ubuntu\u002FDebian 示例\nsudo apt-get update\nsudo apt-get install -y git ffmpeg git-lfs\ngit lfs install\n```\n\n## 安装步骤\n\n### 1. 克隆项目\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S.git\ncd CleanS2S\u002Fbackend\n```\n\n### 2. 安装 Python 依赖\n```bash\npip install -r requirements.txt\n```\n\n### 3. 安装核心语音模型依赖\n本项目依赖 `FunASR` (语音识别) 和 `CosyVoice` (语音合成)。请按以下官方指引安装：\n\n- **安装 FunASR** (推荐版本 1.1.6):\n  参考 [FunASR 安装文档](https:\u002F\u002Fgithub.com\u002Fmodelscope\u002FFunASR?tab=readme-ov-file#installation)\n  \n- **安装 CosyVoice**:\n  参考 [CosyVoice 安装文档](https:\u002F\u002Fgithub.com\u002FFunAudioLLM\u002FCosyVoice?tab=readme-ov-file#install)\n\n> **国内加速提示**: 如果访问 GitHub 或 HuggingFace 较慢，建议使用镜像源或配置代理。下载模型时可尝试使用 HuggingFace 镜像（如 `hf-mirror.com`）。\n\n### 4. 下载必要模型\n你需要下载 3 个 ASR 模型和 1 个 TTS 模型。建议将模型下载到本地指定目录。\n\n| 类型 | 模型名称 | 下载地址 |\n| :--- | :--- | :--- |\n| **ASR** | paraformer-zh | [HuggingFace](https:\u002F\u002Fhuggingface.co\u002Ffunasr\u002Fparaformer-zh) |\n| **ASR** | ct-punc | [HuggingFace](https:\u002F\u002Fhuggingface.co\u002Ffunasr\u002Fct-punc) |\n| **ASR** | fsmn-vad | [HuggingFace](https:\u002F\u002Fhuggingface.co\u002Ffunasr\u002Ffsmn-vad) |\n| **TTS** | CosyVoice-300M | [GitHub 指引](https:\u002F\u002Fgithub.com\u002FFunAudioLLM\u002FCosyVoice?tab=readme-ov-file#install) |\n\n**参考音频准备**:\n项目自带示例参考音频目录 (`backend\u002Fref_audio`)。若需自定义音色，请准备时长 10~20 秒、发音清晰的音频文件，格式需与示例目录一致。\n\n## 基本使用\n\n### 1. 配置 API Key\n默认使用 DeepSeek 作为大语言模型（LLM），也可替换为 MiniMax 或其他兼容 OpenAI 接口的模型。\n\n```bash\nexport LLM_API_KEY=\u003Cyour-deepseek-api-key>\n```\n\n*若使用 MiniMax:*\n```bash\nexport MINIMAX_API_KEY=\u003Cyour-minimax-api-key>\n```\n\n### 2. 启动服务端\n以下命令以 DeepSeek 为例启动服务。请替换 `\u003Cyour-asr-path>`、`\u003Cyour-tts-path>` 和 `\u003Cref-audio-path>` 为你本地的实际路径。\n\n```bash\npython3 -u s2s_server_pipeline.py \\\n        --recv_host 0.0.0.0 \\\n        --send_host 0.0.0.0 \\\n        --stt_model_name \u003Cyour-asr-path> \\\n        --enable_llm_api \\\n        --lm_model_name \"deepseek-chat\" \\\n        --lm_model_url \"https:\u002F\u002Fapi.deepseek.com\" \\\n        --tts_model_name \u003Cyour-tts-path> \\\n        --ref_dir \u003Cref-audio-path> \\\n        --enable_interruption\n```\n\n**参数说明：**\n- `--stt_model_name`: ASR 模型路径（包含 paraformer-zh 等）。\n- `--tts_model_name`: TTS 模型路径（CosyVoice-300M）。\n- `--ref_dir`: 参考音频目录路径。\n- `--enable_interruption`: 启用打断功能，支持全双工交互。\n- `--lm_model_name` \u002F `--lm_model_url`: 指定 LLM 模型名称和 API 地址。\n\n> **注**: 若需使用本地部署的 LLM（如 Qwen2.5, DeepSeek-V2.5 本地版），请移除 `--enable_llm_api` 和 `--lm_model_url` 参数，并将 `--lm_model_name` 改为本地模型路径。\n\n### 3. 连接客户端\n服务端启动后，前端客户端可通过 WebSocket 连接到 `ws:\u002F\u002F\u003C服务器 IP>:\u003C端口>` 进行语音交互。具体前端代码请参考项目中的 `frontend` 目录或自行开发 WebSocket 客户端。\n\n---\n*如需启用联网搜索和 RAG 功能，请先安装 `backend\u002Frequirements-rag.txt`，配置 `SERPER_API_KEY`，并使用 `s2s_server_pipeline_rag.py` 脚本启动服务。*","一位独立开发者希望快速构建一个能像真人一样实时对话、支持随时打断的语音助手原型，用于验证新的交互理念。\n\n### 没有 CleanS2S 时\n- **工程搭建繁琐**：需要分别集成 ASR、LLM 和 TTS 多个模块，配置复杂的依赖环境和项目文件结构，耗时数天才能跑通基础流程。\n- **交互体验割裂**：传统方案多为“说完再转、转完再答”的半双工模式，用户必须等待对方完全说完才能回应，无法实现自然的人机对话节奏。\n- **难以支持打断**：若想在模型播报时通过语音插话打断，需自行设计复杂的音频流中断逻辑和多线程队列管理，开发门槛极高。\n- **迭代验证缓慢**：每更换一个底层大模型或调整流水线逻辑，都涉及大量代码重构，严重阻碍了新想法的快速验证。\n\n### 使用 CleanS2S 后\n- **单文件即刻启动**：所有核心逻辑封装在单一文件中，无需纠结依赖配置，开发者下载即可运行，几分钟内建立起完整的流式语音链路。\n- **拟人化实时流交互**：基于 WebSocket 的全双工架构，让声音与文字数据实时流转，用户可与 CleanS2S 进行如 GPT-4o 般流畅的“边说边听”对话。\n- **原生支持智能打断**：内置 VAD（语音活动检测）与中断机制，用户在助手播报时随时开口，CleanS2S 能立即停止当前输出并响应新指令。\n- **灵活定制易扩展**：代码结构清晰透明，开发者可轻松替换喜欢的 LLM 模型或添加新功能组件，极大加速了从原型到产品的探索过程。\n\nCleanS2S 通过极简的单文件架构与强大的全双工流式能力，让开发者能以最低成本瞬间拥有高保真的类人语音交互原型。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fopendilab_CleanS2S_d67d3ff5.png","opendilab","OpenDILab","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fopendilab_83f31d72.png","Open-source Decision Intelligence (DI) Platform",null,"opendilab@pjlab.org.cn","https:\u002F\u002Fgithub.com\u002Fopendilab",[22,26,30,34],{"name":23,"color":24,"percentage":25},"Python","#3572A5",62.4,{"name":27,"color":28,"percentage":29},"TypeScript","#3178c6",37.1,{"name":31,"color":32,"percentage":33},"CSS","#663399",0.5,{"name":35,"color":36,"percentage":37},"JavaScript","#f1e05a",0,510,53,"2026-04-10T10:18:09","Apache-2.0",4,"Linux","未明确说明具体型号，但运行 FunASR (paraformer-zh) 和 CosyVoice-300M 通常需要 NVIDIA GPU。建议使用支持 CUDA 的显卡以确保实时流式处理性能。","未说明（建议 16GB+ 以承载多个语音模型及 LLM 上下文）",{"notes":47,"python":48,"dependencies":49},"1. 核心组件包括 ASR (FunASR\u002Fparaformer-zh, ct-punc, fsmn-vad) 和 TTS (CosyVoice-300M)，需单独按官方指引安装。\n2. LLM 默认通过 API 调用（支持 DeepSeek, MiniMax 等兼容 OpenAI 接口的服务），也可配置本地模型。\n3. 若启用 Web Search 和 RAG 功能，需额外安装 requirements-rag.txt 并配置 Serper API Key。\n4. 需要准备参考音频目录（ref_audio），音频长度建议 10-20 秒且发音清晰，用于韵律和音色迁移。\n5. 项目设计为单文件实现，强调低配置负担和快速验证。","3.x (通过 pip install -r requirements.txt 安装，未指定具体小版本，通常推荐 3.8+)",[50,51,52,53,54,55],"funasr (推荐 1.1.6)","cosyvoice","websockets","torch (隐含依赖)","transformers (隐含依赖)","sentence-transformers (RAG 模式需要，如 all-MiniLM-L6-v2)",[57,58,59,60,61],"音频","图像","语言模型","开发框架","Agent",[63,64,65,66,67,68,69,70],"ai","gpt-4o","machine-learning","python","speech-recognition","speech-synthesis","speech-to-speech","streaming",2,"ready","2026-03-27T02:49:30.150509","2026-04-11T04:54:47.302990",[76,81,86,91,96,101,106,111],{"id":77,"question_zh":78,"answer_zh":79,"source_url":80},28947,"如何配置 CosyVoice 和 CleanS2S 项目的环境变量及依赖版本以解决安装和运行错误？","1. 设置环境变量：使用命令 `export PYTHONPATH=\u002Froot\u002Fautodl-tmp\u002FCosyVoice:\u002Froot\u002Fautodl-tmp\u002FCosyVoice\u002Fthird_party\u002FMatcha-TTS` 指定路径。\n2. 推荐依赖版本：建议使用 PyTorch 2.0.1 (cu118) 和 Transformers 4.46.0。CleanS2S 对 PyTorch 无特殊要求，建议优先满足 CosyVoice 的依赖需求以避免段错误。","https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S\u002Fissues\u002F9",{"id":82,"question_zh":83,"answer_zh":84,"source_url":85},28948,"前端启动后报错或无法连接后端，如何排查和配置环境变量？","1. 浏览器排查：运行前端后在谷歌浏览器打开，按 F12 查看控制台报错信息。\n2. 配置文件检查：确保已配置前端环境变量文件（如 `.env.local` 或 `.env.example`）。\n3. URL 格式：文件中填入的后端服务 URL 必须遵循 `ws:\u002F\u002F\u003Cip>:\u003Cport>` 格式，否则会导致连接失败。","https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S\u002Fissues\u002F3",{"id":87,"question_zh":88,"answer_zh":89,"source_url":90},28949,"运行时报错 KeyError: 'timestamp' 该如何解决？","该错误通常与 FunASR 模型返回结果缺少时间戳字段有关。解决方案是修改后端代码 `backend\u002Fs2s_server_pipeline.py` 第 753 行附近的配置，将相关布尔值参数设置为 `False`。注意：设置为 False 可能会导致语音识别功能受限，需根据实际需求调整 FunASR 版本或模型配置。","https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S\u002Fissues\u002F27",{"id":92,"question_zh":93,"answer_zh":94,"source_url":95},28950,"启动服务端时报错 'AssertionError: failed to initialize ttsfrd resource' 怎么办？","如果在 Python 3.10 环境下安装 `ttsfrd` 导致初始化资源失败，可以尝试卸载该库。CosyVoice 检测到 `ttsfrd` 未安装时会自动使用替代库。执行 `pip uninstall ttsfrd` 后重新启动后端服务通常可解决问题。目前官方测试运行也未强制依赖 `ttsfrd`。","https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S\u002Fissues\u002F22",{"id":97,"question_zh":98,"answer_zh":99,"source_url":100},28951,"WebSocket 连接几秒后自动断开的原因及解决方法？","1. 检查端口配置：最常见原因是前后端配置的接收主机端口不一致。请检查前端环境变量 `NEXT_PUBLIC_FX_RECV_HOST` 和 `NEXT_PUBLIC_FX_SEND_HOST`，确保端口号正确且与后端监听端口匹配。\n2. 静音操作：说完话后可尝试点击 UI 上的静音按钮，防止环境噪音误触发打断逻辑导致连接断开。","https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S\u002Fissues\u002F25",{"id":102,"question_zh":103,"answer_zh":104,"source_url":105},28952,"如何将现有的 TTS 和 STT 模块替换为外部 API 服务？","需要自定义两个处理类来对接外部 API：\n1. `STTAPIHandler`：模仿 `ParaFormerSTTHandler` 编写，实现调用外部语音识别 API 的逻辑，保持输入输出参数类型一致。\n2. `TTSAPIHandler`：模仿 `CosyVoiceTTSHandler` 编写，实现调用外部文本转语音 API 的逻辑，保持输入输出参数类型一致。\n这两个类应放置在 `backend\u002F` 目录下并集成到主流程中。","https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S\u002Fissues\u002F17",{"id":107,"question_zh":108,"answer_zh":109,"source_url":110},28953,"本地安装依赖复杂导致失败，有什么推荐的部署方式？","如果本地通过 pip 安装依赖遇到路径错误或版本冲突问题，建议优先使用 Docker 部署。维护者表示可以考虑制作官方后端镜像以简化安装过程。若坚持本地调试，请单独运行模型加载代码片段（参考 `backend\u002Fs2s_server_pipeline.py` 第 1485 行）来排查具体的模型路径或 HuggingFace 下载问题。","https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S\u002Fissues\u002F31",{"id":112,"question_zh":113,"answer_zh":114,"source_url":115},28954,"整个语音对话链路（从提问到回答）延迟较高，如何优化性能？","1. 性能分析：首先在当前运行环境中对整个 pipeline 进行运行时间统计（profile），定位时间瓶颈。\n2. 模型替换：TTS 部分通常是耗时大头。可将模型替换为 CosyVoice 官方推出的 `CosyVoice-300M-25Hz` 模型，虽然效果略有损失，但推理速度可提升一倍以上。\n3. 架构升级：关注项目后续的 Web UI 和 RAG 机制升级，官方正在推进推理效率优化和多用户支持。","https:\u002F\u002Fgithub.com\u002Fopendilab\u002FCleanS2S\u002Fissues\u002F21",[],[118,128,136,144,152,161],{"id":119,"name":120,"github_repo":121,"description_zh":122,"stars":123,"difficulty_score":124,"last_commit_at":125,"category_tags":126,"status":72},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[61,60,58,127],"数据工具",{"id":129,"name":130,"github_repo":131,"description_zh":132,"stars":133,"difficulty_score":124,"last_commit_at":134,"category_tags":135,"status":72},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[60,58,61],{"id":137,"name":138,"github_repo":139,"description_zh":140,"stars":141,"difficulty_score":71,"last_commit_at":142,"category_tags":143,"status":72},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",149489,"2026-04-10T11:32:46",[60,61,59],{"id":145,"name":146,"github_repo":147,"description_zh":148,"stars":149,"difficulty_score":71,"last_commit_at":150,"category_tags":151,"status":72},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[60,58,61],{"id":153,"name":154,"github_repo":155,"description_zh":156,"stars":157,"difficulty_score":71,"last_commit_at":158,"category_tags":159,"status":72},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[160,61,58,60],"插件",{"id":162,"name":163,"github_repo":164,"description_zh":165,"stars":166,"difficulty_score":71,"last_commit_at":167,"category_tags":168,"status":72},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[160,60]]