自定义容器要求

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

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

容器映像要求

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

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

运行 HTTP 服务器

您可以使用 ENTRYPOINT 指令、CMD 指令在您用于构建容器映像的 Dockerfile 中运行 HTTP 服务器。了解 CMD 和 ENTRYPOINT 之间的互动。

或者，您可以在创建模型版本时指定 containerSpec.command 和 containerSpec.args 字段，以分别替换容器映像的 ENTRYPOINT 和 CMD。通过指定其中一个字段，您可以使用一个容器映像，此映像会由于 ENTRYPOINT 或 CMD 不兼容（或不存在）而不满足要求。

不过，您可以确定容器在启动时运行的命令，请确定此 entrypoint 命令会无限期运行。例如，不要运行在后台启动 HTTP 服务器然后退出的命令；否则，容器将在开始运行后立即退出。

您的 HTTP 服务器必须在您选择的端口上侦听 0.0.0.0 上的请求。创建模型版本时，请在 containerSpec.ports 字段中指定此端口。如需了解容器如何访问此值，请阅读本文档中有关 AIP_HTTP_PORT 环境变量的部分。

活跃性检查

当您的容器启动时，AI Platform Prediction 会执行活跃性检查，以确定服务器正在运行。在版本创建过程中，AI Platform Prediction 使用 TCP 活跃性探测尝试与已配置端口上的容器建立 TCP 连接。探测最多尝试建立 4 次连接，每次失败后等待 10 秒。此时，如果探测尚未建立连接，AI Platform Prediction 会重启您的容器。

您的 HTTP 服务器不需要执行任何特殊行为来处理这些检查。只要其正在监听已配置端口上的请求，活跃性探测便可以建立连接。

健康检查

AI Platform Prediction 会针对正在运行的 HTTP 服务器间歇性地执行健康检查，以确定其已准备好处理预测请求。该服务使用健康状况探测将 HTTP GET 请求发送到服务器上的可配置健康检查路径。创建模型版本时，请在 routes.health 字段中指定此路径。如需了解容器如何访问此值，请阅读本文档中有关 AIP_HEALTH_ROUTE 环境变量的部分。

配置 HTTP 服务器，以响应每个健康检查请求，如下所示：

  • 如果服务器已准备好处理预测请求，则以状态代码 200 OK 响应健康检查请求。响应正文的内容无关紧要；AI Platform Prediction 会忽略它们。

    此响应表明服务器运行状况良好。

  • 如果服务器未准备好处理预测请求，则不响应健康检查请求，也不以 200 OK 之外的任何状态代码响应。例如，以状态代码 503 Service Unavailable 响应。

    此响应表明服务器运行状况不佳。

如果健康状况探测收到服务器返回的健康状况不佳响应，则以 10 秒为间隔发送多达 3 次额外健康检查。在此期间，AI Platform Prediction 仍会认为您的服务器运行状况良好。如果探测收到上述任一检查的健康状况良好响应，则探测会立即返回其间歇性健康检查的时间安排。但是，如果探测收到 4 次连续运行状况不佳的响应，则 AI Platform Prediction 会停止将预测流量路由到容器。（如果模型版本已扩容以使用多个预测节点，则 AI Platform Prediction 会将预测请求路由到其他运行状况良好的容器。）

AI Platform Prediction 不会重启容器；而健康状况探测会继续向健康状况不佳的服务器发送间歇性健康检查请求。如果它收到运行状况良好响应，则会将该容器标记为运行状况良好，并再次开始将预测流量路由到该容器。

实用指南

在某些情况下，容器中的 HTTP 服务器始终以状态代码 200 OK 响应健康检查。如果您的容器在启动服务器之前加载资源，则在启动期间以及 HTTP 服务器发生故障的任何时间段内，容器运行状况不佳。在其他情况下，它始终返回运行状况良好的响应。

对于更复杂的配置，您可能需要专门设计 HTTP 服务器，以在特定时间响应健康状况不佳的健康检查。例如，您可能希望阻止预测流量在一段时间内流向某一节点，以使容器可以执行维护工作。

预测请求

