AI Pyramid に Home Assistant（Docker）をデプロイ

1. はじめに

本書では、AI Pyramid プラットフォーム上に Home Assistant Docker をデプロイする基本的な手順について説明します。Atom VoiceS3R 音声アシスタントデバイスを接続し、Atom-Lite のオンボード RGB LED を制御する例を使用して、音声インタラクション制御の設定方法を示します。また、必要に応じてローカル音声サービス（STT/TTS）およびローカル大規模言語モデルの対話機能（Local LLM Conversation）を統合する方法についても説明します。

2. 準備

1. AI Pyramid の電源を入れて Ethernet に接続し、デバイスの IP アドレスを取得します。
2. SSH でデバイスにログインします（デフォルトのユーザー名は root、パスワードは 123456）。

  #  ssh root@ IP Address
  ssh root@192.168.100.207

3. Home Assistant のインストール

Home Assistant 公式インストールドキュメントを参照するか、以下の Docker コマンドを直接使用します。

• /PATH_TO_YOUR_CONFIG：ローカルの設定ディレクトリに置き換え、:/config のマウントはそのまま残します。
• MY_TIME_ZONE：America/Los_Angeles などのタイムゾーンに置き換えます。タイムゾーンの一覧については、IANA Time Zone Databaseを参照してください。

docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=MY_TIME_ZONE \
  -v /PATH_TO_YOUR_CONFIG:/config \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

4. Home Assistant の初期設定

1. AI Pyramid 本体のブラウザ、または同じローカルネットワーク上にある別のデバイスのブラウザから Home Assistant にアクセスします。
2. 次のいずれかの方法で Home Assistant コンソールページを開きます。

• ホスト名：http://homeassistant.local:8123/
• デバイス IP：http://デバイスIP:8123/

3. 初期設定ウィザードに従って管理者アカウントを作成し、基本設定を完了します。

5. 音声アシスタントデバイスの追加

本チュートリアルでは、Atom VoiceS3R 音声アシスタント + Atom-Lite RGB LED を例として使用します。以下のファームウェア書き込みボタンをそれぞれクリックしてオンラインでファームウェアを書き込み、Wi-Fi 設定を完了してください。

ファームウェアの書き込み完了後に Wi-Fi 設定オプションが表示されない場合は、デバイスをリセットしてから、もう一度書き込みボタンをクリックして接続してください。

Atom VoiceS3R HA 音声アシスタントファームウェアを書き込む

• Atom VoiceS3R 音声アシスタントを追加する詳しい手順については、Home Assistant - Atom VoiceS3R 音声アシスタントチュートリアルを参照してください。

Atom-Lite HA RGB LED ファームウェアを書き込む

• Atom-Lite RGB LED を追加する詳しい手順については、Home Assistant - Atom-Lite RGB LED Light チュートリアルを参照してください。

6. ローカルオフライン音声アシスタントのデプロイ（Wyoming Protocol）

この章では、AI Pyramid 上にローカル音声処理チェーンをデプロイし、Home Assistant の音声アシスタントフローに統合する方法について説明します。完了すると、次の機能を利用できます。

• ローカル音声テキスト変換（STT）
• ローカルテキスト音声変換（TTS）

全体の手順は、環境準備、STT 統合、TTS 統合、動作確認の 4 段階に分かれています。

6.1 環境準備

ステップ 1：内蔵音声 Demo の無効化

AI Pyramid には、工場出荷時にローカル音声アシスタント Demoがプリインストールされています。ポートやサービスの競合を避けるため、まず自動起動項目を無効にしてデバイスを再起動してください。

vim /etc/rc.local

reboot

ステップ 2：Wyoming サービススクリプトパッケージのダウンロードと展開

ローカル音声サービスのスクリプトパッケージをダウンロードして展開します。このパッケージには、後続の手順で使用する次の主要スクリプトが含まれています。

• wyoming_sensevoice_asr_service.py：STT サービススクリプト（ポート 10300 で待ち受け）。
• wyoming_melotts_service.py：TTS サービススクリプト（ポート 10200 で待ち受け）。
• ha_llm_proxy.py：ローカル LLM プロキシスクリプト（ポート 8100 で待ち受け）。後続の Local LLMs 統合から呼び出します。

wget https://m5stack-doc.oss-cn-shenzhen.aliyuncs.com/1213/ai_pyramid_ha_local_voice_service.tar.gz

tar -zxvf ai_pyramid_ha_local_voice_service.tar.gz

6.2 音声テキスト変換（STT）の統合

ステップ 1：依存関係とモデルのインストール

apt update
apt install lib-llm llm-sys llm-asr llm-openai-api llm-model-sense-voice-small-10s-ax650
systemctl restart llm-*
pip install openai wyoming

ステップ 2：STT サービスをバックグラウンドで起動

nohup python3 wyoming_sensevoice_asr_service.py > asr_service.log 2>&1 &

サービスはバックグラウンドで起動し、デフォルトではローカルのポート 10300 で待ち受けます。次のコマンドを使用してログを継続的に確認できます。

