本頁面說明如何使用 Identity and Access Management (IAM) 管理 Gemini Enterprise Agent Platform 資源的存取權。如要管理 Gemini Enterprise Agent Platform Workbench 執行個體的存取權,請參閱「Agent Platform Workbench 執行個體存取控管」。
總覽
Agent Platform 使用 IAM 管理資源存取權。規劃資源的存取控管機制時,請考量下列事項:
您可以在專案或資源層級管理存取權。專案層級存取權適用於該專案中的所有資源。特定資源的存取權僅適用於該資源。請參閱「專案層級與資源層級存取權」。
您可以將 IAM 角色指派給主體,藉此授予存取權。您可以透過預先定義的角色輕鬆設定存取權,但建議使用自訂角色,因為您可以自行建立角色,只授予必要的權限。請參閱「IAM 角色」。
IAM 角色
您可以在 Agent Platform 中使用不同類型的 IAM 角色:
自訂角色可讓您選擇特定權限組合、建立具備這些權限的角色,並將該角色授予貴機構的使用者。
預先定義的角色可讓您在專案層級,為 Agent Platform 資源授予一組相關權限。
基本角色 (擁有者、編輯者和檢視者) 可在專案層級控管 Agent Platform 資源的存取權,適用於所有 Google Cloud 服務。
如要在 Agent Platform 專案中新增、更新或移除這些角色,請參閱這份說明文件,瞭解如何授予、變更及撤銷存取權。
自訂角色
自訂角色可讓您選擇一組特定權限、建立具備這些權限的角色,並將該角色授予組織中的使用者。詳情請參閱「瞭解 IAM 自訂角色」。
使用自訂角色授予最小權限
預先定義的角色通常包含超出您需求的權限。您可以建立自訂角色,僅授予主體所需的特定權限。
舉例來說,您可以建立具有 aiplatform.endpoints.predict 權限的自訂角色,然後將該角色指派給端點上的服務帳戶。這可讓服務帳戶呼叫端點進行預測,但無法控制端點。
Agent Platform 的預先定義角色
| Role | Permissions |
|---|---|
Agent Platform Administrator( Grants full access to all resources in Agent Platform. |
|
Aiplatform Editor( Editor role for aiplatform |
|
Agent Platform Express User Beta( Grants user access to Agent Platform Express. |
|
Agent Platform User( Grants access to use all resource in Agent Platform. |
|
Agent Platform Viewer( Grants access to view all resource in Agent Platform. |
|
Agent Platform Agents Admin Role Beta( Grants full administrative access to Agent Platform agents, including reading and managing their memories and their access control policies. |
|
Agent Platform Agents Creator Role Beta( Grants access to create and discover Agent Platform agents and their auth providers. |
|
Agent Platform Agents User Role Beta( Grants access to view agents and to create, update, and delete their tasks. |
|
Agent Platform Agents Viewer Role Beta( Grants read-only access to Agent Platform agents. |
|
Colab Enterprise Admin( Admin role of using colab enterprise. |
|
Colab Enterprise User( User role of using colab enterprise. |
|
Agent Platform Feature Store EntityType owner( Provides full access to all permissions for a particular entity type resource. Lowest-level resources where you can grant this role:
|
|
Agent Platform Express Admin Beta( Grants admin access to Agent Platform Express. |
|
Agent Platform Feature Store Admin( Grants full access to all resources in Agent Platform Feature Store. Lowest-level resources where you can grant this role:
|
|
Agent Platform Feature Store Data Viewer( This role provides permissions to read Feature data. Lowest-level resources where you can grant this role:
|
|
Agent Platform Feature Store Data Writer( This role provides permissions to read and write Feature data. Lowest-level resources where you can grant this role:
|
|
Agent Platform Feature Store Instance Creator( Administrator of Featurestore resources, but not the child resources under Featurestores. Lowest-level resources where you can grant this role:
|
|
Agent Platform Feature Store Resource Viewer( Viewer of all resources in Agent Platform Feature Store but cannot make changes. Lowest-level resources where you can grant this role:
|
|
Agent Platform Feature Store User Beta( Deprecated. Use featurestoreAdmin instead. |
|
Agent Platform Memory Bank Editor Role( Grants edit access to Agent Platform Memory Bank. |
|
Agent Platform Memory Bank User Role( Grants full user access to Agent Platform Memory Bank. |
|
Agent Platform Memory Bank Viewer Role( Grants viewer access to Agent Platform Memory Bank. |
|
Agent Platform Migration Service User( Grants access to use migration service in Agent Platform |
|
Notebook Executor User Beta( Grants users full access to schedules and notebook execution jobs. |
|
Notebook Runtime Admin( Grants full access to all runtime templates and runtimes in Notebook Service. |
|
Notebook Runtime User( Grants users permissions to create runtime resources using a runtime template and manage the runtime resources they created. |
|
Vertex AI Platform Provisioned Throughput Admin Beta( Grants access to use all resources related to Vertex AI Provisioned Throughput |
|
Vertex AI Platform Publisher Provisioned Throughput Admin Beta( Grants Publisher access to use all resources related to Vertex AI Provisioned Throughput Orders |
|
Vertex AI Platform Publisher Provisioned Throughput Viewer Beta( Grants Publisher access to view all resources related to Vertex AI Provisioned Throughput Orders |
|
Agent Platform Sessions Editor Role( Grants edit access to Agent Platform Sessions. |
|
Agent Platform Sessions User Role( Grants full user access to Agent Platform Sessions. |
|
Agent Platform Sessions Viewer Role( Grants viewer access to Agent Platform Sessions |
|
Agent Platform Tensorboard Web App User Beta( Grants access to the Vertex AI TensorBoard web app. |
|
Service agent roles
Service agent roles should only be granted to service agents.
| Role | Permissions |
|---|---|
Vertex AI Agent Sandbox Service Agent( Vertex AI Service Agent used to access Agent Sandbox managed resources in consumer project with restricted permissions. |
|
Vertex AI Batch Prediction Service Agent( Vertex AI Batch Prediction Service Agent for serving batch prediction requests. |
|
Vertex AI Colab Service Agent( Gives Vertex AI Colab the proper permissions to function. |
|
Vertex AI Custom Code Service Agent( Gives Vertex AI Custom Code the proper permissions. The aiplatform.customJobs.create IAM permission is highly privileged. Through Vertex AI Custom Training jobs, it effectively grants editor-level access to other services activated for the consumer project, such as GCS and BigQuery. |
|
Vertex AI Extension Custom Code Service Agent( Gives Vertex AI Extension that executes custom code the permissions it needs to function. |
|
Vertex AI Extension Service Agent( Gives Vertex AI Extension the permissions it needs to function. |
|
Vertex AI Model Monitoring Service Agent( Gives Vertex AI Model Monitoring the permissions it needs to function. |
|
Vertex AI Notebook Service Agent( Vertex AI Service Agent used to run Notebook managed resources in user project with restricted permissions. |
|
Vertex AI Online Prediction Service Agent( Gives Vertex AI Online Prediction the permissions it needs to function. |
|
Vertex AI RAG Data Service Agent( Vertex AI Service Agent used by Vertex RAG to access user imported data, Vertex AI, Document AI processors, and Vector Search in the project |
|
Vertex AI Rapid Eval Service Agent( Vertex AI Service Agent used by GenAI Rapid Evaluation Service to access publisher model endpoints in the user project |
|
Vertex AI Reasoning Engine Service Agent( Gives Vertex AI Reasoning Engine the proper permissions to function. The aiplatform.reasoningEngines.create IAM permission implies read access to the GCS objects of the consumer project through this service agent. |
|
Vertex AI Service Agent( Gives Vertex AI the permissions it needs to function. |
|
Vertex AI Telemetry Service Agent( Allows Vertex AI Telemetry Service Agent to access telemetry data. |
|
Vertex AI Tuning Service Agent( Vertex AI Service Agent used for tuning in user project. |
|
基本角色
舊版 Google Cloud 基本角色 適用於所有 Google Cloud 服務。包括擁有者、編輯者和檢視者。
專案層級與資源層級存取權
您可以在專案或資源層級管理存取權,您可能也可以在資料夾或組織層級管理存取權。
對於大多數 Agent Platform 資源,存取權只能由專案、資料夾和機構控管。您只能針對特定資源類型 (例如端點或特徵儲存庫) 授予個別資源的存取權。
使用者會共用可存取的所有資源控制權。舉例來說,如果使用者註冊模型,專案中所有其他授權使用者都可以存取、變更及刪除模型。
如要授予專案層級的資源存取權,請將一或多個角色指派給主體 (使用者、群組或服務帳戶)。
對於允許在資源層級授予存取權的 Agent Platform 資源,您可以在該資源上設定 IAM 政策。這項政策會定義要將哪些角色指派給哪些主體。
在資源層級設定政策不會影響專案層級政策。資源會繼承其祖先的所有政策。您可以運用這兩個精細程度的權限,自訂權限。 舉例來說,您可以在專案層級授予使用者讀取的權限,讓他們讀取專案中的所有資源,然後在資源層級授予使用者寫入權限。
並非所有 Agent Platform 預先定義的角色和資源都支援資源層級政策。如要瞭解哪些角色可用於哪些資源,請參閱預先定義的角色表格。
支援的資源
Agent Platform 支援 Vertex AI 特徵儲存庫、實體類型和 Model Registry 資源。詳情請參閱「控管 Vertex AI 特徵儲存庫資源的存取權」。Model Registry 存取權是在 Agent Platform 層級管理。
授予或撤銷資源存取權後,這些變更需要一段時間才會生效。詳情請參閱「存取權變更傳播」。
資源、服務帳戶和服務代理
Agent Platform 服務通常會管理執行動作的長時間執行資源,例如執行讀取訓練資料的訓練工作,或提供讀取模型權重的機器學習 (ML) 模型。執行動作時,這類獨立資源會有自己的資源 ID。這個身分與建立資源的主體身分不同。授予資源身分的權限,會定義資源身分可存取的資料和其他資源,而非建立資源的主體權限。
根據預設,Agent Platform 資源會使用 Agent Platform 管理的服務帳戶做為資源 ID。這些服務帳戶稱為 Agent Platform 服務代理,會附加至建立資源的專案。具備特定 Agent Platform 權限的使用者,可以建立使用 Agent Platform 服務代理的資源。部分服務可讓您指定要附加至資源的服務帳戶。資源會使用這個服務帳戶存取其他資源和服務。如要進一步瞭解服務帳戶,請參閱服務帳戶。
Agent Platform 會根據呼叫的 API,使用不同的服務代理。每個服務代理在所屬專案中都有特定的 IAM 權限。資源身分會使用這些權限執行動作,權限可能包括專案中所有 Cloud Storage 資源和 BigQuery 資料的唯讀存取權。
服務帳戶
服務帳戶是應用程式或虛擬機器 (VM) 執行個體使用的特殊帳戶,不屬於個人。您可以建立服務帳戶並指派權限,為資源或應用程式提供特定權限。
如要瞭解如何使用服務帳戶,自訂自訂訓練容器或容器的可用權限,以便為自訂訓練模型提供線上預測服務,請參閱「使用自訂服務帳戶」。
服務帳戶會透過電子郵件地址來識別。
服務代理
系統會自動提供服務代理,讓服務能代表您存取資源。
建立服務代理時,系統會為專案授予預先定義的角色。下表列出 Agent Platform 服務代理、其電子郵件地址和各自的角色:
| 名稱 | 適用於: | 電子郵件地址 | 角色 |
|---|---|---|---|
| Agent Platform 服務代理 | Agent Platform 功能 | service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com |
roles/aiplatform.serviceAgent |
| Gemini Enterprise Agent Platform RAG 資料服務代理 | Agent Platform RAG 會存取使用者匯入的資料、Agent Platform,以及專案中的 Document AI 處理器 | service-PROJECT_NUMBER@gcp-sa-vertex-rag.iam.gserviceaccount.com |
roles/ |
| Gemini Enterprise Agent Platform Custom Code 服務代理 |
自訂訓練程式碼 Ray on Agent Platform 應用程式程式碼 |
service-PROJECT_NUMBER@gcp-sa-aiplatform-cc.iam.gserviceaccount.com |
roles/aiplatform.customCodeServiceAgent |
| Agent Platform 擴充功能服務代理 | Vertex 擴充功能 | service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com |
|
| Cloud AI Platform Notebooks 服務帳戶 | Agent Platform Workbench 功能 | service-PROJECT_NUMBER@gcp-sa-notebooks.iam.gserviceaccount.com |
roles/notebooks.serviceAgent |
只有在執行自訂訓練程式碼,訓練自訂訓練模型時,系統才會建立 Gemini Enterprise Agent Platform 自訂程式碼服務代理。
服務代理角色和權限
請參閱下列授予 Agent Platform 服務代理的角色和權限。
| 角色 | 權限 |
|---|---|
Vertex AI 服務代理( 授予 Vertex AI 正常運作所需的權限。 |
|
Vertex AI RAG 資料服務代理( Vertex RAG 可以透過這個 Vertex AI 服務代理,在專案存取使用者匯入的資料、Vertex AI、Document AI 處理器和 Vector Search |
|
Vertex AI 自訂程式碼服務代理( 可將適當的權限授予 Vertex AI Custom Code。aiplatform.customJobs.create 這項 IAM 權限的範圍相當廣泛,可以透過 Vertex AI Custom Training 工作,讓使用者實質上取得編輯者層級的權限,能夠存取用戶專案已啟用的其他服務,例如 GCS 和 BigQuery。 |
|
Vertex AI 擴充功能服務代理( 可授予 Vertex AI 擴充功能運作所需的權限。 |
|
AI Platform Notebooks 服務代理( 為筆記本服務代理授予管理使用者專案中筆記本執行個體的權限 |
|
授予 Agent Platform 服務代理其他資源的存取權
有時您需要為 Agent Platform 服務代理授予其他角色。舉例來說,如果需要 Agent Platform 存取其他專案中的 Cloud Storage bucket,您必須為服務代理授予一或多個額外角色。
BigQuery 的角色新增規定
下表說明,如果 BigQuery 資料表或檢視表位於其他專案,或由外部資料來源支援,則須為代理平台服務代理新增哪些額外角色。
住家專案是指 Agent Platform 資料集或模型所在的專案。「不同專案」一詞是指任何其他專案。
| 資料表類型 | 資料表專案 | 資料來源專案 | 必須新增角色 |
|---|---|---|---|
| 原生 BigQuery 資料表 | 住家專案 | 不適用 | 無 |
| 原生 BigQuery 資料表 | 其他專案 | 不適用 | 不同專案的 BigQuery Data Viewer。瞭解詳情。 |
| BigQuery 檢視畫面 | 住家專案 | 不適用 | 無 |
| BigQuery 檢視表 | 其他專案 | 不適用 | 不同專案的BigQuery Data Viewer。瞭解詳情。 |
| 以 Bigtable 為基礎的外部 BigQuery 資料來源 | 住家專案 | 住家專案 | Bigtable Reader 適用於居家專案。瞭解詳情。 |
| 由 Bigtable 支援的外部 BigQuery 資料來源 | 住家專案 | 其他專案 | Bigtable Reader,適用於不同專案。瞭解詳情。 |
| 由 Bigtable 支援的外部 BigQuery 資料來源 | 其他專案 | 其他專案 | BigQuery Reader和Bigtable Reader,瞭解詳情。 |
| 由 Cloud Storage 支援的外部 BigQuery 資料來源 | 住家專案 | 住家專案 | 無 |
| 由 Cloud Storage 支援的外部 BigQuery 資料來源 | 住家專案 | 其他專案 | 不同專案的 Storage Object Viewer。瞭解詳情。 |
| 由 Cloud Storage 支援的外部 BigQuery 資料來源 | 其他專案 | 其他專案 | Storage Object Viewer 和 BigQuery Data Viewer 適用於不同專案。瞭解詳情。 |
| 以 Google 試算表為基礎的外部 BigQuery 資料來源 | 住家專案 | 不適用 | 與 Agent Platform 服務帳戶共用試算表檔案。瞭解詳情。 |
| 以 Google 試算表為基礎的外部 BigQuery 資料來源 | 其他專案 | 不適用 | BigQuery Reader 適用於不同專案,並與 Agent Platform 服務帳戶共用試算表檔案。 |
Cloud Storage 的角色新增規定
如要存取其他專案中 Cloud Storage bucket 的資料,您必須將 Storage > Storage Object Viewer 角色授予該專案中的 Agent Platform。瞭解詳情。
如果您使用 Cloud Storage bucket 接收本機電腦的資料,以便執行匯入作業,且 bucket 位於Google Cloud 專案以外的專案,則必須將 Storage > Storage Object Creator 角色授予該專案中的 Agent Platform。瞭解詳情。
授予 Agent Platform 存取主專案資源的權限
如要將其他角色授予住家專案中的 Agent Platform 服務代理,請按照下列步驟操作:
前往 Google Cloud 控制台主專案的「IAM」頁面。
勾選「包含 Google 提供的角色授予項目」核取方塊。
決定要授予權限的服務代理,然後按一下 鉛筆圖示。
您可以篩選「主體:@gcp-sa-aiplatform-cc」。iam.gserviceaccount.com,找出 Agent Platform 服務代理。
將必要角色授予服務代理,並儲存變更。
將 Agent Platform 存取權授予其他專案中的資源
在不同專案中使用資料來源或目的地時,您必須在該專案中授予 Agent Platform 服務代理權限。啟動第一個非同步工作 (例如建立端點) 後,系統就會建立 Agent Platform 服務代理程式。您也可以明確建立 Agent Platform 服務代理程式。詳情請參閱「gcloud beta services identity create」。這項 Google Cloud CLI 指令會建立主要服務代理和自訂程式碼服務代理。不過,回應中只會傳回主要服務代理。
如要在其他專案中新增 Agent Platform 的權限,請按照下列步驟操作:
前往主專案 (使用 Agent Platform 的專案) 的 Google Cloud 控制台「IAM」頁面。
勾選「包含 Google 提供的角色授予項目」核取方塊。
決定要授予權限的服務代理,並複製其電子郵件地址 (列在「Principal」(主體) 下方)。
您可以篩選「主體:@gcp-sa-aiplatform-cc.iam.gserviceaccount.com,找出 Agent Platform 服務代理。
將專案變更為需要授予權限的專案。
按一下「新增」,然後在「新增主體」中輸入電子郵件地址。
新增所有必要角色,然後按一下「儲存」。
提供 Google 試算表存取權
如果使用 Google 試算表支援的外部 BigQuery 資料來源,請務必與 Agent Platform 服務帳戶共用試算表。啟動第一個非同步工作 (例如建立端點) 後,系統會建立 Agent Platform 服務帳戶。您也可以按照這項操作說明,使用 gcloud CLI 明確建立 Agent Platform 服務帳戶。
如要授權 Agent Platform 存取 Google 試算表檔案,請按照下列步驟操作:
前往 Google Cloud 控制台的「IAM」頁面。
找出名稱為
Agent Platform Service Agent的服務帳戶,並複製其電子郵件地址 (列在「主體」下方)。開啟 Google 試算表檔案,並與該地址共用。
後續步驟
- 進一步瞭解 IAM。
- 瞭解特定 IAM 權限及其支援的操作。
- 如要瞭解為團隊設定專案的建議方式,請參閱「為團隊設定專案」。
- 概略瞭解 Agent Platform。