Whispera 是 Windows 上的本地实时语音对话桌面应用。VAD 打断、SenseVoice 语音识别、llama-server 本地大模型和 VoxCPM 流式 TTS 被串成一条完整链路，全程跑在本机。

项目简介

目前支持本地麦克风输入、VAD 打断、SenseVoice ASR、llama-server 本地大模型推理、可选的 VoxCPM 流式 TTS，以及可选的 mem0 长期记忆。

演示视频：Bilibili BV1nFE36mEmc

概览

• Electron 负责桌面界面、配置、日志和本地服务的编排。
• Python realtime/ 负责 VAD、ASR、LLM、TTS、WebSocket 协议和会话状态。
• 支持本地 llama-server、可选 VoxCPM 流式 TTS、可选 mem0 长期记忆。
• 大模型、ASR/TTS 权重和分发资源不随 Git 仓库提交，需要自己准备。

核心功能

• Electron 桌面前端，带资源状态、日志和配置面板
• 拉起并复用本地 llama-server
• Silero VAD + barge-in 打断
• SenseVoice ASR
• 流式文本输出，按句切分
• 可选 VoxCPM 流式 TTS
• 可选 mem0 长期记忆检索与保存
• Windows 便携目录打包流程

系统架构

Plain Text

Electron renderer / web client
  -> WebSocket
  -> Python realtime backend
  -> Silero VAD
  -> SenseVoice ASR
  -> optional mem0 memory search
  -> llama-server (OpenAI-compatible API)
  -> text segmenter
  -> optional VoxCPM streaming TTS
  -> audio chunks back to Electron

开发态启动时，Electron 会按需拉起这几个本地服务：

1. llm-module/scripts/start_llama_server.py
2. 可选 memory embedding llama-server
3. python -m realtime.app
4. 本地 Web client 和 Electron renderer

运行要求

• Windows 10/11
• PowerShell
• Node.js
• 本地可用的 Python 运行时
• 本地模型与资源文件

开发时建议用自己的 Python 或 conda 环境，runtime/python/ 只用于打包便携 runtime。

快速开始

1. 获取代码

仓库里有些大文件走 Git LFS，拉代码前先安装并初始化：

PowerShell

git lfs install
git clone https://github.com/maomao-2001/Whispera.git
cd Whispera
git lfs pull

2. 准备 Python 环境并安装依赖

Whispera 默认要用 GPU 版 PyTorch。首次安装时别换成 CPU-only 的 torch，否则 ASR 在默认配置下跑不起来。在根目录执行：

PowerShell

conda create -n whispera python=3.11 -y
conda activate whispera
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
npm install --prefix electron-app

装完先确认 PyTorch 是 CUDA 版本，再启动项目：

PowerShell

python -c "import torch; print(torch.__version__); print(torch.version.cuda); print(torch.cuda.is_available())"

应该看到 torch.__version__ 类似 2.6.0+cu126，torch.version.cuda 有值（例如 12.6），torch.cuda.is_available() 输出 True。

不用 conda 的话，直接拿系统 Python 装也行。只有在需要指定某个 Python 时才设置：

PowerShell

$env:MINIMIND_PYTHON="C:\Users\you\anaconda3\envs\your_env\python.exe"

另外，首次启动前最好清掉下面这个环境变量，免得 Electron 被当成普通 Node 进程启动：

PowerShell

Remove-Item Env:ELECTRON_RUN_AS_NODE -ErrorAction SilentlyContinue

3. 准备本地资源

这些大资源默认不在 Git 仓库里，一条命令就能下载到 assets/（等价于 python scripts/download_assets.py）：

PowerShell

npm run setup:assets

这条命令会下载：

• llama-bin/：从 ggml-org/llama.cpp GitHub Releases 下载 llama-server 运行时
• asr/SenseVoiceSmall/：从 Hugging Face 下载 SenseVoiceSmall
• tts/openbmb__VoxCPM1.5/：从 Hugging Face 下载 VoxCPM1.5
• tts/openbmb__VoxCPM2/：从 Hugging Face 下载 VoxCPM2
• embedding/：从 Hugging Face 下载 nomic-embed-text-v1.5.Q8_0.gguf
• lora/、reference/、llm/：只创建占位目录

Plain Text

assets/
  llama-bin/
    llama-server.exe
  llm/
    *.gguf
  embedding/
    *.gguf                     # 仅 memory 模式需要
  asr/
    SenseVoiceSmall/
  tts/
    openbmb__VoxCPM1.5/
    openbmb__VoxCPM2/
  lora/
  reference/

说明：