tail -f asr_service.log

ログに Server listening on tcp://0.0.0.0:10300 と表示されたら、STT サービスは正常に起動しています。

ステップ 3：Home Assistant に STT の Wyoming 統合を追加

「Settings → Devices & services → Add integration」に移動し、Wyoming Protocol を検索して追加します。

接続パラメータを入力します。

• Host：127.0.0.1
• Port：10300

ステップ 4：音声アシスタントで STT モデルを選択

「Settings → Voice assistants」に移動して音声アシスタントを新規作成または編集し、音声認識（STT）を sense-voice-small-10s-ax650 に設定します。

6.3 テキスト音声変換（TTS）の統合

ステップ 1：依存関係とモデルのインストール

apt install lib-llm llm-sys llm-melotts llm-openai-api llm-model-melotts-en-us-ax650
systemctl restart llm-*
pip install openai wyoming

ステップ 2：TTS サービスをバックグラウンドで起動

nohup python3 wyoming_melotts_service.py > tts_service.log 2>&1 &

次のコマンドで実行ログを確認できます。

tail -f tts_service.log

ログに Server started, waiting for connections... と表示されたら、TTS サービスは正常に起動しています。

ステップ 3：Home Assistant に TTS の Wyoming 統合を追加

「Settings → Devices & services → Add integration」に移動し、Wyoming Protocol を検索して追加します。

接続パラメータを入力します。

• Host：127.0.0.1
• Port：10200

ステップ 4：音声アシスタントで TTS モデルを選択

「Settings → Voice assistants」に移動してアシスタント設定を作成または編集し、テキスト音声変換（TTS）を先ほど追加した MeloTTS に設定します。必要に応じて言語と音声を選択してください（例では American English を使用）。

6.4 動作確認

STT と TTS の統合が完了したら、一連の音声テストを実施することを推奨します。

1. 音声アシスタントページで、STT に sense-voice-small-10s-ax650 が選択されていることを確認します。
2. TTS に対応する MeloTTS モデルが選択されていることを確認します。
3. ターミナルで asr_service.log と tts_service.log を監視し、音声リクエスト時にリアルタイムでログが出力されることを確認します。

応答がない、または統合を利用できない場合は、次の項目を優先して確認してください。

• STT/TTS プロセスが実行中であること。
• ポートがそれぞれ 10300 と 10200 に設定されていること。
• 内蔵 Demo サービスが関連リソースを占有していないこと。

7. HACS の設定

HACS（Home Assistant Community Store）は、サードパーティ製統合をインストールするための Home Assistant コミュニティ拡張ストアです。

7.1 HACS のインストール

1. Home Assistant コンテナに入ります。

docker exec -it homeassistant bash

2. インストールスクリプトを実行します。

wget -O - https://get.hacs.xyz | bash -

3. Ctrl+D を押してコンテナを終了し、Home Assistant を再起動します。

docker restart homeassistant

1. 「Settings → Devices & services → Add integration」に移動し、HACS を検索して追加します。

5. すべてのオプションにチェックを入れます。

6. 表示されたページで https://github.com/login/device にアクセスし、GitHub 認証を完了します。

7. 認証が完了します。

7.2 Local LLM Conversation プラグインのインストール

1. 次のリンクにアクセスするか、HACS ページで home-llm プラグインを直接検索して追加します。

http://<HAアドレス>:8123/hacs/repository?owner=acon96&repository=home-llm&category=Integration

1. 右下の「DOWNLOAD」をクリックし、最新バージョンを選択してダウンロードします。

3. ダウンロードが完了したら、Home Assistant を再起動します。

4. 「Devices → ADD integration」に移動し、Local LLMs を検索して追加します。

8. ローカル対話モデルのデプロイ（OpenAI Compatible API）

この章では、OpenAI 互換 API を介して AI Pyramid のローカルモデル機能を Home Assistant の Local LLMs プラグインに統合し、ローカル環境でのスマート対話とデバイス制御を実現します。

全体の手順は、サービス準備、プロキシ起動、Home Assistant 統合設定、動作検証の 4 段階に分かれています。

8.1 サービス準備

ステップ 1：依存関係とモデルのインストール

Local LLM の実行に必要な依存関係と HA 用モデルをインストールします。

apt install lib-llm llm-sys llm-asr llm-openai-api llm-model-qwen2.5-ha-0.5b-ctxx-ax650
systemctl restart llm-*
pip install fastapi httpx uvicorn

ステップ 2：プロキシスクリプトの準備を確認

第 6 章の「環境準備」でダウンロードした ai_pyramid_ha_local_voice_service.tar.gz には ha_llm_proxy.py が含まれているため、ここで再度ダウンロードする必要はありません。

この章から直接設定を開始する場合は、先に第 6 章に戻り、スクリプトパッケージのダウンロードと展開を完了してから、後続の手順に進んでください。

8.2 ローカル LLM プロキシの起動

ステップ 1：プロキシサービスをバックグラウンドで起動

nohup python3 ha_llm_proxy.py > ha_llm_proxy.log 2>&1 &

