推論作業的自訂容器需求

如要使用自訂容器從自訂訓練模型提供推論結果，您必須向 Vertex AI 提供執行 HTTP 伺服器的 Docker 容器映像檔。本文說明容器映像檔必須符合哪些規定，才能與 Vertex AI 相容。本文也說明 Vertex AI 在啟動後如何與自訂容器互動。換句話說，本文說明設計要搭配 Vertex AI 使用的容器映像檔時，需要考量的事項。

如要逐步瞭解如何使用自訂容器映像檔提供推論服務，請參閱「使用自訂容器」。

容器映像檔需求

Docker 容器映像檔以容器形式執行時，容器必須執行 HTTP 伺服器。具體來說，容器必須監聽並回應即時檢查、健康狀態檢查和推論要求。下列小節將詳細說明這些規定。

您可以使用任何程式設計語言，以任何方式實作 HTTP 伺服器，只要符合本節規定即可。舉例來說，您可以使用 Flask 等網路架構編寫自訂 HTTP 伺服器，也可以使用執行 HTTP 伺服器的機器學習 (ML) 服務軟體，例如 TensorFlow Serving、TorchServe 或 KServe Python 伺服器。

執行 HTTP 伺服器

您可以在用來建構容器映像檔的 Dockerfile 中，使用 ENTRYPOINT 指令、CMD 指令或兩者，執行 HTTP 伺服器。請參閱這篇文章，瞭解 CMD 和 ENTRYPOINT 之間的互動。

或者，您可以在建立 Model 資源時指定 containerSpec.command 和 containerSpec.args 欄位，分別覆寫容器映像檔的 ENTRYPOINT 和 CMD。指定其中一個欄位後，您就能使用不符合規定的容器映像檔，因為不相容 (或不存在) 的 ENTRYPOINT 或 CMD。

無論您如何決定容器啟動時執行的指令，請確保這項 ENTRYPOINT 指令會無限期執行。舉例來說，請勿執行會啟動背景 HTTP 伺服器，然後結束的指令；否則容器會在啟動後立即結束。

HTTP 伺服器必須在您選擇的通訊埠上，監聽 0.0.0.0 的要求。建立 Model 時，請在 containerSpec.ports 欄位中指定這個連接埠。如要瞭解容器如何存取這個值，請參閱這份文件的 AIP_HTTP_PORT 環境變數一節。

有效性檢查

容器啟動時，Vertex AI 會執行有效性檢查，確保伺服器正在執行。將自訂訓練模型部署至 Endpoint 資源時，Vertex AI 會使用 TCP 存活探測，嘗試在設定的通訊埠上與容器建立 TCP 連線。探測最多會嘗試建立連線 4 次，每次失敗後會等待 10 秒。如果探測器在這時仍未建立連線，Vertex AI 會重新啟動容器。

HTTP 伺服器不需要執行任何特殊行為來處理這些檢查。只要在設定的通訊埠上監聽要求，存活探測就能建立連線。

健康狀態檢查

您可以選擇指定 startup_probe 或 health_probe。

啟動探測會檢查容器應用程式是否已啟動。如果未提供啟動探測，系統就不會執行啟動探測，並立即開始健康狀態檢查。如果提供啟動探測，系統會等到啟動探測成功後，再執行健康狀態檢查。

如果舊版應用程式在首次初始化時可能需要額外的啟動時間，請設定啟動探針。舉例來說，如果應用程式需要從外部來源複製模型構件，則應設定啟動探查，在初始化完成時傳回成功。

健康狀態探測會檢查容器是否準備好接受流量。如果未提供健康狀態探查，Vertex AI 會使用預設健康狀態檢查中所述的預設健康狀態檢查。

如果舊版應用程式未傳回 200 OK，表示模型已載入並準備好接受流量，則應設定健康狀態探查。舉例來說，應用程式可能會傳回 200 OK 表示成功，但回應主體中的實際模型載入狀態指出模型可能未載入，因此可能尚未準備好接受流量。在這種情況下，應將健康狀態探測設定為僅在模型載入完畢並準備好提供流量時，才傳回成功。

如要執行探查，Vertex AI 會在目標容器中執行指定的 exec 指令。如果指令成功執行，則會傳回 0，且容器會視為運作中且健康的。

預設健康狀態檢查

