本地 AI 语音助手部署教程：Whisper、llama.cpp 与 Qwen3-TTS 实时对话

作者： /

这篇文章教你在 Windows 电脑上部署一套本地实时 AI 语音对话系统：你对着麦克风说话，电脑完成语音识别、调用本地大模型思考，再用中文语音回答。整套流程可以放在本地运行，适合想学习离线语音助手、隐私友好 AI 工作流和本地大模型应用的用户。

合规提醒：本文仅用于个人学习、本地测试和合法的 AI 应用研究。使用开源模型、语音识别和语音合成工具时，请遵守对应项目许可证、模型使用条款和当地法律法规，不要用于冒充他人声音、欺诈、骚扰或未经授权的录音处理。

本地 AI 语音助手部署教程封面
本地语音助手流程：语音识别、LLM 思考、语音合成和网页实时对话。

一、这套方案能实现什么

参考方案的核心是 Hugging Face 的 speech-to-speech 语音智能体流水线。它把 VAD、STT、LLM、TTS 串在一起：先判断你什么时候开始说话，再把语音转文字，把文字交给本地大模型生成回答，最后把回答合成语音播放出来。

  • 实时语音对话：对着麦克风说中文，浏览器里可以看到转写和回答。
  • 本地大模型：使用 llama.cpp 在本机提供 OpenAI 兼容接口。
  • 本地语音合成：使用 Qwen3-TTS 输出中文语音。
  • 隐私友好：模型和服务都在本机跑，适合学习离线语音助手架构。
  • 可替换组件：STT、LLM、TTS 都可以按硬件性能替换。

二、电脑配置和准备工作

本教程更适合有 NVIDIA 显卡的 Windows 电脑。参考文章使用高性能显卡演示，如果你的显卡较弱，可以把 Whisper 模型换小、把大模型换成更低量化版本，或者改用 Ollama 已经跑好的模型接口。

  • Windows 10/11 电脑，建议有 NVIDIA 显卡和较新的驱动。
  • Python 3.10 及以上，推荐 Python 3.11。
  • Git，用于下载网页客户端或示例项目。
  • FFmpeg，用于音频处理。
  • llama.cpp Windows CUDA 版本，用于启动本地 LLM 服务。
  • Chrome 或 Edge 浏览器，并允许网页使用麦克风。

三、安装 Python、Git 和 FFmpeg

先安装 Python 3.11。安装时一定要勾选 Add Python to PATH，否则后面 PowerShell 可能找不到 python 命令。Git 可以从官网安装，FFmpeg 可以用 winget 一键安装。

winget install Gyan.FFmpeg

安装完成后，重新打开一个 PowerShell 窗口，让环境变量生效。可以用下面的命令检查：

python --version
git --version
ffmpeg -version

四、创建 speech-to-speech 虚拟环境

为了不污染系统 Python，建议单独创建虚拟环境。下面命令会在 C:\s2s 下创建项目目录和 venv。

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
cd C:mkdir s2s
cd s2s
python -m venv venv
.env\Scripts\Activate.ps1

命令行前面出现 (venv)，说明已经进入虚拟环境。接着安装语音对话核心组件：

pip install speech-to-speech

五、准备本地大模型服务

这里使用 llama.cpp 启动本地 OpenAI 兼容接口。进入 llama.cpp Releases 页面，按你的 CUDA 版本下载 Windows CUDA 包。NVIDIA 新卡常见 CUDA 12.x，具体以你的驱动和发布包说明为准。

  • 主程序包：包含 llama-server.exe。
  • 运行时包：包含 CUDA 相关 DLL。
  • 两个压缩包解压到同一个目录，例如 D:\llama。
  • 不要把 AMD HIP 包或纯 CPU 包当成 CUDA 包下载。

下载模型可以使用 Hugging Face Hub。下面以 Qwen3 4B GGUF 的 Q4_K_M 量化版本作为示例，路径可以按自己的磁盘修改。

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')"

