開發人員可以透過 geminidataanalytics.googleapis.com 或區域端點存取對話式數據分析 API,建構採用人工智慧 (AI) 技術的對話介面或資料代理。這項 API 會使用自然語言,回答有關 BigQuery、Looker、數據分析和資料庫資料來源 (AlloyDB、GoogleSQL for Spanner、MySQL 適用的 Cloud SQL,以及 v1beta 預先發布版的 PostgreSQL 適用的 Cloud SQL) 中結構化資料的問題。除了多輪對話,您也可以使用 QueryData 方法執行單輪查詢。
透過 Conversational Analytics API,您可以為資料代理提供業務資訊和資料 (背景資訊),並授予 SQL、Python 和視覺化程式庫等工具的存取權。這些代理回覆會呈現給使用者,並可由用戶端應用程式記錄,打造流暢且可稽核的資料對話體驗。
瞭解 Gemini for Google Cloud 如何使用您的資料。
開始使用對話式數據分析 API
如要開始使用對話式數據分析 API,請參閱下列說明文件,瞭解可用的整合方法和核心概念:
- 架構和重要概念:瞭解資料代理如何處理要求、代理建立者和使用者的工作流程、對話模式,以及必要的 Identity and Access Management (IAM) 角色。
- 資料代理的整合模式:比較架構方法,判斷最適合應用程式的連線方式。
- 狀態管理:瞭解有狀態和無狀態對話模式、API 如何管理對話記錄,以及 ADK 工作階段狀態範圍。
- 安全性、隱私權、風險和法規遵循:瞭解對話式數據分析 API 的安全性和法規遵循選項。
- 對話式數據分析 API 位置:提供區域或多區域 API 端點的總覽,讓您控管代理資源、設定和資料的地理位置。
如要開始建構資料代理,請完成設定和必要條件說明文件中的步驟。如需逐步操作說明、範例應用程式、SDK 和其他開發人員工具,請參閱「Conversational Analytics API 教學課程、示範和工具」。
設定和事前準備
使用 API 或範例前,請先完成下列步驟:
- 啟用對話式數據分析 API:說明啟用對話式數據分析 API 的必要條件。
- 使用 IAM 控管存取權:說明如何使用 Identity and Access Management 共用及管理資料代理存取權。
- 驗證並連線至資料來源:提供驗證 API 的操作說明,以及設定連線至 BigQuery、Lakehouse、Looker、數據分析和資料庫資料來源 (AlloyDB、GoogleSQL for Spanner、MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL) 的操作說明。
- 連線至 BigQuery:說明必要角色,以及如何將資料代理連結至 BigQuery 資料表和圖表。
- 連線至 Looker:說明如何將資料代理連結至 Looker 探索,並驗證 Looker 執行個體。
- 客戶自行管理的加密金鑰 (CMEK):說明如何在 Cloud Key Management Service 使用自己的加密金鑰,保護資料代理和對話。
- 組織政策限制:說明如何使用預先定義的組織政策限制,在組織、資料夾或專案層級控管資源。
建構資料代理並與其互動
完成上述步驟後,請按照下列步驟,使用 Conversational Analytics API 建構資料代理並與其互動:
- 使用 HTTP 建構資料代理:提供已完成樣本,說明如何使用 Python 透過直接 HTTP 要求建構資料代理並與其互動。
- 使用 Python SDK 建構資料代理:提供已完成樣本,說明如何使用 Python SDK 建構資料代理並與其互動。
- 使用 A2A 調度管理資料代理:瞭解如何探索代理能力、委派數據分析查詢,以及在多代理系統中串流 SQL 查詢和圖表視覺化。
- 使用編寫的背景資訊引導代理行為:瞭解如何提供編寫的背景資訊,引導代理行為並提高回覆準確度。您也可以查看使用 BigQuery 資料來源和 Looker 資料來源編寫的內容範例。
將對話式數據分析 API 回應代理回覆轉為圖表:提供範例,說明如何使用 Python SDK 和 Vega-Altair 程式庫,處理 API 回應中的圖表規格,並轉為圖表。
設定對話記錄:瞭解如何將資料代理的對話記錄到 BigQuery 資料表,以便查看使用者的問題和代理的回覆。
最佳做法
請參閱下列指南,瞭解使用 Conversational Analytics API 的最佳做法:
- 管理代理的 BigQuery 費用:瞭解如何設定專案層級、使用者層級和查詢層級的支出上限,監控及管理對話式數據分析 API 代理的 BigQuery 費用。
- 提出有效問題:瞭解如何為代理程式精心設計有效問題,充分發揮對話式數據分析 API 的效益。
- 資料保留與刪除:瞭解 Conversational Analytics API 資料代理、對話和對話記錄的資料保留與刪除。
- 配額與限制:瞭解 Conversational Analytics API 的配額與限制。
- 排解 Conversational Analytics API 錯誤:排解常見的 Conversational Analytics API 錯誤。
- 已知限制:提供有關對話式數據分析 API 已知限制的詳細資料,包括查詢、資料、圖表和問題的限制。
- 為 Looker 資料來源轉譯代理回覆:瞭解使用 Looker 資料來源時,在使用者介面轉譯 Conversational Analytics API 回應的最佳做法。
API 參考資料和用戶端程式庫
- Gemini Data Analytics REST 參考資料:提供 API 版本、方法、端點和類型定義的詳細說明。
- SDK 和開發人員工具:列出特定語言的用戶端程式庫。
重要 API 作業
API 提供下列核心端點,用於管理資料代理和對話。下表中的 v1 端點支援 BigQuery、Looker 和數據分析資料來源。由於資料庫資料來源在 v1beta 中處於預先發布版,請指定資料庫來源的對應 /v1beta/ 路徑。
建構這些路徑 (或對應的 SDK 資源名稱) 時,請將萬用字元 (*) 替換為專案 ID、位置 ID (例如 global 或 us) 和資源 ID (例如代理 ID 或對話 ID) (如適用)。
| 作業 | HTTP 方法 | 端點 | 說明 |
|---|---|---|---|
| 建立虛擬服務專員 | POST |
/v1/projects/*/locations/*/dataAgents |
建立新的資料代理。 |
| 同步建立代理 | POST |
/v1/projects/*/locations/*/dataAgents:createSync |
同步建立新的資料代理。 |
| 取得代理 | GET |
/v1/projects/*/locations/*/dataAgents/* |
擷取特定資料代理程式的詳細資料。 |
| 取得 Identity and Access Management 政策 | POST |
/v1/projects/*/locations/*/dataAgents/*:getIamPolicy |
取得指派給每位使用者的特定資料代理 Identity and Access Management 權限。具備資料代理擁有者角色的使用者,可以呼叫這個端點來查看資料代理的 Identity and Access Management 政策,然後再使用 setIAMpolicy 端點與其他使用者共用資料代理。 |
| 設定 Identity and Access Management 政策 | POST |
/v1/projects/*/locations/*/dataAgents/*:setIamPolicy |
設定特定資料代理的 Identity and Access Management 政策。具備資料代理擁有者角色的使用者應呼叫這個端點,與其他使用者共用資料代理,這會有效更新這些使用者的 Identity and Access Management 權限。 |
| 更新代理 | PATCH |
/v1/projects/*/locations/*/dataAgents/* |
修改現有的資料代理。 |
| 同步更新代理 | PATCH |
/v1/projects/*/locations/*/dataAgents/*:updateSync |
同步修改現有資料代理。 |
| 列出代理程式 | GET |
/v1/projects/*/locations/*/dataAgents |
列出專案中可用的資料代理。 |
| 列出可存取的代理 | GET |
/v1/projects/*/locations/*/dataAgents:listaccessible |
列出專案中可存取的資料代理。如果叫用這個 API 的使用者具備代理的 get 權限,則視為可存取資料代理。您可以使用 creator_filter 欄位,管理這個方法傳回的代理:
|
| 刪除代理程式 | DELETE |
/v1/projects/*/locations/*/dataAgents/* |
移除資料代理。 |
| 同步刪除代理 | DELETE |
/v1/projects/*/locations/*/dataAgents/*:deleteSync |
同步移除資料代理。 |
| 建立對話 | POST |
/v1/projects/*/locations/*/conversations |
發起新的永久對話。 |
| 使用對話參考資料進行對話 | POST |
/v1/projects/*/locations/*:chat |
傳送即時通訊訊息,參照現有對話和相關聯的代理結構定義,繼續進行有狀態的對話。 Google Cloud 會儲存及管理多輪對話的記錄。 |
| 使用資料代理參考資料進行對話 | POST |
/v1/projects/*/locations/*:chat |
傳送無狀態即時通訊訊息,並參照已儲存的資料代理做為背景資訊。如果是多輪對話,應用程式必須管理並提供每項要求的對話記錄。 |
| 使用內嵌內容進行對話 | POST |
/v1/projects/*/locations/*:chat |
直接在要求中提供所有情境資訊,傳送無狀態即時通訊訊息,不使用已儲存的資料代理。如果是多輪對話,應用程式必須管理並提供每項要求的對話記錄。 |
| 取得對話 | GET |
/v1/projects/*/locations/*/conversations/* |
擷取特定對話的詳細資料。 |
| 列出對話 | GET |
/v1/projects/*/locations/*/conversations |
列出特定專案中的對話。 |
| 列出對話中的訊息 | GET |
/v1/projects/*/locations/*/conversations/*/messages |
列出特定對話中的訊息。 |
| 刪除對話 | DELETE |
/v1/projects/*/locations/*/conversations/* |
刪除特定對話。您必須具備主題管理員 Identity and Access Management 角色,或至少具備 cloudaicompanion.topics.delete Identity and Access Management 權限,才能呼叫這個端點。 |
| 查詢資料 | POST |
/v1beta/projects/*/locations/*/conversations:queryData |
使用自然語言查詢 AlloyDB、GoogleSQL for Spanner、MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL 資料庫。 |
| 取得代理資訊卡 (A2A) | GET |
/v1/a2a/projects/*/locations/*/agents/*/v1/card |
使用 A2A 通訊協定,擷取內建或自訂資料代理的功能、技能和支援的擴充功能。 |
| 傳送訊息 (A2A) | POST |
/v1/a2a/projects/*/locations/*/agents/*/v1/message:send |
使用 A2A 通訊協定,將訊息傳送至資料代理。 |
| 傳送串流訊息 (A2A) | POST |
/v1/a2a/projects/*/locations/*/agents/*/v1/message:stream |
使用 A2A 通訊協定將串流訊息傳送至資料代理,傳回即時推論進度和結構化構件 (例如 SQL 查詢和圖表視覺化)。 |
支援和意見回饋
如需協助或回報問題,請與客戶服務團隊聯絡。請按照「建立及管理客服案件」一文的指引,建立客服案件。建立案件時,請遵循下列規範:
- 如需 Conversational Analytics API 搭配 BigQuery 的支援服務,請在「選取產品」清單中選取「BigQuery」,並在「功能」欄位中選取「AI 與機器學習::BigQuery 中的 Conversational Analytics API」。
- 如需 Conversational Analytics API with Looker 的支援,請在「選取產品」清單中選取「Looker (原始)」,並在「功能」欄位中選取「Gemini in Looker::Conversational Analytics API」。
如果您對 Conversational Analytics API 有一般意見或疑問,請傳送電子郵件至 conversational-analytics-api-feedback@google.com。我們不保證會回覆電子郵件,但會閱讀電子郵件,並在規劃藍圖時參考這些意見。
您也可以提交功能要求,申請新的 對話式數據分析 API 功能。