内容
# mcp-voice
本地语音代理：**语音转文本** → **Gemini 2.5 Flash** (+ **MCP 工具**) → **Jarvis 文本转语音**.
| 模式 | 最适合 |
|---|---|
| **Docker Compose (CPU)** | Windows 和 Mac 共用 |
| **原生 Windows + CUDA** | 最快的文本转语音 |
| **原生 Mac (MPS/CPU)** | Apple Silicon |
## 与代理对话（第三阶段）
终端 1 — 网关：
```bash
# 在安装 venv、依赖项和 voices/jarvis_conds.pt 以及在 .env 中设置 GEMINI_API_KEY 后
uvicorn apps.gateway.main:app --host 0.0.0.0 --port 8000
```
终端 2 — Jarvis Orb UI：
```bash
cd apps/jarvis-orb
npm install
npm run dev
```
打开 **http://127.0.0.1:5173** → 按住 **说话** → 松开 → 听到 Jarvis 的回复。
### 简易工作坊模式（无网关）
如果与会者只需要一个最小的本地流程（代理 + MCP 工具 + 语音），跳过 FastAPI/UI 并运行一个脚本：
```bash
python scripts/voice_agent_cli.py --text "记住我的工作坊是星期五" --print-tools
```
或使用音频输入：
```bash
python scripts/voice_agent_cli.py --audio-in sample.wav --audio-out reply.wav --print-tools
```
此方法使用相同的核心管道模块，但避免在工作坊期间使用 HTTP 路由/websocket。
### 可选：唤醒词（"嘿 Jarvis"）
说 "嘿 Jarvis" 而不是按住按钮。使用 [openWakeWord](https://github.com/dscripka/openWakeWord) 的预训练 `hey_jarvis` 模型，完全在网关（CPU via ONNX Runtime — 无需账号、无需 API 密钥、无需每位与会者注册）本地运行。唤醒词监听的麦克风流除发送到您自己的网关进程外，不会离开您的机器。
模型会在网关启动时自动下载（需要互联网一次；之后会缓存）。在 UI 中点击 **启用唤醒词**，然后说 "嘿 Jarvis" 后面跟着您的请求 — 它会在您安静后自动停止录音。如果出现 `WAKE WORD UNAVAILABLE`，请在网关日志中检查下载/加载警告。
### MCP 工具（无需额外 API 密钥）
| 工具 | 功能 |
|---|---|
| `web_search` | 搜索网络（工作坊 TODO 框架） |
| `notes` | 带有 action=add/list/search 的统一记忆工具（工作坊 TODO 框架） |
如果 Gemini 在运行时失败，并且配置了 Groq 回退，则回退路径也会运行相同的工具集，然后再回答。
### 快速查找工作坊 TODO
使用 VS Code 搜索所有编码检查点：
- 查询：`TODO(Workshop|:)`
- 正则表达式：开启
- 包含文件：`apps/gateway/**,mcp_servers/assistant/**`
另请参见 `WORKSHOP_TODOS.md` 中的与会者检查清单。
尝试说：
- “孟买的天气怎么样？”
- “有关 AI 芯片的新闻有哪些？”
- “搜索最新的 AI 芯片头条新闻。”
- “记住我的工作坊是星期五。”
- “您有给我保存什么笔记吗？”
独立 MCP 服务器（用于 Cursor / 其他 MCP 客户端）：
```bash
python -m mcp_servers.assistant.server
```
---
## 快速开始（Docker）
```bash
cp .env.example .env # 设置 GEMINI_API_KEY
# voices/jarvis-5s.wav (>5s)
docker compose build
docker compose run --rm gateway python scripts/build_jarvis_conds.py --device cpu --backend turbo
docker compose up
```
`docker compose up` 现在启动两个服务：
- `gateway`（FastAPI on `:8000`）
- `mcp-server`（用于外部 MCP 客户端的_stdio MCP 服务器）
如果您只想要 HTTP 网关：
```bash
docker compose up gateway
```
如果您只想要独立的 MCP 服务器：
```bash
docker compose up mcp-server
```
UI 仍然在主机上运行：
```bash
cd apps/jarvis-orb && npm install && npm run dev
```
### NVIDIA GPU Docker（仅限 Windows/Linux）
```bash
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up --build
```
仅在 GPU 主机上使用网关：
```bash
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up --build gateway
```
---
## 原生设置（无 Docker）
Python **3.11 或 3.12**:
```bash
python -m venv .venv
# Windows: .\.venv\Scripts\Activate.ps1
# Mac: source .venv/bin/activate
pip install -U pip wheel
pip install "setuptools>=70,<81"
# Windows NVIDIA:
pip install torch==2.6.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu124
# Mac / CPU:
# pip install torch==2.6.0 torchaudio==2.6.0
pip install -r requirements.txt
cp .env.example .env # GEMINI_API_KEY, TTS_DEVICE=auto
python scripts/build_jarvis_conds.py --device auto --backend turbo
uvicorn apps.gateway.main:app --host 0.0.0.0 --port 8000
```
然后像上面一样启动 `apps/jarvis-orb`。
### 提高转录速度/质量（推荐首选）
网关现在通过 `.env` 支持 STT 调优：
```bash
# 模型
WHISPER_MODEL=medium.en
# 解码配置文件：fast | balanced | accurate
STT_PROFILE=balanced
# 自动选择 int8_float16 on cuda，int8 否则
STT_COMPUTE_TYPE=auto
# 强制英语以获得更好的速度/稳定性（或使用自动）
STT_LANGUAGE=en
# 去除静音并调整搜索宽度
STT_VAD_FILTER=true
STT_BEAM_SIZE=2
```
NVIDIA + conda 上的推荐低延迟设置：
```bash
WHISPER_MODEL=medium.en
STT_DEVICE=cuda
STT_PROFILE=fast
STT_COMPUTE_TYPE=auto
STT_LANGUAGE=en
STT_VAD_FILTER=true
STT_BEAM_SIZE=1
```
如果 GPU 内存仍然紧张，请使用 `small.en` 和 `STT_PROFILE=fast`。
---
## API
| 方法 | 路径 | 目的 |
|---|---|---|
| GET | `/health` | 状态 + MCP 工具列表 |
| POST | `/stt` | 音频 → 文本 |
| POST | `/tts` | 文本 → wav |
| POST | `/v1/turn` | 音频 → 转录 + 工具 + 回复 + wav |
| POST | `/v1/turn/text` | 文本 → 工具 + 回复 + wav（调试） |
| WS | `/ws/turn` | 二进制音频输入 → JSON 事件输出 |
---
## 布局
```
apps/gateway/ FastAPI + STT/TTS + Gemini 代理 + 工具
apps/jarvis-orb/ React orb UI（语音 + 唤醒词）
mcp_servers/ MCP stdio 服务器（相同工具）
data/notes.db 已保存的笔记（运行时创建）
voices/ jarvis wav + conds
scripts/ 烟雾测试
```
工作坊指南：参见 `WORKSHOP.md`。
## 阶段状态
- [x] 第一阶段 — STT + TTS + conds
- [x] 第二阶段 — Gemini 转管道
- [x] 第三阶段 — MCP 工具 + React 语音 UI
