本頁面由 Cloud Translation API 翻譯而成。

透過 Data Insights 代理程式取得洞察資訊

資料洞察代理程式是由 Google 製作的代理程式，並從 BigQuery 資料提供資料洞察。有了資料洞察代理程式，您不需要具備 SQL 相關知識，這樣您就能根據資料做出明智的業務決策，資料分析師也能專注於更複雜的工作。

本頁說明專案管理員如何使用 Google Cloud 控制台和 REST API 授權、建立及部署 Data Insights 代理程式。 Google Cloud 本頁面也會說明使用者如何使用代理程式。

總覽

資料洞察代理程式的設計用途如下：

瞭解使用者意圖：分析已連結資料來源的內容和使用者的自然語言查詢，瞭解使用者的目標
生成 SQL：根據這項理解，將使用者的問題轉換為語法和語意正確的 SQL 查詢。
擷取資料：接著執行產生的 SQL，直接從已連結的資料來源 (BigQuery 資料集) 擷取相關資料。
提供洞察資料：以圖表、表格等視覺化方式呈現擷取的資料，或以文字摘要形式回答使用者查詢。

您可以向資料洞察代理提出的查詢範例

以下列舉幾個可以向資料洞察代理程式提出的查詢：

資料匯總和視覺化：
- 「與去年第 2 季相比，今年第 2 季的拉丁美洲地區銷售額如何？」
- 「繪製長條圖，顯示該區域前 5 大國家/地區的比較結果。」
趨勢分析：
- 「過去 6 個月，各個地點的撥出電話量有何變化？」
- 「Analyze the booking patterns for the hotels in Lisbon rated higher than 3 stars」(分析里斯本評等高於 3 星的飯店訂房模式)
資料採礦：
- 「顧客購物時，哪些因素與總銷售價值相關？請提供顯示關係的熱視圖。」
分析和報表：
- 「請匯總商機和帳戶表格，並製作簡短報告，重點說明任何重要趨勢。」

事前準備

如要開始在 Gemini Enterprise 中使用資料洞察代理程式，請按照下列步驟操作：

按照操作說明開始使用 Gemini Enterprise。
按照操作說明取得 Gemini Enterprise 授權。
如要存取資料洞察代理程式，請與 Google 帳戶管理員聯絡。
準備 BigQuery 資料。詳情請參閱 BigQuery 說明文件。
如要充分發揮代理程式的效用，請先瞭解 BigQuery 資料集中的資料。

授予 BigQuery 資料存取權

如要讓 Data Insights 代理程式查看及查詢 BigQuery 資料，請將身分與存取權管理 (IAM) 角色授予代理程式的使用者：

工作流程

設定及使用 Data Insights 代理程式的整體工作流程如下：

取得授權詳細資料。
使用 Google Cloud 控制台或 REST API 設定代理程式。
新增或修改使用者及其權限
變更代理程式例項的工作狀態
使用代理程式

取得授權詳細資料

請按照下列步驟設定授權。您必須取得這些詳細資料，才能授權 Data Insights 代理程式連線至 BigQuery 資料。

在 Google Cloud 控制台中，前往「APIs & Services」(API 和服務) 中的「Credentials」(憑證) 頁面。

前往「憑證」
選取 Google Cloud 包含要讓代理程式查詢的 BigQuery 資料集的專案。
按一下「建立憑證」，然後選取「OAuth 用戶端 ID」。
在「應用程式類型」中，選取「網頁應用程式」。
在「已授權的重新導向 URI」部分，新增下列 URI：
- https://vertexaisearch.cloud.google.com/oauth-redirect
- https://vertexaisearch.cloud.google.com/static/oauth/oauth.html
點選「建立」。
在「OAuth client created」(已建立 OAuth 用戶端) 面板中，按一下「Download JSON」(下載 JSON)。下載的 JSON 檔案包含所選Google Cloud 專案的下列詳細資料：您需要這些詳細資料才能建立授權資源：
- 用戶端 ID：CLIENT_ID
- 授權 URI：
```
https://accounts.google.com/o/oauth2/v2/auth?client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbigquery&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
```
- 權杖 URI：TOKEN_URI
- 用戶端密鑰：CLIENT_SECRET

