SF32 Xiaozhi音声アシスタント¶

Xiaozhiとは¶

Xiaozhiは、MCPベースのオープンソース音声チャットボットです。2025年にESP32実装を通じて広く知られるようになりました。音声対話デバイスとクラウドの大規模モデルサービス、デバイス側またはクラウド側のMCP拡張を組み合わせており、単なるテキストチャットアプリではなく、対話型AIハードウェアを開発するための実用的な出発点です。

SF32実装を選ぶ理由¶

78/xiaozhi-sf32はSF32向け実装ですが、接続方式は意図的に異なります。元のESP32プロジェクトはWi-Fiなどの直接ネットワーク接続をサポートしますが、SF32版はBluetooth Classic上のBluetooth PANを使い、ペアリング済みスマートフォンからインターネット接続を得ます。これにより広域ネットワーク接続の負荷をデバイスからスマートフォンへ移せるため、スマートフォンにテザリングする製品では、通信に伴うデバイス側の消費電力を大きく抑えられる可能性があります。実際の削減量は、スマートフォン、無線状態、対話のデューティー比、電源方針によって異なります。この構成は、ペンダント、バッジ、小型アシスタント、小型ウェアラブルなど、バッテリー駆動の個人向け携帯製品に特に適しています。

このプロジェクトが製品開発の参考として特に有用なのは、別々に扱われがちなディスプレイ／オーディオハードウェア、スマートフォン経由のネットワーク、クラウド音声サービス、ユーザー向けの利用開始手順、デバイス制御、製品出荷後の更新を一つにつないでいる点です。

目標、対象範囲、開始条件¶

このページでは、この参考実装を製品開発の方向性へ適応させるための一連の手順を示します。Xiaozhiがデバイス上でオフライン動作するLLMであること、上流の全機能について量産に必要な検証が完了していること、対応開発ボードが量産向け完成品と同等であることを主張するものではありません。デバイスはペアリング済みスマートフォンからBluetooth PAN経由でインターネットに接続し、対話処理にはXiaozhiのクラウドサービスを使用します。製品化を決定する前に、サービスの利用条件、アカウント管理、プライバシー、セキュリティ、費用、可用性、地域適合性を確認してください。

目標： スマートフォン経由で設定でき、クラウドを介した対話を完了し、安全なデバイス機能を1つ制御し、PAN接続断から復旧する音声／ディスプレイアシスタントを再現可能な形で構築します。カスタムハードウェアを開発すべきか判断するための証跡も残します。

対象読者： SF32の基準構成をすでにビルド・書き込みでき、C／C++、ボード回路図、Bluetooth設定、クラウドサービス統合に取り組めるファームウェア、ハードウェア、製品エンジニア。

ハードウェアとソフトウェアの仕様¶

以下のマニフェストは、SiFliが公開する外部ディスプレイ／オーディオ回路を備えたSF32LB52-DevKit-Nano-R16N16 V1.0.0を、具体的なソースビルド基準として定義します。すべてのXiaozhi対応ボードに共通するBOMではありません。DevKit-ULP、DevKit-LCD、またはXiaotangyuanを選ぶ場合は、ハードウェアマニフェスト全体をそのボードの資料にある構成へ置き換え、正確な仕入先部品とボードリビジョンを記録してください。

ハードウェア仕様¶

上記のサードパーティー部品URLは公式SiFli Nanoガイドに掲載されたマーケットプレイスのリンクであり、メーカーの恒久的な部品番号を保証するものではありません。評価した部品の注文記録または画面コピーを保管し、製品設計前にマーケットプレイス依存を適格性を確認した仕入先の型番とデータシートに置き換えてください。

ソフトウェア仕様¶

サポート対象の基準構成を選ぶ¶

SiFliのXiaozhiクイックスタート資料では、プリビルドファームウェアの対象としてSF32LB52-DevKit-ULP（Huangshan）、SF32LB52-DevKit-LCD、SF32LB52-DevKit-Nano、Xiaotangyuanプラグインボードの4種類が案内されています。ソースビルド資料に現時点で掲載されているのはDevKit-ULP、DevKit-LCD、DevKit-Nanoです。ソースのカスタマイズが要件なら、ソースビルド資料にあるボードを選択してください。プリビルドイメージがあるからといって、ソースビルド手順も公開されているとは限りません。

プロジェクトの開発段階と判断ポイント¶

各段階は機能チェックリストではなく、判断ポイントとして使ってください。次の判断をレビュー可能かつ再現可能にする成果物を、各段階で残します。

