設定對話記錄

Conversational Analytics API 可讓您開啟或關閉資料代理的對話記錄功能,並選擇儲存記錄的 BigQuery 資料表。如要查看使用者的問題和代理的回覆,請查詢該資料表。

事前準備

為資料代理設定對話記錄前,請先完成下列工作:

  1. 在 Google Cloud 專案中,啟用 Conversational Analytics API 和 BigQuery 的必要 API。
  2. 確認您具備必要的 Identity and Access Management (IAM) 角色。
  3. 請確認您有資料代理,且其資料來源參照 BigQuery 資料表。如要瞭解未記錄的代理程式設定,請參閱「限制」。
  4. 在資料代理專案中規劃 BigQuery 資料集,僅保留記錄。專案中的所有資料代理程式都會共用一個服務代理程式,且專屬資料集會限制其對記錄的寫入權限。
  5. 決定誰可以讀取記錄。記錄會包含使用者的完整問題和代理的回覆。如果使用者透過您的應用程式與代理對話,您必須負責提供適用於對話記錄的任何通知、揭露聲明或同意聲明。詳情請參閱「隱私權、資料治理和安全性」。

必要的角色

如要取得設定資料代理對話記錄及查詢記錄所需的權限,請要求管理員授予您下列 IAM 角色:

如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色,取得必要權限。

建立記錄資料集後,系統會自動授予您該資料集的 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) 授予服務代理。

選取下列選項之一:

控制台

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」

  2. 在「Explorer」窗格中展開專案,點選「Datasets」(資料集),然後選取記錄資料集。

  3. 依序點選「共用」>「管理權限」。

  4. 按一下「Add principal」(新增主體)。

  5. 在「New principals」(新增主體) 欄位中,輸入服務代理的電子郵件地址:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com。

    將 PROJECT_NUMBER 替換為包含資料代理的專案編號。

  6. 在「Select a role」(選取角色) 清單中,選取「BigQuery Data Editor」(BigQuery 資料編輯者)。

  7. 按一下「儲存」。

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。

確認對話已記錄

  1. 向資料代理傳送對話要求。如需範例,請參閱「使用 API 提問」(Python SDK 或 HTTP)。
  2. 等候約 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。

後續步驟