使用 Google Cloud 控制台設定代理程式

本節說明如何使用 Google Cloud 控制台授權、建立及部署 Data Insights 代理程式執行個體。您也可以新增使用者權限，決定誰可以存取建立的代理程式。

授權及建立代理程式執行個體

按照下列步驟授權及建立 Data Insights 代理程式執行個體：

前往 Google Cloud 控制台的「Gemini Enterprise」。

前往 Gemini Enterprise
選取要建立代理程式的應用程式。
按一下選單中的「代理程式」。

「代理程式」頁面會顯示現有代理程式。
按一下「新增代理程式」。
在「建立代理程式」窗格中，按一下「資料代理程式」資訊卡中的「建立」。
在「授權」中，按一下「新增授權」，然後輸入授權詳細資料。詳情請參閱「取得授權」。
按一下 [完成]。
點選「下一步」。
請按以下方式設定代理程式：
1. 輸入代理程式名稱和說明。
2. 在「BigQuery 資料集」中，按一下「瀏覽」，然後執行下列其中一項操作：
  - 選取可用的資料集，然後按一下「選取」。
  - 輸入所需 BigQuery 資料集的路徑，按一下「搜尋」，選取該資料集，然後選取「選取」。
3. 選用：按一下「顯示更多」，即可查看進階選項。
4. 選取正確的資料表存取權選項。如要強制執行允許清單或封鎖清單，請指定受限資料表的路徑。
5. 選用：定義自然語言查詢設定，提供自然語言翻譯為 SQL 或 Python 程式碼的專屬自訂項目。您也可以使用自然語言查詢、預期的 SQL 輸出內容和預期回應，提供 SQL 範例。這有助於提升代理程式輸出內容的品質。
  - 結構定義說明：以自然語言描述 BigQuery 資料集結構定義的字串。
  - 將自然語言查詢轉換為 SQL 程式碼的提示詞：以自然語言查詢，並轉換為 SQL 指令。
  - 將自然語言查詢轉換為 Python 程式碼的提示詞：將自然語言查詢轉換為 Python 指令。
6. 選用：新增轉換為 SQL 查詢的自然語言查詢範例：
  - 查詢：必須轉換為 SQL 查詢的自然查詢範例。例如：「加州客戶的姓名和電子郵件地址為何？」
  - 預期的 SQL：字串，說明與自然語言查詢對應的 SQL 查詢範例。舉例來說，假設您有一個名為 customers 的 BigQuery 資料表。接著，預期的 SQL 查詢可以是 SELECT customer_name, email FROM customers WHERE state = 'California'。
  - 預期回應：執行預期 SQL 查詢後，查詢的預期答案字串。例如：
```
Here are the names and email addresses of your customers in California: \
* Customer name: Lara B, Email address: 222larabrown@gmail.com \
* Customer name: Alex A, Email address: baklavainthebalkans@gmail.com \
* Customer name: Bola C, Email address: cloudysanfrancisco@gmail.com \
```
點選「建立」。

Data Insights 代理程式執行個體會顯示在「Agents」清單中。
如要開始使用代理程式，請等待「Agent state」(代理程式狀態) 欄顯示執行個體的「Enabled」(已啟用)。

使用 REST API 設定代理程式

本節說明如何使用 REST API 授權、建立及部署 Data Insights 代理程式例項。

授權代理程式

管理員可以在 Gemini Enterprise 中建立授權資源。這樣一來，資料洞察代理程式就能存取 BigQuery 資料。

建立授權資源。

REST

下列範例說明如何使用 authorizations.create 方法建立授權資源。

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 -H "X-Goog-User-Project: PROJECT_NUMBER" \
 "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTHORIZATION_ID" \
 -d '{
   "name": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTHORIZATION_ID",
   "serverSideOauth2": {
     "clientId": "CLIENT_ID",
     "clientSecret": "CLIENT_SECRET",
     "authorizationUri": "AUTHORIZATION_URI",
     "tokenUri": "TOKEN_URI"
}
}'

