与 AI 进行自然的语音对话！

这个项目让你只用语音就能与大型语言模型（LLM）聊天，并在几乎实时的情况下接收语音回复。
可以把它当作你自己的数字对话伙伴。

技术架构

一个为低延迟交互打造的高级 客户端-服务器 系统：

• 🎙 捕捉：浏览器捕捉你的声音。

• ➡ 流式传输：音频块通过 WebSockets 发送到 Python 后端。

• ✍ 转写：RealtimeSTT 迅速将语音转成文本。

• 🤔 思考：文本发送给 LLM（如 Ollama 或 OpenAI）进行处理。

• 🗣 合成：AI 的文本回复通过 RealtimeTTS 转回语音。

• ⬅ 返回：生成的音频流回浏览器并播放。

• 🔄 中断：随时插话！系统可平滑处理打断。

主要特性 ✨

• 流畅对话：像真实聊天一样说话和聆听。

• 实时反馈：即时查看部分转录与 AI 响应。

• 低延迟优化：使用音频分块流式架构。

• 智能轮流：动态静音检测（turndetect.py）匹配对话节奏。

• 灵活的 AI 大脑：可插拔 LLM 后端（默认 Ollama，可通过 llm_module.py 支持 OpenAI）。

• 可定制语音：可选不同 TTS 引擎（Kokoro、Coqui、Orpheus，配置在 audio_module.py）。

• Web 界面：基于 Vanilla JS 和 Web Audio API 的简洁 UI。

• Docker 化部署：推荐使用 Docker Compose 方便管理依赖。

技术栈 🛠

• 后端：Python < 3.13、FastAPI

• 前端：HTML、CSS、JavaScript（Vanilla JS、Web Audio API、AudioWorklets）

• 通信：WebSockets

• 容器化：Docker、Docker Compose

• 核心 AI/ML 库：

  • RealtimeSTT（语音转文本）

  • RealtimeTTS（文本转语音）

  • transformers（轮次检测、分词）

  • torch / torchaudio

  • ollama / openai（LLM 客户端）

• 音频处理：numpy、scipy

环境要求 🏊‍♀

此项目依赖强大的 AI 模型，需要满足以下条件：

• 操作系统

  • Docker：推荐 Linux，以获得最佳 GPU 集成

  • 手动安装：Windows 提供 install.bat 脚本；Linux/macOS 需手动配置（特别是 DeepSpeed 可能需额外调试）

• Python：3.9 或更高

• GPU：强大的 NVIDIA CUDA GPU（加速 Whisper STT 和 Coqui TTS）。CPU 或低端 GPU 运行会慢很多。

  • 默认假设 CUDA 12.1，如不同版本需调整 PyTorch 安装。

• Docker（推荐）：Docker Engine 和 Docker Compose v2+

• Ollama（可选）：如需使用 Ollama 后端且不走 Docker，需单独安装并拉取模型。

• OpenAI API Key（可选）：如使用 OpenAI 后端，在环境变量或 .env 中设置 OPENAI_API_KEY。

安装与运行 ⚙

1. 克隆仓库

   git clone https://github.com/KoljaB/RealtimeVoiceChat.git
   cd RealtimeVoiceChat

2. 安装方式

   • 🚀 A：Docker（推荐，Linux/GPU）

   • 🛠 B：手动（Windows 脚本 / venv）

3. 启动应用

   • Docker：docker compose up -d 即可运行，查看日志 docker compose logs -f app

   • 手动：

     # 激活虚拟环境
     source ../venv/bin/activate  # Linux/macOS
     ..\venv\Scripts\activate     # Windows
     cd code
     python server.py

4. 访问客户端

   • 浏览器打开 http://localhost:8000

   • 允许麦克风权限，点击“Start”开始聊天，“Stop”结束，“Reset”清空会话。

深度配置 🔧

可在 code/ 目录修改 Python 文件调整：

• TTS 引擎与声音（server.py, audio_module.py）

  • START_ENGINE 可选 "coqui", "kokoro", "orpheus"

  • 在 AudioProcessor.__init__ 中调整语音模型路径、说话人 ID、语速等

• LLM 后端与模型（server.py, llm_module.py）

  • LLM_START_PROVIDER 设为 "ollama" 或 "openai"

  • LLM_START_MODEL 指定模型名

  • 自定义 AI 人格：编辑 system_prompt.txt

• STT 设置（transcribe.py）

  • 修改 DEFAULT_RECORDER_CONFIG 以更换 Whisper 模型、语言或静音阈值

• 轮次检测（turndetect.py）

  • 调整 TurnDetector.update_settings 中的停顿时间参数

• SSL/HTTPS

  • USE_SSL = True 并提供证书与密钥路径

  • Docker 用户需修改 docker-compose.yml 映射 443 端口并挂载证书