企业官网建设流程全解析

使用 ZenML GCP Cloud Run Deployer 将流水线部署为无服务器 HTTP 服务

【免费下载链接】zenmlZenML 🙏: One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml

本文是 ZenML 开源仓库中 GCP Cloud Run Deployer 组件指南 的深度展开版，聚焦于如何借助 ZenML 的 GCP 集成把训练/推理流水线一键部署为 Google Cloud Run 上的 HTTP 微服务。阅读完本文后，你将掌握：GCP Cloud Run deployer 的适用场景、本地gcloud与 GCP Service Connector 两种凭据接入方式、GCPDeployerSettings全部配置参数、基于ResourceSettings的资源与扩缩容设定，以及底层实现原理（部署、健康检查、日志、下线清理的完整调用链）。

什么是 GCP Cloud Run Deployer

GCP Cloud Run 组件：它作为 ZenML Stack 中的一个 deployer 组件，接管流水线快照（snapshot）从容器镜像构建到 Cloud Run 服务创建/更新/删除的完整生命周期。

⚠️使用前提：该组件只应在远程 ZenML 部署环境下使用。与本地 ZenML 安装配合使用可能会导致非预期行为。

从源码结构看，该组件由两部分构成，两者都在src/zenml/integrations/gcp/目录下：

• 配置与口味定义：flavors/gcp_deployer_flavor.py 定义了GCPDeployerSettings、GCPDeployerConfig与GCPDeployerFlavor；
• 具体实现：deployers/gcp_deployer.py 中的GCPDeployer类负责与 Cloud Run / Secret Manager / Cloud Logging API 交互。

口味标识为gcp（见 integrations/gcp/init.py），并且通过service_connector_requirements声明其需要gcp-generic类型的资源，用于过滤可兼容的 Service Connector（见 gcp_deployer_flavor.py）。

什么时候使用它

根据官方文档，在以下情况你应该使用 GCP Cloud Run deployer：

• 你已经在使用 GCP；
• 你在寻找一个久经生产验证的 deployer；
• 你在寻找把流水线部署为 HTTP 微服务的无服务器（serverless）方案；
• 你想要按使用量付费（pay-per-use）的自动扩缩容；
• 你需要以极少的配置部署容器化应用。

部署前提：先有远程 ZenML，再谈 Cloud Run

在使用 GCP Cloud Run deployer 之前，需要先完成将 ZenML 部署到云端。官方建议（非必须）将 ZenML 部署在与 Cloud Run 基础设施相同的 Google Cloud 项目中。在使用该 stack 组件之前，必须确保你已连接到远程 ZenML 服务器。

除此之外，唯一需要准备的是在目标 Google Cloud 项目中启用 Cloud Run 相关 API。如果你希望跳过手工步骤、一次性部署一整套 ZenML 云栈（含 GCP Cloud Run deployer），可以参考仓库中 infrastructure-deployment 文档中关于 GCP Terraform 模块的说明，它会自动完成组件部署与注册。

使用前置条件与整体流程

要实际使用 GCP Cloud Run deployer，你需要：

1. 安装 ZenML 的gcp集成：

   zenml integration install gcp

2. 本机安装并运行 Docker（用于构建流水线镜像）；

3. Stack 中必须包含一个远程 Artifact Store；

4. Stack 中必须包含一个远程 Container Registry；

5. 具备相应权限的 GCP 凭据；

6. 明确想要部署流水线的 GCP 项目 ID（project ID）与区域（location）。

其中第 3、4 点也由源码中的StackValidator强制校验：GCPDeployer要求栈中必须同时存在IMAGE_BUILDER与CONTAINER_REGISTRY两类组件（见 gcp_deployer.py），因为 ZenML 需要先构建镜像再推送到 Cloud Run。

GCP 凭据与权限

你有两种方式向 GCP Cloud Run deployer 提供凭据：

• 使用gcloudCLI 在本地完成 GCP 认证；
• （推荐）配置一个 GCP Service Connector 存放 GCP 凭据，再把 GCP Cloud Run deployer 组件与该 Service Connector 关联。

无论采用哪种认证方式，所用凭据在目标 GCP 项目中都需要以下权限：

更简单的替代方案：直接在项目级授予roles/secretmanager.admin角色且不附加任何条件。

配置实践一：本地gcloudCLI 用户账号

该方案假设你已经通过gcloud auth login在本机完成 GCP 账号认证，且该账号拥有上述权限。它是最简单的配置方式，但有如下缺点：

• 配置不可移植、不可复现：其他用户无法用该 deployer 部署流水线或管理你的 Deployments（尽管他们仍可访问暴露的端点并发送 HTTP 请求）；
• 它使用的是 Compute Engine 默认服务账号，该账号默认权限过大且被许多其他 GCP 服务共用，官方不推荐。

注册命令如下：

zenml deployer register <DEPLOYER_NAME> \ --flavor=gcp \ --project=<PROJECT_ID> \ --location=<GCP_LOCATION> \

配置实践二：GCP Service Connector

