如要使用自訂容器,提供自訂訓練模型的推論,您必須向 Gemini Enterprise Agent Platform 提供執行 HTTP 伺服器的 Docker 容器映像檔。本文說明容器映像檔必須符合哪些規定,才能與 Gemini Enterprise Agent Platform 相容。此外,本文也說明 Agent Platform 如何與啟動後的自訂容器互動。換句話說,本文說明設計要與 Agent Platform 搭配使用的容器映像檔時,需要考量的事項。
如要瞭解如何使用自訂容器映像檔提供推論,請參閱「使用自訂容器」。
容器映像檔需求
當 Docker 容器映像檔以容器形式執行時,容器必須執行 HTTP 伺服器。具體來說,容器必須監聽並回應有效性檢查、健康狀態檢查和推論要求。以下子節將詳細說明這些規定。
您可以使用任何程式設計語言,以任何方式實作 HTTP 伺服器,只要符合本節規定即可。例如,您可以使用 Flask 等網頁架構編寫自訂 HTTP 伺服器,或使用執行 HTTP 伺服器的機器學習 (ML) 服務軟體,例如 TensorFlow Serving、TorchServe 或 KServe Python Server。
執行 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 環境變數的部分。
有效性檢查
容器啟動時,代理平台會執行運作狀態檢查,確保伺服器正常運作。當您將自訂訓練模型部署至 Endpoint 資源時,Agent Platform 會使用 TCP 運作狀態探測,嘗試透過設定的通訊埠與容器建立 TCP 連線。探測最多會嘗試建立連線 4 次,每次失敗後會等待 10 秒。如果探測器此時仍未建立連線,Agent Platform 會重新啟動容器。
HTTP 伺服器不需要執行任何特殊行為,即可處理這些檢查。只要在設定的通訊埠上監聽要求,存活探測就能建立連線。
健康狀態檢查
您可以視需要指定 startup_probe 或 health_probe。
啟動探測會檢查容器應用程式是否已啟動。如未提供啟動探測,則不會有啟動探測,且健康狀態檢查會立即開始。如果提供啟動探測,則在啟動探測成功前,系統不會執行健康狀態檢查。
如果舊版應用程式在首次初始化時可能需要額外的啟動時間,則應設定啟動探測。舉例來說,如果應用程式需要從外部來源複製模型構件,則應設定啟動探測,在初始化完成時傳回成功。
健康狀態探測會確認容器是否準備好接受流量。如未提供健康狀態探測,Agent Platform 會使用「預設健康狀態檢查」一節所述的預設健康狀態檢查。
如果舊版應用程式不會傳回 200 OK,表示模型已載入並準備好接受流量,則應設定健康狀態探測。舉例來說,應用程式可能會傳回 200 OK 表示成功,但回應主體中的實際模型載入狀態指出模型可能未載入,因此可能尚未準備好接受流量。在這種情況下,應設定健康狀態探測,只有在模型載入並準備好提供流量時,才傳回成功。
為執行探測,代理程式平台會在目標容器中執行指定的 exec 指令。如果指令執行成功,則會傳回 0,容器會視為運作正常。
預設健康狀態檢查
根據預設,Agent Platform 會在 HTTP 伺服器運作時,間歇性執行健康狀態檢查,確保伺服器已準備好處理推論要求。這項服務會使用健康狀態探測,將 HTTP GET 要求傳送至伺服器上可設定的健康狀態檢查路徑。建立 Model 時,請在「containerSpec.healthRoute」欄位中指定這個路徑。如要瞭解容器如何存取這個值,請參閱本文件中關於 AIP_HEALTH_ROUTE 環境變數的部分。
設定 HTTP 伺服器,按照下列方式回應每項健康狀態檢查要求:
如果伺服器已準備好處理推論要求,請在 10 秒內回覆健康狀態檢查要求,並附上狀態碼
200 OK。回應主體的內容並不重要,Agent Platform 會忽略這些內容。這項回應表示伺服器健康狀態良好。
如果伺服器尚未準備好處理推論要求,請勿在 10 秒內回應健康狀態檢查要求,或以
200 OK以外的任何狀態碼回應。例如,以狀態碼503 Service Unavailable回應。這項回應 (或未回應) 表示伺服器健康狀態不佳。
如果健康狀態探測從伺服器收到健康狀態不良的回應 (包括 10 秒內未收到回應),則會以 10 秒為間隔,傳送最多 3 次額外的健康狀態檢查。在這段期間,Agent Platform 仍會將伺服器視為健康狀態。如果探測器在任何一項檢查中收到健康狀態良好的回應,就會立即恢復間歇性健康狀態檢查。不過,如果探測作業連續收到 4 次健康狀態不良的回應,Agent Platform 就會停止將推論流量轉送至容器。(如果 DeployedModel 資源已擴充為使用多個推論節點,Agent Platform 會將推論要求轉送至其他健康狀態良好的容器)。
Agent Platform 不會重新啟動容器,而是由健康狀態探測繼續間歇性傳送健康狀態檢查要求至健康狀態不良的伺服器。如果收到健康狀態良好的回應,就會將該容器標示為健康狀態良好,並再次開始將推論流量轉送至該容器。
實用指南
在某些情況下,容器中的 HTTP 伺服器只要一律以狀態碼 200 OK 回應健康狀態檢查,就足以滿足需求。如果容器在啟動伺服器前載入資源,則容器在啟動期間和 HTTP 伺服器故障期間會處於健康狀態不良。其他時間則會回應健康。
如要進行更複雜的設定,您可以刻意設計 HTTP 伺服器,在特定時間以健康狀態不良回應健康狀態檢查。舉例來說,您可能想在一段時間內封鎖傳送至節點的推論流量,以便容器執行維護作業。
推論要求
設定模型伺服器路徑時,有兩種模式。一種是由 Gemini Enterprise Agent Platform 定義 (/predict),另一種則允許完全自訂,因此您可以直接放入所選的模型伺服器 (/invoke)。
Vertex 定義的 /predict 路由
用戶端向 Agent Platform API 傳送 projects.locations.endpoints.predict 要求時,Agent Platform 會將這項要求做為 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 物件,內含容器所需的任何參數,可協助在執行個體上提供推論。Agent Platform 將
parameters欄位視為選用欄位,因此您可以將容器設計為需要該欄位、僅在提供時使用,或忽略該欄位。
進一步瞭解要求主體規定。
回覆要求
如果模型部署至共用公開端點,每項推論回應的大小不得超過 1.5 MB。HTTP 伺服器傳送的回應必須包含符合下列格式的 JSON 主體:
{
"predictions": INFERENCES
}
在這些回應中,請將 INFERENCES 替換為 JSON 值陣列,代表容器為對應要求中每個 INSTANCES 產生的推論。
HTTP 伺服器傳送這項回應後,Agent Platform 會在回應中加入 deployedModelId 欄位,再傳回給用戶端。這個欄位會指定 Endpoint 上的哪個 DeployedModel 正在傳送回應。進一步瞭解回應主體格式。
自訂推論路徑
如果模型伺服器實作多個推論路徑,建議使用叫用 API 存取多個推論路徑。上傳模型時,只要將 Model.containerSpec.invokeRoutePrefix 欄位設為「/*」,即可啟用叫用 API。部署完成後,傳送至 /invoke/foo/bar 路徑的 HTTP 要求會轉送至模型伺服器的 /foo/bar 路徑。如要瞭解詳情,請參閱「使用任意自訂路徑」。
容器映像檔發布規定
您必須將容器映像檔推送至 Artifact Registry,才能與 Agent Platform 搭配使用。瞭解如何將容器映像檔推送至 Artifact Registry。
具體來說,容器映像檔和存放區必須符合下列位置、URI 格式和權限規定。
位置
使用 Artifact Registry 時,存放區必須使用與您打算建立 Model 的位置端點相符的區域。舉例來說,如果您打算在 us-central1-aiplatform.googleapis.com 端點上建立 Model,容器映像檔的全名開頭必須是 us-central1-docker.pkg.dev/。請勿使用多區域存放區來存放容器映像檔。
映像檔 URI 格式
建立 Model 時,請使用下列其中一種格式指定 containerSpec.imageUri:
- 依摘要:
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:DIGEST - 依標記:
LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG - 不含標記或摘要 (預設為
:latest):LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE
請勿在同一個 URI 中同時包含標記和摘要 (例如 IMAGE:TAG@sha256:DIGEST)。上傳模型時,Agent Platform 會拒絕同時包含標記和摘要的映像檔 URI。
權限
建立 Model 時,Agent Platform 必須具備提取容器映像檔的權限。具體來說,專案的 Agent Platform 服務代理必須具備容器映像檔存放區的 Artifact Registry 讀取者角色 (roles/artifactregistry.reader) 權限。
Agent Platform 會使用專案的 Agent Platform 服務代理,與其他 Google Cloud 服務互動。這個服務帳戶的電子郵件地址為 service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com,其中 PROJECT_NUMBER 會替換為 Agent Platform 專案的專案編號。
如果您已將容器映像檔推送至使用 Agent Platform 的 Google Cloud 專案,就不必設定任何權限。授予 Agent Platform 服務代理的預設權限已足夠。
另一方面,如果您將容器映像檔推送至與使用 Agent Platform 的專案不同的Google Cloud 專案,則必須將 Artifact Registry 存放區的 Artifact Registry 讀取者角色授予 Agent Platform 服務代理。
存取模型構件
建立自訂訓練的 Model 時,如果沒有自訂容器,則必須將含有模型構件的 Cloud Storage 目錄 URI 指定為 artifactUri 欄位。使用自訂容器建立 Model 時,您可以選擇是否在 Cloud Storage 中提供模型構件。
如果容器映像檔包含提供推論所需的模型構件,就不需要從 Cloud Storage 載入檔案。不過,如果您透過指定 artifactUri 欄位提供模型構件,容器必須在開始執行時載入這些構件。Agent Platform 啟動容器時,會將 AIP_STORAGE_URI 環境變數設為以 gs:// 開頭的 Cloud Storage URI。容器的 ENTRYPOINT 指令可以下載這個 URI 指定的目錄,以便存取模型構件。
請注意,AIP_STORAGE_URI 環境變數的值與您在建立 Model 時於 artifactUri 欄位中指定的 Cloud Storage URI 不同。AIP_STORAGE_URI 指向的是另一個 Cloud Storage bucket 中的模型構件目錄副本,由 Agent Platform 管理。建立 Model 時,Agent Platform 會填入這個目錄。您無法更新目錄內容。如要使用新的模型構件,則必須建立新的 Model。
容器預設使用的服務帳戶有權讀取這個 URI。
另一方面,如果您在將 Model 部署至 Endpoint 時指定自訂服務帳戶,Agent Platform 會自動將 URI 的 Cloud Storage bucket Storage 物件檢視者 (roles/storage.objectViewer) 角色授予指定的服務帳戶。
使用任何支援應用程式預設憑證 (ADC) 的程式庫載入模型構件,不必明確設定驗證。
容器中可用的環境變數
執行時,容器的 ENTRYPOINT 指令可以參照您手動設定的環境變數,以及 Agent Platform 自動設定的環境變數。本節說明設定環境變數的各種方式,並詳細介紹 Agent Platform 自動設定的變數。
在容器映像檔中設定的變數
如要在建構容器映像檔時設定環境變數,請使用 Docker 的 ENV 指令。請勿設定任何開頭為 AIP_ 的環境變數。
容器的 ENTRYPOINT 指令可以使用這些環境變數,但您無法在任何 Model 的 API 欄位中參照這些變數。
由 Agent Platform 設定的變數
Agent Platform 開始執行容器時,會在容器環境中設定下列環境變數。每個變數都以 AIP_ 前置字元開頭。請勿手動設定任何使用這個前置字串的環境變數。
容器的 ENTRYPOINT 指令可以存取這些變數。如要瞭解哪些
Agent Platform API 欄位也可以參照這些變數,請參閱
ModelContainerSpec 的 API 參考資料。
| 變數名稱 | 預設值 | 如何設定價值 | 詳細資料 |
|---|---|---|---|
| AIP_ACCELERATOR_TYPE | 未設定 | 將 Model 做為 DeployedModel 部署至 Endpoint 資源時,請設定 dedicatedResources.machineSpec.acceleratorType 欄位。 |
如果適用,這個變數會指定容器執行所在的虛擬機器 (VM) 執行個體使用的加速器類型。 |
| AIP_DEPLOYED_MODEL_ID | 一串數字,用於識別這個容器的 Model 部署到的 DeployedModel。 |
無法設定 | 這個值是 DeployedModel 的 id 欄位。 |
| AIP_ENDPOINT_ID | 一串數字,用於識別容器 Model 部署所在的 Endpoint。 |
無法設定 | 這個值是 Endpoint 的 name 欄位最後一個區段 (位於 endpoints/ 之後)。 |
| AIP_FRAMEWORK | CUSTOM_CONTAINER |
無法設定 | |
| AIP_HEALTH_ROUTE | /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL在這個字串中,將 ENDPOINT 替換為 AIP_ENDPOINT_ID 變數的值,並將 DEPLOYED_MODEL 替換為 AIP_DEPLOYED_MODEL_ID 變數的值。 |
建立 Model 時,請設定 containerSpec.healthRoute 欄位。 |
這個變數會指定容器上的 HTTP 路徑,Agent Platform 會將健康狀態檢查傳送至該路徑。 |
| IP_HTTP_PORT | 8080 |
建立 Model 時,請設定 containerSpec.ports 欄位。這個欄位中的第一個項目會成為 AIP_HTTP_PORT 的值。 |
Agent Platform 會將運作狀態檢查、健康狀態檢查和推論要求傳送至容器的這個通訊埠。容器的 HTTP 伺服器必須監聽這個通訊埠的要求。 |
| AIP_MACHINE_TYPE | 無預設值,必須設定 | 將 Model 做為 DeployedModel 部署至 Endpoint 資源時,請設定 dedicatedResources.machineSpec.machineType 欄位。 |
這個變數會指定容器執行的 VM 類型。 |
| AIP_MODE | PREDICTION |
無法設定 | 這個變數代表容器正在 Agent Platform 上執行,用於提供線上推論。您可以使用這個環境變數,在容器中加入自訂邏輯,讓容器在多個運算環境中執行,但只在 Agent Platform 上執行時使用特定程式碼路徑。 |
| IP_MODE_VERSION 版 | 1.0.0 |
無法設定 | 這個變數代表 Agent Platform 預期容器符合的自訂容器需求版本 (本文件)。這份文件會根據語意版本管理更新。 |
| AIP_MODEL_NAME | AIP_ENDPOINT_ID 變數的值 |
無法設定 | 請參閱 AIP_ENDPOINT_ID 列。這個變數是基於相容性考量而存在。 |
| AIP_PREDICT_ROUTE | /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict在這個字串中,將 ENDPOINT 替換為 AIP_ENDPOINT_ID 變數的值,並將 DEPLOYED_MODEL 替換為 AIP_DEPLOYED_MODEL_ID 變數的值。 |
建立 Model 時,請設定 containerSpec.predictRoute 欄位。 |
這個變數會指定容器上的 HTTP 路徑,Agent Platform 會將推論要求轉送至該路徑。 |
| AIP_PROJECT_NUMBER | 使用 Agent Platform 的 Google Cloud 專案編號 | 無法設定 | |
| AIP_STORAGE_URI |
|
無法設定 | 這個變數會指定包含模型構件副本的目錄 (如適用)。 |
| AIP_VERSION_NAME | AIP_DEPLOYED_MODEL_ID 變數的值 |
無法設定 | 請參閱 AIP_DEPLOYED_MODEL_ID 列。這個變數是基於相容性考量而存在。 |
在 Model 資源中設定的變數
建立 Model 時,您可以在「containerSpec.env」欄位中設定其他環境變數。
容器的 ENTRYPOINT 指令可以存取這些變數。如要瞭解哪些
Agent Platform API 欄位也可以參照這些變數,請參閱
ModelContainerSpec 的 API 參考資料。
後續步驟
- 進一步瞭解如何使用自訂容器提供推論,包括匯入模型時如何指定容器相關 API 欄位。