当客户端向 AI Platform Training and Prediction API 发送 projects.predict 请求时，AI Platform Prediction 会将此请求作为 HTTP POST 请求转发到服务器上的可配置预测路径。创建模型版本时，请在 routes.predict 字段中指定此路径。如需了解容器如何访问此值，请阅读本文档中有关 AIP_PREDICT_ROUTE 环境变量的部分。

AI Platform Prediction 不会验证预测请求和响应；它会将每个预测请求原封不动地传递给容器中的 HTTP 服务器，并将服务器的响应传递回客户端。

每个预测请求和响应不得超过 1.5 MB。但是，您无需遵循其他请求正文要求和响应正文要求；这些要求仅适用于不使用自定义容器的模型版本。使用自定义容器时，请求和响应正文可以采用任何格式。

但是，我们仍建议您设计 HTTP 服务器，以符合前面链接中所述的请求和响应要求。如果未这样做，则无法保证其他 AI Platform Prediction 功能，例如日志记录、监控和 AI Explanations 将正常运行。

容器映像发布要求

您必须将容器映像推送到 Artifact Registry，才能将容器映像与 AI Platform Prediction 搭配使用。了解如何将容器映像推送到 Artifact Registry。

具体而言，您必须将容器映像推送到满足下列位置和权限要求的代码库。

位置

代码库必须使用与您计划创建模型版本的地区端点匹配的地区。例如，如果您计划在 us-central1-ml.googleapis.com 端点上创建模型版本，则您的容器映像的全名必须以 us-central1-docker.pkg.dev/ 开头。

请勿为您的容器映像使用多地区代码库。

权限

创建模型版本时，AI Platform Prediction 必须具有拉取容器映像的权限。具体来说，AI Platform Service Agent 必须对容器映像的代码库拥有 Artifact Registry Reader 角色 (roles/artifactregistry.reader) 的权限。

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

另一方面，如果您已将容器映像推送到其他 Google Cloud 项目（而不是您使用 AI Platform Prediction 所在的项目），则必须向 AI Platform 服务代理授予对 Artifact Registry 代码库的 Artifact Registry Reader 角色。

访问模型工件

创建没有自定义容器的模型版本时，您必须将含有模型工件的 Cloud Storage 目录的 URI 指定为 deploymentUri 字段值。使用自定义容器创建模型版本时，您可以视情况在 Cloud Storage 中提供模型工件。

如果容器映像包含处理预测所需的模型工件，则无需从 Cloud Storage 加载文件。但是，如果您通过指定 deploymentUri 字段提供模型工件，则容器必须在开始运行时加载这些工件。在 AI Platform Prediction 启动容器时，它会将 AIP_STORAGE_URI 环境变量设置为以 gs:// 开头的 Cloud Storage URI。容器的 entrypoint 命令可下载此 URI 指定的目录，以便访问模型工件。

请注意，AIP_STORAGE_URI 环境变量的值与您在创建模型版本时在 deploymentUri 字段中指定的 Cloud Storage URI 不同。相反，AIP_STORAGE_URI 指向其他 Cloud Storage Prediction 存储分区中由 AI Platform Prediction 管理的模型工件目录副本。创建模型版本时，AI Platform Prediction 会填充此目录。您无法更新该目录的内容。如果要使用新的模型工件，则必须创建新的模型版本。

您的容器默认使用的服务账号拥有读取此 URI 的权限。另一方面，如果您在创建模型版本时指定自定义服务账号，则 AI Platform Prediction 会自动向指定的服务账号授予对 URI 的 Cloud Storage 存储分区的 Storage Object Viewer (roles/storage.objectViewer) 角色。

使用任何支持应用默认凭据 (ADC) 的库加载模型工件；您不需要明确配置身份验证。

由于容器支持 AI Platform 服务代理的 ADC， 自定义服务账号（如果您有 它还可以访问其 服务账号拥有哪些权限。

容器中可用的环境变量

容器运行容器时，容器的 entrypoint 命令可以引用您已手动配置的环境变量以及由 AI Platform Prediction 自动设置的环境变量。本部分介绍可用于设置环境变量的每种方法，并详细介绍了 AI Platform Prediction 自动设置的变量。

容器映像中设置的变量

如需在构建容器映像时设置容器映像的环境变量，请使用 Docker 的 ENV 指令。切勿设置任何以前缀 AIP_ 开头的环境变量。

