RealtimeVoiceChat

像打电话一样和 AI 实时语音聊天

开源 🏷️完全免费 🔧 仅开源项目，无在线服务，需自行部署对话助手 🍴 复刻 460 🐛 待处理 40 👀 关注 35

GitHub ↗

GitHub 星标 ★ 3868

维护状态活跃

是否开源开源

定价模式 🏷️完全免费开源免费，需自行部署

项目预览

RealtimeVoiceChat 项目界面预览图 — 图片来源：GitHub 官方仓库名片

项目数据

分类对话助手

开发团队KoljaB

GitHubhttps://github.com/KoljaB/RealtimeVoiceChat

定价模式🏷️完全免费

价格说明开源免费，需自行部署

访问状态🔧 仅开源项目，无在线服务，需自行部署

是否开源是

主要语言Python

GitHub 星标★ 3868

上线时间2025-04-19 00:00:00

代码更新2026-11-07

仓库体积60.2 MB

本站数据更新2026-11-10

维护状态活跃

收录时间2026-11-10

浏览次数0

项目介绍

RealtimeVoiceChat 是一个用 Python 实现的开源实时语音对话项目，目标是让用户像打电话一样与 AI 自然交谈，而不是打字或等待整段录音转写。它把语音识别、对话模型和语音合成串成低延迟流水线，支持边说话边识别、流式生成回复并即时播报，尽量缩短从用户说完到 AI 开口的等待。项目提供可本地运行的完整示例，包含前端交互页面和服务端逻辑，方便开发者替换 ASR、LLM、TTS 组件，也便于在自有硬件上做原型验证。适合研究实时语音交互、搭建语音助手 Demo，或作为二次开发底座。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

数据来源：GitHub API 逐日快照 · 收录于 2026-11-10 · 当前星标 ★ 3868

使用教程

难度：进阶约 30 分钟部署方式：Docker 7 步

环境要求

已安装 Git，能克隆 GitHub 仓库
已安装 Docker 与 Docker Compose（推荐方案）
可选：NVIDIA GPU 与驱动，docker-compose.yml 中已配置 GPU 访问
浏览器需允许麦克风权限
首次构建需下载基础镜像、ML 依赖与默认 STT 模型，需较长时间与足够磁盘空间

安装与启动步骤

1克隆仓库

把项目源码下载到本地并进入目录，后续所有命令都在该目录执行。
```
git clone https://github.com/KoljaB/RealtimeVoiceChat.git
cd RealtimeVoiceChat
```
2构建镜像

下载基础镜像、安装 Python/ML 依赖并预下载默认 STT 模型，耗时较长。若要改 code/*.py 配置须在构建前完成。
```
docker compose build
```
3后台启动服务

同时拉起应用与 Ollama 两个容器，启动后等待约一分钟让其初始化完成。
```
docker compose up -d
```
4拉取对话模型

启动后再把默认模型拉进运行中的 Ollama 容器，这样换模型不必重新构建镜像。
```
docker compose exec ollama ollama pull hf.co/bartowski/huihui-ai_Mistral-Small-24B-Instruct-2501-abliterated-GGUF:Q4_K_M
```
5确认模型已就绪

列出 Ollama 中已有的模型，确认上一步的模型名称出现在列表里。
```
docker compose exec ollama ollama list
```
6查看运行日志

持续跟踪应用日志，观察服务是否报错、WebSocket 是否正常建立。
```
docker compose logs -f app
```
7打开页面开始对话

浏览器访问 8000 端口，允许麦克风权限后点 Start 说话，Stop 结束、Reset 清空对话。

关键配置

配置项	必填	说明	示例
`START_ENGINE`	否	server.py 中选择语音合成引擎	`kokoro`
`LLM_START_PROVIDER`	否	server.py 中选择对话模型提供方	`ollama`
`LLM_START_MODEL`	否	server.py 中指定使用的模型名，需与已拉取模型一致	`hf.co/bartowski/huihui-ai_Mistral-Small-24B-Instruct-2501-ab`
`system_prompt.txt`	否	编辑该文件自定义 AI 的人设与回复风格	`You are a helpful voice assistant.`
`USE_SSL`	否	server.py 中开启 HTTPS，需同时配置证书与私钥路径	`True`
`DEFAULT_RECORDER_CONFIG`	否	transcribe.py 中调整 Whisper 模型、语言与静音判定阈值	`model=base.en`

如何确认成功

浏览器打开 http://localhost:8000 页面正常加载，授权麦克风后点击 Start 说话能收到语音回复，日志无报错。

常见问题

Q：构建或启动特别慢怎么办？

A：首次构建要下载基础镜像、ML 依赖和默认 STT 模型，属正常现象；保持网络稳定并预留足够磁盘空间，后续启动会快很多。

Q：改了 code/ 里的配置为什么不生效？

A：Docker 方案下配置在构建时被打进镜像，需先改文件再执行 docker compose build，然后 docker compose up -d 重建容器。

Q：不想用 Docker 怎么装？

A：可按 README 的手动方式：python -m venv venv 创建并激活虚拟环境，升级 pip，进入 code 目录先按硬件安装对应 PyTorch，再 pip install -r requirements.txt，最后 python server.py。

Q：没有独立显卡能跑吗？

A：可以，但 CPU 推理速度慢，体验会明显下降；有 NVIDIA GPU 时按 CUDA 12.1 对应版本安装 PyTorch 效果更好。

Q：页面打不开或没有声音？

A：先看 docker compose logs -f app 是否报错，确认容器已运行、Ollama 模型已拉取完成，并检查浏览器麦克风权限与端口访问。

注意事项

项目已转为社区维护，作者不再提供官方支持与新功能开发，遇到问题可参考社区 PR。
Docker 方案建议在修改 code/*.py 配置之后再执行 docker compose build，否则改动不会进入镜像。
默认 STT 模型为 base.en（英文），需要其他语言或更高质量请在 transcribe.py 中调整。
对外开放或远程访问时，可在 server.py 开启 USE_SSL 并配置证书路径，同时调整 docker-compose.yml 端口映射。

核心亮点

端到端串起 ASR、LLM、TTS，开箱即可体验实时语音对话
采用流式识别与流式合成，明显压缩首字响应等待
组件可替换，方便接入不同语音模型或本地推理服务

不足之处

实时链路对算力和网络延迟敏感，低配机器体验下降明显
依赖多个外部模型与服务，部署配置步骤较多

适用场景

本地搭建实时语音助手原型
研究低延迟语音对话流水线
为智能硬件或客服场景做语音交互验证

替代项目

pipecat、LiveKit Agents、TEN Agent

上一篇：extended_openai_conversation

下一篇：quillman