liveapi-service

LiveAPI サービススキル

このスキルでは、WebSocket 経由で Gemini Enterprise Live API に接続する LiveAPI クライアントサービスクラスを生成する手順を説明します。生成されるクライアントは、双方向ストリーミング、Application Default Credentials（ADC）によるベアラートークン認証、透過的なセッション再開、ClientMessage / ServerMessage プロトコルバッファのやり取りに対応します。

また、生成したクライアントをユーザーが対話的に検証できるデモ用のフロントエンドとバックエンドサービスも作成します（テキスト、音声、動画、文字起こし、中断処理）。

前提条件

生成フローを実行する前に、ホスト上で以下が利用可能であることを確認してください。

• Vertex AI / Gemini Enterprise Agent Platform API が有効になっている Google Cloud プロジェクト。

• 生成したクライアントを実行するホスト上で設定済みの Application Default Credentials：

  gcloud auth application-default login
  

• ユーザーが指定した出力先フォルダー（例：/tmp/liveapi_out）。生成されたコード、環境、デモはここに書き込まれます。ホストのシステム Python 環境は絶対に変更しないでください。

• ユーザーが選択した実装言語（このスキルでは Python をデフォルトかつ参照言語とします）。

参照ファイル

references/ 内の提供ファイル（単独のスキルとして扱わないでください。必要に応じて読み込まれます）：

• client_server_messages.md：Live API で使用される ClientMessage / ServerMessage スキーマの公開リファレンスです。
• client_server_messages.proto：client_server_messages.md から生成されたプロトコルバッファ定義です。
• session_manager.md：切断時のセッション、バッファリング、再開を適切に処理する方法について説明します。

手順

ステップ 1：参照ファイルをコピーする

このスキルの references/ フォルダーから、client_server_messages.md、client_server_messages.proto、session_manager.md をユーザーの出力先フォルダーにコピーします。これらのファイルは、生成するクライアントの信頼できる情報源となります。

ステップ 2：公開ドキュメントと照合する

client_server_messages.md からリンクされている公開ドキュメントを確認します。公開ドキュメントと、コピーした client_server_messages.md / client_server_messages.proto の間に相違点がある場合は、生成したクライアントが現在のサーバー仕様に対してコンパイルおよび実行できるよう、出力先フォルダー内のコピーを更新します。

ステップ 3：クライアントクラスを実装する

ユーザーが選択した言語で、次の要件を満たすクラスを実装します。

• ローカルの client_server_messages.proto の型（ClientMessage、ServerMessage）をインポートします。
• Live API エンドポイントへの WebSocket 接続を開きます。
• ユーザーがモデルとの間でデータを送受信できる非同期メソッドを公開します。

Python など、分離されたランタイムが必要な言語では、分離環境（例：venv）を出力先フォルダー内に作成し、環境を再作成して依存関係をインストールする bash スクリプト（例：setup.sh）を生成します。システムインタープリターやユーザーのグローバルな site-packages には絶対にインストールしないでください。また、sudo pip install の実行をユーザーに指示しないでください。

初期化パラメーター

ユーザーは、インスタンスの作成時に以下を指定します。

• project_id
• location
• model_id
• config：setup フィールドが設定された ClientMessage。

認証

Application Default Credentials を使用してベアラートークンを取得し、WebSocket 接続リクエストに Authorization: Bearer <token> として付加します。有効期限前または期限切れ時にトークンを更新し、再接続のたびに（go_away の場合や予期しない切断を含む）更新後のトークンを再利用します。長期間有効な API キーを唯一の認証方式としてハードコードしないでください。

公開非同期 API

このクラスは、送信前に setup_complete ServerMessage を受信することを条件として、次の非同期メソッドを公開する必要があります。

• send_realtime_data(data)：リアルタイム入力を送信します。data は realtime_input フィールドを持つ ClientMessage です。
• send_client_content(data)：履歴に追加される、リアルタイムではないターン単位のコンテンツを送信します。data は client_content フィールドを持つ ClientMessage です。
• receive()：WebSocket ストリームから解析した ServerMessage インスタンスを順に返します。

主要な API として、同期的にブロックするメソッドを公開しないでください。

ステップ 4：テストファイルを作成する

クライアントを実装したら、接続を初期化し、text、audio、video データの送信と応答の受信をテストするファイルを生成します。テストの実行に必要な情報（プロジェクト、モデル、メディアサンプル）について、ユーザーに確認してください。

ステップ 5：how_to_run.md を生成する

