本地实时语音对话AI 完整部署文档（断网可用+极简排错）

文档简介

本方案基于 HuggingFace 官方 speech-to-speech 流水线 + llama.cpp 本地大模型 + hf-realtime-voice 可视化前端，实现全程本地运算、数据不出本机、断网可正常对话的实时中文语音AI。全程开源免费，适配Windows NVIDIA显卡设备，支持可视化呼吸球交互、实时字幕展示。

核心特性：纯本地部署、无云端上传、实时语音交互、可视化状态提示、支持离线使用（首次部署需联网下载模型）

一、整体架构与服务说明

1.1 三大核心服务（端口常驻、缺一不可）

服务模块 运行程序 监听端口 核心职责
大模型后端服务 llama-server.exe（llama.cpp） 8080 运行Qwen3大模型，提供兼容OpenAI的文本推理接口，负责对话思考与文本回复生成
语音调度核心服务 speech-to-speech 8765 全局链路调度：麦克风音频→Whisper语音识别→调用本地大模型→Qwen3-TTS语音合成→输出音频流
Web可视化前端 uvicorn + hf-realtime-voice 7860 提供呼吸球可视化界面，负责麦克风采集、AI语音播放、实时字幕展示、状态可视化

1.2 服务调用链路（完整数据流）

麦克风音频输入 → 前端7860（WebSocket推流）→ 语音服务8765

1. 语音服务内置 Whisper-large-v3：音频转中文文本（STT语音识别）

2. 语音服务HTTP调用 大模型8080服务：文本输入大模型，流式获取AI回复文本

3. 语音服务内置 Qwen3-TTS：AI文本转语音音频（TTS语音合成）

4. 语音服务WebSocket回传音频+字幕 → 前端7860：播放语音、展示实时字幕、更新呼吸球状态

核心规则：前端不直接调用大模型，所有AI推理请求均由语音服务中转；STT/TTS模型内嵌于语音服务，无独立端口。

1.3 服务依赖与启动顺序（严格不可逆）

✅ 正确启动顺序：大模型服务(8080) → 语音调度服务(8765) → 网页前端(7860)

  • 大模型服务：基础依赖，所有对话推理的核心，必须最先启动，否则语音服务连接失败

  • 语音调度服务：依赖8080端口正常监听，是前后端、语音与大模型的中转核心

  • 前端服务：仅依赖8765语音服务，最后启动即可

1.4 环境依赖区分

  • llama.cpp：独立EXE程序，不依赖Python虚拟环境，仅依赖CUDA运行库、GGUF模型文件

  • speech-to-speech/前端：依赖Python虚拟环境，需CUDA版PyTorch、音频处理、web框架等依赖

二、分步部署教程（Windows专属）

2.1 基础环境安装（全局必备）

1. Python 3.11（安装务必勾选 Add Python to PATH）

2. Git（代码拉取必备）

3. FFmpeg（音频编解码）：PowerShell执行 winget install Gyan.FFmpeg

4. SoX（音频处理）：PowerShell执行 winget install ChrisBagwell.SoX

2.2 创建Python虚拟环境

PowerShell依次执行以下命令，搭建独立运行环境：

Text
1
2
3
4
5
6
7
8
9
# 权限放行
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
# 创建项目目录
cd C:\
mkdir s2s && cd s2s
# 创建虚拟环境
python -m venv venv
# 激活环境（出现(venv)绿标即成功）
.\venv\Scripts\Activate.ps1

2.3 安装核心依赖

1. 安装语音调度核心库

Text
1
pip install speech-to-speech

2. 修复huggingface_hub版本（解决模型下载失败）

Text
1
pip install "huggingface_hub>=0.36.0,<1.0"

3. 安装CUDA版PyTorch（必做，替换默认CPU版，否则速度极慢）

Text
1
2
pip uninstall torch torchaudio -y
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu124

2.4 部署llama.cpp本地大模型

1. 下载对应CUDA版本包（40系显卡选cuda-12.4，新卡选cuda-13.3，仅选NVIDIA CUDA版，勿下CPU/AMD HIP版）

需下载两个压缩包：主程序包、CUDA运行时包，解压至同一目录 D:\llama

2. 下载Qwen3-4B量化模型（虚拟环境中执行）

Text
1
python -c "from huggingface_hub import snapshot_download; snapshot_download('unsloth/Qwen3-4B-Instruct-2507-GGUF', allow_patterns='*Q4_K_M.gguf', local_dir=r'D:\llama\models\qwen3-4b')"

3. 启动大模型服务（新PowerShell窗口）

