会話分析 API に関するよくある質問

プレビュー

このプロダクトまたは機能は サービス固有規約の「一般サービス規約」セクションの「一般提供前のサービス規約」の対象となります 。 pre-GA のプロダクトと機能は「現状のまま」利用できますが、サポートが制限されることがあります。 詳細については、 リリース ステージの説明をご覧ください。

会話分析 API でデータを変更または削除できますか？

会話分析 API は、データの変更や削除を防ぐための保護機能を備えて設計されています。

データソースごとのデータ セーフティの取り扱いは次のとおりです。

• BigQuery: API は、データ定義言語（DDL）ステートメントとデータ操作言語（DML）ステートメントをブロックします。具体的には、生成された SQL でテスト実行を行い、SELECT タイプのクエリのみを許可します。
• Looker: API は、選択、フィルタ、上限などの読み取りオペレーションに制限されている run_inline_query などのメソッドを使用して Looker とやり取りします。これらのメソッドは DDL オペレーションまたは DML オペレーションをサポートしておらず、削除オペレーションまたはドロップ オペレーションは含まれていません。
• データポータル（CSV と Google スプレッドシートの場合）: データポータルは、構造化された形式を使用して、可視化とレポートのデータを定義して取得します。このメソッドで実行されるクエリは読み取り専用であり、データ ミューテーションはサポートされていません。
• データベース: システムは SELECT タイプのクエリのみを許可します。データの変更や削除を防ぐため、会話分析 API を操作するサービス アカウントまたはユーザーにデータベースへの読み取り専用権限があることを確認してください。

会話分析 API は、これらのデータソース全体で読み取り専用になるように設計されています。会話分析 API のセキュリティの詳細については、安心して会話: Looker の会話分析のセキュリティを解説のブログ投稿をご覧ください。

認証エラーと権限エラーを処理するにはどうすればよいですか？

注: エラーと解決策の詳細については、会話分析 API エラーのトラブルシューティング ガイドをご覧ください。

会話分析 API の使用時に発生する可能性のある一般的な認証エラーと権限エラーは次のとおりです。

1. エラー: PERMISSION_DENIED または 403 Write access to project ... was denied

   • 考えられる原因: このメッセージは、 Google Cloud IAM ロールに関する問題を示していることがよくあります。API を使用しようとしているユーザーまたはサービス アカウントに、 Google Cloud プロジェクトに対する必要な権限がありません。
   • トラブルシューティング
     • Google Cloud プロジェクト オーナーは、ユーザーまたはサービス アカウントに Google Cloud プロジェクトで正しい IAM ロールが割り当てられていることを確認する必要があります。API の有効化や関数のテストなどの特定のオペレーションには、Project Editor などのロールが必要になることがあります。
     • リージョンを切り替えるときに Write access to project 'us-gcp-project-name' was denied などの 403 エラーが発生した場合は、プロジェクトの IAM 構成を確認してください。

2. エラー: 500 Internal Server Error。ユーザー ロールを持つ Looker ユーザーがデータ エージェントとチャットしようとした場合。

   • 考えられる原因: Looker ユーザーに十分な権限がない可能性があります。
   • トラブルシューティング: データ エージェントとチャットするには、IAM と Looker で適切なロールがユーザーに付与されていることを確認します。詳細については、このよくある質問の 会話分析 API を使用するための Looker の要件は何ですか？をご覧ください。

レスポンスをストリーミングすると 503 エラーまたは 500 エラーが表示されるのはなぜですか？

基本的な HTTP クライアントまたは REST クライアント（Python の requests ライブラリなど）を使用してストリーミング :chat エンドポイントを呼び出すと、API から 503 Connection reset by peer や 500 Internal error などの一般的なエラー メッセージが返されることがあります。

これらの一般的なエラーは、ストリーミング API がストリームを開くとすぐに HTTP 200 OK ヘッダーを送信するために発生します。ストリーム中にデータ エージェントで致命的なエラー（長時間実行クエリのタイムアウトや権限の突然の拒否など）が発生すると、ストリームが終了し、HTTP/2 トレーラに特定のエラーコードが含まれます。標準の HTTP クライアントまたは REST クライアントは、これらのトレーリング ヘッダーを解析できず、突然の終了をソケット クラッシュとして解釈します。

ストリーム中に発生するエラーを処理するには、Python SDK などの公式 Google Cloud クライアント ライブラリ（SDK）を使用することを強くおすすめします。これらの gRPC ベースの SDK は、HTTP/2 トレーラを解析し、一般的なネットワーク エラーではなく、DEADLINE_EXCEEDED や PERMISSION_DENIED などの特定のエラーコードを返します。