更改下列內容：

PROJECT_NUMBER：您的 Google Cloud 專案編號。
LOCATION：專案 Google Cloud 的位置。
AUTHORIZATION_ID：您必須提供的 ID，用於識別授權資源。
CLIENT_ID：您在上一個步驟中取得的用戶端 ID。
CLIENT_SECRET：您在上一個步驟中取得的用戶端密鑰。
AUTHORIZATION_URI：您在上一個步驟中取得的授權 URI。
TOKEN_URI：在上一個步驟中取得的權杖 URI。

回應

您應該會收到類似以下的回應。請注意 AUTHORIZATION_RESOURCE_NAME，您必須使用這個符號建立資料洞察代理程式。AUTHORIZATION_RESOURCE_NAME 結尾的專屬 ID 就是 AUTHORIZATION_ID。

{
 "name": "AUTHORIZATION_RESOURCE_NAME",
 "serverSideOauth2": {
   "clientId": "CLIENT_ID",
   "clientSecret": "CLIENT_SECRET",
   "tokenUri": "TOKEN_URI",
   "authorizationUri": "AUTHORIZATION_URI"
 }
}

建立虛擬服務專員執行個體

Google Cloud 專案管理員可以建立 Data Insights 代理程式例項。如要使用代理程式查詢 BigQuery 資料，您必須提供專案 ID 和資料集 ID。

REST

以下範例說明如何使用 agents.create 方法建立 Data Insights 代理程式執行個體。如要瞭解可新增至這個範例的進階欄位，請參閱「為代理程式新增進階設定」。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: PROJECT_NUMBER" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
  -d '{
    "displayName": "AGENT_DISPLAY_NAME",
    "description": "AGENT_DESCRIPTION",
    "icon": {
       "uri": "AGENT_ICON_URI"
     },
    "managed_agent_definition": {
      "tool_settings": {
        "tool_description": "AGENT_DESCRIPTION"
      },
      "data_science_agent_config": {
        "bq_project_id": "BIGQUERY_PROJECT_ID",
        "bq_dataset_id": "BIGQUERY_DATASET_ID"
      }
    },
    "authorization_config": {
      "tool_authorizations" : [
        "AUTHORIZATION_RESOURCE_NAME"
      ]
    }
  }'

更改下列內容：

PROJECT_NUMBER：您的 Google Cloud 專案編號。
LOCATION：Gemini Enterprise 應用程式的位置。
APP_ID：應用程式的 ID。
AGENT_DISPLAY_NAME：Data Insights 代理程式執行個體的名稱。
AGENT_ICON_URI：選填欄位，可提供代理程式圖示的 URI。
AGENT_DESCRIPTION：Data Insights 代理程式執行個體的說明，指出代理程式的用途或 BigQuery 資料來源詳細資料。
BIGQUERY_PROJECT_ID：包含 BigQuery 資料集的專案 ID。Google Cloud
BIGQUERY_DATASET_ID：包含要查詢資料的 BigQuery 資料集 ID。
AUTHORIZATION_RESOURCE_NAME：您在上一個部分取得的授權資源名稱。

回應

您應該會收到類似以下的回應。請注意 AGENT_RESOURCE_NAME，您必須使用這個值部署 Data Insights 代理程式。AGENT_RESOURCE_NAME 結尾的專屬 ID 就是 AGENT_ID。

{
  "name": "AGENT_RESOURCE_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "icon": {
    "uri": "AGENT_ICON_URI"
  },
  "createTime": "CREATION_TIME",
  "managedAgentDefinition": {
    "toolSettings": {
      "toolDescription": "AGENT_DISPLAY_NAME"
    },
    "deploymentInfo": {},
    "dataScienceAgentConfig": {
      "bqProjectId": "BIGQUERY_PROJECT_ID",
      "bqDatasetId": "BIGQUERY_DATASET_ID"
    }
  },
  "authorization_config": {
    "tool_authorizations" : [
      "AUTHORIZATION_RESOURCE_NAME"
    ]
  },
  "state": "CONFIGURED"
}

