coderzc/open-xiaoai-bridge

Open‑XiaoAI Bridge – 小米小爱音箱与外部AI服务之间的桥梁

是什么 – 一个基于 Python 3.12+ 编写的服务器端组件（附带 Rust 客户端），可在 Docker 或裸金属环境中运行，通过 WebSocket 与修改过的 XiaoAI 音箱通信。它拦截音箱的麦克风/音频流，执行唤醒词检测、VAD 和可选的离线 ASR，然后将识别出的文本转发到多个可配置的 AI 后端之一。回复通过音箱的原生 TTS、Doubao 云 TTS、OpenAI 兼容 TTS 或本地 MLX‑Audio 模型转换为语音，并通过同一 WebSocket 回传至音箱进行播放。

核心功能（README 中列出）

功能	作用
OpenAI 兼容服务	连接到任何 `/v1/chat/completions` 端点（Hermes Agent API Server、OpenAI、Ollama、LM Studio 等）。
QwenPaw 集成	将识别出的文本通过其 HTTP 控制台 API 发送到阿里云 QwenPaw 代理，并播放代理的回复。
OpenClaw 集成	将命令路由到 OpenClaw 网关，支持单次和持续多轮对话。
XiaoZhi AI 集成	使用 `xiaozhi‑esp32‑server` 协议实现实时音频流。
自定义唤醒词	可定义多个中英文唤醒词；每个唤醒词可映射到不同的 AI 服务或 OpenClaw 代理。
多代理路由	一台音箱，多个唤醒词 → 每个唤醒词选择不同的 OpenClaw 会话，实现“零开销”切换。
持续对话	唤醒后，桥接器保持对话活跃，无需重复唤醒词；说“小爱同学”可中断。
VAD + KWS 前端	语音活动检测（VAD）减少误识别并节省功耗。
HTTP API	远程控制音箱——播放文本、URL、文件，触发 TTS，中断播放，查询状态，健康检查。
模块化设计	每个连接器（XiaoZhi、OpenClaw、OpenAI、QwenPaw、API 服务器、TTS）可通过环境变量开启或关闭。

快速开始（来自 README）

准备音箱 – 刷入支持 SSH 的新固件，并安装 Rust 客户端（packages/client‑rust）。
下载模型 – VAD + KWS（始终需要）以及可选的 Sherpa ASR（如需本地离线转录）。模型 zip 包在发布页面提供。

使用 Docker Compose 运行（推荐）

curl -O https://raw.githubusercontent.com/coderzc/open-xiaoai-bridge/main/config.py
curl -O https://raw.githubusercontent.com/coderzc/open-xiaoai-bridge/main/docker-compose.yml
# 根据需要编辑 config.py / docker‑compose.yml
docker compose up -d

将 ./models 挂载到容器中，并在端口 9092 上暴露 API。

或本地运行 – 克隆仓库后，安装 uv（Python）和 Rust，将模型文件放在 core/models/ 目录下，然后启动：
```
API_SERVER_ENABLE=1 XIAOZHI_ENABLE=1 OPENCLAW_ENABLE=1 OPENAI_ENABLE=1 QWENPAW_ENABLE=1 ./scripts/start.sh
```
可通过 OPEN_XIAOAI_TOKEN 启用基于令牌的客户端认证。
配置服务 – 编辑 config.py。每个后端（openai、openclaw、qwenpaw、xiaozhi）都有一个配置块，用于设置端点 URL、API 密钥、模型名称、TTS 提供商等。

环境变量（摘要）

变量	作用	默认值
`XIAOZHI_ENABLE`	启用 XiaoZhi AI 后端	禁用
`OPENCLAW_ENABLE`	启用 OpenClaw 连接器	禁用
`OPENAI_ENABLE`	启用通用 OpenAI 兼容连接器	禁用
`QWENPAW_ENABLE`	启用 QwenPaw 连接器	禁用
`API_SERVER_ENABLE`	启动 HTTP 控制 API	禁用
`AUDIO_INPUT_ENABLE`	启用麦克风处理（VAD/KWS/ASR 所需）	启用
`API_SERVER_HOST` / `API_SERVER_PORT`	HTTP API 的主机/端口	`127.0.0.1` / `9092`
`OPEN_XIAOAI_TOKEN`	客户端认证共享密钥	无（无认证）
`CONFIG_PATH`	自定义 `config.py` 的路径	`./config.py`
`LOGLEVEL`	日志详细程度	`INFO`