会話分析 API を使用するための Looker の要件は何ですか？

会話分析 API を使用するには、実行するデータソースとアクションに応じて、 Google Cloud IAM と Looker の両方で適切な権限が必要です。

1. Google Cloud IAM ロール:

   • geminidataanalytics.googleapis.com API を操作するには、 Google Cloud プロジェクトに十分な IAM ロールが必要です。IAM ロールの構成が正しくないと、PERMISSION_DENIED エラーが発生することがよくあります。
   • 必要な特定のロールはアクションによって異なりますが、特定のオペレーションでは プロジェクト編集者などの一般的なロールが必要になる場合があります。

2. Looker の権限とロール:

   • モデルレベルの権限: 会話分析と会話分析 API を使用するには、操作するモデルに対する gemini_in_looker 権限を含む Looker ロール が Looker ユーザーに割り当てられている必要があります。

会話分析 API の使用に必要な権限とロールの詳細については、会話分析 API の IAM ロールと権限を付与するのドキュメント ページをご覧ください。

また、Looker インスタンスは特定の要件を満たしている必要があります。

• Looker（オリジナル）
• Looker（Google Cloud コア）

会話分析 API をデータポータル Pro で使用するには、Pro サブスクリプションが VPC-SC 境界外にある必要があります。

会話分析 API を使用するためのデータベースの要件は何ですか？

AlloyDB for PostgreSQL、GoogleSQL for Spanner、Cloud SQL for MySQL、Cloud SQL for PostgreSQL などのデータベースで会話分析 API を使用するには、適切な IAM 認証と有効化を行う必要があります。

1. Google Cloud **IAM ロール**:

   • サービス アカウントまたはユーザーには、特定のデータベースに接続してクエリを実行するために必要な IAM ロールが必要です。通常、これにはデータベースに対する読み取りアクセス権を持つロールが含まれます。

2. API の有効化:

   • プロジェクトで Cloud AI Companion API が有効になっていることを確認します Google Cloud 。

IAM 認証を有効にする方法の詳細については、各データベースのドキュメントをご覧ください。

• AlloyDB: IAM 認証を管理する。
• Spanner: Spanner に対する認証。
• Cloud SQL for MySQL: IAM 認証。
• Cloud SQL for PostgreSQL: IAM 認証。

Data QnA API から会話分析 API に移行するにはどうすればよいですか？

以前の試験運用版の Data QnA API（dataqna.googleapis.com）を使用していた場合は、移行ガイドで、会話分析 API（geminidataanalytics.googleapis.com）の新しい公式エンドポイントに移行する方法をご覧ください。

データ エージェントの名前と ID の違いは何ですか？

data_agent_id の値として定義されるデータ エージェントの ID は、データ エージェントの固有識別子です。データ エージェントの名前 data_agent.name は、data_agent_id から完全修飾名（FQN）として自動的に派生し、projects/<project>/locations/<location>/dataAgents/<data_agent_id> の形式になります。

データ エージェントを作成するときに data_agent.name に入力した値は無視されます。get、update、delete のオペレーションを実行する場合、完全な data_agent.name はデータ エージェントの固有識別子として扱われます。

会話分析 API を使用してデータ エージェントを作成する場合、次のシナリオが適用されます。

• data_agent_id を定義しない場合、一意の ID が自動的に生成されます。
• data_agent_id を TestID などとして定義すると、data_agent.name に入力した値は projects/<project>/locations/<location>/dataAgents/TestID で上書きされます。
• FQN を使用して data_agent_id を定義すると、「名前の形式が正しくありません」というエラーが表示されます。

エージェントの作成または会話の作成で ID に使用できる形式は何ですか？

データ エージェントの場合:

projects/{project}/locations/{location}/dataAgents/{data_agent_id}

{data_agent} はリソース ID です。63 文字以下で、https://google.aip.dev/122#resource-id-segments で説明されている形式と一致する必要があります。

例: projects/1234567890/locations/us-central1/dataAgents/my-agent

このフィールドは自動的に推論され、{parent}/dataAgents/{data_agent_id} で上書きされるため、エージェントの作成時にこのフィールドの設定をスキップすることをおすすめします。

会話の場合:

projects/{project}/locations/{location}/conversations/{conversation_id}

{conversation_id} はリソース ID で、63 文字以下である必要があります。また、https://google.aip.dev/122#resource-id-segments で説明されている形式と一致する必要があります。

