設定呼叫 Gemini Enterprise Agent Platform LLM 的生成式 AI 函式權限
本文說明如何設定執行生成式 AI 查詢的權限。生成式 AI 查詢包含 AI.* 函式,可呼叫 Gemini Enterprise Agent Platform 中的基礎模型,例如 AI.GENERATE。
設定權限來執行使用 AI.* 函式的查詢,有兩種方法:
- 使用使用者憑證執行查詢
- 建立 BigQuery 連線,使用服務帳戶執行查詢
在多數情況下,您可以使用使用者憑證,並將 CONNECTION 引數留空。如果查詢工作預計執行 48 小時以上,請使用 BigQuery 連線,並將其納入 CONNECTION 引數。
使用使用者憑證執行生成式 AI 查詢
如要使用使用者憑證執行生成式 AI 查詢,請透過 Google Cloud 控制台設定必要權限。請注意,如果您是專案擁有者,就表示您已具備所有必要權限,因此不需採取任何行動。
必要的角色
如要取得執行查詢工作來呼叫 Agent Platform 模型所需的權限,請要求管理員授予您專案的下列 IAM 角色:
-
執行查詢工作:BigQuery 工作使用者 (
roles/bigquery.jobUser) -
存取 Gemini Enterprise Agent Platform 中的基礎模型:Agent Platform 使用者 (
roles/aiplatform.user)
如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。
將必要角色授予使用者或群組
您可以使用 Google Cloud 控制台或 SQL,為特定主體授予必要角色。主體是指執行查詢的使用者或群組,該查詢會使用 AI.* 函式呼叫 Gemini Enterprise Agent Platform 基礎模型。
控制台
前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。
選取專案。
如要將角色授予主體,請按照下列步驟操作:
前往「IAM & Admin」(IAM 與管理) 頁面。
按一下「Grant access」(授予存取權)。
「Add principals」(新增主體) 對話方塊隨即開啟。
在「New principals」(新增主體) 欄位中,輸入主體 ID,例如
my-user@example.com或//iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com。在「Assign roles」(指派角色) 專區,按一下「Select a role」(請選擇角色) 的下拉式箭頭。
搜尋並選取「Agent Platform 使用者」角色。
按一下 [Add another role] (新增其他角色)。
在「Assign roles」(指派角色) 專區,點選「Select a role」(請選擇角色) 的下拉式箭頭。
搜尋或瀏覽「BigQuery 工作使用者」角色,然後選取該角色。
按一下 [儲存]。
SQL
使用 GRANT 陳述式:
前往 Google Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中輸入下列陳述式:
GRANT `roles/aiplatform.user`, `roles/bigquery.jobUser` ON PROJECT `PROJECT_ID` TO "USER_OR_GROUP";
替換下列內容:
-
PROJECT_ID:您打算使用AI.*函式的專案。 -
USER_OR_GROUP:要授予存取權的使用者或群組,格式為user:USER@DOMAIN或group:GROUP@DOMAIN。
-
按一下「 執行」。
如要進一步瞭解如何執行查詢,請參閱「執行互動式查詢」。
如要修改已具備專案角色的主體角色,請參閱「為相同的主體授予其他角色」。
如要瞭解如何透過其他方法,將專案層級角色授予主體,請參閱「以程式輔助方式授予或撤銷多個 IAM 角色」。
透過 BigQuery 連線執行生成式 AI 查詢
如要使用連線執行生成式 AI 查詢,請建立連線,然後將存取權授予連線建立的服務帳戶。
建立連線
您可以設定 Cloud 資源連結,執行所有包含 AI.* 函式的生成式 AI 查詢。建立連線時,您會將執行查詢的權限授予服務帳戶。
控制台
前往「BigQuery」頁面。
點選左側窗格中的 「Explorer」。

