用于预测的自定义容器的要求

注意：这是本文档的 1.0.0 版。本文档会根据语义版本控制进行更新。

如需使用自定义容器通过自定义训练的模型执行预测，您必须为 Vertex AI 提供运行 HTTP 服务器的 Docker 容器映像。本文档介绍了容器映像必须满足才能与 Vertex AI 兼容的要求。本文档还介绍了 Vertex AI 如何与开始运行的自定义容器进行交互。换句话说，本文档介绍了在设计用于 Vertex AI 的容器映像时需要考虑的事项。

如需逐步了解如何使用自定义容器映像来提供预测服务，请参阅使用自定义容器。

容器映像要求

如果您的 Docker 容器映像作为容器运行，则该容器必须运行 HTTP 服务器。具体而言，容器必须侦听并响应活跃性检查、健康检查和预测请求。以下各小节详细介绍了这些要求。

您可以使用任何编程语言以任何方式实现 HTTP 服务器，只要满足本部分中的要求即可。例如，您可以使用 Web 框架（如 Flask）编写自定义 HTTP 服务器，也可以使用运行 HTTP 服务器（如 TensorFlow Serving、TorchServe 或 KServe Python Server）的机器学习 (ML) 服务软件。

运行 HTTP 服务器

您可以使用 ENTRYPOINT 指令、CMD 指令在您用于构建容器映像的 Dockerfile 中运行 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 服务器，以在特定时间响应健康状况不佳的健康检查。例如，您可能希望阻止预测流量在一段时间内流向某一节点，以使容器可以执行维护工作。

预测请求

当客户端向 Vertex AI API 发送 projects.locations.endpoints.predict 请求时，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": PREDICTIONS
}

在这些响应中，将 PREDICTIONS 替换为一组 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 Service Agent 必须拥有容器映像制品库的 Artifact Registry Reader 角色 (roles/artifactregistry.reader) 的权限。

Vertex AI 使用您的项目的 Vertex AI Service Agent 与其他 Google Cloud 服务进行交互。此服务账号的电子邮件地址为 [e-mail]，其中 PROJECT_NUMBER 被替换为 Vertex AI 项目的编号。

如果您已将容器映像推送到使用 Vertex AI 所在的 Google Cloud 项目，则无需配置任何权限。向 Vertex AI Service Agent 授予的默认权限已足够。

另一方面，如果您已将容器映像推送到其他 Google Cloud 项目（而不是您使用 Vertex AI 所在的项目），则必须为 Vertex AI Service Agent 授予 Artifact Registry 制品库的 Artifact Registry Reader 角色。

注意：即使您打算在自定义容器中使用自定义服务账号，也不需要向您的自定义服务账号授予 Artifact Registry 权限；只有服务代理需要这些权限。Vertex AI 不会使用您的自定义服务账号来拉取容器映像。它仅使用自定义服务账号运行您的模型服务代码。

访问模型工件

如果您不使用自定义容器创建自定义训练的 Model，则必须在 artifactUri 字段中指定包含模型工件的 Cloud Storage 目录的 URI。如果使用自定义容器创建 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 不同。AIP_STORAGE_URI 指向由 Vertex AI 管理的另一个 Cloud Storage 存储分区中的模型工件目录的副本。创建 Model 时，Vertex AI 会填充此目录。您无法更新该目录的内容。如果您想使用新模型工件，则必须创建新的 Model。

您的容器默认使用的服务账号拥有读取此 URI 的权限。

另一方面，如果您在将 Model 部署到 Endpoint 时指定自定义服务账号，Vertex AI 会自动向您指定的服务授予该 URI 的 Cloud Storage 存储分区的 Storage Object Viewer (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 参考文档。

注意：用于构建容器映像的 Docker 指令（例如 RUN）无法访问这些变量，因为您必须先构建容器映像，然后再将其提供给 Vertex AI。

注意：您将 Model 作为 DeployedModel 部署到 Endpoint 时，Vertex AI 会设置以下某些变量的值。创建 Model 时，您可以在其他 API 字段中引用；每次部署 Model 时，这些值都会展开。

变量名称	默认值	如何配置值	详情
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 路径作为 Vertex AI 发送健康检查的目的地。
AIP_HTTP_PORT	8080	创建 Model 时，设置 containerSpec.ports 字段。此字段中的第一个条目是 AIP_HTTP_PORT 的值。	Vertex AI 会将活跃性检查、健康检查和预测请求发送到容器上的这个端口。您的容器的 HTTP 服务器必须侦听这个端口上的请求。
AIP_MACHINE_TYPE	无默认值，必须配置	将 Model 作为 DeployedModel 部署到 Endpoint 资源时，设置 dedicatedResources.machineSpec.machineType 字段。	此变量用于指定运行容器所在的虚拟机类型。
AIP_MODE	PREDICTION	不可配置	此变量表示容器正在 Vertex AI 上运行以提供在线预测服务。您可以使用此环境变量向容器添加自定义逻辑，使容器可在多个计算环境中运行，但在 Vertex AI 上运行时仅使用特定代码路径。
AIP_MODE_VERSION	1.0.0	不可配置	此变量表示 Vertex AI 期望容器满足的自定义容器要求（本文档）的版本。本文档根据语义版本控制进行更新。
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 路径作为 Vertex AI 转发预测请求的目的地。
AIP_PROJECT_NUMBER	您在其中使用 Vertex AI 的 Google Cloud 项目的编号	不可配置
AIP_STORAGE_URI	如果在创建 Model 时不设置 artifactUri 字段，则为空字符串 如果在创建 Model 时设置了 artifactUri 字段，则为 Cloud Storage URI（以 gs:// 开头），指定由 Vertex AI 管理的存储桶中的目录	不可配置	此变量指定模型工件副本所在的目录（如果适用）。
AIP_VERSION_NAME	AIP_DEPLOYED_MODEL_ID 变量的值。	不可配置	请参阅 AIP_DEPLOYED_MODEL_ID 行。此变量是为了保持兼容而存在。

在 Model 资源中设置的变量

创建 Model 时，您可以在 containerSpec.env 字段中设置其他环境变量。

容器的 ENTRYPOINT 指令可以访问这些变量。如需了解哪些 Vertex AI API 字段也可以引用这些变量，请参阅 ModelContainerSpec 的 API 参考文档。

注意：用于构建容器映像的 Docker 指令（例如 RUN）无法访问这些变量，因为您必须先构建容器映像，然后再将其提供给 Vertex AI。

后续步骤

• 详细了解如何使用自定义容器执行预测，包括如何在导入模型时指定与容器相关的 API 字段。