Conversational Analytics API を使用すると、データ エージェントの会話ロギングをオンまたはオフにしたり、ログを保存する BigQuery テーブルを選択したりできます。ユーザーの質問とエージェントの回答を確認するには、そのテーブルをクエリします。
始める前に
データ エージェントの会話ロギングを構成する前に、次のタスクを完了します。
- Google Cloud プロジェクトで、Conversational Analytics API と BigQuery に必要な API を有効にします。
- 必要な Identity and Access Management(IAM)ロールがあることを確認します。
- データソースが BigQuery テーブルを参照するデータ エージェントがあることを確認します。ログに記録されないエージェント構成については、制限事項をご覧ください。
- ログのみを保持するデータ エージェントのプロジェクトで BigQuery データセットを計画します。プロジェクト内のすべてのデータ エージェントは 1 つのサービス エージェントを共有し、専用のデータセットによってログへの書き込みアクセスが制限されます。
- ログを読み取ることができるユーザーを決定します。ログには、ユーザーの質問全体とエージェントの回答が含まれます。ユーザーが独自のアプリケーションを介してエージェントとチャットする場合、ログに記録された会話に適用される通知、開示、同意はお客様の責任となります。詳細については、プライバシー、データ ガバナンス、セキュリティをご覧ください。
必要なロール
データ エージェントの会話ロギングを構成してログをクエリするために必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。
-
ログ データセットを作成する: プロジェクトに対する BigQuery ユーザー(
roles/bigquery.user) -
サービス エージェントにログ データセットへのアクセス権を付与します。ログ データセットに対する BigQuery データオーナー(
roles/bigquery.dataOwner) -
データ エージェントの会話ロギング設定を変更する: データ エージェントまたはプロジェクトに対する Gemini データ分析データ エージェント編集者(
roles/geminidataanalytics.dataAgentEditor) -
ログをクエリします。
- ログ データセットに対する BigQuery データ閲覧者(
roles/bigquery.dataViewer) - プロジェクトに対する BigQuery ジョブユーザー (
roles/bigquery.jobUser)
- ログ データセットに対する BigQuery データ閲覧者(
ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。
ログ データセットを作成すると、BigQuery データオーナーのロールが自動的に付与されます。データ エージェントを作成すると、そのデータ エージェントに対する Gemini データ分析データ エージェント オーナーのロール(roles/geminidataanalytics.dataAgentOwner)が自動的に付与されます。これには、会話ロギング設定を変更する権限が含まれます。
データ エージェントとチャットするユーザーには、会話ロギング用の追加のロールは必要ありません。一部のユーザーの会話がログに記録されない場合は、会話のロギングのトラブルシューティングをご覧ください。
サービス エージェントのロール
会話型分析 API サービス エージェント(service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com)がログを書き込みます。PROJECT_NUMBER は、データ エージェントを含むプロジェクトの番号に置き換えます。
会話型分析 API サービス エージェントに、ログテーブルを作成して会話ログを書き込むために必要な権限があることを確認するには、ログ データセットに対する BigQuery データ編集者(roles/bigquery.dataEditor)IAM ロールを 会話型分析 API サービス エージェントに付与するよう管理者に依頼してください。
管理者は、カスタムロールや他の事前定義ロールを使用して、会話型分析 API サービス エージェントに必要な権限を付与することもできます。
会話のロギングを有効にする
会話ロギングには、サービス エージェントが書き込み可能なデータセットが必要です。まずデータセットを作成してアクセス権を付与してから、データ エージェントのロギングを有効にします。
ログ データセットを作成する
データ エージェントのプロジェクトに、ログを保持するデータセットを作成します。サービス エージェントは、最初のログに記録されたターンで、このデータセットにログテーブルを作成します。データセットを作成するには、bq コマンドライン ツールで bq mk --dataset コマンドを使用します。bq ツールコマンドは、Cloud Shell または Google Cloud CLI がインストールされているローカル ターミナルで実行できます。
bq --location=LOCATION mk --dataset PROJECT_ID:LOG_DATASET
サンプル値を次のように置き換えます。
- LOCATION: ログ データセットの BigQuery のロケーション(
USなど)。 - PROJECT_ID: データ エージェントを含むプロジェクトの ID。
- LOG_DATASET: 作成するデータセットの ID。
他の方法でデータセットを作成するには、データセットの作成をご覧ください。
サービス エージェントにデータセットへのアクセス権を付与する
サービス エージェントに、ログ データセットのみに対する BigQuery データ編集者のロール(roles/bigquery.dataEditor)を付与します。
次のオプションのいずれかを選択します。
コンソール
Google Cloud コンソールで、[BigQuery] ページに移動します。
[エクスプローラ] ペインでプロジェクトを開き、[データセット] をクリックして、ログ データセットを選択します。
[共有] > [権限の管理] をクリックします。
[プリンシパルを追加] をクリックします。
[新しいプリンシパル] フィールドに、サービス エージェントのメールアドレス(
service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com)を入力します。PROJECT_NUMBERは、データ エージェントを含むプロジェクトの番号に置き換えます。[ロールを選択] リストで、[BigQuery データ編集者] を選択します。
[保存] をクリックします。
SQL
BigQuery クエリエディタで、クエリのロケーションをログ データセットのロケーションに設定し、次の GRANT ステートメントを実行します。
GRANT `roles/bigquery.dataEditor`
ON SCHEMA `PROJECT_ID`.LOG_DATASET
TO "serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com";
サンプル値を次のように置き換えます。
- PROJECT_ID: データ エージェントとログ データセットを含むプロジェクトの ID。
- LOG_DATASET: ログ データセットの ID。
- PROJECT_NUMBER: データ エージェントを含むプロジェクトの番号。
アクセス権を付与するその他の方法については、データセットへのアクセス権を付与するをご覧ください。サービス エージェントが存在しないために付与が失敗した場合は、サービス エージェントが存在しないため、データセットへのアクセス権の付与が失敗するをご覧ください。
データ エージェントのロギングを有効にする
既存のデータ エージェントのロギングを有効にするには、エージェントの bigquery_agent_analytics_enabled フィールドと bigquery_agent_analytics_table フィールド(HTTP リクエストの bigqueryAgentAnalyticsEnabled と bigqueryAgentAnalyticsTable)を設定し、両方のフィールドを更新マスクに含めます。更新では、更新マスク内のフィールドのみが変更されます。サービス エージェントは、ロギングを有効にしてログテーブルを設定した場合にのみ、ログ行を書き込みます。
設定を構成してクライアントを初期化する(Python SDK)または初期設定と認証を構成する(HTTP)で設定した Python 環境(Colaboratory ノートブックなど)で、次のサンプルを実行します。このページの Python SDK サンプルには、google-cloud-geminidataanalytics バージョン 0.13.4 以降が必要です。
Python SDK
from google.protobuf import field_mask_pb2
data_agent_id = "DATA_AGENT_ID"
log_dataset = "LOG_DATASET"
log_table = "LOG_TABLE"
data_agent = geminidataanalytics.DataAgent()
data_agent.name = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
data_agent.bigquery_agent_analytics_enabled = True
data_agent.bigquery_agent_analytics_table = geminidataanalytics.BigQueryTableReference(
project_id=billing_project,
dataset_id=log_dataset,
table_id=log_table,
)
update_mask = field_mask_pb2.FieldMask(
paths=["bigquery_agent_analytics_enabled", "bigquery_agent_analytics_table"]
)
request = geminidataanalytics.UpdateDataAgentRequest(
data_agent=data_agent,
update_mask=update_mask,
)
try:
response = data_agent_client.update_data_agent_sync(request=request)
print(response.bigquery_agent_analytics_enabled)
print(response.bigquery_agent_analytics_table)
except Exception as e:
print(f"Error updating data agent: {e}")
サンプル値を次のように置き換えます。
- DATA_AGENT_ID: データ エージェントの ID。
- LOG_DATASET: ログ データセットの ID。
- LOG_TABLE: ログテーブルの ID(
agent_eventsなど)。テーブルが存在しない場合、サービス エージェントは最初のログに記録されたターンでテーブルを作成します。
HTTP
data_agent_id = "DATA_AGENT_ID"
log_dataset = "LOG_DATASET"
log_table = "LOG_TABLE"
data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}:updateSync"
payload = {
"bigqueryAgentAnalyticsEnabled": True,
"bigqueryAgentAnalyticsTable": {
"projectId": billing_project,
"datasetId": log_dataset,
"tableId": log_table,
},
}
params = {
"updateMask": "bigqueryAgentAnalyticsEnabled,bigqueryAgentAnalyticsTable"
}
data_agent_response = requests.patch(
data_agent_url, headers=headers, params=params, json=payload
)
if data_agent_response.status_code == 200:
body = data_agent_response.json()
if body.get("bigqueryAgentAnalyticsEnabled") and body.get(
"bigqueryAgentAnalyticsTable"
):
print("Conversation logging is turned on.")
else:
print("Logging isn't turned on. Check the returned data agent.")
print(json.dumps(body, indent=2))
else:
print(f"Error updating data agent: {data_agent_response.status_code}")
print(data_agent_response.text)
サンプル値を次のように置き換えます。
- DATA_AGENT_ID: データ エージェントの ID。
- LOG_DATASET: ログ データセットの ID。
- LOG_TABLE: ログテーブルの ID(
agent_eventsなど)。テーブルが存在しない場合、サービス エージェントは最初のログに記録されたターンでテーブルを作成します。
このメソッドは、更新されたデータ エージェントを返します。ロギングが有効になっていて、ログテーブルが設定されていることを確認します。
データ エージェントの作成時にロギングを有効にするには、作成リクエストに同じフィールドを含めます。作成リクエストについては、データ エージェントの作成(Python SDK または HTTP)をご覧ください。HTTP リクエスト本文では、フィールドは次のようになります。
"bigqueryAgentAnalyticsEnabled": true,
"bigqueryAgentAnalyticsTable": {
"projectId": "PROJECT_ID",
"datasetId": "LOG_DATASET",
"tableId": "LOG_TABLE"
}
サンプル値を次のように置き換えます。
- PROJECT_ID: データ エージェントを含むプロジェクトの ID。
- LOG_DATASET: ログ データセットの ID。
- LOG_TABLE: ログテーブルの ID。
会話がログに記録されていることを確認する
- データ エージェントにチャット リクエストを送信します。例については、API を使用して質問する(Python SDK または HTTP)をご覧ください。
エージェントが応答してから 10 秒ほど待ちます。次に、Cloud Shell またはターミナルで次の
bq queryコマンドを実行して、最近の質問と回答を確認します。BigQuery クエリエディタで SQL を実行することもできます。bq query --use_legacy_sql=false ' SELECT timestamp, event_type, JSON_VALUE(content, "$.text_summary") AS text FROM `PROJECT_ID.LOG_DATASET.LOG_TABLE` WHERE timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR) AND event_type IN ("USER_MESSAGE_RECEIVED", "AGENT_RESPONSE") ORDER BY timestamp DESC LIMIT 20'サンプル値を次のように置き換えます。
- PROJECT_ID: データ エージェントを含むプロジェクトの ID。
- LOG_DATASET: ログ データセットの ID。
- LOG_TABLE: ログテーブルの ID。
クエリが質問とエージェントの回答を返した場合、会話ロギングは正常に機能しています。テーブルが存在しないか空の場合は、会話ロギングのトラブルシューティングをご覧ください。
宛先テーブルを変更する
別のテーブルにログを書き込むには、データ エージェントの bigquery_agent_analytics_table フィールド(HTTP リクエストの bigqueryAgentAnalyticsTable)を更新し、更新マスクにこのフィールドを含めます。新しいテーブルはデータ エージェントのプロジェクトに存在する必要があり、サービス エージェントには新しいテーブルのデータセットに対する BigQuery データ編集者のロールが必要です。
データ エージェントのロギングを有効にすると同じ環境で、次のサンプルを実行します。
Python SDK
from google.protobuf import field_mask_pb2
data_agent_id = "DATA_AGENT_ID"
log_dataset = "NEW_LOG_DATASET"
log_table = "NEW_LOG_TABLE"
data_agent = geminidataanalytics.DataAgent()
data_agent.name = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
data_agent.bigquery_agent_analytics_table = geminidataanalytics.BigQueryTableReference(
project_id=billing_project,
dataset_id=log_dataset,
table_id=log_table,
)
update_mask = field_mask_pb2.FieldMask(paths=["bigquery_agent_analytics_table"])
request = geminidataanalytics.UpdateDataAgentRequest(
data_agent=data_agent,
update_mask=update_mask,
)
try:
response = data_agent_client.update_data_agent_sync(request=request)
print(response.bigquery_agent_analytics_table)
except Exception as e:
print(f"Error updating data agent: {e}")
サンプル値を次のように置き換えます。
- DATA_AGENT_ID: データ エージェントの ID。
- NEW_LOG_DATASET: 新しいログ データセットの ID。
- NEW_LOG_TABLE: 新しいログテーブルの ID。
HTTP
data_agent_id = "DATA_AGENT_ID"
log_dataset = "NEW_LOG_DATASET"
log_table = "NEW_LOG_TABLE"
data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}:updateSync"
payload = {
"bigqueryAgentAnalyticsTable": {
"projectId": billing_project,
"datasetId": log_dataset,
"tableId": log_table,
},
}
params = {"updateMask": "bigqueryAgentAnalyticsTable"}
data_agent_response = requests.patch(
data_agent_url, headers=headers, params=params, json=payload
)
if data_agent_response.status_code == 200:
body = data_agent_response.json()
table = body.get("bigqueryAgentAnalyticsTable", {})
if table.get("datasetId") == log_dataset and table.get("tableId") == log_table:
print("Log table updated.")
else:
print("The log table didn't change. Check the returned data agent.")
print(json.dumps(body, indent=2))
else:
print(f"Error updating data agent: {data_agent_response.status_code}")
print(data_agent_response.text)
サンプル値を次のように置き換えます。
- DATA_AGENT_ID: データ エージェントの ID。
- NEW_LOG_DATASET: 新しいログ データセットの ID。
- NEW_LOG_TABLE: 新しいログテーブルの ID。
すでにログに記録されている行は、以前のテーブルに残ります。変更は次のターンで有効になります。
会話のロギングをオフにする
データ エージェントの会話ロギングをオフにするには、エージェントの bigquery_agent_analytics_enabled フィールド(HTTP リクエストの bigqueryAgentAnalyticsEnabled)を false に設定し、更新マスクにこのフィールドを含めます。
データ エージェントのロギングを有効にすると同じ環境で、次のサンプルを実行します。
Python SDK
from google.protobuf import field_mask_pb2
data_agent_id = "DATA_AGENT_ID"
data_agent = geminidataanalytics.DataAgent()
data_agent.name = f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
data_agent.bigquery_agent_analytics_enabled = False
update_mask = field_mask_pb2.FieldMask(paths=["bigquery_agent_analytics_enabled"])
request = geminidataanalytics.UpdateDataAgentRequest(
data_agent=data_agent,
update_mask=update_mask,
)
try:
response = data_agent_client.update_data_agent_sync(request=request)
print(response.bigquery_agent_analytics_enabled)
except Exception as e:
print(f"Error updating data agent: {e}")
DATA_AGENT_ID は、データ エージェントの ID に置き換えます。
HTTP
data_agent_id = "DATA_AGENT_ID"
data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}:updateSync"
payload = {"bigqueryAgentAnalyticsEnabled": False}
params = {"updateMask": "bigqueryAgentAnalyticsEnabled"}
data_agent_response = requests.patch(
data_agent_url, headers=headers, params=params, json=payload
)
if data_agent_response.status_code == 200:
print("Conversation logging is turned off.")
print(json.dumps(data_agent_response.json(), indent=2))
else:
print(f"Error updating data agent: {data_agent_response.status_code}")
print(data_agent_response.text)
DATA_AGENT_ID は、データ エージェントの ID に置き換えます。
変更は次のターンで有効になります。すでに実行されているターンは、開始時の設定で完了します。
ログ データセットに書き込むすべてのデータ エージェントのロギングを停止するには、データセットに対するサービス エージェントの BigQuery データ編集者のロールを取り消します。ロギングは各エージェントで有効のままですが、サービス エージェントは行を書き込めなくなります。
ロギングをオフにしても、すでにログに記録されている行は保持されます。ログに記録されたデータを削除するには、行、パーティション、またはログテーブルを削除します。
会話のロギングのトラブルシューティング
次の情報を使用して、BigQuery の会話型分析の会話ロギングに関する一般的な問題のトラブルシューティングを行います。ロギングエラーは会話のターンを失敗させず、チャット、API レスポンス、Cloud Logging で報告されないため、宛先テーブルが空または存在しないことが、構成または権限の問題の主なシグナルとなります。
ログテーブルがないか、空です
会話のターン後に宛先テーブルが作成されない、または空のままになっている場合は、次の原因が考えられます。
会話のロギングが有効になっていない。会話ロギングが有効になっていて、データ エージェントで宛先テーブルが構成されていることを確認します。
宛先データセットが存在しないか、別のプロジェクトにあります。宛先データセットがデータ エージェントと同じプロジェクトにすでに存在することを確認します。データセットが存在することを確認するには、
bq show PROJECT_ID:LOG_DATASETを実行します。PROJECT_IDは、データ エージェントを含むプロジェクトの ID に置き換え、LOG_DATASETは、宛先データセットの ID に置き換えます。サービス エージェントは、最初にログに記録されたターンでログテーブルを作成しますが、データセットは作成しません。宛先データセットが、リンクされたデータセットなどの読み取り専用データセットである。BigQuery Sharing のリンク済みデータセットまたは外部データセット(AWS Glue 連携データセットなど)は読み取り専用であり、会話ログを保存できません。データセット タイプを確認するには、
bq show --format=prettyjson PROJECT_ID:LOG_DATASETを実行して"type"フィールド("LINKED"または"EXTERNAL")を調べます。データ エージェントと同じプロジェクト内の標準の書き込み可能なデータセットを選択します。サービス エージェントまたは CMEK の権限がありません。会話型分析 API サービス エージェント(
service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com、プロジェクト ID ではなくエージェント プロジェクトの番号を使用)に、ログ データセットに対する BigQuery データ編集者(roles/bigquery.dataEditor)ロールが付与されていることを確認します。データセットで顧客管理の Cloud KMS 鍵(CMEK)を使用している場合は、BigQuery 暗号化サービス アカウント(bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com)に鍵のroles/cloudkms.cryptoKeyEncrypterDecrypterロールが付与されていることを確認します。VPC Service Controls の境界が書き込みをブロックする。会話型分析 API サービス エージェントは、Google が管理するインフラストラクチャからログテーブルに書き込みます。そのため、サービス境界で
bigquery.googleapis.comが制限されている場合、roles/bigquery.dataEditorを付与するだけでは不十分です。このリストの他の原因とは異なり、境界ブロックは、エージェントのプロジェクトの Cloud Logging にポリシー拒否の監査ログを記録します。bigquery.googleapis.comのlog_id("cloudaudit.googleapis.com/policy")(テーブルのルックアップまたは作成の場合)とbigquerystorage.googleapis.com(行の追加の場合)でフィルタして、ブロックを確認します。geminidataanalytics.googleapis.comとbigquery.googleapis.comの両方が境界内にあることを確認し、bigquery.googleapis.comのサービス エージェントに上り(内向き)ルールを追加します。上り(内向き)ルールの例については、アクセス制御、暗号化、ネットワーク セキュリティをご覧ください。一般的な境界設定のガイダンスについては、VPC Service Controls で境界セキュリティを構成するをご覧ください。サポートされていない会話サーフェスまたはエージェント構成。BigQuery Studio の [プレビュー] ペインでの会話と、データ エージェントを使用しないステートレス API 呼び出しはログに記録されません。テストするには、API を介してデータ エージェントにチャット リクエストを送信します。特定の BigQuery テーブルではなく検索スコープを使用するエージェント、BigQuery プロパティ グラフ(BigQuery テーブルなし)のみをナレッジソースとして構成するエージェント、BigQuery テーブルを宣言しないエージェントはログに記録されません。詳細については、制限事項をご覧ください。
ナレッジソース テーブルはアクセス ポリシーを使用します。ナレッジソース テーブル(エージェントのデータソース内の BigQuery テーブル)で行レベルのアクセス ポリシー、列レベルのセキュリティ(ポリシータグ)、または動的データ マスキングが使用されている場合、ターンはログに記録されません。
既存の宛先テーブルでスキーマの競合が発生している。既存のテーブルを宛先として構成し、列が会話ログスキーマ列と同じ名前で、異なる型またはモードを持つ場合、BigQuery はそのテーブルに行を書き込みません。
通常、行はターンが完了してから数秒以内に表示されます。数分待っても行が表示されない場合は、データセットを更新します。
一部のユーザーの会話が記録されない
原因
各ターンの前に、プライバシー チェックはチャット ユーザーの認証情報を使用して、エージェントのナレッジソース テーブルに行レベルのセキュリティ、列レベルのセキュリティ、データ マスキング ポリシーがないことを確認します。ユーザーにこのチェックを実行する権限がない場合、そのユーザーのターンはログに記録されません。
解決策
チャットを使用するすべてのユーザーに、ナレッジソース テーブルに対する BigQuery データ閲覧者(roles/bigquery.dataViewer)ロールと、クエリを実行するプロジェクトに対する BigQuery ジョブユーザー(roles/bigquery.jobUser)ロールを付与します。または、ナレッジソース テーブルに対する bigquery.tables.get 権限と bigquery.rowAccessPolicies.list 権限を持つカスタムロールを付与します。
エージェントの作成または更新が INVALID_ARGUMENT エラーで失敗する
エラー メッセージ
The BigQuery Agent Analytics table must be in the same project as the agent (agent project: ..., table project: ...).BigQuery Agent Analytics can only be enabled on agents whose datasource is BigQuery. Remove bigquery_agent_analytics_enabled and bigquery_agent_analytics_table, or point the agent at a BigQuery datasource.
原因
宛先データセットがデータ エージェントとは異なるプロジェクトにあるか、エージェントのデータソースが BigQuery ではありません。
解決策
データ エージェントと同じプロジェクト内の既存の宛先データセットを指定するか、BigQuery データソースを使用してデータ エージェントを構成します。
サービス エージェントが存在しないため、データセットへのアクセス権の付与に失敗する
エラー メッセージ
Service account service-PROJECT_NUMBER@gcp-sa-geminidataanalytics... does not exist
原因
Conversational Analytics API サービス エージェントがプロジェクトにまだプロビジョニングされていません。
解決策
次のいずれかを行います。
まず、エージェントでログの宛先を構成してから、ロールを再度付与します。
次のコマンドを実行して、サービス ID をプロビジョニングします。
gcloud beta services identity create \ --service=geminidataanalytics.googleapis.com \ --project=PROJECT_ID
PROJECT_IDは、データ エージェントを含むプロジェクトの ID に置き換えます。
次のステップ
- 会話ログのスキーマを確認する。
- 会話ログを分析する。
- 会話型分析 API のセキュリティ、プライバシー、リスク、コンプライアンスを確認する。
- BigQuery Studio で会話ロギングを構成する。