Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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

このページでは、会話分析 API に関するよくある質問について説明します。

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

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

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

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

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

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

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

エラー: 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 構成を確認してください。
エラー: 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 の両方で適切な権限が必要です。

Google Cloud IAM ロール:
- geminidataanalytics.googleapis.com API を操作するには、 Google Cloud プロジェクトに十分な IAM ロールが必要です。IAM ロールの構成が正しくないと、PERMISSION_DENIED エラーが発生することがよくあります。
- 必要な特定のロールはアクションによって異なりますが、特定のオペレーションでは プロジェクト編集者などの一般的なロールが必要になる場合があります。
Looker の権限とロール:
- モデルレベルの権限: 会話分析と会話分析 API を使用するには、操作するモデルに対する gemini_in_looker 権限を含む Looker ロールが Looker ユーザーに割り当てられている必要があります。

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

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

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

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

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

Google Cloud **IAM ロール**:
- サービスアカウントまたはユーザーには、特定のデータベースに接続してクエリを実行するために必要な IAM ロールが必要です。通常、これにはデータベースに対する読み取りアクセス権を持つロールが含まれます。
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 ロールを割り当てることができます。

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

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

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

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

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

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

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

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

Looker のセマンティックレイヤでは、LookML 定義内でコンテキストを指定できます。詳細と例については、Looker で作成されたコンテキストでエージェントの動作をガイドするのドキュメントページをご覧ください。
BigQuery データソースの場合、テーブルレベルと列レベルの説明、同義語、タグ、クエリの例などの構造化コンテキストフィールドとシステム指示を使用して、作成されたコンテキストを提供できます。このコンテキストを提供すると、レスポンスの精度が向上し、エージェントがレスポンスでソースを引用できるようになります。詳細については、BigQuery データソースのデータエージェントコンテキストを定義するをご覧ください。
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 は一般提供（GA）されています。料金の詳細については、料金ガイドをご覧ください。

また、データエージェントが BigQuery などのデータソースに対して実行するクエリでは、これらのサービスから費用が発生する可能性があります。BigQuery では、費用を管理するには、割り当てを設定するか、クエリごとに課金されるバイト数を制限し、bigquery_max_billed_bytes パラメータを使用します。

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

会話分析 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 はデータ所在地をサポートしています。データの処理場所と保存場所を制御するには、API リクエストを行うときにリージョンまたはマルチリージョンのサービスエンドポイントを指定します。特定のロケーションのサポートと構成の詳細については、データ所在地をご覧ください。

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

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