该方案假设你已经创建了一个具备所需权限的 GCP 服务账号，并已下载其密钥文件到本地（例如zenml-cloud-run-deployer.json）。如果你的环境支持，也可以通过 GCP Workload Identity 等免密钥方式完成认证。

准备好服务账号与密钥后，按如下方式注册 GCP Service Connector 与 deployer 并完成关联：

zenml service-connector register <CONNECTOR_NAME> \ --type gcp \ --auth-method=service-account \ --project_id=<PROJECT_ID> \ --service_account_json=@zenml-cloud-run-deployer.json \ --resource-type gcp-generic zenml deployer register <DEPLOYER_NAME> \ --flavor=gcp \ --location=<GCP_LOCATION> \ --connector <CONNECTOR_NAME>

这里--resource-type gcp-generic与源码中GCPDeployerFlavor.service_connector_requirements声明的资源类型（GCP_RESOURCE_TYPE = "gcp-generic"，见 gcp/init.py）保持一致，这样注册时 ZenML 才能自动匹配到兼容的 connector。

配置 Stack 并部署流水线

deployer 注册完成后，将其加入活动栈并激活：

# 注册并激活包含新 deployer 的 stack zenml stack register <STACK_NAME> -D <DEPLOYER_NAME> ... --set

提示：ZenML 会构建一个名为<CONTAINER_REGISTRY_URI>/zenml:<PIPELINE_NAME>的 Docker 镜像，并用它把流水线部署为 Cloud Run 服务。镜像的构建方式及自定义方法可参考仓库中关于容器化/镜像构建的文档（containerization 说明）。

栈就绪后，即可部署任意 ZenML 流水线：

zenml pipeline deploy --name my_deployment my_module.my_pipeline

部署完成后，还可以通过zenml deployment系列命令完成部署的生命周期管理（命令定义见 cli/deployment.py）：

zenml deployment list # 列出已注册的部署 zenml deployment describe <DEPLOYMENT> # 查看部署详情 zenml deployment logs <DEPLOYMENT> # 获取部署日志（支持 --tail 行数） zenml deployment refresh <DEPLOYMENT> # 刷新部署运行状态 zenml deployment deprovision <DEPLOYMENT> # 下线部署（删除 Cloud Run 服务） zenml deployment delete <DEPLOYMENT> # 下线并删除部署记录

附加配置：GCPDeployerSettings 参数详解

除了注册命令中的参数，还可以通过zenml.integrations.gcp.flavors.gcp_deployer_flavor模块中的GCPDeployerSettings对 deployer 进行细粒度配置。该类的完整字段、默认值与取值约束定义在 gcp_deployer_flavor.py，以下表格即由此整理。

所有 Deployer 共有的基础设置（继承自BaseDeployerSettings，见 base_deployer.py）：

GCP Cloud Run 特有设置：

关于如何在代码中指定这些 settings，可参考步骤与流水线配置相关文档。例如，若想对本次部署禁用 GCP Secret Manager：

from zenml import step, pipeline from zenml.integrations.gcp.flavors.gcp_deployer_flavor import GCPDeployerSettings @step def greet(name: str) -> str: return f"Hello {name}!" settings = { "deployer": GCPDeployerSettings( use_secret_manager=False ) } @pipeline(settings=settings) def greet_pipeline(name: str = "John"): greet(name=name)

从源码可以进一步印证两个设计细节：其一，GCPDeployerConfig.is_remote恒为True（见 gcp_deployer_flavor.py），这正是"必须在远程 ZenML 部署环境下使用"这一警告的实现依据——本地数据库会拒绝该组件；其二，deployer 的GCPDeployerSettings与注册时的GCPDeployerConfig叠加生效（GCPDeployerConfig同时继承BaseDeployerConfig、GoogleCredentialsConfigMixin与GCPDeployerSettings），注册时给定的--location等参数即作为配置默认值。

资源与扩缩容设置

你可以在流水线级别通过ResourceSettings类指定部署的资源与扩缩容需求（ResourceSettings的完整字段定义见 config/resource_settings.py）：

from zenml import step, pipeline from zenml.config import ResourceSettings resource_settings = ResourceSettings( cpu_count=2, memory="32GB", min_replicas=0, max_replicas=10, max_concurrency=50 ) ... @pipeline(settings={"resources": resource_settings}) def greet_pipeline(name: str = "John"): greet(name=name)

默认资源值

如果不设置任何资源参数，GCP Cloud Run deployer 将使用以下默认值（源码常量见 gcp_deployer.py）：

另有一个易被忽略的映射规则：ResourceSettings.max_replicas=0在 ZenML 语义中表示"不限上限"，GCP Cloud Run 需要具体数值，因此 deployer 会将其换算为平台最大值1000（GCP_CLOUD_RUN_MAX_INSTANCES），具体见 _convert_scaling_settings_to_gcp_format。

Cloud Run 的 CPU 与内存约束及自动校正

GCP Cloud Run 对 CPU 与内存的合法组合有专门规则（截至 2025 年 10 月）：

CPU 约束：