容器的 entrypoint 命令可以使用这些环境变量，但您不能在模型版本 API 字段的任何环境变量中引用它们。

AI Platform Prediction 设置的变量

AI Platform Prediction 开始运行容器时，会在容器环境中设置以下环境变量。每个变量都以前缀 AIP_ 开头。请勿手动设置任何使用此前缀的环境变量。

容器的 entrypoint 命令可以访问这些变量。如需了解哪些 AI Platform Training and Prediction API 字段也可以引用这些变量，请参阅 ContainerSpec 的 API 参考文档。

变量名称 默认值 如何配置值 详情
AIP_ACCELERATOR_TYPE 尚未设置 创建模型版本时，请设置 acceleratorConfig.type 字段。 如果适用，此变量用于指定运行容器所在的虚拟机 (VM) 实例使用的加速器类型。
AIP_FRAMEWORK CUSTOM_CONTAINER 不可配置
AIP_HEALTH_ROUTE /v1/models/MODEL/versions/VERSION

在此字符串中，将 MODEL 替换为 AIP_MODEL_NAME 变量的值，并将 VERSION 替换为 AIP_VERSION_NAME 变量的值。		 创建模型版本时，请设置 routes.health 字段。 此变量指定容器上的 HTTP 路径作为 AI Platform Prediction 发送健康检查的目的地。
AIP_HTTP_PORT 8080 创建模型版本时，请设置 containerSpec.ports 字段。此字段中的第一个条目是 AIP_HTTP_PORT 的值。 AI Platform Prediction 将活跃性检查、健康检查和预测请求发送到容器上的这个端口。您的容器的 HTTP 服务器必须侦听这个端口上的请求。
AIP_MACHINE_TYPE 无默认值，必须配置 创建模型版本时，请设置 machineType 字段。 此变量用于指定运行容器所在的虚拟机类型。
AIP_MODE PREDICTION 不可配置 此变量表示容器正在 AI Platform Prediction 上运行以提供在线预测服务。您可以使用此环境变量向容器添加自定义逻辑，以便此容器可在多个计算环境中运行，但只有在 AI Platform Prediction 上运行时才使用某些代码路径。
AIP_MODE_VERSION 1.0.0 不可配置 此变量表示 AI Platform Prediction 期望容器满足的自定义容器要求（本文档）的版本。本文档根据语义版本控制进行更新。
AIP_MODEL_NAME 无默认值，必须配置 如果您创建模型（使用容器的模型版本的父级），请指定 name 字段。 该值不包含 AI Platform Training and Prediction API 在输出中生成的 projects/PROJECT_ID/models/ 前缀。
AIP_PREDICT_ROUTE /v1/models/MODEL/versions/VERSION:predict

在此字符串中，将 MODEL 替换为 AIP_MODEL_NAME 变量的值，并将 VERSION 替换为 AIP_VERSION_NAME 变量的值。		 创建模型版本时，请设置 routes.predict 字段。 此变量指定容器上的 HTTP 路径作为 AI Platform Prediction 转发预测请求的目的地。
AIP_PROJECT_NUMBER 您使用 AI Platform Prediction 所在的 Google Cloud 项目的项目编号 不可配置
AIP_STORAGE_URI
  • 如果在创建模型版本时未设置 deploymentUri 字段：空字符串
  • 如果您在创建模型版本时设置了 deploymentUri 字段：Cloud Storage URI（以 gs:// 开头），用于指定 AI Platform Prediction 所管理存储分区中的目录
 不可配置 此变量指定模型工件副本所在的目录（如果适用）。
AIP_VERSION_NAME 无默认值，必须配置 创建模型版本时，请设置 name 字段。 该值不包含 AI Platform Training and Prediction API 在输出中生成的 projects/PROJECT_ID/models/MODEL/versions/ 前缀。

在版本资源中设置的变量

创建模型版本时，您可以在 container.env 字段中设置其他环境变量。

容器的 entrypoint 命令可以访问这些变量。如需了解哪些 AI Platform Training and Prediction API 字段也可以引用这些变量，请参阅 ContainerSpec 的 API 参考文档。

后续步骤