對話記錄功能總覽

對話式數據分析的對話記錄功能可讓您將資料代理的對話記錄到專案的 BigQuery 資料表，以便查看答案品質、追蹤採用情形，以及監控所有對話式數據分析代理的成本。記錄會擷取每輪對話的使用者問題、代理回覆、延遲時間、模型權杖用量，以及依代理、對話和使用者分組所需的 ID。系統會透過 BigQuery Storage Write API (gRPC)，使用 BigQuery 代理程式分析結構定義寫入資料列。

記錄內容

每個記錄的回合都會將多個事件列 (events) 寫入目的地資料表，記錄下列資訊：

  • 使用者的問題。

  • 代理的回覆：文字、洞察、假設、建議的後續問題、引用來源，以及任何資料結果或圖表的名稱。

  • 每回合延遲時間。

  • 每次模型呼叫的模型詞元用量、模型版本和完成原因 (模型停止生成詞元的原因)。

  • 資料代理 ID 和對話 ID，以便在一個資料表中分析多個代理。

  • 使用者 ID。如要進一步瞭解使用者 ID，請參閱「使用者身分」。

  • 狀態和錯誤詳細資料。

不會記錄的內容

對話記錄功能不會記錄下列內容：

  • 代理執行的 SQL 查詢：記錄檔包含最終答案，以及參照資料結果和圖表的名稱，但不包含產生這些結果和圖表的查詢。除非使用者明確要求代理顯示或說明 SQL，否則 SQL 查詢不會出現在回覆文字中。

  • 代理的工具呼叫：每次模型呼叫都會寫入一個 LLM_RESPONSE 資料列，包括模型決定執行工具的呼叫。寫入資料列前，系統會移除模型的輸出內容，包括模型呼叫的任何工具名稱和引數。系統只會保留權杖用量、模型版本和完成原因。

  • 使用者意見回饋：系統不會記錄「喜歡」或「不喜歡」的意見回饋。

部分對話完全不會記錄，例如 BigQuery Studio 預覽窗格中的對話。如要進一步瞭解不支援的對話介面，請參閱「限制」一節。

對話記錄功能的運作方式

使用者與已啟用對話記錄功能的資料代理對話時，對話數據分析會透過下列階段處理每個對話回合：

  1. 設定：代理擁有者啟用對話記錄功能，並在 BigQuery Studio 中選取代理專案內現有的目的地資料集和資料表名稱。

  2. 提問：使用者向代理傳送問題。在 BigQuery Studio 中，使用者會看到對話記錄通知。

  3. 隱私權檢查：在代理開始處理對話前，隱私權檢查會使用對話使用者的憑證，讀取代理知識來源資料表的中繼資料。這項檢查會確認資料表是否使用資料列層級安全性 (資料列存取政策)、資料欄層級安全性 (政策標記) 或動態資料遮蓋。如果檢查發現政策，或無法確認沒有政策，系統就不會記錄該回合，但代理仍會回答使用者的問題。

  4. 回答：代理會照常回答使用者。

  5. 寫入：專案的 Conversational Analytics API 服務代理 (service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.s3ns-system.iam.gserviceaccount.com) 透過 Storage Write API (gRPC) 將記錄列寫入目的地資料表。在第一個記錄的回合中，如果資料表不存在，服務代理會建立資料表。

  6. 查詢：資料列通常會在答案完成後幾秒內顯示。我們無法保證包裹會在多久內送達。

記錄錯誤不會導致回合失敗，但隱私權檢查和記錄寫入作業可能會增加延遲時間。如果記錄資料集缺少權限、資料集不存在，或配額用盡，對話要求不會失敗。對話式數據分析不會在即時通訊介面或 Cloud Logging 中回報記錄失敗。

隱私權、資料治理和安全性

為代理啟用對話記錄功能時，請查看使用者通知、資料存取、加密和網路控制項如何套用至記錄。

使用者通知和記錄內容