API 服务器（当 `API_SERVER_ENABLE=1` 时）

方法	路径	目的
`POST`	`/api/play/text`	使用选定的 TTS 合成文本并在音箱上播放
`POST`	`/api/play/url`	从公开 URL 流式传输音频文件
`POST`	`/api/play/file`	上传本地音频文件并播放
`POST`	`/api/tts/doubao`	直接调用 Doubao TTS（云语音）
`GET`	`/api/tts/doubao_voices`	列出可用的 Doubao 语音 ID
`POST`	`/api/wakeup`	程序化触发唤醒流程
`POST`	`/api/interrupt`	停止当前播放/TTS
`GET`	`/api/status`	当前播放状态
`GET`	`/api/health`	简单健康检查

示例用法（curl）：

curl -X POST http://localhost:9092/api/play/text \
  -H "Content-Type: application/json" \
  -d '{"text": "你好，我是小爱同学"}'

TTS 提供商优先级

每个后端（openai、openclaw、qwenpaw）可指定 tts_provider：
- xiaoai – 使用音箱内置 TTS（无需额外配置）
- doubao – Volcano Engine 云 TTS（需 app_id/access_key）
- openai – 任意 OpenAI 兼容 /v1/audio/speech 服务
- mlx_audio – 本地 MLX‑Audio 服务器（Apple Silicon 上有用）
若未指定 tts_provider，则使用原始逻辑：XiaoAI 使用原生 TTS，其他则回退至 Doubao。

桥接器工作原理（高层流程）

音频捕获 – 音箱上的 Rust 客户端通过 WebSocket（open_xiaoai_server:4399）流式传输 PCM 音频。
预处理 – 服务器对传入流运行 VAD 和 KWS。当唤醒词匹配时，WakeupSessionManager 启动会话。
ASR – 根据 input_mode 选择：
- local_asr – VAD → Sherpa ASR（离线）→ 文本
- xiaoai_asr – 将音箱的原生 ASR 交由桥接器处理。
路由 – before_wakeup 钩子（可在 config.py 中编辑）可返回如 "openai"、"openclaw"、"qwenpaw" 等字符串，以选择此会话的目标后端。
后端交互 – 选定的连接器将文本发送至远程服务，接收响应，可选地运行 TTS，并通过同一 WebSocket 将音频流回音箱。
持续对话 – XiaoAIConversationController 监控 ASR/AudioPlayer 事件；说“小爱同学”或配置的退出短语可结束会话。

扩展 / 自定义

自定义唤醒词 – 在 KWS 配置中定义新关键词；通过在 before_wakeup 中返回相应标识符，可将每个关键词映射到不同后端。
多代理路由 – 通过为不同 OpenClaw 代理分配不同唤醒词，可实现“即插即用”式代理切换，无需重启桥接器。
Docker 网络 – 若桥接器容器需访问主机上运行的服务，可使用 host.docker.internal 别名（Mac）或设置 network_mode: host。
认证 – 设置 OPEN_XIAOAI_TOKEN 可要求 Rust 客户端使用相同令牌；否则任意客户端均可连接。

谁会使用它？

希望让智能音箱与 ChatGPT、Claude、LLaMA 或自定义代理对话的小爱音箱爱好者。
需要廉价、始终在线硬件前端构建语音优先代理的研究人员。
希望通过语音触发本地服务（如 Home Assistant）而不依赖小米云的智能家居爱好者。

许可与社区

许可证：MIT（见 LICENSE）。
星标数：显示在徽章中；项目持续维护中。
Docker 镜像：发布于 GitHub Container Registry（ghcr.io/coderzc/open-xiaoai-bridge）。
演示视频：README 中提供两个 Bilibili 链接。

总结

Open‑XiaoAI Bridge 是一个真正的开源集成层，使小米小爱音箱能作为多种现代 LLM/代理服务的前端。它处理唤醒词检测、可选的离线语音转文本、多后端路由和灵活的 TTS 输出，所有配置均通过简单的 config.py 和环境变量完成。