Text
1
2
cd D:\llama
.\llama-server.exe -m .\models\qwen3-4b\Qwen3-4B-Instruct-2507-Q4_K_M.gguf -c 32768 -fa on --port 8080 -ngl 99

启动成功标识：控制台输出监听 http://127.0.0.1:8080

参数说明：-ngl 99（全层GPU加速）、-c 32768（超大上下文）、-fa on（性能加速）

2.5 启动语音调度服务

回到激活的(venv)虚拟环境窗口，执行完整启动命令：

Text
1
2
3
4
5
6
7
8
9
10
11
12
13
speech-to-speech `
--mode realtime `
--stt whisper `
--stt_model_name openai/whisper-large-v3 `
--language zh `
--llm_backend responses-api `
--model_name "unsloth/Qwen3-4B-Instruct-2507-GGUF" `
--responses_api_base_url "http://127.0.0.1:8080/v1" `
--responses_api_api_key "none" `
--responses_api_stream `
--tts qwen3 `
--qwen3_tts_language zh `
--enable_live_transcription

启动成功标识：Realtime server listening on ws://localhost:8765/v1/realtime

2.6 启动前端可视化界面

新开PowerShell窗口，执行以下命令部署网页端：

Text
1
2
3
4
5
cd C:\s2s
git clone https://huggingface.co/spaces/smolagents/hf-realtime-voice
cd hf-realtime-voice
pip install -r requirements.txt
uvicorn server:app --port 7860

浏览器打开：http://127.0.0.1:7860

页面配置：Settings中填写语音地址 localhost:8765，允许麦克风权限即可对话

2.7 一键启动脚本（懒人必备）

下载官方 启动语音对话.bat，放置桌面，双击即可自动执行：

启动大模型服务(20s延时) → 启动语音服务(30s延时) → 启动前端页面 → 自动打开浏览器

注意：低配电脑可手动修改脚本延时参数，避免服务未加载完成导致连接失败

三、呼吸球状态可视化说明

  • 🟢 绿色：服务就绪，可直接对话

  • 🔵 青色：正在聆听麦克风语音

  • 🟠 琥珀色：大模型正在思考推理

  • 🟣 紫色：AI正在合成并播放语音回答

  • 🔴 红色：服务报错、连接中断

四、极简排错清单（高频问题全覆盖）

本清单为部署90%报错的核心解决方案，优先对照排查

4.1 模型下载失败

  • 问题：huggingface_hub版本过高导致下载中断

  • 解决方案：执行 pip install "huggingface_hub>=0.36.0,<1.0" 锁定版本

4.2 语音识别/合成速度极慢

  • 问题：Python环境默认安装CPU版PyTorch，无GPU加速

  • 解决方案：卸载原有版本，安装CUDA12.4版本PyTorch

4.3 前端点球无法连接、无响应

  • 原因1：服务启动顺序错误（先开前端、后开大模型/语音服务）

  • 原因2：语音服务8765端口未完全加载完成

  • 解决方案：严格按顺序重启服务，等待端口监听成功后再刷新网页

4.4 llama-server启动失败

  • 问题1：下载错误版本（CPU/AMD版）

  • 解决方案：核对显卡型号，重新下载对应CUDA版本的双压缩包并解压合并

  • 问题2：模型路径错误/文件缺失

  • 解决方案：确认模型目录与启动命令路径一致，保留Q4_K_M量化模型

4.5 断网后无法使用

  • 原因：首次部署未完成模型全量下载

  • 解决方案：联网启动一次服务，等待Whisper、TTS、大模型全部加载缓存完成，后续可断网运行

4.6 Windows拦截bat脚本

  • 解决方案：弹窗选择「更多信息」→「仍要运行」（本地无签名脚本，属于正常系统防护）

4.7 替代方案（已有Ollama）

无需部署llama.cpp，直接修改语音服务启动参数，替换为Ollama接口：

--responses_api_base_url "http://127.0.0.1:11434/v1"，模型名改为本地Ollama模型即可

五、关键注意事项

  1. 三个服务终端窗口全程不可关闭，关闭任意窗口对应服务立即停止

  2. 仅NVIDIA显卡支持CUDA加速，AMD显卡无法适配本方案

  3. 显存不足可降级模型：Whisper-large-v3 → Whisper-medium，降低显存占用

  4. 所有数据运算、音频处理、对话推理均在本地完成，无网络上传，隐私性拉满

  5. 支持WSL2部署，适配Linux环境，显卡可直通GPU加速

（注：部分内容可能由 AI 生成）