下列聲明和規則規範了對話記錄的內容，以及可查看記錄資料的人員：

  • BigQuery Studio 中的使用者通知：如果代理啟用對話記錄功能，使用者在 BigQuery Studio 與代理對話時，會看到下列通知，包括在使用者傳送第一個提示前的新對話畫面：

    所有提示詞和回覆都會記錄至 BigQuery，具備資料集權限的使用者可以存取。

  • 使用 API 時的責任：如果您在資料代理上啟用對話記錄 (追蹤記錄)，並透過自己的應用程式或整合功能向使用者提供該代理，Google 就無法向這些使用者顯示通知。您有責任根據適用法律和與使用者達成的協議，提供與記錄對話相關的任何通知、揭露事項或同意聲明。詳情請參閱「Conversational Analytics API 的安全性、隱私權、風險和法規遵循」。

  • 記錄內容和可查看記錄的人員：目的地資料表會根據下列隱私權規則儲存問答內容：

    • 完整問答：答案可包含知識來源傳回的值。凡是能讀取記錄資料表的人，都能查看代理傳回給使用者的資料，包括他們無法在來源資料表中讀取的資料。請只將記錄資料集的讀取權限，授予應查看這項內容的人員。

    • 使用者 ID 和寫入位置：user_id 欄會識別提問的呼叫端 (請參閱「使用者身分」)，且資料列只會寫入您在代理專案中設定的目的地。

    • 具有資料列層級安全性、資料欄層級安全性或資料遮蓋功能的資料表：如果代理的知識來源使用資料列層級安全性 (資料列存取權政策)、資料欄層級安全性 (政策標記) 或動態資料遮蓋，則不會記錄其回合。隱私權檢查會略過 bigquery-public-data 中的資料表，只檢查您選為知識來源的資料表和檢視表，不會檢查檢視表背後的資料表：

      • 使用這些政策的資料表檢視表可以通過檢查，因此可以記錄其輪次。啟用記錄功能前，請確認檢視表背後的資料表未使用資料列存取政策、政策標記或資料遮蓋。

      • 如果日後將其中一項政策新增至來源資料表，已記錄的資料列仍會保留在記錄資料表中。如果資料保留或管理政策禁止保留這些資料列，請將其刪除。

存取控管、加密和網路安全

您可以使用下列設定，管理對話記錄的保留、存取、加密和 perimeter 安全性：

  • 記錄資料集的保留和存取控管：設定目的地資料表的保留、資料集角色、資料表政策和稽核記錄：

    • 保留：Google 不會刪除記錄列。在記錄資料集或資料表上，設定符合政策的分區到期時間 (例如 90 天)。

    • 最小權限：將記錄資料集與其他資料集分開，讓共用的 Conversational Analytics API 服務代理寫入權限與其他資料表保持距離。將記錄資料集的 roles/bigquery.dataViewer 授予分析師，或僅授予授權檢視表或授權資料集的存取權。

    • 記錄資料表的資料欄層級和資料列層級控制項：您可以將政策標記、資料遮蓋或資料列存取政策套用至記錄資料表本身，例如 content 或 user_id。這些記錄資料表控制項不會影響知識來源隱私權檢查。

    • 稽核記錄：資料代理程式的變更會記錄在管理員活動稽核記錄中。在 BigQuery 稽核記錄中，服務代理建立資料表和更新中繼資料的記錄會記錄在 bigquery.googleapis.com 下，而透過 Storage Write API (gRPC) 附加資料列的記錄則會記錄在 bigquerystorage.googleapis.com 下。

  • CMEK、VPC Service Controls 和資料落地：下列加密、perimeter 和位置控管機制適用於對話記錄：

    • CMEK：如果記錄資料集使用客戶自行管理的 Cloud KMS 金鑰 (CMEK)，請將金鑰的 roles/cloudkms.cryptoKeyEncrypterDecrypter 角色授予 BigQuery 加密服務帳戶 (bq-PROJECT_NUMBER@bigquery-encryption.s3ns-system.iam.gserviceaccount.com)。資料代理上的 CMEK 會加密代理資源，而非記錄資料表 (請參閱「客戶自行管理的加密金鑰」)。

    • VPC Service Controls：如果使用 service perimeter，請在包含代理專案的 perimeter 中，同時納入 geminidataanalytics.googleapis.com 和 bigquery.googleapis.com。服務代理會從 Google 代管的基礎架構寫入記錄資料表，因此如果 perimeter 限制 bigquery.googleapis.com，請新增類似下列的輸入規則。將 PROJECT_NUMBER 替換為代理程式的專案編號：

      - ingressFrom:
    identities:
    - serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.s3ns-system.iam.gserviceaccount.com
    sources:
    - accessLevel: "*"
  ingressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - permission: bigquery.tables.get
      - permission: bigquery.tables.create
      - permission: bigquery.tables.update
      - permission: bigquery.tables.updateData
    resources:
    - projects/PROJECT_NUMBER

      詳情請參閱「使用 VPC Service Controls 設定 perimeter 安全性」。

    • 資料落地：記錄列和自動建立的資料表會儲存在記錄資料集的位置，並套用資源位置組織政策 (gcp.resourceLocations)。