如果下载时提示 Hugging Face Hub 版本不兼容，可以把版本固定在 1.0 以下：

pip install "huggingface_hub>=0.36.0,<1.0"

六、启动 llama.cpp 本地 LLM

重新打开一个 PowerShell 窗口，专门运行大模型服务。这个窗口不要关闭，关闭后语音助手就无法调用本地 LLM。

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 用于启用加速。

七、启动实时语音对话服务

回到前面带 (venv) 的 PowerShell 窗口，启动 speech-to-speech。这里使用 Whisper 做中文语音识别，使用本地 llama.cpp 接口做 LLM，使用 Qwen3-TTS 合成中文语音。

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

PowerShell 多行换行用的是反引号 `，不是 Linux/macOS 的反斜杠。首次启动会下载语音识别和语音合成模型，时间会比较久。看到 Realtime server listening on ws://localhost:8765/v1/realtime 说明语音服务已经就绪。

八、如果 PyTorch 是 CPU 版怎么办

如果你发现语音识别或语音合成速度很慢，可能是虚拟环境里装到 CPU 版 PyTorch。NVIDIA CUDA 12.4 环境可以参考下面命令重装 CUDA 版。不同 CUDA 版本请以 PyTorch 官方页面为准。

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

九、打开网页呼吸球界面

再打开第三个 PowerShell 窗口，下载并启动 Hugging Face 的实时语音网页客户端。这个网页负责连接本地 WebSocket 服务，并提供麦克风权限、实时字幕和呼吸球动画。

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

进入页面后，把本地语音服务地址设置为 localhost:8765，允许浏览器使用麦克风，然后点击中间的球开始说话。一般颜色含义可以理解为：绿色是就绪，青色是在听你说话，琥珀色是思考中，紫色是 AI 正在回答，红色表示连接或服务出错。

十、重启电脑后如何快速启动

重启电脑后通常要启动三个窗口：大模型服务、语音对话服务、网页客户端。建议你先手动跑通，再写一键启动脚本。脚本要预留足够等待时间，因为模型加载比普通程序慢。

@echo off
start "llama-server" powershell -NoExit -Command "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"
timeout /t 25
start "speech-to-speech" powershell -NoExit -Command "cd C:\s2s; .env\Scripts\Activate.ps1; speech-to-speech --mode realtime --stt whisper --language zh --llm_backend responses-api --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"
timeout /t 35
start "voice-ui" powershell -NoExit -Command "cd C:\s2s\hf-realtime-voice; uvicorn server:app --port 7860"
timeout /t 8
start http://127.0.0.1:7860

如果网页先打开但点球连接失败，通常是语音服务还没完全启动。等窗口出现服务监听提示后刷新浏览器即可。

十一、常见问题排查

1. PowerShell 提示脚本不能运行

执行策略没有放开时，虚拟环境激活脚本可能无法运行。使用本文前面的 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned 后重新打开窗口再试。

2. 下载 Hugging Face 模型很慢

模型文件较大，首次下载慢是正常的。可以换网络环境，或提前在浏览器/下载工具里把 GGUF 模型下载到本地，再把启动命令里的模型路径改成实际文件路径。

3. 麦克风没有声音

检查 Windows 隐私设置里的麦克风权限，浏览器地址栏的麦克风授权，以及是否选中了正确输入设备。

4. AI 回答很慢

优先换更小的 STT 模型或更小的 LLM。比如把 Whisper large-v3 换成 medium，或者把大模型换成更低参数、更低量化的 GGUF。

5. llama.cpp 服务启动失败

检查是否下错 CUDA 包、模型文件路径是否正确、显存是否足够，以及 DLL 是否和 llama-server.exe 在同一个目录。

十二、官方项目和参考链接

十三、总结

本地 AI 语音助手的关键不是单独安装某个模型，而是把语音识别、本地大模型、语音合成和网页客户端串成一条稳定链路。建议先按本文步骤手动启动三个窗口，确认能完整对话后，再考虑一键启动脚本、模型替换和提示词优化。

滚动至顶部