如果沒有看到左側窗格,請按一下 「Expand left pane」(展開左側窗格),開啟窗格。
在「Explorer」窗格中展開專案名稱,然後點選「Connections」(連線)。
在「Connections」(連線) 頁面,按一下「Create connection」(建立連線)。
在「連線類型」部分,選擇「Vertex AI 遠端模型、遠端函式、BigLake 和 Spanner (Cloud 資源)」。
在「連線 ID」欄位輸入連線名稱。
在「位置類型」部分,選取連線位置。連線應與資料集等其他資源位於相同位置。
點選「建立連線」。
點選「前往連線」。
在「連線資訊」窗格中,複製服務帳戶 ID,以便在後續步驟中使用。
SQL
前往 Google Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中輸入下列陳述式:
CREATE CONNECTION [IF NOT EXISTS] `CONNECTION_NAME` OPTIONS ( connection_type = "CLOUD_RESOURCE", friendly_name = "FRIENDLY_NAME", description = "DESCRIPTION" );
替換下列內容:
-
CONNECTION_NAME:連線名稱,格式為PROJECT_ID.LOCATION.CONNECTION_ID、LOCATION.CONNECTION_ID或CONNECTION_ID。如果省略專案或位置,系統會根據執行陳述式的專案和位置推論。 -
FRIENDLY_NAME(選用):連線的描述性名稱。 -
DESCRIPTION(選用):連線說明。
-
按一下「 執行」。
如要進一步瞭解如何執行查詢,請參閱「執行互動式查詢」。
bq
在指令列環境中建立連線:
bq mk --connection --location=REGION --project_id=PROJECT_ID \ --connection_type=CLOUD_RESOURCE CONNECTION_ID
--project_id參數會覆寫預設專案。更改下列內容:
REGION:連線區域PROJECT_ID:您的 Google Cloud 專案 IDCONNECTION_ID:連線 ID
建立連線資源時,BigQuery 會建立專屬的系統服務帳戶,並與連線建立關聯。
疑難排解:如果收到下列連線錯誤,請更新 Google Cloud SDK:
Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
擷取並複製服務帳戶 ID,以便在後續步驟中使用:
bq show --connection PROJECT_ID.REGION.CONNECTION_ID
輸出結果會與下列內容相似:
name properties 1234.REGION.CONNECTION_ID {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}
Python
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Python 設定操作說明進行操作。詳情請參閱 BigQuery Python API 參考文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Node.js
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Node.js 設定操作說明進行操作。詳情請參閱 BigQuery Node.js API 參考文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Java
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Java 設定操作說明進行操作。詳情請參閱 BigQuery Java API 參考文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Terraform
使用 google_bigquery_connection 資源。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
下列範例會在 US 區域建立名為 my_cloud_resource_connection 的 Cloud 資源連結:
如要在 Google Cloud 專案中套用 Terraform 設定,請完成下列各節的步驟。
準備 Cloud Shell
- 啟動 Cloud Shell。
-
設定要套用 Terraform 設定的預設 Google Cloud 專案。
每個專案只需執行這個指令一次,而且可以在任何目錄中執行。
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
如果您在 Terraform 設定檔中設定明確的值,環境變數就會遭到覆寫。
準備目錄
每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。
-
在 Cloud Shell 中建立目錄,並在該目錄中建立新檔案。檔案名稱必須有
.tf副檔名,例如main.tf。在本教學課程中,這個檔案稱為main.tf。mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
如果您正在進行教學課程,可以複製每個章節或步驟中的程式碼範例。
將程式碼範例複製到新建立的
main.tf。您也可以從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分,建議您採用這種做法。
- 請查看並修改範例參數,以便套用至您的環境。
- 儲存變更。
-
初始化 Terraform。每個目錄只需執行一次這項操作。
terraform init
如要使用最新版 Google 供應商,請視需要加入
-upgrade選項:terraform init -upgrade
套用變更
-
查看設定,確認 Terraform 要建立或更新的資源符合預期:
terraform plan
視需要修正設定。
-
執行下列指令,並在提示中輸入
yes,套用 Terraform 設定:terraform apply
等待 Terraform 顯示「Apply complete!」訊息。
- 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台的使用者介面中,前往資源頁面,確認 Terraform 已建立或更新資源。
詳情請參閱「建立及設定 Cloud 資源連結」。
將存取權授予服務帳戶
如要執行查詢,並使用生成式 AI.* 函式呼叫 Gemini Enterprise Agent Platform 模型,您必須為建立連線時建立的服務帳戶授予適當權限。如要執行呼叫 Gemini Enterprise Agent Platform 基礎模型的函式,必須具備 Agent Platform 使用者角色 (roles/aiplatform.user)。
選取下列選項之一:
控制台
前往「IAM & Admin」(IAM 與管理) 頁面。
按一下「Grant access」(授予存取權)。
「Add principals」(新增主體) 對話方塊隨即開啟。
在「新增主體」欄位,輸入先前複製的服務帳戶 ID。
在「指派角色」部分,按一下「新增角色」。
搜尋並選取「Agent Platform 使用者」角色,然後按一下「套用」。
按一下 [儲存]。
SQL
使用 GRANT 陳述式:
前往 Google Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中輸入下列陳述式:
GRANT `roles/aiplatform.user` ON PROJECT `PROJECT_ID` TO "connection:CONNECTION_NAME";
替換下列內容:
-
PROJECT_ID:您打算使用 Agent Platform 的專案。 -
CONNECTION_NAME:連線名稱,格式為PROJECT_ID.LOCATION.CONNECTION_ID或LOCATION.CONNECTION_ID。如果省略專案,系統會從執行陳述式的專案推斷。
-
按一下「 執行」。
如要進一步瞭解如何執行查詢,請參閱「執行互動式查詢」。
gcloud
使用 gcloud projects add-iam-policy-binding 指令:
gcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:$(bq show --format=prettyjson --connection $PROJECT_ID.$REGION.$CONNECTION_ID | jq -r .cloudResource.serviceAccountId)" --role=roles/aiplatform.user
更改下列內容:
PROJECT_ID:專案名稱。REGION:建立連線的位置。CONNECTION_ID:您建立的連線名稱。
Terraform
使用 google_bigquery_connection 資源。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
下列範例會將 IAM 角色存取權授予 Cloud 資源連結的服務帳戶:
如要在 Google Cloud 專案中套用 Terraform 設定,請完成下列各節的步驟。
準備 Cloud Shell
- 啟動 Cloud Shell。
-
設定要套用 Terraform 設定的預設 Google Cloud 專案。
每個專案只需執行這個指令一次,而且可以在任何目錄中執行。
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
如果您在 Terraform 設定檔中設定明確的值,環境變數就會遭到覆寫。
準備目錄
每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。
-
在 Cloud Shell 中建立目錄,並在該目錄中建立新檔案。檔案名稱必須有
.tf副檔名,例如main.tf。在本教學課程中,這個檔案稱為main.tf。mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
如果您正在進行教學課程,可以複製每個章節或步驟中的程式碼範例。
將程式碼範例複製到新建立的
main.tf。您也可以從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分,建議您採用這種做法。
- 請查看並修改範例參數,以便套用至您的環境。
- 儲存變更。
-
初始化 Terraform。每個目錄只需執行一次這項操作。
terraform init
如要使用最新版 Google 供應商,請視需要加入
-upgrade選項:terraform init -upgrade
套用變更
-
查看設定,確認 Terraform 要建立或更新的資源符合預期:
terraform plan
視需要修正設定。
-
執行下列指令,並在提示中輸入
yes,套用 Terraform 設定:terraform apply
等待 Terraform 顯示「Apply complete!」訊息。
- 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台的使用者介面中,前往資源頁面,確認 Terraform 已建立或更新資源。