如果你对云端语音助手的隐私安全有所顾虑，或者希望在完全不联网的环境下拥有一套实时交互的语音对话系统，可以通过本地部署 HuggingFace 官方的语音智能体流水线来实现。

该方案将语音识别 (STT)、大语言模型 (LLM) 与语音合成 (TTS) 串联，并配有可视化交互界面。系统整体完全开源免费，在配备 4GB 及以上显存的本地电脑上即可流畅运行。

环境准备

在开始部署前，请确保系统中已安装并配置好以下基础组件：

  1. Python 3.11：点击下载官方安装包，安装时务必勾选 **”Add Python to PATH”**。

  2. Git：点击下载配置程序。

  3. FFmpeg：以管理员身份打开 PowerShell，执行以下命令一键安装，完成后需重启 PowerShell 窗口使变量生效：

    1
    winget install Gyan.FFmpeg

部署步骤

1. 初始化虚拟环境

打开 PowerShell，依序执行以下命令创建并激活独立的虚拟环境：

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\Scripts\Activate.ps1

当命令行前端出现 (venv) 标记时，说明已成功进入虚拟环境。

2. 安装核心依赖

在激活的虚拟环境中，安装 speech-to-speech 流水线及所需组件：

1
2
3
pip install speech-to-speech
pip install "huggingface_hub>=0.36.0,<1.0"
winget install ChrisBagwell.SoX

注意（显卡加速配置）：

默认安装的 PyTorch 可能为 CPU 版本。为了调用显卡提高响应速度，建议先卸载纯 CPU 版，再安装对应的 CUDA 12.4 运行库：

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

3. 配置本地大模型（基于 llama.cpp）

为了实现低延迟的本地推理，推荐使用免编译的 llama.cpp 作为后端服务：

  1. 下载程序：前往 llama.cpp 官方 Releases 页面，根据你的显卡驱动下载最新版的二进制主程序包与运行时组件（如：win-cuda-12.4-x64 相关压缩包），解压合并至同一个文件夹中（例如 D:\llama）。

  2. 下载中文大模型：在 (venv) 窗口中运行以下命令，将 Qwen3-4B-Instruct 的 GGUF 模型下载至本地：

    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 窗口，进入 D:\llama 并运行：

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

    注：-ngl 99 代表将模型所有层加载至 GPU 显存，--port 8080 为本地服务端口。若习惯使用 Ollama，可跳过此步并调整后续终端的 API 地址。

4. 启动语音对话核心服务

回到此前激活了 (venv) 的 PowerShell 窗口，将下述指令粘贴并回车（首次运行会自动下载 Whisper 和 Qwen3-TTS 模型）：

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 时，说明底层语音服务已就绪。

若显卡配置较低，可将 --stt_model_name 的参数变更为 openai/whisper-medium 以提高识别速度。

5. 部署前端可视化界面

再开启一个全新的 PowerShell 窗口，克隆前端 UI 代码并利用 uvicorn 托管：

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

调试与使用

  1. 使用 Chrome 或 Edge 浏览器访问本地前端地址：[http://127.0.0.1:7860](http://127.0.0.1:7860)。
  2. 首次进入界面后，点击 Settings，将本地语音地址（WS 地址）修改为 localhost:8765。
  3. 点击页面中央的“交互球”并允许麦克风权限。当球体变为绿色时，即可直接进行普通话语音对话。

状态指示球说明：

  • 绿/青色：系统就绪 / 正在接收或聆听你的语音。
  • 琥珀色：大模型本地思考中。
  • 紫色：AI 正在进行本地语音实时合成与回答。

更强模型下载

Qwen3.5 A3B 模型：【点击下载】 或 【更多模型下载】

下载将模型放入D:\llama\models 模型文件夹下，把把启动脚本里的模型文件名称改成你新放入的模型名称即可。

重启电脑后怎么使用？

你可以使用下方这个一键启动脚本来执行，它会自动依次弹出三个服务窗口、等各自加载好、最后打开浏览器。

一键启动脚本【点击下载】 或 【备用下载】

怎么用：

  1. 把 启动语音对话.bat 下载下来，放一个好找的位置（比如桌面）
  2. 双击运行
  3. 它会自动：弹窗口1(大模型)→等20秒→弹窗口2(语音服务)→等30秒→弹窗口3(网页)→等6秒→自动打开浏览器
  4. 浏览器打开后，进 Settings 填 localhost:8765，点球开始说话``

几个要注意的点：

① 那几个”等待秒数”可能要微调。 脚本里给大模型留了20秒、语音服务留了30秒。如果你机器加载慢，可能网页窗口起来了、语音服务还没好，导致第一次点球连不上——这时等语音服务窗口出现 running on http://0.0.0.0:8765 之后，刷新一下浏览器再点球就行。如果你发现每次都要等更久，告诉我，我把秒数调大。

② 三个服务窗口别关。 脚本主窗口(黑色那个提示信息的)可以关，但弹出的三个 cmd 窗口要留着，它们就是在跑服务。关掉哪个哪个服务就停了。

③ 第一次双击如果 Windows 拦截。 可能弹”Windows 已保护你的电脑”，点”更多信息”→”仍要运行”即可（因为是本地脚本、没有数字签名，属正常）。

④ 想改中文提示词。 网页 Settings 里的 Instructions（中文提示词）浏览器会自己记住，脚本不管这个，填一次以后就在。

先双击试一次，看三个窗口能不能都正常起来、浏览器能不能自动打开。如果哪个窗口报错、或者点球连不上，把情况告诉我，我帮你调脚本的等待时间或路径。

Linux方案：

WSL2（原生装不上时用这个）

WSL2 是 Windows 自带的 Linux 子系统，4090 能直通，Linux 依赖装起来最顺，对观众来说仍然是”在 Windows 电脑上”。

装 WSL2（管理员 PowerShell）：

1
wsl --install -d Ubuntu

重启后设个用户名密码，开始菜单搜 “Ubuntu” 进 Linux 终端。在里面跑 nvidia-smi 能看到 驱动版本号 就说明 GPU 直通成功了。

在 Ubuntu 里装（跟 Linux 一样）：

1
2
3
4
5
sudo apt update && sudo apt install -y python3-venv ffmpeg
python3 -m venv ~/s2s && source ~/s2s/bin/activate
pip install "qwentts-cpp-python==0.3.0+cu124" -f https://huggingface.co/datasets/andito/qwentts-cpp-python-wheels/tree/main/whl/cu124
pip install speech-to-speech
pip install "llama-cpp-python[server]"

启动命令和正文第三、四步一样，只是换行符改回 Linux 的斜杠 \、路径用 Linux 风格。网页部分照旧——WSL 里跑 python3 -m http.server 9000，Windows 上的 Chrome 直接访问 http://127.0.0.1:9000/voice-chat-client.html（WSL2 会自动把端口转发到 Windows）。