Conversational Analytics API 可讓您開啟或關閉資料代理的對話記錄功能,並選擇儲存記錄的 BigQuery 資料表。如要查看使用者的問題和代理的回覆,請查詢該資料表。
事前準備
為資料代理設定對話記錄前,請先完成下列工作:
- 在 Google Cloud 專案中,啟用 Conversational Analytics API 和 BigQuery 的必要 API。
- 確認您具備必要的 Identity and Access Management (IAM) 角色。
- 請確認您有資料代理,且其資料來源參照 BigQuery 資料表。如要瞭解未記錄的代理程式設定,請參閱「限制」。
- 在資料代理專案中規劃 BigQuery 資料集,僅保留記錄。專案中的所有資料代理程式都會共用一個服務代理程式,且專屬資料集會限制其對記錄的寫入權限。
- 決定誰可以讀取記錄。記錄會包含使用者的完整問題和代理的回覆。如果使用者透過您的應用程式與代理對話,您必須負責提供適用於對話記錄的任何通知、揭露聲明或同意聲明。詳情請參閱「隱私權、資料治理和安全性」。
必要的角色
如要取得設定資料代理對話記錄及查詢記錄所需的權限,請要求管理員授予您下列 IAM 角色:
-
建立記錄資料集:專案的 BigQuery 使用者 (
roles/bigquery.user) -
授予服務代理記錄資料集的存取權:記錄資料集的 BigQuery 資料擁有者 (
roles/bigquery.dataOwner) -
變更資料代理的對話記錄設定:資料代理或專案的 Gemini 資料分析資料代理編輯者 (
roles/geminidataanalytics.dataAgentEditor) -
查詢記錄:
- 記錄檔資料集的 BigQuery 資料檢視者 (
roles/bigquery.dataViewer) - 專案的 BigQuery 工作使用者 (
roles/bigquery.jobUser)
- 記錄檔資料集的 BigQuery 資料檢視者 (
如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。
建立記錄資料集後,系統會自動授予您該資料集的 BigQuery 資料擁有者角色。如果您建立了資料代理,系統會自動授予 Gemini Data Analytics 資料代理擁有者角色 (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 指令。您可以在 Cloud Shell 或已安裝 Google Cloud CLI 的本機終端機中,執行 bq 工具指令。
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」頁面。
在「Explorer」窗格中展開專案,點選「Datasets」(資料集),然後選取記錄資料集。
依序點選「共用」>「管理權限」。
按一下「Add principal」(新增主體)。
在「New principals」(新增主體) 欄位中,輸入服務代理的電子郵件地址:
service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com。將
PROJECT_NUMBER替換為包含資料代理的專案編號。在「Select a role」(選取角色) 清單中,選取「BigQuery Data Editor」(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 共用連結資料集或外部資料集 (例如 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 代管的基礎架構寫入記錄資料表,因此當 service perimeter 限制
bigquery.googleapis.com時,僅授予roles/bigquery.dataEditor是不夠的。與這份清單中的其他原因不同,perimeter 封鎖會在代理程式專案的 Cloud Logging 中,記錄「政策遭拒」稽核記錄。請在bigquery.googleapis.com(用於資料表查詢或建立) 和bigquerystorage.googleapis.com(用於附加資料列) 下方,依log_id("cloudaudit.googleapis.com/policy")篩選,確認是否遭到封鎖。確認geminidataanalytics.googleapis.com和bigquery.googleapis.com都在 perimeter 內,並為bigquery.googleapis.com上的服務代理新增輸入規則。如需輸入規則範例,請參閱「存取控管、加密和網路安全」。如需一般 perimeter 設定指南,請參閱「使用 VPC Service Controls 設定 perimeter 安全性」。不支援的對話介面或代理設定。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 服務代理。
解決方式
執行下列其中一個步驟:
請先在代理程式上設定記錄檔目的地,然後再次授予角色。
執行下列指令,佈建服務身分:
gcloud beta services identity create \ --service=geminidataanalytics.googleapis.com \ --project=PROJECT_ID
將
PROJECT_ID替換為資料代理程式所在專案的 ID。