限制

對話記錄有下列限制：

  • BigQuery Studio 代理編輯器的「Preview」(預覽) 窗格不會記錄。

  • 系統不會記錄不含資料代理的直接對話。

  • 如果代理使用搜尋範圍而非特定資料表，或未宣告任何 BigQuery 資料表，則不會記錄。如果代理將 BigQuery 屬性圖譜設為知識來源，系統就不會記錄。

  • 系統不會記錄生成的 SQL、工具呼叫，以及 Agent Development Kit (ADK) 工具或要求事件 (TOOL_STARTING、TOOL_COMPLETED、TOOL_ERROR 和 LLM_REQUEST)，只會記錄答案、資料結果名稱和圖表名稱。直接從已驗證查詢回答的回合不會寫入 LLM_RESPONSE 資料列，且系統不會記錄失敗的已驗證查詢回合。

  • 系統不會記錄使用者給予的「喜歡」或「不喜歡」意見回饋。

  • 如果知識來源使用資料列存取權政策、資料欄層級安全防護機制 (政策標記) 或資料遮蓋，或者隱私權檢查無法完成，系統就不會記錄對話。這項檢查不會透過檢視表查看其背後的資料表。

  • 僅支援 BigQuery 資料表代理，不支援 Looker、數據分析、AlloyDB、Spanner 和 Cloud SQL 資料來源。

  • 目的地資料集必須已存在於代理所在的專案中。

  • 現有資料表的結構定義變更僅限新增；如果資料欄類型或模式發生衝突，系統會停止寫入該資料表。

  • 系統會記錄所有符合條件的回合，不套用取樣設定，而是在查詢時取樣 (請參閱「對所有代理的問答進行取樣以供審查」)。

  • agent 欄會保留代理類型，而非代理顯示名稱；請使用 attributes 中的資料代理 ID。

  • 如果 API 呼叫端為多位使用者使用同一個服務帳戶，則該服務帳戶的電子郵件會顯示在每一列中。

  • 如果文字值超過 512,000 個字元 (500 * 1,024)，系統會截斷文字並加上 ...[TRUNCATED] 後置字串，且無法復原移除的部分。

  • 寫入作業會盡可能執行，但重試次數有限；寫入失敗的回合不會記錄，重試有時可能會產生重複的資料列 (請使用 event_id 簡化)。

  • 代理不會沿用專案層級的觀測能力設定。

定價

對話式數據分析不會另外收取對話記錄費用。您的專案會依標準 BigQuery 價格支付 BigQuery Storage Write API (gRPC) 資料擷取、儲存和分析查詢費用。BigQuery Storage Write API (gRPC) 擷取作業包含每個帳單帳戶每月 2 TiB 的免費使用額度，由 Storage Write API (gRPC) 使用量共用。篩選 timestamp 上的查詢，減少掃描的位元組數。預先檢查會讀取資料表的中繼資料，並執行模擬查詢，不收費。

後續步驟