為代理程式新增進階設定

您可以視需要定義 nlQueryConfig 欄位，提供自然語言翻譯成 SQL 或 Python 程式碼的專屬自訂項目。您也可以使用自然語言查詢提供 SQL 範例、預期的 SQL 輸出內容和預期的回應。這有助於提升代理程式的輸出內容品質。下列程式碼片段顯示如何設定這些進階欄位：

"dataScienceAgentConfig": {
  "nlQueryConfig": {
    "nl2sqlPrompt": "NL_TO_SQL_INSTRUCTIONS",
    "nl2pyPrompt": "NL_TO_PYTHON_INSTRUCTIONS",
    "nl2sqlExample": {
      "query": "EXAMPLE_NL_QUERY",
      "expectedSql": "EXPECTED_SQL_QUERY",
      "expectedResponse": "EXPECTED_SQL_RESPONSE"
    },
    "schemaDescription": "NL_DESCRIPTION_OF_BQ_DATASET"
  }
}

更改下列內容：

NL_TO_SQL_INSTRUCTIONS：以自然語言提出的查詢，轉換為 SQL 指令。
NL_TO_PYTHON_INSTRUCTIONS：以自然語言查詢，並轉換為 Python 指令。
EXAMPLE_NL_QUERY：自然語言查詢範例，必須轉換為 SQL 查詢。例如：「位於加州的顧客姓名和電子郵件地址為何？」
EXPECTED_SQL_QUERY：字串，說明與自然查詢對應的範例 SQL 查詢。舉例來說，假設您有一個名為 customers 的 BigQuery 資料表。接著，預期的 SQL 查詢可以是「SELECT customer_name, email FROM customers WHERE state = 'California'」。

EXPECTED_SQL_RESPONSE：字串，提供查詢的預期答案和預期 SQL 查詢。例如：

Here are the names and email addresses of your customers in California: \
* Customer name: Lara B, Email address: 222larabrown@gmail.com \
* Customer name: Alex A, Email address: baklavainthebalkans@gmail.com \
* Customer name: Bola C, Email address: cloudysanfrancisco@gmail.com \

NL_DESCRIPTION_OF_BQ_DATASET：以自然語言描述 BigQuery 資料集結構定義的字串。

部署執行個體

建立 Data Insights 代理程式執行個體後，管理員可以部署該執行個體，供使用者使用。

REST

部署代理程式。以下範例說明如何使用 agents.deploy 方法部署建立的代理程式。部署代理程式是長時間執行的作業 (LRO)。
```
curl -X POST \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 -H "X-Goog-User-Project: PROJECT_NUMBER" \
 "https://discoveryengine.googleapis.com/v1alpha/AGENT_RESOURCE_NAME:deploy" \
 -d '{
   "name":"AGENT_RESOURCE_NAME"
 }'
```
更改下列內容：
- PROJECT_NUMBER：您的 Google Cloud 專案編號。
- AGENT_RESOURCE_NAME：您在上一節建立代理程式時取得的代理程式資源名稱。
回應

您應該會收到類似以下的回應。請注意 DEPLOY_OPERATION_NAME，您必須使用這個方法取得 LRO 的狀態。
```
{
 "name": "DEPLOY_OPERATION_NAME",
 "metadata": {
   "@type": "type.googleapis.com/google.cloud.discoveryengine.v1alpha.DeployAgentMetadata"
 }
}
```
取得部署作業的狀態。下列範例說明如何使用 operations.get 方法取得部署作業的狀態。
```
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://discoveryengine.googleapis.com/v1alpha/DEPLOY_OPERATION_NAME"
```
將 DEPLOY_OPERATION_NAME 替換為您在上一個步驟中部署代理程式時取得的 LRO 名稱。

