pollen-robotics/reachy_mini_conversation_app

Reachy Mini 会話アプリ – 概要

目的 – Reachy Mini ロボットと会話できる Python アプリケーションです。音声を Hugging Face のリアルタイム音声モデルにストリーミングし、文字起こしされたテキストを大規模言語モデル（LLM）アシスタントに送信し、アシスタントの応答をロボットのアクション（ダンス、頭の動き、感情など）に変換します。

主な機能

低遅延音声 – Hugging Face のリアルタイムバックエンド（またはローカルホストのエンドポイント）を使用して、音声からテキスト、テキストから音声を実現します。
視覚統合 – camera ツールはフレームをキャプチャし、同じリアルタイムバックエンドに送信して画像分析を行います。
モーション合成 – キューシステムが高レベルの動き（ダンス、ポーズ、呼吸）を処理し、「揺れ」レイヤーが音声のリズムに反応します。
ツールエコシステム – LLM は一連の ツール（例：dance、move_head、remember、ウェブ検索、天気）を呼び出すことができます。これらはローカルの Python モジュールまたはリモートの Hugging Face Spaces です。
パーソナリティプロファイル – 各プロファイルはプロンプト、音声、挨拶、デフォルトツールを定義します。オプションの Web UI を使用して、その場でパーソナリティを切り替えることができます。
長期メモリ – ユーザーに関する永続的な事実をオプションで保存し、アシスタントがセッションをまたいで思い出すことができます。
ローカル VAD と割り込み – オプションの Silero 音声アクティビティ検出がデバイス上で実行され、割り込み処理を高速化し、ロボットのリスニングをスムーズにします。

仕組み（アーキテクチャ概要）

ユーザーが話す → マイク音声（16 kHz）が Hugging Face リアルタイムサービスに送信されます。
サービスは文字起こしと、オプションで合成された応答を返します。
文字起こしされたターンは LLM アシスタントに送られ、アシスタントは ツール を要求する場合があります。
アプリはツールを実行し（例：ロボットの頭を動かす、感情クリップを再生する、ウェブを検索する）、結果を LLM に返します。
LLM の最終的な回答がユーザーに読み上げられ、モーション合成をトリガーする場合があります。

リポジトリ内の図（conversation_app_arch.svg）がこれらのコンポーネントを視覚化しています。

はじめに

前提条件

Reachy Mini SDK を最初にインストールする必要があります（リンクされたリポジトリを参照）。
Python 3.12 と、依存関係管理のための uv（推奨）または pip。
オプション：ホスト型サービスを使用したくない場合は、ローカルの Hugging Face リアルタイムエンドポイント。

インストール（uv の例）

uv venv --python /opt/homebrew/bin/python3.12 .venv
source .venv/bin/activate
uv sync               # ランタイム依存関係をインストール
uv sync --group dev  # 開発ツールをインストール（オプション）

（または、従来の python -m venv + pip install -e . ワークフローを使用します。）

設定

.env.example を .env にコピーし、次のような変数を調整します：

HF_REALTIME_CONNECTION_MODE – deployed（デフォルト）または local。
HF_REALTIME_WS_URL – セルフホストバックエンドの WebSocket URL。
LOCAL_VAD_ENABLED / LOCAL_BARGE_IN_ENABLED – デバイス上の音声検出と割り込みを切り替えます。
REACHY_MINI_MEMORY_ENABLED – 永続メモリをオン/オフにします。

Web UI で編集された設定は settings.json に永続化され、.env のデフォルトを上書きします。

アプリの実行

reachy-mini-conversation-app          # コンソールのみのモード
reachy-mini-conversation-app --ui    # Web UI も起動（http://127.0.0.1:7860/）

Reachy Mini デーモンが最初に実行されていることを確認してください。そうしないと TimeoutError が表示されます。

CLI フラグを使用すると、カメラを無効にしたり（--no-camera）、ネットワーク上の特定のロボットを選択したり（--robot-name）、詳細なデバッグを有効にしたり（--debug）できます。

ツール – アシスタントができること

ツール	機能	場所
`dance` / `stop_dance`	公開ダンスライブラリデータセットからダンスシーケンスをキューに入れるかクリアします。	コアインストール
`play_emotion` / `stop_emotion`	感情ライブラリデータセットから短い感情オーディオクリップを再生します。	コアインストール
`camera`	フレームをキャプチャし、リアルタイムバックエンドで実行します（カメラが必要）。	コアインストール
`move_head` / `head_tracking` / `sweep_look`	頭の姿勢を制御するか、顔を追跡します。	コアインストール
`remember` / `forget`	ユーザーに関する短い事実を保存または削除します（`memory.v1.json` に永続化）。	コアインストール
`volume_control`	ロボットデーモンを介してスピーカーまたはマイクの音量を取得/設定します。	コアインストール
`robot_status`	ロボットのメタデータ（ソフトウェアバージョン、Wi-Fi IP、IMU、インストール済みアプリ）を照会します。	コアインストール
`pollen_robotics_reachy_mini_search_tool__search_web`	事前公開された Hugging Face Space を介したウェブ検索。	リモート Space
`pollen_robotics_reachy_mini_weather_tool__get_weather`	現在の天気の検索。	リモート Space
`pollen_robotics_reachy_mini_time_tool__get_time`	タイムゾーン対応の時計情報。	リモート Space
`pollen_robotics_reachy_mini_knowledge_tool__*`	会社/製品の FAQ とドキュメント検索。	リモート Space

Tool をサブクラス化する Python モジュールを作成し、src/reachy_mini_conversation_app/tools/ に配置することで、ローカルツール を追加できます。リモートツールは、MCP API を実装する Hugging Face Space をインストールすることで追加されます。

カスタムプロファイルとパーソナリティ

プロファイルは profiles/ の下にあります（または REACHY_MINI_CUSTOM_PROFILE で指定されたカスタムディレクトリ）。各プロファイルには profile.md ファイルが含まれています：

プロンプト（Markdown 本文）で、アシスタントのペルソナを形成します。
オプションのメタデータ（voice、greeting、default_tools）。
UI から非表示にするための hidden フラグ。

UI を使用すると、プロファイルの作成、選択、編集、およびパーソナリティごとの個々のツールの有効/無効を切り替えることができます。

高度なトピック

ローカル VAD：Silero VAD モデル v6.2.1 は初回実行時にダウンロードされ、キャッシュされ、ONNX Runtime で実行され、サブ秒の検出を実現します。
割り込み：有効にすると、ロボットは応答中にユーザーが話しているのを検出した場合、再生音量を下げ、スムーズな割り込みを可能にします。
デバッグ診断：--debug は /static/vad-monitor.html と、VAD 確率と状態変化をストリーミングする /rpc WebSocket を公開します（レイテンシの調整に役立ちます）。
複数のロボット：--robot-name を使用して、同じサブネット上の特定のデーモンを指定します。

誰がこれを使うべきか？

研究者 具現化された対話エージェントを構築する人。
教育者 物理ロボットでマルチモーダル AI（音声、視覚、動作）をデモする人。
ホビイスト 拡張可能なツールプラグインを備えたプラグアンドプレイの音声制御ロボットを望む人。

ライセンス

このリポジトリは MIT ライセンス の下でリリースされています（LICENSE を参照）。