例: projects/1234567890/locations/us-central1/conversations/my-conversation。

会話分析が自動的に識別して {parent}/conversations/{conversation_id} で上書きするため、会話の作成時にこのフィールドの設定をスキップすることをおすすめします。

更新マスクはどのように使用するのですか？

データ エージェントの更新フローでは、updateMask パラメータは、更新によって dataAgent リソース内のどの dataAgent フィールドが上書きされるかを指定する FieldMask 形式の文字列を受け取ります。updateMask パラメータは必須フィールドであり、次のように検証されます。

• updateMask が空の場合、BadRequestException がスローされ、フィールドは更新されません。
• updateMask のすべてのフィールドが有効な dataAgent フィールドである場合、それらのフィールドのみが更新されます。
• 有効なフィールドと無効なフィールドが混在している場合は、無効なフィールドは無視され、有効なフィールドのみが更新されます。

getIAMPolicy と setIAMPolicy を使用してデータ エージェントの IAM ポリシーを設定するにはどうすればよいですか？

getIamPolicy メソッドと setIamPolicy メソッドを使用して、特定のエージェントのユーザーに IAM ロールを割り当てることができます。

重要: setIamPolicy メソッドは、エージェントの既存の権限をオーバーライドします。既存のポリシーを保持するには、まず getIAMPolicy メソッドを呼び出して既存のポリシーを取得し、setIamPolicy の呼び出しで既存のポリシーと追加の変更を渡します。

次のコードサンプルは、データ エージェントの IAM ポリシーを取得する方法を示しています。

• HTTP を使用する getIAMPolicy
• Python SDK を使用する getIAMPolicy

次のコードサンプルは、IAM をデータ エージェントに割り当てる方法を示しています。

• HTTP を使用する setIAMPolicy
• Python SDK を使用する setIAMPolicy

会話分析 API のデータ エージェントのメモリ機能とは何ですか？

• 単一セッション内: 会話分析 API はマルチターンの会話をサポートしています。つまり、現在の会話の以前の部分を参照できます。
• 複数のセッションにわたる: 会話分析 API には、会話履歴を管理する機能が含まれており、ユーザーは複数のセッションにわたってチャットできます。また、Google マネージドのマルチターンの会話でステートフル エージェントもサポートしています。
• 長期記憶: 会話分析 API データ エージェントは、明示的な長期記憶機能をサポートしていません。

注: 会話分析 API が成功以外のレスポンスを返した場合、データ エージェントとの会話でメッセージが保持されないことがあります。

会話分析 API データ エージェントに同じ質問をすると、毎回同じ回答が返ってきますか？

• 会話分析 API データ エージェントからの自然言語の回答は決定的ではないため、同じ表現の質問でも、エージェントから提供される自然言語の回答が異なる場合があります。
• データクエリのレスポンス: ただし、特定のデータを求める質問については、基盤となる生成クエリ（SQL または Looker クエリ）は決定的であることが想定されます。基盤となるデータが変更されていない場合、取得されるデータは同じになります。

会話分析 API データ エージェントからのレスポンスの精度を高めるにはどうすればよいですか？

Gemini for Google Cloudプロダクトは初期段階のテクノロジーであるため、もっともらしく見えても事実に反する出力を生成する場合があります。Gemini for Google Cloud プロダクトからのすべての出力は、使用する前に検証することをおすすめします。詳細については、Gemini for Google Cloud と責任ある AI をご覧ください。

データ エージェントの回答の精度を高める方法の 1 つは、データ エージェントに堅牢なコンテキスト情報を提供することです。コンテキストは次の方法で追加できます。

• Looker のセマンティック レイヤでは、LookML 定義内でコンテキストを指定できます。詳細と例については、Looker で作成されたコンテキストでエージェントの動作をガイドするのドキュメント ページをご覧ください。
• AlloyDB for PostgreSQL、Cloud SQL for MySQL、Cloud SQL for PostgreSQL、Spanner のデータソースでは、テーブル、列、スキーマの説明、制約をデータのガイダンスとして追加し、そのデータの解釈方法を示すことで、コンテキストを提供できます。