在回應中，如果 done 欄位的值為 true，則表示部署作業已完成。如果 done 欄位的值為 false，表示部署作業正在進行中。

新增或修改使用者及其權限

按照下列步驟，在 Data Insights 代理程式執行個體中新增或修改主體，並指派特定身分與存取權管理 (IAM) 角色：

控制台

前往 Google Cloud 控制台的「Gemini Enterprise」。

前往 Gemini Enterprise
選取含有 Data Insights 代理程式執行個體的應用程式。
按一下選單中的「代理程式」。

「代理程式」頁面會顯示現有代理程式。
按一下要新增或修改使用者的代理程式。

根據預設，新建立的代理程式沒有任何使用者。
在「Permissioned users」(已授權使用者) 表格中，按一下「Add user」(新增使用者)。
從可用清單中選取「成員類型」。
視類型輸入成員身分，並指派一或多個角色。
- 如果是使用者、群組或服務帳戶，成員字串就是電子郵件地址。
- 如果是網域，成員字串必須是有效的網域名稱。
- 如果是主體，成員字串必須是有效的主體。例如 principal://iam.googleapis.com/locations/global/workforcePools/pool-1/subject/subject-1。
- 如果是主體集，成員字串是有效的主體集。例如 principalSet://iam.googleapis.com/locations/global/workforcePools/pool-1/group/group-1。
- 如果是網域和主體集，系統會為這些網域和主體集內的所有使用者身分和群組指派相同角色。如要安全存取代理程式，請選取個別群組和受控網域或主體集，然後指派最低權限角色。
按一下 [儲存]。

IAM 政策會更新，且使用者會新增至授權使用者清單。
如要修改指派的權限，請按一下「動作」，選取「修改」，然後執行下列其中一項操作：
- 修改指派的角色。
- 新增其他角色。
- 按一下「刪除」即可移除角色。您必須為使用者指派至少一個角色。

變更執行個體的工作狀態

建立 Data Insights 代理程式執行個體後，系統預設會啟用代理程式。您可以按照下列步驟，將工作狀態變更為「已停用」、「已暫停」、「已啟用」或「已刪除」：

控制台

前往 Google Cloud 控制台的「Gemini Enterprise」。

前往 Gemini Enterprise
選取含有 Data Insights 代理程式執行個體的應用程式。
按一下選單中的「代理程式」。

「代理程式」頁面會顯示現有代理程式。
按一下代理程式的「動作」，然後選取下列其中一個選項：
- 已暫停：暫時停用代理程式。不過，只要使用者有權存取代理，無論權限程度為何，都能看到代理。
- 已停用：只有建立者能存取代理。
- 已啟用：讓所有具備存取代理權限的使用者都能使用代理。
- 刪除：刪除代理程式執行個體。

使用代理程式

請按照下列步驟，使用虛擬服務專員取得資料洞察：

應用程式

在應用程式導覽選單中，按一下「代理程式」。
按一下「查看所有代理程式」。
選取 Data Insights 代理程式執行個體。
如果服務專員需要額外授權，請按一下「授權」，並提供授權詳細資料。
按一下「新增檔案」，將檔案做為代理可使用的額外資料來源。
按一下「來源」，選取代理程式必須納入的來源，以提供最相關的資料洞察。
輸入問題或提示，然後按下 Enter 鍵或點選「提交」。

透過 Data Insights 代理程式取得洞察資訊 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

您可以向資料洞察代理提出的查詢範例

事前準備

授予 BigQuery 資料存取權

工作流程

取得授權詳細資料

使用 Google Cloud 控制台設定代理程式

授權及建立代理程式執行個體

使用 REST API 設定代理程式

授權代理程式

REST

回應

建立虛擬服務專員執行個體

REST

回應

為代理程式新增進階設定

部署執行個體

REST

回應

新增或修改使用者及其權限

控制台

變更執行個體的工作狀態

控制台

使用代理程式

應用程式

透過 Data Insights 代理程式取得洞察資訊