生成したクラスについて説明する how_to_run.md を出力先フォルダーに用意してください。サポートされているすべてのモダリティについて、ClientMessage ペイロードの作成方法、送信方法、モデルからのデータの受信方法を示す完全な例を含めてください。

ステップ 6：デモ用のフロントエンドとバックエンドサービスを生成する

実装をフロントエンド UI とバックエンドサービスの両方を備えたサービスとしてデプロイするスクリプトを作成してください（言語は問いません）。このサービスは、ワイヤートラフィックにステップ 1 の ClientMessage／ServerMessage proto を再利用する必要があります。UI から、ユーザーは次の操作を行える必要があります。

• 新しい接続を開始する／現在の接続を閉じる。
• 使用するモデルを選択する。
• 入力ソース（カメラまたはスクリーンショットからの音声や動画）を選択し、モデルにストリーミングする。
• モデルにテキストメッセージを送信する。
• モデルの音声を聞き、モデルとユーザーの文字起こし／会話履歴を交互に表示する。

音声と文字起こしの再生を実装する際は、Live API のベストプラクティスのガイダンスに従ってください。

interrupt シグナルの処理

ServerMessage の server_content が interrupted: true とともに届いた場合、UI は次の処理を行う必要があります。

• 再生中の音声と、それに対応する文字起こしの時間的な同期を保ちます。
• 再生中のモデル音声をただちに停止し、進行中の文字起こしバブルへの追記を停止します。
• 再生されていない音声バッファと、まだ描画されていない文字起こしをすべて消去し、古いコンテンツが次のターンに混入しないようにします。
• 次のユーザーターンとモデルターン用に、新しいチャットバブルを開始します。

文字起こしの finished シグナルの処理

ストリーミングされる input_transcription／output_transcription チャンクについて、finished が設定されていない間は現在アクティブなバブルに追記し、finished を検出したらそのバブルを閉じて新しいバブルを開始します。input_transcription のテキストはユーザーロールのバブルに、output_transcription のテキストはモデルロールのバブルに振り分けます。

ステップ 7：how_to_test_with_ui.md を生成する

デモサービスの起動方法と使い方を説明する how_to_test_with_ui.md を作成してください。次の内容を必ず含めてください。

• バックエンドサービスを起動するための正確なシェルコマンドまたはスクリプトの呼び出し方法。
• フロントエンド UI を起動するための正確なシェルコマンドまたはスクリプトの呼び出し方法。
• ブラウザーで開くホストとポート（例：http://localhost:PORT）。
• セッションの開始、モデルの選択、入力ソース（マイク、カメラ、画面）の選択、テキストメッセージの送信、および UI でモデルの音声と文字起こしを確認する方法。

検証チェックリスト

生成を完了とする前に、各項目を確認してください。

• client_server_messages.md、client_server_messages.proto、および session_manager.md が宛先フォルダーにコピーされています。
• 生成されたクライアントは、ローカルで proto から生成された ClientMessage 型と ServerMessage 型をインポートしています。
• クライアントは Live API WebSocket に接続し、 wss://{location}-aiplatform.googleapis.com/ws/google.cloud.aiplatform.v1beta1.LlmBidiService/BidiGenerateContent （または wss://aiplatform.googleapis.com/... のグローバル版）を使用します。また、セットアップの model フィールドを projects/{project_id}/locations/{location}/publishers/google/models/{model_id} の形式にしています。
• 認証には ADC が提供するベアラートークンを使用し、Authorization: Bearer <token> として送信しています。トークンは有効期限前に更新され、再接続のたびに再設定されます。
• 公開非同期メソッド send_realtime_data、send_client_content、および receive が存在し、型が正しく、setup_complete によって制御されています。
• 透過的なセッション再開が有効になっています （session_resumption.transparent = true）。最新の new_handle が追跡され、送信済みメッセージのインデックスは 1 から始まり、バッファーは last_consumed_client_message_index を使って整理され、再接続時（go_away および WebSocket のクローズコード 1000 / 1006 の場合を含む）にバッファー内のメッセージが再生されます。
• Python を使用する場合、宛先フォルダー内に隔離環境（例：venv）と setup.sh および requirements.txt（または同等のファイル）が存在し、システムまたはユーザー全体の Python に変更を加えていません。
• how_to_run.md と how_to_test_with_ui.md があり、デモ UI は同じ ClientMessage / ServerMessage proto を再利用しています。
• 割り込み処理と文字起こしの finished 処理が、上記の説明どおりに動作します。
• クライアントは generativelanguage.googleapis.com を対象にしておらず、クエリ文字列内の API キーによる認証も使用していません。