huangjunsen0406/py-xiaozhi

Open-source AI assistant ecosystem with MCP integrations, multimodal workflows, IoT support, and cross-platform voice interaction.

py‑xiaozhi – 軽量でクロスプラットフォームなマルチモーダルAIフレームワーク

概要 – py-xiaozhi は、リアルタイムで音声を聞き、話し、見て、ハードウェアを制御できるAIアシスタントを構築するための Python ライブラリです。低遅延ストリーミングを実現するために asyncio をベースに構築されており、デスクトップ（Windows/macOS/Linux）および Raspberry Pi、Jetson Nano、Horizon Robotics ボードなどのエッジデバイス上で動作します。

重要性 – このプロジェクトは、大規模言語モデル（LLM）サービスと、デバイス上での知覚（ウェイクワード検出、カメラキャプチャ）および駆動（GPIO、MQTT）を橋渡しします。言い換えれば、多くの個別のツールを組み合わせることなく、エンボディドAI（身体性AI）、音声アシスタント、またはロボットのプロトタイプのための「脳と体」のスタックをすぐに利用できるようにします。

コア機能

機能	内容
リアルタイム音声AI	Opus エンコードのオーディオストリーミング、20ms 未満のレイテンシ、マイクとスピーカーの非同期処理。
オフラインウェイクワード	Sherpa-ONNX キーワード検出がローカルで動作するため、インターネットなしでアシスタントを起動できます。
視覚と言語	カメラキャプチャと視覚言語モデル（画像理解 / シーン認識）の統合。
MCP ツールエコシステム	音楽再生、スクリーンショット、天気、音量調節などのユーティリティを公開する JSON-RPC 2.0 「ツール」サーバー。
クロスプラットフォーム UI	PySide6 + QML によるグラフィカル UI、純粋な CLI モード、およびヘッドレス埋め込みボード用の GPIO のみモード。
セキュアな通信	TLS/WSS を備えた WebSocket または MQTT、自動再接続、およびデバイスフィンガープリント認証。
プラグインアーキテクチャ	イベント駆動型の非同期コア、依存注入コンテナ、新しいツール、プロトコル、または UI プラグインの簡単な追加。
IoT / ロボティクス対応	直接的な GPIO アクセス、MQTT ブリッジ、およびセンサー/アクチュエータ統合のためのモジュール設計。

代表的なユースケース

デスクトップ音声アシスタント – フローティングアバターを表示し、音声コマンドを処理し、音楽を再生し、天気を表示するなどの GUI を備えたノートPCやPC上で実行。
エッジロボットコントローラー – Raspberry Pi や Jetson Nano にデプロイし、ウェイクワードで聞き取りを開始し、カメラフレームを処理し、GPIO 経由でモーターを駆動。
スマートホームハブ – MQTT を介して他のデバイスに接続し、LLM が自然言語の意図解析を行う一方で、ツール API（例：ライトのオン/オフ）を公開。
研究用プロトタイプ – ゼロから仕組みを構築することなく、マルチモーダル・パイプライン（音声 → LLM → 視覚 → 駆動）を迅速にプロトタイプ化。

はじめに (クイックスタートガイド)

# 1. リポジトリをクローン
git clone https://github.com/huangjunsen0406/py-xiaozhi.git
cd py-xiaozhi

# 2. 依存関係のインストール (推奨: uv、さもなくば pip)
uv sync                # 基本インストール (CLI / GPIO モード)
# uv sync --extra gui   # グラフィカル UI 用の PySide6 を含む
# pip install -e.      # pip ユーザー向けの代替手段

# 3. アシスタントを実行
# GUI モード (extra がインストールされている場合のデフォルト)
python main.py

# CLI のみモード (GUI なし、ヘッドレスボードに便利)
python main.py --mode cli

# 通信プロトコルを選択 (デフォルトは WebSocket)
python main.py --protocol mqtt

ドキュメント – 完全なスタートアップチュートリアル、設定リファレンス、および API ドキュメントは https://huangjunsen0406.github.io/py-xiaozhi/ で公開されています。Bilibili にビデオ解説もあります。

アーキテクチャの概要

イベント駆動型非同期コア (asyncio ループ) – すべての I/O（オーディオ、ネットワーク、カメラ）がブロッキングなしで実行されます。
レイヤード設計 – アプリケーションロジック → プロトコル層 (WebSocket/MQTT) → UI 層 (PySide6/CLI/GPIO)。
依存注入 – ブートストラップコンテナがコンポーネントを作成・接続し、プラグインの追加を容易にします。
セキュリティ – TLS 暗号化チャネル、デバイスフィンガープリント、およびツールごとの権限チェック。

フレームワークの拡張

新しい MCP ツールを追加する – 必要な JSON-RPC メソッドを実装した Python モジュールを src/mcp/tools/ の下に配置します。
新しいプロトコルをサポートする – src/protocols/ にある抽象 Protocol クラスをサブクラス化して登録します。
プラグインを作成する – src/plugins/ にコードを配置し、プラグインマニフェストで宣言します。コアが自動的にロードします。

コミュニティ & サポート

スポンサー – GitDo.net, Token能量站, 良心AI (Claude, Gemini, GPT などの集約された API キーを提供)。
貢献 – ワークフローについては CONTRIBUTING.md を参照してください。プロジェクトは典型的な PR レビュー・CI サイクルに従っています。
デモ – 短い Bilibili ビデオで UI と音声インタラクションを紹介しています。

ライセンス

py-xiaozhi は寛容な MIT License の下でリリースされています。

結論 – LLM チャット、音声 I/O、視覚、およびハードウェア制御を組み合わせた、準備済みの async-first な Python スタックが必要な場合、py-xiaozhi は GUI とヘッドレスの両方のオプションを備えた、堅実なクロスプラットフォームの基盤を提供します。