對話內容分析 API：建構資料代理程式，並與資料對話

開發人員可使用透過 geminidataanalytics.googleapis.com 存取的對話式數據分析 API，建構人工智慧 (AI) 輔助的聊天介面或資料代理，以自然語言回答有關 BigQuery、Looker 和 Looker Studio 中結構化資料的問題。透過 Conversational Analytics API，您可以為資料代理程式提供業務資訊和資料 (context)，以及 SQL、Python 和視覺化程式庫等工具的存取權。這些服務專員回覆會顯示給使用者，且可由用戶端應用程式記錄，打造流暢且可稽核的資料即時通訊體驗。

瞭解 Gemini for Google Cloud 如何使用您的資料。

開始使用 Conversational Analytics API

如要開始使用 Conversational Analytics API，請先參閱架構和重要概念說明文件，瞭解代理程式如何處理要求、代理程式建立者和使用者的工作流程、對話模式，以及身分與存取權管理 (IAM) 角色。您也可以觀看這部 Conversational Analytics API 簡介影片，瞭解 API 和主要功能。

如要開始建構資料代理程式，您可以選擇透過快速入門導覽課程、程式碼研究室、筆記本、Agent Development Kit (ADK) 和 MCP Toolbox 取得指引，也可以按照「設定和必要條件」一文中的步驟，自行建構資料代理程式。

快速入門導覽課程

使用 Streamlit 快速入門應用程式，在本地測試環境中與 Conversational Analytics API 整合。

查看對話式數據分析的示範和工具，瞭解 Conversational Analytics API 的功能，以及實用的整合模式。

程式碼研究室

請按照逐步教學課程，瞭解如何透過 Conversational Analytics API Codelab，搭配 BigQuery 資料使用 Python SDK。

筆記本

使用下列 Conversational Analytics API Colaboratory 筆記本，取得導覽體驗，協助您開始使用 Conversational Analytics API：

  • HTTP Colaboratory 筆記本：提供互動式逐步指南，說明如何設定環境、建構資料代理程式，以及使用 HTTP 要求發出 API 呼叫。
  • Python SDK Colaboratory 筆記本：提供互動式逐步指南，說明如何設定環境、建構資料代理程式，以及使用 Python SDK 進行 API 呼叫。

Agent Development Kit (ADK) 和 MCP Toolbox

瞭解如何使用 Agent Development Kit (ADK) 中的 ask_data_insights 函式，以自然語言回答有關資料的問題。

資料庫專用的 MCP Toolbox 提供下列工具，可透過對話式數據分析 API，使用自然語言查詢資料來源：

用戶端程式庫

以下 Conversational Analytics API 用戶端程式庫提供安裝說明和參考說明文件：

設定和必要條件

使用 API 或範例之前，請先完成下列步驟：

建構及使用資料代理程式

完成上述步驟後，請按照下列步驟操作，使用 Conversational Analytics API 建構資料代理程式並與之互動：

最佳做法

請參閱下列指南，瞭解使用 Conversational Analytics API 的最佳做法：

  • 管理代理程式的 BigQuery 費用：瞭解如何設定專案層級、使用者層級和查詢層級的支出上限，監控及管理 Conversational Analytics API 代理程式的 BigQuery 費用。
  • 提出有效問題：瞭解如何為服務專員設計有效問題，充分運用對話式分析 API。
  • 排解對話式數據分析 API 錯誤：排解常見的對話式數據分析 API 錯誤。
  • 已知限制：詳細說明 Conversational Analytics API 的已知限制，包括查詢、資料、視覺化和問題的限制。

主要 API 作業

這個 API 提供下列核心端點，用於管理資料代理程式和對話：

作業 HTTP 方法 端點 說明
建立虛擬服務專員 POST /v1beta/projects/*/locations/*/dataAgents 建立新的資料代理程式。
取得代理程式 GET /v1beta/projects/*/locations/*/dataAgents/* 擷取特定資料代理程式的詳細資料。
取得 Identity and Access Management 政策 POST /v1beta/projects/*/locations/*/dataAgents/*:getIamPolicy 取得指派給特定資料代理程式的每位使用者身分與存取權管理權限。具有資料代理程式擁有者角色的使用者可以呼叫這個端點，查看資料代理程式的身分與存取權管理政策，然後使用 setIAMpolicy 端點與其他使用者共用資料代理程式。
設定身分與存取權管理政策 POST /v1beta/projects/*/locations/*/dataAgents/*:setIamPolicy 為特定資料代理程式設定 Identity and Access Management 政策。具有資料代理程式擁有者角色的使用者應呼叫這個端點，與其他使用者共用資料代理程式，這會有效更新這些使用者的身分與存取權管理權限。
更新代理程式 PATCH /v1beta/projects/*/locations/*/dataAgents/* 修改現有資料代理程式。
列出代理程式 GET /v1beta/projects/*/locations/*/dataAgents 列出專案中可用的資料代理程式。
列出可存取的代理程式 GET /v1beta/projects/*/locations/*/dataAgents:listaccessible 列出專案中可存取的資料代理程式。如果呼叫此 API 的使用者具備代理程式的 get 權限，則視為可存取資料代理程式。您可以使用 creator_filter 欄位管理這個方法傳回的代理程式：
  • NONE (預設)：傳回使用者可存取的所有資料代理程式，無論代理程式是由誰建立。
  • CREATOR_ONLY：只會傳回使用者可存取且由該使用者建立的資料代理程式。
  • NOT_CREATOR_ONLY：只會傳回使用者可存取且由他人建立的資料代理程式。
刪除代理程式 DELETE /v1beta/projects/*/locations/*/dataAgents/* 移除資料代理程式。
建立對話 POST /v1beta/projects/*/locations/*/conversations 發起新的持續性對話。
使用對話參考資料進行即時通訊 POST /v1beta/projects/*/locations/*:chat 傳送參照現有對話及其相關聯代理程式情境的即時通訊訊息，繼續進行有狀態的對話。如果是多輪對話， Google Cloud 會儲存及管理對話記錄。
使用資料代理程式參照進行即時通訊 POST /v1beta/projects/*/locations/*:chat 傳送無狀態的即時通訊訊息，並參照已儲存的資料代理程式來提供背景資訊。如果是多輪對話，應用程式必須管理對話記錄，並在每個要求中提供記錄。
使用內嵌脈絡對話 POST /v1beta/projects/*/locations/*:chat 直接在要求中提供所有內容，不使用已儲存的資料代理程式，傳送無狀態的即時通訊訊息。如果是多輪對話，應用程式必須管理對話記錄，並在每個要求中提供記錄。
取得對話 GET /v1beta/projects/*/locations/*/conversations/* 擷取特定對話的詳細資料。
列出對話 GET /v1beta/projects/*/locations/*/conversations 列出特定專案中的對話。
列出對話中的訊息 GET /v1beta/projects/*/locations/*/conversations/*/messages 列出特定對話中的訊息。
刪除對話 DELETE /v1beta/projects/*/locations/*/conversations/* 刪除特定對話。如要呼叫這個端點，您必須具備 Topic Admin Identity and Access Management 角色，或至少具備 cloudaicompanion.topics.delete Identity and Access Management 權限。

提供意見

如要回報錯誤或要求功能，請使用下列連結。

其他資源

對話式分析 API REST 參考資料詳細說明瞭要求和回應結構的方法、端點和型別定義。