根據預設，Vertex AI 會在 HTTP 伺服器執行期間，間歇性地執行健康狀態檢查，確保伺服器已準備好處理推論要求。這項服務會使用健康狀態探測器，將 HTTP GET 要求傳送至伺服器上可設定的健康狀態檢查路徑。建立 Model 時，請在containerSpec.healthRoute 欄位中指定這個路徑。如要瞭解容器如何存取這個值，請參閱這份文件的AIP_HEALTH_ROUTE環境變數一節。

設定 HTTP 伺服器，讓伺服器對每項健康狀態檢查要求做出以下回應：

• 如果伺服器已準備好處理推論要求，請在 10 秒內以狀態碼 200 OK 回應健康狀態檢查要求。回應主體的內容並不重要，Vertex AI 會忽略這些內容。

  這項回應表示伺服器健康狀態良好。

• 如果伺服器尚未準備好處理推論要求，請在 10 秒內不要回應健康狀態檢查要求，或以 200 OK 以外的任何狀態碼回應。例如，以狀態碼 503 Service Unavailable 回應。

  這項回應 (或沒有回應) 表示伺服器健康狀態不良。

如果健康狀態探測器從伺服器收到不健康的狀態回應 (包括 10 秒內沒有回應)，就會以 10 秒間隔傳送最多 3 次額外的健康狀態檢查。在此期間，Vertex AI 仍會將伺服器視為正常運作。如果探測收到任何一項檢查的健康狀態回應，探測會立即返回間歇性健康狀態檢查排程。不過，如果探測器連續 4 次收到不正常的狀態回應，Vertex AI 就會停止將推論流量轉送至容器。(如果 DeployedModel 資源已擴充，可使用多個推論節點，Vertex AI 會將推論要求傳送至其他正常的容器)。

Vertex AI 不會重新啟動容器，而是繼續將間歇性健康狀態檢查要求傳送至健康狀態不良的伺服器。如果收到健康狀態良好的回應，就會將該容器標示為健康狀態良好，並開始將推論流量重新導向至該容器。

實用指南

在某些情況下，容器中的 HTTP 伺服器一律以狀態碼 200 OK 回應健康狀態檢查就已足夠。如果容器在啟動伺服器前載入資源，容器在啟動期間和 HTTP 伺服器發生故障的任何期間，都會處於不正常的狀態。在其他時間，則會回應為健康狀態。

如要進行更精密的設定，您可能會刻意設計 HTTP 伺服器，在特定時間以健康狀態不良回應健康狀態檢查。舉例來說，您可能會想在一段時間內封鎖節點的推論流量，讓容器執行維護作業。

推論要求

當用戶端將 projects.locations.endpoints.predict 要求傳送至 Vertex AI API 時，Vertex AI 會將這項要求轉送至伺服器上可設定的推論路徑，做為 HTTP POST 要求。建立 Model 時，請在 containerSpec.predictRoute 欄位中指定這個路徑。如要瞭解容器如何存取這個值，請參閱本文件有關 AIP_PREDICT_ROUTE 環境變數的章節。

申請規定

如果模型部署至公開端點，每個推論要求不得超過 1.5 MB。HTTP 伺服器必須接受具有 Content-Type: application/json HTTP 標頭和 JSON 主體的推論要求，格式如下：

{
  "instances": INSTANCES,
  "parameters": PARAMETERS
}

在這些要求中：

• INSTANCES 是由一或多個任意類型的 JSON 值組成的陣列。每個值代表您要提供推論的執行個體。

• PARAMETERS 是 JSON 物件，內含容器為執行個體提供推論服務時所需的任何參數。Vertex AI 會將 parameters 欄位視為選用欄位，因此您可以設計容器來要求提供該欄位、僅在提供該欄位時使用，或忽略該欄位。

進一步瞭解要求主體規定。

回覆規定

如果模型部署至公開端點，每個推論回應不得超過 1.5 MB。HTTP 伺服器必須傳送含有 JSON 主體的格式回應，且格式須符合下列規定：

{
  "predictions": INFERENCES
}

在這些回應中，請將 INFERENCES 替換為 JSON 值陣列，代表容器為對應要求中的每個 INSTANCES 產生的推論。

HTTP 伺服器傳送這項回應後，Vertex AI 會在回應中加入 deployedModelId 欄位 ，然後再傳回給用戶端。這個欄位會指定 Endpoint 上的哪個 DeployedModel 傳送回應。進一步瞭解回應主體格式。

容器映像檔發布規定

您必須將容器映像檔推送至 Artifact Registry，才能搭配 Vertex AI 使用。瞭解如何將容器映像檔推送到 Artifact Registry。