• データ エージェントを作成する際に、システム指示、検証済みクエリ、高度なコンテキストを指定できます。

  • システム指示。これは、データ エージェントの動作を形成できるユーザー定義のガイダンスです。このガイダンスには、ビジネス固有のロジック、レスポンスの形式、データのプレゼンテーションが含まれます。
  • 正しい SQL クエリまたは Looker クエリとペア設定された自然言語の質問の例である検証済みクエリ（データソースによってはゴールデン クエリ とも呼ばれます）を指定できます。
  • AlloyDB、Cloud SQL for MySQL、Cloud SQL for PostgreSQL、Spanner のデータソースでは、エージェントのデータ理解と精度を最適化するのに役立つ高度なコンテキストを指定できます。

  詳細については、 作成されたコンテキストでエージェントの動作をガイドするをご覧ください。

より効果的で正確な回答を得るための質問方法については、効果的な質問をするをご覧ください。

エージェントが生成した Python コードを安全に検査して処理するにはどうすればよいですか？

Python を使用した高度な分析を有効にしている場合、データ エージェントから Python コードが返されることがあります。データ エージェントが返す Python コードは、Google が管理する安全なサンドボックス内で実行されるように設計されています。このコードをローカル環境や他の未検証の環境で実行すると、サンドボックスのセキュリティ保護がバイパスされ、悪意のあるコードの実行など、システムがセキュリティ リスクにさらされる可能性があります。

エージェントが生成した Python コードを安全に検査して処理するには、次のガイドラインに従ってください。

• 生成されたコードを実行する前に、手動で検査します。予期しないネットワーク リクエスト（socket、requests、urllib など）、システムレベルのコマンド（os.system、subprocess など）、難読化された文字列リテラルや変数など、不審なパターンを探します。
• 未検証のコードをローカルマシンや本番環境で直接実行しないでください。機密性の高い認証情報、内部ネットワーク、ローカル ファイル システムにアクセスできない、安全で隔離されたサンドボックス（Colaboratory ノートブック、エフェメラル Docker コンテナ、仮想マシンなど）を使用します。
• 可能な場合は、コードを実行する前に、静的分析ツールまたはリンターをコードに対して実行して、安全でない可能性のあるオペレーションや既知の悪意のあるパターンにフラグを設定します。

会話分析 API をサードパーティ アプリケーションと統合できますか？

会話分析 API をサードパーティ アプリケーションと統合すると、ユーザーは毎日使用しているツール内でデータを直接操作できます。

geminidataanalytics.googleapis.com API エンドポイントとやり取りするサードパーティ アプリケーションは、アプリケーションからエージェントにユーザー メッセージを送信し、レスポンスを表示できる必要があります。

インテグレーションを構築するには、会話分析のクイックスタート リポジトリで例やライブラリをご覧ください。Google デベロッパー フォーラムで、他のユーザーの例を検索することもできます。

会話分析 API の費用はどのくらいですか？

会話分析 API はプレビュー段階であり、プレビュー版のプロダクトに対して Google が料金を請求することはありません。今後、料金が変更される場合は事前にお知らせいたします。

会話分析 API はどのようなデータソースをサポートしていますか？

注: QueryData メソッドは、BigQuery または Looker のデータソースをサポートしていません。Chat メソッドと DataAgent メソッドは、AlloyDB for PostgreSQL、GoogleSQL for Spanner、Cloud SQL、Cloud SQL for PostgreSQL などのデータベース データソースをサポートしていません。

会話分析 API は、次のデータソースをサポートしています。

• BigQuery
• Looker の Explore
• データポータル
• AlloyDB for PostgreSQL
• GoogleSQL for Spanner
• Cloud SQL と Cloud SQL for PostgreSQL

BigQuery を介して SAP や Salesforce などのソースへの接続や、データポータルを介して CSV や Google スプレッドシートに接続することもできます。

会話分析 API の既知の制限事項は何ですか？

会話分析 API の既知の制限事項について詳しくは、会話分析 API の既知の制限事項のドキュメント ページをご覧ください。

Google Cloud プロジェクトで注意すべき割り当ては何ですか？

Google Cloud プロジェクトの選択やロケーションに制限はありません。データ エージェントを作成して、任意のプロジェクトまたはリージョンに属するサポートされているデータソースに対してクエリを実行できます。

会話分析 API はデータ リージョン指定をサポートしていますか？

会話分析 API はデータ所在地（DRZ）をまだサポートしていないため、特定の地理的リージョンでエージェントをホストすることはできません。データのリージョン指定はサポートされていません。

会話分析 API は英語以外の言語をサポートしていますか？

会話分析 API で正式にサポートされている言語は英語のみです。基盤となる Gemini モデルは多くの言語をサポートしており、英語以外のクエリで成功したという報告も一部のユーザーから寄せられていますが、会話分析 API は英語以外の言語を正式にはサポートしていません。