Vertex AI 持續性資源是長期執行的叢集，可用於執行自訂訓練工作和管線執行作業。為管線執行作業使用永久資源，有助於確保運算資源可用性，並縮短管線工作啟動時間。持續性資源支援自訂訓練工作支援的所有 VM 和 GPU。如要進一步瞭解永久資源，請參閱「永久資源總覽」。
本頁面說明如何執行下列操作：
事前準備
如要使用持續性資源建立管道執行作業，請先完成下列先決條件。
定義及編譯管道
定義管道，然後將管道定義編譯為 YAML 檔案。如要進一步瞭解如何定義及編譯管道，請參閱「建構管道」。
必要 IAM 角色
如要取得建立永久資源所需的權限，請要求管理員授予您專案的 Vertex AI 管理員 (roles/aiplatform.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。
這個預先定義的角色具備 aiplatform.persistentResources.create權限，這是建立永久資源的必要權限。
建立永久性資源
請使用下列範例建立永久性資源，並與管道執行作業建立關聯。如要進一步瞭解如何建立永久資源，請參閱「建立永久資源」。
gcloud
如要建立可與管道執行作業建立關聯的永久資源，請使用 gcloud ai persistent-resources create 指令搭配 --enable-custom-service-account 旗標。
持續性資源可有一或多個資源集區。如要在永久資源中建立多個資源集區，請指定多個 --resource-pool-spec 旗標。
您可以指定所有資源集區設定做為指令列的一部分，也可以使用 --config 標記指定 YAML 檔案的路徑，該檔案包含設定。
使用下列任何指令資料之前，請先替換以下項目：
- PROJECT_ID：您要在哪個 Google Cloud 專案中建立持續性資源，請輸入該專案的 ID。
- LOCATION：您要在其中建立永久資源的地區。如需支援的地區清單，請參閱「功能適用情形」。
- PERSISTENT_RESOURCE_ID：永久資源的專屬使用者定義 ID。開頭須為英文字母，結尾則須為英文字母或數字，其他部分只能使用小寫英文字母、數字和連字號 (-)。
- DISPLAY_NAME：選用。永久資源的顯示名稱。
- MACHINE_TYPE：要使用的虛擬機器 (VM) 類型。如需支援的 VM 清單，請參閱「機器類型」。這個欄位對應於
ResourcePoolAPI 訊息中的machineSpec.machineType欄位。 - REPLICA_COUNT：選用。如不想使用自動調度資源功能，請指定要為資源集區建立的副本數量。這個欄位對應於
ResourcePoolAPI 訊息中的replicaCount欄位。如未指定 MIN_REPLICA_COUNT 和 MAX_REPLICA_COUNT 欄位，就必須指定副本數量。 - MIN_REPLICA_COUNT：選用。如果您為資源集區使用自動調度資源，這是指備用資源數量下限。如要使用自動調度功能，請務必同時指定 MIN_REPLICA_COUNT 和 MAX_REPLICA_COUNT。
- MAX_REPLICA_COUNT：選用。如果您為資源集區啟用自動調度資源功能，這是指備用資源的數量上限。如要使用自動調度功能，請務必同時指定 MIN_REPLICA_COUNT 和 MAX_REPLICA_COUNT。
- CONFIG：持續性資源 YAML 設定檔的路徑，內含
ResourcePool規格清單。如果設定檔和指令列引數中都指定了選項，則指令列引數會覆寫設定檔。請注意，含有底線的金鑰會視為無效。YAML 設定檔範例：
resourcePoolSpecs: machineSpec: machineType: n1-standard-4 replicaCount: 1
執行下列指令：
Linux、macOS 或 Cloud Shell
gcloud ai persistent-resources create \ --persistent-resource-id=PERSISTENT_RESOURCE_ID \ --display-name=DISPLAY_NAME \ --project=PROJECT_ID \ --region=LOCATION \ --resource-pool-spec="replica-count=REPLICA_COUNT,machine-type=MACHINE_TYPE,min-replica-count=MIN_REPLICA_COUNT,max-replica-count=MAX_REPLICA_COUNT" \ --enable-custom-service-account
Windows (PowerShell)
gcloud ai persistent-resources create ` --persistent-resource-id=PERSISTENT_RESOURCE_ID ` --display-name=DISPLAY_NAME ` --project=PROJECT_ID ` --region=LOCATION ` --resource-pool-spec="replica-count=REPLICA_COUNT,machine-type=MACHINE_TYPE,min-replica-count=MIN_REPLICA_COUNT,max-replica-count=MAX_REPLICA_COUNT" ` --enable-custom-service-account
Windows (cmd.exe)
gcloud ai persistent-resources create ^ --persistent-resource-id=PERSISTENT_RESOURCE_ID ^ --display-name=DISPLAY_NAME ^ --project=PROJECT_ID ^ --region=LOCATION ^ --resource-pool-spec="replica-count=REPLICA_COUNT,machine-type=MACHINE_TYPE,min-replica-count=MIN_REPLICA_COUNT,max-replica-count=MAX_REPLICA_COUNT" ^ --enable-custom-service-account
您應該會收到類似以下的回應：
Using endpoint [https://us-central1-aiplatform.googleapis.com/] Operation to create PersistentResource [projects/PROJECT_NUMBER/locations/us-central1/persistentResources/mypersistentresource/operations/OPERATION_ID] is submitted successfully. You can view the status of your PersistentResource create operation with the command $ gcloud ai operations describe projects/sample-project/locations/us-central1/operations/OPERATION_ID
gcloud 指令範例：
gcloud ai persistent-resources create \
--persistent-resource-id=my-persistent-resource \
--region=us-central1 \
--resource-pool-spec="replica-count=4,machine-type=n1-standard-4"
--enable-custom-service-account
進階gcloud設定
如要指定上述範例中未提供的設定選項，可以使用 --config 旗標，在含有 persistentResources 欄位的本機環境中，指定 config.yaml 檔案的路徑。例如：
gcloud ai persistent-resources create \
--persistent-resource-id=PERSISTENT_RESOURCE_ID \
--project=PROJECT_ID \
--region=LOCATION \
--config=CONFIG
--enable-custom-service-account
Python
在試用這個範例之前，請先按照Python使用用戶端程式庫的 Vertex AI 快速入門中的操作說明進行設定。 詳情請參閱 Vertex AI Python API 參考說明文件。
如要向 Vertex AI 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。
如要建立可搭配管道執行的持續性資源，請在建立持續性資源時，將ResourceRuntimeSpec 物件中的 enable_custom_service_account 參數設為 True。
from google.cloud.aiplatform.preview import persistent_resource
from google.cloud.aiplatform_v1beta1.types.persistent_resource import ResourcePool
from google.cloud.aiplatform_v1beta1.types.machine_resources import MachineSpec
my_example_resource = persistent_resource.PersistentResource.create(
persistent_resource_id='PERSISTENT_RESOURCE_ID',
display_name='DISPLAY_NAME',
resource_pools=[
ResourcePool(
machine_spec=MachineSpec(
machine_type='MACHINE_TYPE'
),
replica_count=REPLICA_COUNT
)
],
enable_custom_service_account=True,
)
更改下列內容：
- PERSISTENT_RESOURCE_ID：使用者定義的永久資源專屬 ID。ID 只能包含小寫英文字母、數字和連字號 (
-)。第一個字元須為小寫英文字母，最後一個字元則須為小寫英文字母或數字。 - DISPLAY_NAME：選用。永久資源的顯示名稱。
- MACHINE_TYPE：要使用的虛擬機器 (VM) 類型。如需支援的 VM 清單，請參閱「機器類型」。這個欄位對應於
ResourcePoolAPI 訊息中的machineSpec.machineType欄位。 - REPLICA_COUNT：建立這個資源集區時要建立的副本數量。
REST
如要建立可與管道執行作業建立關聯的 PersistentResource 資源，請使用 persistentResources/create 方法傳送 POST 要求，並在要求主體中將 enable_custom_service_account 參數設為 true。
持續性資源可有一或多個資源集區。您可以將每個資源集區設定為使用固定數量的副本或自動調度資源。
使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：您要在哪個 Google Cloud 專案中建立持續性資源，請輸入該專案的 ID。
- LOCATION：您要在其中建立永久資源的地區。如需支援的地區清單，請參閱「功能適用情形」。
- PERSISTENT_RESOURCE_ID：永久資源的專屬使用者定義 ID。開頭須為英文字母，結尾則須為英文字母或數字，其他部分只能使用小寫英文字母、數字和連字號 (-)。
- DISPLAY_NAME：選用。永久資源的顯示名稱。
- MACHINE_TYPE：要使用的虛擬機器 (VM) 類型。如需支援的 VM 清單，請參閱「機器類型」。這個欄位對應於
ResourcePoolAPI 訊息中的machineSpec.machineType欄位。 - REPLICA_COUNT：選用。如不想使用自動調度資源功能，請指定要為資源集區建立的副本數量。這個欄位對應於
ResourcePoolAPI 訊息中的replicaCount欄位。如未指定 MIN_REPLICA_COUNT 和 MAX_REPLICA_COUNT 欄位，就必須指定副本數量。 - MIN_REPLICA_COUNT：選用。如果您為資源集區使用自動調度資源，這是指備用資源數量下限。如要使用自動調度功能，請務必同時指定 MIN_REPLICA_COUNT 和 MAX_REPLICA_COUNT。
- MAX_REPLICA_COUNT：選用。如果您為資源集區啟用自動調度資源功能，這是指備用資源的數量上限。如要使用自動調度功能，請務必同時指定 MIN_REPLICA_COUNT 和 MAX_REPLICA_COUNT。
HTTP 方法和網址：
POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/persistentResources?persistent_resource_id=PERSISTENT_RESOURCE_ID
JSON 要求主體：
{
"display_name": "DISPLAY_NAME",
"resource_pools": [
{
"machine_spec": {
"machine_type": "MACHINE_TYPE"
},
"replica_count": REPLICA_COUNT,
"autoscaling_spec": {
"min_replica_count": MIN_REPLICA_COUNT,
"max_replica_count": MAX_REPLICA_COUNT
}
}
],
"resource_runtime_spec": {
"service_account_spec": {
"enable_custom_service_account": true
}
}
}
如要傳送要求，請展開以下其中一個選項：
您應該會收到如下的 JSON 回應：
{
"name": "projects/PROJECT_NUMBER/locations/LOCATION/persistentResources/mypersistentresource/operations/OPERATION_ID",
"metadata": {
"@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreatePersistentResourceOperationMetadata",
"genericMetadata": {
"createTime": "2023-02-08T21:17:15.009668Z",
"updateTime": "2023-02-08T21:17:15.009668Z"
}
}
}
使用永久性資源建立管道執行作業
如要建立管道工作，請先建立管道規格。管道規格是您透過轉換已編譯的管道定義所建立的記憶體內物件。
建立管道規格
請按照下列操作說明建立可供建立管道執行的記憶體內管道規格：
定義管道並編譯成 YAML 檔案。如要進一步瞭解如何定義及編譯管道，請參閱「建構管道」。
使用下列程式碼範例，將已編譯的管道 YAML 檔案轉換為記憶體內管道規格。
import yaml with open("COMPILED_PIPELINE_PATH", "r") as stream: try: pipeline_spec = yaml.safe_load(stream) print(pipeline_spec) except yaml.YAMLError as exc: print(exc)將 COMPILED_PIPELINE_PATH 改為已編譯管道 YAML 檔案的本機路徑。
建立管道執行作業
請使用下列 Python 程式碼範例，建立使用永久性資源的管道執行作業：
# Import aiplatform and the appropriate API version v1beta1
from google.cloud import aiplatform, aiplatform_v1beta1
from google.cloud.aiplatform_v1beta1.types import pipeline_job as pipeline_job_types
# Initialize the Vertex SDK using PROJECT_ID and LOCATION
aiplatform.init(project='PROJECT_ID', location='LOCATION')
# Create the API Endpoint
client_options = {
"api_endpoint": f"LOCATION-aiplatform.googleapis.com"
}
# Initialize the PipeLineServiceClient
client = aiplatform_v1beta1.PipelineServiceClient(client_options=client_options)
# Construct the runtime detail
pr_runtime_detail = pipeline_job_types.PipelineJob.RuntimeConfig.PersistentResourceRuntimeDetail(
persistent_resource_name=(
f"projects/PROJECT_NUMBER/"
f"locations/LOCATION/"
f"persistentResources/PERSISTENT_RESOURCE_ID"
),
task_resource_unavailable_wait_time_ms=WAIT_TIME,
task_resource_unavailable_timeout_behavior='TIMEOUT_BEHAVIOR',
)
# Construct the default runtime configuration block
default_runtime = pipeline_job_types.PipelineJob.RuntimeConfig.DefaultRuntime(
persistent_resource_runtime_detail=pr_runtime_detail
)
# Construct the main runtime configuration
runtime_config = pipeline_job_types.PipelineJob.RuntimeConfig(
gcs_output_directory='PIPELINE_ROOT',
parameter_values={
'project_id': 'PROJECT_ID'
},
default_runtime=default_runtime
)
# Construct the pipeline job object
pipeline_job = pipeline_job_types.PipelineJob(
display_name='PIPELINE_DISPLAY_NAME',
pipeline_spec=PIPELINE_SPEC,
runtime_config=runtime_config,
)
# Construct the request
parent_path = f"projects/PROJECT_ID/locations/LOCATION"
request = aiplatform_v1beta1.CreatePipelineJobRequest(
parent=parent_path,
pipeline_job=pipeline_job,
)
# Make the API Call to create the pipeline job
response = client.create_pipeline_job(request=request)
# Construct the Google Cloud console link
job_id = response.name.split('/')[-1]
console_link = (
f"https://console.cloud.google.com/vertex-ai/locations/LOCATION"
f"/pipelines/runs/{job_id}"
f"?project=PROJECT_ID"
)
# Print the Google Cloud console link to the pipeline run
print(f"View Pipeline Run in Google Cloud console: {console_link}")
更改下列內容：
PROJECT_ID：管道執行的 Google Cloud 專案。
LOCATION：執行管道執行的區域。如要進一步瞭解 Vertex AI Pipelines 的適用區域，請參閱 Vertex AI 服務地區指南。如未設定這項參數，Vertex AI Pipelines 會使用
aiplatform.init中設定的預設位置。PERSISTENT_RESOURCE_ID：您建立的永久資源 ID。
PROJECT_NUMBER：專案的專案編號。 Google Cloud這與專案 ID 不同。您可以在控制台的「專案設定」頁面中找到專案編號。 Google Cloud
COMPILED_PIPELINE_PATH：已編譯管道 YAML 檔案的路徑。可以是本機路徑或 Cloud Storage URI。
WAIT_TIME：如果持續性資源無法使用，等待時間 (以毫秒為單位)。
TIMEOUT_BEHAVIOR：管道工作超出 WAIT_TIME 時的回溯行為。可能的值如下：
FAIL超過等待時間後，管道工作會失敗。FALL_BACK_TO_ON_DEMANDpipeline 工作會繼續使用預設的 Vertex AI 訓練資源執行，不會使用持續性資源。
PIPELINE_ROOT：Cloud Storage URI 的路徑，用於儲存管道執行的構件。
PIPELINE_DISPLAY_NAME：管道執行的名稱。顯示名稱的長度上限為 128 個 UTF-8 字元。
PIPELINE_SPEC：您在「建立管道規格」中建立的管道規格。
後續步驟
- 瞭解如何執行管道。