• model/vad/silero_vad.onnx 由仓库提供
• LLM GGUF 默认不下载。需要自己挑一个放进 assets/llm/，或者在设置里选本地 GGUF
• assets/llm/ 下只有一个 *.gguf 时，Electron 会自动用它
• assets/llm/ 下至少要有一个 *.gguf，否则 llama-server 起不来
• Hugging Face 下载慢的话，可以先设置 HF_ENDPOINT 指向可用的镜像

只检查资源是否齐全：

PowerShell

npm run verify:assets

4. 启动开发版

PowerShell

npm run dev

这条命令实际执行的是 electron-app/ 下的 npm run dev。启动后核心服务端口一般是：

Plain Text

llama-server:      http://127.0.0.1:8080
memory embedding:  http://127.0.0.1:8081
realtime backend:  http://127.0.0.1:8011
realtime ws:       ws://127.0.0.1:8011/ws/realtime
web client:        http://127.0.0.1:8012/

仓库结构

Plain Text

electron-app/                    # Electron 前端、打包配置、进程编排
realtime/                        # Python 实时后端
llm-module/                      # llama-server 启动与本地客户端
voxcpm-tts-streaming-module/     # VoxCPM TTS 模块
mem0/                            # vendored mem0 SDK 源码
model/vad/                       # Silero VAD 模型
runtime/                         # 便携 Python runtime 说明与产物目录
scripts/                         # 打包、runtime 导出、后端编译脚本
assets/                          # 本地资源目录，不提交 Git
distribution-assets/             # 分发资源整理目录，不提交 Git

常用环境变量

PowerShell

$env:MINIMIND_PYTHON="C:\Users\you\python.exe"
$env:MINIMIND_ASSETS_ROOT="D:\assets"
$env:MINIMIND_LLM_MODEL="D:\models\chat.gguf"
$env:MINIMIND_LLM_BASE_URL="http://127.0.0.1:8080"
$env:MINIMIND_BACKEND_HTTP_BASE="http://127.0.0.1:8011"
$env:MINIMIND_BACKEND_WS_URL="ws://127.0.0.1:8011/ws/realtime"
$env:MINIMIND_ASR_DEVICE="cuda"
$env:MINIMIND_DEBUG_TURNS="1"

MINIMIND_ASR_DEVICE 不设置时默认是 cuda。

可选记忆模块

仓库把 mem0/ 作为源码目录直接放了进来，用来做本地长期记忆。

当前状态：记忆模块还有已知问题，不太稳定，默认关闭。问题修复前建议一直关着。

记忆功能由环境变量 MINIMIND_MEMORY_ENABLED 控制，默认值 0（关闭）。Electron 主进程（electron-app/main.js）根据它决定要不要拉起记忆相关服务，Python 后端（realtime/memory_service.py）也看它决定是否启用。想试试的话（目前仍不稳定）：

PowerShell

$env:MINIMIND_MEMORY_ENABLED="1"
$env:MINIMIND_MEMORY_EMBEDDER_MODEL_PATH="D:\models\embedding.gguf"
$env:MINIMIND_MEMORY_EMBEDDING_DIMS="1024"
npm run dev

补充说明：

• 还有一个 MINIMIND_MEMORY_INFER 开关，控制保存的内容要不要做记忆提取推理。只想关掉记忆提取、保留其他功能，设 MINIMIND_MEMORY_INFER=0
• requirements.txt 已经包含 requirements-mem0.txt，后者会把本地 ./mem0 作为 editable package 安装
• memory 数据默认写入 runtime/mem0/qdrant 和 runtime/mem0/history.db

打包与发布

要构建 Windows 便携版，按这个顺序执行：

PowerShell

# 1. 准备便携 Python runtime
.\scripts\pack_runtime.ps1 -ReplaceExisting

# 2. 编译后端（可加 -PythonExe C:\Users\you\python.exe 显式指定 Python）
.\scripts\build_compiled_backend.ps1

# 3. 生成便携目录
npm run dist --prefix electron-app

输出目录是 electron-app/dist/win-unpacked/。最终分发通常包含两部分：electron-app/dist/win-unpacked/ 和单独准备好的 assets/ 资源目录。

参考项目

• OpenBMB/VoxCPM：流式 TTS 能力来源
• jingyaogong/minimind-o：底层参考
• mem0ai/mem0：长期记忆模块来源

许可证：Apache License 2.0（集成的第三方模块遵循各自许可证）。

相关链接

• GitHub：maomao-2001/Whispera
• 演示视频：Bilibili BV1nFE36mEmc

感谢作者 @maomao-2001 的开源分享，也感谢作者提到的 linux.do 社区。