具體來說，您必須將容器映像檔推送至符合下列位置和權限規定的存放區。

位置

使用 Artifact Registry 時，存放區必須使用與您預計建立 Model 的位置端點相符的區域。舉例來說，如果您打算在 us-central1-aiplatform.googleapis.com 端點上建立 Model，容器映像檔的全名就必須以 us-central1-docker.pkg.dev/ 開頭。請勿使用容器映像檔的多區域存放區。

權限

建立 Model 時，Vertex AI 必須具備提取容器映像檔的權限。具體來說，專案的 Vertex AI 服務代理必須具備容器映像檔存放區的 Artifact Registry 讀取者角色 (roles/artifactregistry.reader) 權限。

Vertex AI 會使用專案的 Vertex AI 服務代理與其他 Google Cloud 服務互動。這個服務帳戶的電子郵件地址為 service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com，其中 PROJECT_NUMBER 會替換為 Vertex AI 專案的專案編號。

如果您已將容器映像檔推送至使用 Vertex AI 的 Google Cloud 專案，則不必設定任何權限。授予 Vertex AI 服務代理的預設權限已足夠。

另一方面，如果您已將容器映像檔推送至與 Vertex AI 所在專案不同的Google Cloud 專案，則必須將 Artifact Registry 存放區的 Artifact Registry 讀者角色授予 Vertex AI 服務代理程式。

存取模型構件

建立自訂訓練的 Model 時，如未使用自訂容器，請務必指定 Cloud Storage 目錄的 URI，並將模型構件做為 artifactUri 欄位。使用自訂容器建立 Model 時，您可選擇是否在 Cloud Storage 中提供模型構件。

如果容器映像檔包含提供推論服務所需的模型構件，就不必從 Cloud Storage 載入檔案。不過，如果您透過指定 artifactUri 欄位提供模型構件，容器啟動時必須載入這些構件。Vertex AI 啟動容器時，會將 AIP_STORAGE_URI 環境變數設為以 gs:// 開頭的 Cloud Storage URI。您可以使用容器的 ENTRYPOINT 指令下載這個 URI 指定的目錄，存取模型構件。

請注意，AIP_STORAGE_URI 環境變數的值與您在建立 Model 時於 artifactUri 欄位中指定的 Cloud Storage URI 並不相同。而是指向不同 Cloud Storage bucket 中模型構件目錄的副本，由 Vertex AI 管理。AIP_STORAGE_URI建立 Model 時，Vertex AI 會填入這個目錄。您無法更新目錄內容。如要使用新的模型構件，請建立新的 Model。

根據預設，容器使用的服務帳戶有權從這個 URI 讀取資料。

另一方面，如果您在將 Model 部署至 Endpoint 時指定自訂服務帳戶，Vertex AI 就會自動授予您指定的服務 URI 帳戶 Cloud Storage 值區的 Storage 物件檢視者 (roles/storage.objectViewer) 角色角色。

使用支援應用程式預設憑證 (ADC) 的任何程式庫載入模型構件，不需要明確設定驗證。

可在容器中使用的環境變數

執行時，容器的 ENTRYPOINT 指令可以參照您手動設定的環境變數，以及 Vertex AI 自動設定的環境變數。本節將說明設定環境變數的各種方式，並詳細介紹 Vertex AI 自動設定的變數。

容器映像檔中設定的變數

如要在建構容器映像檔時設定環境變數，請使用 Docker 的 ENV 指令。請勿設定任何以 AIP_ 前置字元開頭的環境變數。

容器的 ENTRYPOINT 指令可以使用這些環境變數，但您無法在任何 Model 的 API 欄位中參照這些變數。

Vertex AI 設定的變數

Vertex AI 開始執行容器時，會在容器環境中設定下列環境變數。每個變數開頭都是前置字串 AIP_。請勿手動設定使用這個前置字元的任何環境變數。

容器的 ENTRYPOINT 指令可以存取這些變數。如要瞭解哪些 Vertex AI API 欄位也能參照這些變數，請參閱 ModelContainerSpec 的 API 參考資料。

在 Model 資源中設定的變數

建立 Model 時，您可以在containerSpec.env 欄位中設定其他環境變數。

容器的 ENTRYPOINT 指令可以存取這些變數。如要瞭解哪些 Vertex AI API 欄位也能參照這些變數，請參閱 ModelContainerSpec 的 API 參考資料。

後續步驟

• 進一步瞭解如何使用自訂容器提供推論結果，包括匯入模型時如何指定容器相關的 API 欄位。