システム構成と依存関係¶

flowchart LR
    U["ユーザー：ウェイクワードまたは対話キー"] --> D["SF32LB52デバイス\nマイク、UI、ローカル制御"]
    D --> E["オーディオパイプライン\nOPUS／有効時はAEC・VAD"]
    D <-->|"Bluetooth ClassicのPAN\nBNEP + IP"| P["ペアリング済みスマートフォン\nBluetoothによるインターネット共有"]
    P <-->|"WebSocket、選択されたHTTP API"| S["Xiaozhiクラウドサービス\nストリーミングASR／LLM／TTS"]
    S --> P --> D
    D --> O["スピーカー、ディスプレイ、\nデバイス側MCPアクション"]

公式アーキテクチャガイドでは、ネットワーク経路としてBluetooth Classic上のBluetooth PANと、デバイス上の軽量IPネットワークを説明しています。アプリケーションのリアルタイム通信にはWebSocketを主に使用し、一部のAPI操作にはHTTPを使います。SiFliの概要ページでは、キーワードウェイクアップ（KWS）、連続対話、AEC/VAD、動的表情、ベクターフォント、ローカルMCPが実装済み機能として挙げられています。ほかの公式資料では、画面UI、バッテリー／電源動作、クラウド側MCP拡張、PAN OTAも説明されています。具体的な対応状況は、選択したボードとファームウェアで確認してください。

この構成には個別に診断すべき4つの故障領域があります。ローカルのハードウェア／オーディオ、BluetoothペアリングとPAN、インターネット／クラウドサービスへの到達性、アプリケーション／サービス設定です。BLEのペアリング成功だけでは、ボードがインターネットへ接続できたことや音声サービスがアクティベートされたことを確認できません。

段階1 — 未変更のリファレンス基準構成を確立する¶

1. ボード固有の公式ハードウェア設定を完了します。DevKit-LCDの場合、指定AMOLED／FPC構成、SPKへのスピーカー接続、ウェイク／対話用KEY1、長押し電源オフ用KEY2が含まれます。
2. 公式Xiaozhi手順に従って、対応するプリビルドファームウェアを書き込みます。クイックスタートガイドではUI書き込みツールが推奨されており、そのガイドの時点ではファームウェアv1.4.0以降をターミナルから書き込む方法はサポートされないと説明しています。
3. ペアリング前にスマートフォンのBluetoothインターネット共有を有効にします。sifli-panデバイスとペアリングした後、ボードUIとスマートフォンの共有状態を確認し、単なるBluetoothペアリングではなくPANが有効であることを確認します。iOSでは、sifli-panが表示されない場合にスマートフォンの再起動が必要になることがあると公式ガイドに記載されています。
4. xiaozhi.meのXiaozhiコンソールで、公式アクティベーション手順に従います。エージェントを作成／設定し、ボードに表示されるデバイスコードを追加します。
5. ボードの対話キーまたは設定したウェイク方法で対話を1回実行します。ファームウェアバージョン、ボード、スマートフォンの機種／OS、サービスのアカウント／エージェントIDをプロジェクト記録に残します。

ゲート1の終了条件： コールドブート後にPANへ接続してアクティベーション済みと認識し、対話リクエストを受け付けて応答を再生し、想定どおりのUI状態を表示すること。

段階2 — 復旧と製品上重要な動作を確認する¶

ソースを変更する前に、次の試験を実施してください。これによりデモを信頼できる基準構成にします。

公式ガイドでは、ボードごとのデフォルトbattery_table.cカーブが別のバッテリーでは不正確な場合があると警告しています。製品用バッテリーでは、仕入先の充放電データを入手するか実測し、charging_curve_tableとdischarge_curve_tableを更新して再ビルドし、バッテリー試験を繰り返してください。

ゲート2の終了条件： すべての試験結果が記録され、故障領域ごとに原因を区別でき、各文書化された復旧方法が再書き込みや手動状態修復なしに動作すること。

段階3 — 再現可能なソースの基準構成を整える¶

リポジトリーにはSiFli-SDKがサブモジュールとして含まれています。再帰的にクローンし、XiaozhiコミットとSDKサブモジュールのコミットの両方を記録してください。

git clone --recursive https://github.com/78/xiaozhi-sf32.git
cd xiaozhi-sf32
git checkout 1d3ef641ace47fae68227e9173647fd5db01f6f5
git submodule update --init --recursive
cd sdk
# Windows: .\install.ps1, then .\export.ps1
# macOS/Linux: ./install.sh, then . ./export.sh