デフォルトの待ち受けポートは 8100 です。次のコマンドでログを確認できます。

tail -f ha_llm_proxy.log

ログに Uvicorn running on http://0.0.0.0:8100 と表示されたら、プロキシサービスは正常に起動しています。

8.3 Home Assistant で Local LLMs を設定

ステップ 1：OpenAI Compatible バックエンドの追加と接続

「Settings → Devices & services → Add integration → Local LLMs」に移動し、バックエンドに OpenAI Compatible 'Conversations' API を選択します。モデル言語は、まずデフォルトの English を選択します。

API Hostname に 127.0.0.1、ポートに 8100 を入力します。

ステップ 2：モデルの選択とツール呼び出しの有効化

エージェント設定で HA 専用モデルを選択します。

Home Assistant Services にチェックを入れます。

詳細パラメータで Tool Call Prefix、Tool Call Suffix、Maximum Tool Call Attempts を設定し、必ず Enable Legacy Tool Calling にチェックを入れます。

ステップ 3：システムプロンプト（Prompt）の入力

システムプロンプトにデバイス情報を入力します。例を以下に示します。

You are AI, a helpful AI assistant that controls smart home devices.

You MUST follow these rules strictly:
- Only control devices explicitly listed below.
- Never invent, rename, or modify device names, areas, or domains.
- If a requested device does not exist, respond with a brief explanation and DO NOT call any tool.
- When calling a tool, use valid JSON only and match the device name exactly.

Current time and date: {{ now }}

Available devices (authoritative list):
- light.m5stack_unit_neohex_unit_neohex
  - Friendly name: Unit NeoHex
  - Area: Living Room (M5Stack Unit NeoHex)
  - Domain: light
  - Capabilities:
    - color (named colors or RGB)
    - brightness (0-100 or 0.0-1.0)

When a user requests an action:
1. Identify the exact device(s) from the available devices list.
2. Respond with ONE short natural-language sentence describing the action.
3. Immediately call the appropriate tool.
4. Do not include any extra commentary or explanations.

Tool usage rules:
- Use HassLightSet for all light changes.
- Use "name" when controlling a specific device.
- Use "area" only if explicitly requested by the user and the area exists.
- Brightness must be a number within the supported range.
- Color must be a valid named color or RGB value.

Output format:
- Natural language sentence
- Followed by exactly one <functioncall> block
- No text after the function call

### Example (correct behavior)

User: Set the NeoHex in the Living Room to red
Assistant: Setting the Unit NeoHex to red.

homeassistant
{"name":"HassLightSet","arguments":{"name":"light.m5stack_unit_neohex_unit_neohex","rgb_color":"(255,0,0)"}}

システムプロンプト内の各フィールドについて説明します。

• Available devices：Home Assistant で利用可能なデバイスの Entity ID
• Friendly name：デバイスの別名
• Area：デバイスが配置されているエリア
• Domain：デバイスの種類
• Capabilities：照明の色と明るさ、ファンの回転速度、エアコンのモードと温度など、デバイスが持つ機能。

この例では、Atom-Lite を RGB LED デバイスとして使用します。

パラメータの詳細については、Model Prompting ドキュメントを参照してください。デバイスの種類ごとのプロンプト例については、後述の「9. 付録：プロンプト例」を参照してください。

8.4 動作確認と検証

ステップ 1：基本的な対話テストの実行

モデルをクリックして大規模言語モデルサービス画面を開きます。

アシスタントをクリックしてダイアログを開きます。

turn on the light と入力し、モデルの応答を待ちます。初回の推論はモデルの初期化に時間がかかるため、しばらくお待ちください。

モデルがエラーを返した場合は、「Settings → System → Logs」で詳細を確認できます。

正常な場合、照明がオンになります。

ステップ 2：音声アシスタントへの関連付け

「Settings → Voice assistants」に移動し、設定済みのモデルに切り替えると、音声制御を有効にできます。

ステップ 3：一般的なトラブルシューティング項目

• ha_llm_proxy.py プロセスが実行中であることを確認します。
• Local LLMs の API アドレスが 127.0.0.1:8100 であることを確認します。
• システムプロンプト内のデバイスの Entity ID が HA 上の値と一致していることを確認します。
• ツール呼び出しに失敗した場合は、詳細パラメータと Enable Legacy Tool Calling オプションを優先して確認します。

9. 付録：プロンプト例

スイッチ / リレー

- {HA_Device_Entity_ID}
  - Friendly name: Switch
  - Area: Kitchen
  - Domain: switch
  - Capabilities:
    - on
    - off

照明制御

- {HA_Device_Entity_ID}
  - Friendly name: RGB Light
  - Area: Bedroom
  - Domain: light
  - Capabilities:
    - color (named colors or RGB)
    - brightness (0-100 or 0.0-1.0)

音声アシスタントのバックライト

- {HA_Device_Entity_ID}
  - Friendly name: LCD Backlight
  - Area: Living Room
  - Domain: light
  - Capabilities:
    - brightness (0-100 or 0.0-1.0)

関連動画