如要自訂 Agent Platform 如何從自訂訓練模型提供線上推論,您可以在建立 Model 資源時指定自訂容器,而非預先建構的容器。使用自訂容器時,Agent Platform 會在每個推論節點上,執行您選擇的 Docker 容器。
您可能會基於下列原因使用自訂容器:
- 使用非預建容器的架構訓練機器學習模型,並透過該模型提供推論
- 預先處理推論要求,或後續處理模型生成的推論
- 執行以您選擇的程式設計語言編寫的推論伺服器
- 安裝要用於自訂推論的依附元件
本指南說明如何建立使用自訂容器的模型。不會提供設計及建立 Docker 容器映像檔的詳細操作說明。
準備容器映像檔
如要建立使用自訂容器的 Model,您必須提供 Docker 容器映像檔,做為該容器的基礎。這個容器映像檔必須符合「自訂容器需求」一節所述的規定。
如果您打算使用由信任的第三方建立的現有容器映像檔,則可以略過下列一或兩個部分。
建立容器映像檔
設計及建構符合容器映像檔規定的 Docker 容器映像檔。
如要瞭解設計及建構 Docker 容器映像檔的基本概念,請參閱 Docker 說明文件的快速入門導覽課程。
將容器映像檔推送至 Artifact Registry
將容器映像檔推送至 Artifact Registry 存放區。
瞭解如何將容器映像檔推送至 Artifact Registry。
建立 Model
如要建立使用自訂容器的 Model,請執行下列任一操作:
以下各節說明如何透過上述任一方式建立 Model,並設定與自訂容器相關的 API 欄位。
容器相關 API 欄位
建立 Model 時,請務必使用自訂容器詳細資料設定 containerSpec 欄位,而非使用預先建構的容器。
您必須在 Model.containerSpec 欄位中指定 ModelContainerSpec 訊息。您可以在這則訊息中指定下列子欄位:
imageUri(必要元素)容器映像檔的 Artifact Registry URI。請指定摘要 (
IMAGE@sha256:DIGEST)、標記 (IMAGE:TAG) 或兩者皆不指定 (預設為:latest);請勿在同一個 URI 中同時指定標記和摘要。詳情請參閱「圖片 URI 格式」。如果您使用
gcloud ai models upload指令,則可透過--container-image-uri旗標指定這個欄位。command(選填)可執行檔和引數的陣列,用於覆寫容器的
ENTRYPOINT指令。如要進一步瞭解如何設定這個欄位的格式,以及這個欄位與args欄位的互動方式,請參閱ModelContainerSpec的 API 參考資料。如果使用
gcloud ai models upload指令,則可透過--container-command旗標指定這個欄位。args(選填)可執行檔和引數的陣列,用於覆寫容器的
CMD。如要進一步瞭解如何設定這個欄位的格式,以及這個欄位與command欄位的互動方式,請參閱ModelContainerSpec的 API 參考資料。如果使用
gcloud ai models upload指令,則可透過--container-args旗標指定這個欄位。ports(選填)通訊埠陣列;Agent Platform 會將存活狀態檢查、健康狀態檢查和推論要求傳送至容器上列出的第一個通訊埠,或預設為
8080。指定其他通訊埠不會產生任何影響。如果使用
gcloud ai models upload指令,則可透過--container-ports旗標指定這個欄位。env(選填)容器的
ENTRYPOINT指令以及command和args欄位可參照的環境變數陣列。如要進一步瞭解 其他欄位如何參照這些環境變數,請參閱ModelContainerSpec的 API 參考資料。如果使用
gcloud ai models upload指令,則可透過--container-env-vars旗標指定這個欄位。healthRoute(選填)Agent Platform 應將健康狀態檢查傳送至容器 HTTP 伺服器的哪個路徑。
如未指定這個欄位,當您將
Model做為DeployedModel部署至Endpoint資源時,系統會預設為/v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL,其中 ENDPOINT 會替換為Endpoint的name欄位最後一個區段 (位於endpoints/之後),DEPLOYED_MODEL 則會替換為DeployedModel的id欄位。如果使用
gcloud ai models upload指令,則可透過--container-health-route旗標指定這個欄位。predictRoute(選填)容器 HTTP 伺服器上的路徑,Agent Platform 會將推論要求轉送至此。
如未指定這個欄位,當您將
Model做為DeployedModel部署至Endpoint資源時,系統會預設為/v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict,其中 ENDPOINT 會替換為Endpoint的name欄位最後一個區段 (位於endpoints/之後),DEPLOYED_MODEL 則會替換為DeployedModel的id欄位。如果使用
gcloud ai models upload指令,則可透過--container-predict-route旗標指定這個欄位。invokeRoutePrefix(選填)自訂容器的叫用路徑前置字串。將這個欄位設為「/*」,即可為模型啟用任意轉送功能。部署完成後,模型伺服器上的任何非根路徑,都可以透過叫用 HTTP 呼叫來存取。例如,「/invoke/foo/bar」會以「/foo/bar」的形式轉送至模型伺服器。這項功能目前處於公開預先發布版階段。如要建立可叫用的模型,請按照指示使用任意自訂路徑。
sharedMemorySizeMb(選填)在共用記憶體磁碟區中,為模型預留的 VM 記憶體量 (以 MB 為單位)。
共用記憶體是一種處理序間通訊 (IPC) 機制,可讓多個處理序存取及操控共同的記憶體區塊。所需的共用記憶體量 (如有) 是容器和模型的實作細節。請參閱模型伺服器說明文件,瞭解相關規範。
如果使用
gcloud ai models upload指令,則可透過--container-shared-memory-size-mb旗標指定這個欄位。startupProbe(選填)探測作業的規格,用於檢查容器應用程式是否已啟動。
如果使用
gcloud ai models upload指令,則可透過--container-startup-probe-exec, --container-startup-probe-period-seconds, --container-startup-probe-timeout-seconds旗標指定這個欄位。healthProbe(選填)探測規格,用於檢查容器是否準備好接受流量。
如果使用
gcloud ai models upload指令,則可透過--container-health-probe-exec, --container-health-probe-period-seconds, --container-health-probe-timeout-seconds旗標指定這個欄位。
除了您在 Model.containerSpec.env 欄位中設定的變數外,Agent Platform 也會根據您的設定,設定其他幾個變數。進一步瞭解如何在這些欄位和容器的 ENTRYPOINT 指令中使用這些環境變數。
模型匯入範例
以下範例說明如何在匯入模型時指定容器相關 API 欄位。
gcloud
下列範例使用 gcloud ai models upload 指令:
gcloud ai models upload \
--region=LOCATION \
--display-name=MODEL_NAME \
--container-image-uri=IMAGE_URI \
--container-command=COMMAND \
--container-args=ARGS \
--container-ports=PORTS \
--container-env-vars=ENV \
--container-health-route=HEALTH_ROUTE \
--container-predict-route=PREDICT_ROUTE \
--container-shared-memory-size-mb=SHARED_MEMORY_SIZE \
--container-startup-probe-exec=STARTUP_PROBE_EXEC \
--container-startup-probe-period-seconds=STARTUP_PROBE_PERIOD \
--container-startup-probe-timeout-seconds=STARTUP_PROBE_TIMEOUT \
--container-health-probe-exec=HEALTH_PROBE_EXEC \
--container-health-probe-period-seconds=HEALTH_PROBE_PERIOD \
--container-health-probe-timeout-seconds=HEALTH_PROBE_TIMEOUT \
--artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY
--container-image-uri 標記為必要,所有其他以 --container- 開頭的標記則為選用。如要瞭解這些欄位的值,請參閱本指南的前一節。
Java
在試用這個範例之前,請先按照「使用用戶端程式庫的 Agent Platform 快速入門導覽課程」中的 Java 設定說明操作。
如要向 Agent Platform 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Node.js
在試用這個範例之前,請先按照「使用用戶端程式庫的 Agent Platform 快速入門導覽課程」中的 Node.js 設定說明操作。
如要向 Agent Platform 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Python
如要瞭解如何安裝或更新 Vertex AI SDK for Python,請參閱「安裝 Vertex AI SDK for Python」。 詳情請參閱 Python API 參考文件。
如需更多背景資訊,請參閱模型匯入指南。
傳送推論要求
如要將線上推論要求傳送至 Model,請按照「從自訂訓練模型取得推論」中的操作說明進行:無論是否使用自訂容器,這項程序都相同。
後續步驟
- 如要瞭解設計與 Agent Platform 搭配使用的自訂容器時,應考量的所有事項,請參閱「自訂容器需求」。