公式DevKit-ULPのスクリプトビルド例では、資料に記載された外部ボードパスを指定してapp/projectからビルドします。

scons --board=sf32lb52-lchspi-ulp --board_search_path="../boards" -j8

正確なターゲットと書き込みスクリプトは、ボード別の公式ビルドページを参照してください。ULPのボード名や生成物のパスを別ボードに流用してはいけません。再現可能なビルド記録には、ホストOS、ツール導入結果、エクスポート済み環境、ボード引数、上流／SDKリビジョン、ビルドログ、書き込みイメージ、シリアルログを含めます。

ゲート3の終了条件： 2台目のマシン、またはビルドディレクトリーを削除した後のクリーンチェックアウトから生成したイメージが、段階2の全試験に合格すること。

段階4 — 意図的に変更する¶

一度に1つだけ変更し、合格済みの基準イメージを保管してください。公式カスタマイズ資料では、Bluetooth名、静止画／アニメーション、フォント、PAN DFU、MCPを扱っています。

デバイス側MCPでは、公式ガイドはapp/src/mcp/mcp_server.ccにあるMcpServer::AddCommonTools()を使用しています。LLMから要求されたアクションは信頼できないリクエストとして扱ってください。コールバックで範囲と状態を検証し、出力のデフォルトを安全な状態にし、製品固有の認可なしに取り消し不能、危険、またはセキュリティ上重要な制御を公開しないでください。

PAN OTAの公式資料では、コード、画像アセット、フォントアセットの3種類を個別に配布でき、イメージのアドレスとサイズはパーティションテーブルを使うよう案内しています。量産OTAをユーザーに提供する前に、バージョン方針、サーバーアクセス制御、完全性検証、中断試験、有線またはローカルでの復旧経路を用意してください。

ゲート4の終了条件： 選定した変更、そのロールバック／復旧経路、該当する回帰試験のすべてが記録され、元の対話ループとデバイスアクションの安全境界が引き続き合格すること。

段階5 — 製品化準備のレビュー¶

チームが次のすべてに回答できるまでは、カスタムハードウェアに進まないでください。

• 正確なPANセットアップ手順に対応するスマートフォン／OSのバージョンはどれですか。対応しない場合の代替手段は何ですか。
• 使用するクラウドエンドポイント、アカウント、エージェント、MCPエンドポイント、認証情報は何ですか。誰が所有し、ローテーションしますか。
• デバイス／音声／ユーザーデータのうち、何がデバイス外へ送信されますか。同意をどう得て、保持期間や地域要件にどう対応しますか。
• 想定するバッテリーと筐体で、対話中、接続アイドル、スリープ、充電、ウェイク時の電流の実測値はいくらですか。
• 更新失敗、スマートフォン紛失、クラウド停止、アセット破損、設定誤りから、デバイスをどう復旧しますか。
• 上流コード、サービス、モデル動作、OTA基盤のうち、製品チームが管理するものと外部プロバイダーが管理するものは何ですか。

ゲート5の終了条件： 回答、担当者、残存リスクが記録され、製品チームが受容していること。未解決の項目には緩和策、明示的な延期、または中止の判断が必要です。

製品設計への引き継ぎ¶

選定したSF32型番、電源構成、ディスプレイ／オーディオ設計、RF方針、ストレージ／パーティション計画、量産試験、復旧に関する前提を量産設計へ引き継いでください。SF32LB52製品統合手順で、適切なチップ、モジュール、ボード、ガイド、チェックリストを選定します。

プロジェクトの完了条件： 新しいチームメンバーが選定した基準構成を再現し、観測した各故障の担当者または復旧経路をたどり、カスタマイズしたイメージを再ビルドし、カスタムハードウェアの判断に必要な証跡をレビューできた時点で、この参考実装は役割を果たしたといえます。その時点で、これは量産へそのまま持ち込む未検証のデモではなく、製品開発の参考実装となります。

主な情報源¶

• 78/xiaozhi-esp32リポジトリー
• 78/xiaozhi-sf32リポジトリー
• SiFli Wiki: AI Xiaozhi概要（中国語）
• SiFli Xiaozhiクイックスタート
• SiFli Xiaozhiソースビルド
• SiFli Xiaozhiアーキテクチャ
• SiFli Xiaozhiカスタマイズ
• SiFli Xiaozhi DFU_PANガイド
• SiFli Xiaozhi MCPガイド

最終更新: 2026-10-19