coderzc/open-xiaoai-bridge

Open‑XiaoAI Bridge – ミニ・スマートスピーカー Xiaomi XiaoAI と外部AIサービスの橋渡し

何であるか – Python 3.12+ で記述され、Rustクライアントを備えたサーバーサイドコンポーネント。Dockerまたはベアメタル上でホストに実行され、WebSocket経由で修正済みのXiaoAIスピーカーと通信する。スピーカーのマイク/音声ストリームを傍受し、ウェイクワード検出、VAD、オプションのオフラインASRを実行した後、設定可能な複数のAIバックエンドのいずれかに認識されたテキストを転送する。返信は、スピーカーのネイティブTTS、DoubaoクラウドTTS、OpenAI互換TTS、またはローカルのMLX‑Audioモデルを用いて音声に変換され、スピーカーに再生用に送信される。

コア機能（READMEに記載）

機能	機能内容
OpenAI互換サービス	`/v1/chat/completions`エンドポイント（Hermes Agent API Server、OpenAI、Ollama、LM Studioなど）に接続可能。
QwenPaw統合	認識されたテキストをAlibabaのQwenPawエージェントにHTTPコンソールAPI経由で送信し、エージェントの返答を再生。
OpenClaw統合	コマンドをOpenClawゲートウェイにルーティングし、シングルショットおよび継続的マルチターン会話の両方をサポート。
XiaoZhi AI統合	`xiaozhi‑esp32‑server`プロトコルを使用してリアルタイム音声ストリーミングを実現。
カスタムウェイクワード	複数の中国語/英語ウェイクワードを定義可能。各ウェイクワードは異なるAIサービスまたはOpenClawエージェントにマッピング可能。
マルチエージェントルーティング	1台のスピーカー、複数のウェイクワード → 各ウェイクワードが異なる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をコンテナにマウントし、APIをポート9092で公開。

ローカルで実行 – リポジトリをクローン後、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クライアントがPCM音声をWebSocket経由で送信（open_xiaoai_server:4399）。
前処理 – サーバーは受信ストリームに対して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ネットワーク – ブリッジコンテナがホスト上のサービスにアクセスする必要がある場合、Macではhost.docker.internalエイリアスを使用、またはnetwork_mode: hostを設定。
認証 – OPEN_XIAOAI_TOKENを設定すると、Rustクライアント側でも同じトークンが必要。それ以外は任意のクライアントが接続可能。

どのような人に向いているか？

ChatGPT、Claude、LLaMA、カスタムエージェントなどに接続したいXiaoAI愛好家。
低コストで常に稼働するハードウェアフロントエンドが必要な、音声優先エージェント開発研究者。
Xiaomiクラウドに依存せずに、音声でローカルサービス（例：Home Assistant）をトリガーしたいホームオートメーション愛好家。

ライセンスとコミュニティ

ライセンス：MIT（LICENSEを参照）。
スター数：バッジに表示。プロジェクトは積極的にメンテナンス中。
Dockerイメージ：GitHub Container Registry（ghcr.io/coderzc/open-xiaoai-bridge）に公開。
デモ動画：READMEに2つのBilibiliリンクが記載。

まとめ

Open‑XiaoAI Bridgeは、Xiaomi XiaoAIスピーカーが多様な現代のLLM/エージェントサービスのフロントエンドとして動作できる、本格的でオープンソースの統合レイヤーです。ウェイクワード検出、オプションのオフライン音声認識、複数バックエンドへのルーティング、柔軟なTTS出力などをすべて、シンプルなconfig.pyと環境変数で構成可能です。