• 小数 CPU：0.08 到 < 1.0（以 0.01 为步进）；
• 整数 CPU：仅允许 1、2、4、6、8（≥ 1.0 不允许小数）。

各 CPU 档位对应的最小内存：

关键行为：指定不合法的cpu_count/memory值不会导致部署报错，而是会被自动调整到满足规则的最近合法值。官方给出的示例：

• cpu_count=0.25与memory="100MiB"→ 调整为cpu_count=0.25与memory="128MiB"；
• cpu_count=1.5、未指定memory→ 调整为cpu_count=2与memory="128MiB"；
• cpu_count=6与memory="1GB"→ 调整为cpu_count=6与memory="4GiB"。

该校正逻辑在源码中有完整实现：_convert_resource_settings_to_gcp_format 负责把cpu_count归一化到合法集合（< 1.0 时保留两位小数且下限 0.08，≥ 1.0 时向上取整到 1/2/4/6/8 中最小满足值）；_validate_memory_for_cpu 则依据上表对内存做max(请求值, 最小要求)的抬升处理。内存最终以Gi或Mi为单位写入 Cloud Run 的资源 limits（例如"2Gi"、"0.5Gi"），参见 do_provision_deployment。

底层实现原理（源码级解读）

架构与继承关系

GCPDeployer继承自ContainerizedDeployer，后者又继承自BaseDeployer（定义于 deployers/base_deployer.py）。BaseDeployer承担三大职责：保存与远程部署平台交互所需的栈配置属性；实现部署的生命周期管理（发现、创建、删除、更新）；作为 ZenML 部署注册表，把每个流水线部署以数据库实体的形式经 ZenML Client 落库，从而跟踪所有外部运行的部署。BaseDeployer还提供了provision_deployment/refresh_deployment/deprovision_deployment/delete_deployment/get_deployment_logs等统一入口，并以内置轮询（每 5 秒一次）等待部署达到目标状态，超时则抛出DeploymentTimeoutError（见 base_deployer.py）。

GCPDeployer只需实现四个抽象方法（见 gcp_deployer.py）：

• do_provision_deployment：基于流水线快照创建或更新 Cloud Run 服务（服务已存在时走update_service，否则走create_service），并返回操作状态；
• do_get_deployment_state：通过get_service查询 Cloud Run 服务并映射为 ZenML 的DeploymentOperationalState（reconciling 时为 PENDING，终态条件成功为 RUNNING，失败为 ERROR）；
• do_get_deployment_state_logs：通过 Cloud Logging 按resource.type="cloud_run_revision"与service_name过滤拉取日志；
• do_deprovision_deployment：删除 Cloud Run 服务并清理与之关联的全部 Secret Manager secrets。

命名规范与唯一性保证

Cloud Run 服务名要求小写字母、数字、连字符，且以字母或数字开头结尾。_sanitize_name（见 gcp_deployer.py）负责把流水线部署名清洗为合法名称；_get_service_name（见 gcp_deployer.py）在此基础上拼接service_name_prefix与部署 ID 的前 8 位，并将总长度限制在 49 个字符以内以保证唯一性——这也解释了文档中service_name_prefix设置的作用。

Secret Manager 与敏感信息处理

当use_secret_manager=True时，_prepare_environment_variables（见 gcp_deployer.py）会把敏感环境变量逐一写入 Secret Manager（secret 名由secret_name_prefix与变量名拼接、同样附带部署 ID 短前缀，最大 255 字符），并在 Cloud Run 服务中以EnvVarSource引用version="latest"的 secret，而不是把明文写进服务配置；若 secret 创建失败则回退为直接注入环境变量并给出警告。下线部署时，_cleanup_deployment_secrets会遍历并删除该部署关联的全部 secrets（见 gcp_deployer.py）。

健康检查的特殊处理

当服务配置了受限入站流量（ingress为internal或internal-and-cloud-load-balancing）或禁用了未认证访问（allow_unauthenticated=False）时，基类默认的 HTTP 健康检查请求会被 Cloud Run 的 ingress 规则拦截或遭 IAM 以 403 拒绝，导致部署超时。因此GCPDeployer._check_deployment_health（见 gcp_deployer.py）会在这些场景下跳过 HTTP 探测，改以 Cloud Run API 状态作为健康依据。

小结

GCP Cloud Run deployer 是 ZenML GCP 集成中把流水线发布为生产级无服务器 HTTP 服务的一等公民：它通过gcp口味、GCPDeployerSettings配置矩阵、ResourceSettings资源映射以及BaseDeployer统一的生命周期框架，屏蔽了 Cloud Run API 的底层细节，同时保留了命名规范、Secret Manager 集成、CPU/内存自动校正等工程化能力。结合本仓库的 deployers 组件文档 与 gcp 集成源码，你可以在此基础上进一步定制镜像构建、网络与扩缩容策略，把任意 ZenML 流水线快速变成可按需伸缩的在线服务。

【免费下载链接】zenmlZenML 🙏: One AI Platform from Pipelines to Agents. https://zenml.io.项目地址: https://gitcode.com/GitHub_Trending/ze/zenml