Vertex AI 自定义容器部署 YOLO 模型:健康检查与预测端点配置指南

小萱酱_3725

小萱酱_3725

2026-10-30

404人浏览

原创

Vertex AI 自定义容器部署 YOLO 模型:健康检查与预测端点配置指南

本文详解在 Vertex AI 上成功部署 FastAPI + YOLO 自定义容器时的关键缺失项——必须显式声明 /health 和 /predict 端点,并通过 gcloud 参数正确注册,否则服务将因健康探针失败而持续 Crash,且无有效日志输出。

本文详解在 vertex ai 上成功部署 fastapi + yolo 自定义容器时的关键缺失项——必须显式声明 `/health` 和 `/predict` 端点,并通过 `gcloud` 参数正确注册,否则服务将因健康探针失败而持续 crash,且无有效日志输出。

在 Vertex AI 上部署自定义容器模型(如基于 FastAPI 封装的 YOLO 推理服务)与 Cloud Run 的核心差异,并非在于运行时能力,而在于平台对服务生命周期的契约化约束。Cloud Run 仅需容器监听指定端口(默认 8080)并响应 HTTP 请求即可;而 Vertex AI 要求容器严格遵循一套可观察、可编排的服务协议——其中最关键的是两个标准化端点:/health(就绪探针)和 /predict(推理入口)。若未显式声明或实现,Vertex AI 会持续发送健康检查请求并因超时/404 失败判定实例不可用,最终触发反复重建,导致“容器能跑、平台不认”的典型问题。

✅ 正确实现 FastAPI 健康与预测端点

在您的 main.py(或 FastAPI 启动文件)中,务必添加以下标准路由:

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import base64
from io import BytesIO
from PIL import Image
import torch

app = FastAPI(title="YOLO26 Vertex AI Endpoint")

# --- 必须:健康检查端点 ---
@app.get("/health")
def health_check():
    """
    Vertex AI 健康探针调用此端点。
    要求:返回 200 OK,且响应体轻量(建议空 JSON 或 {"status": "ok"})
    注意:此端点应在模型加载完成后才返回成功,避免“假就绪”。
    """
    # 可选:校验模型是否已加载(例如检查全局 model 变量)
    if 'model' not in globals() or not hasattr(globals()['model'], 'names'):
        raise HTTPException(status_code=503, detail="Model not loaded")
    return {"status": "ok"}

# --- 必须:预测端点(Vertex AI 强制要求路径为 /predict)---
class PredictRequest(BaseModel):
    image: str  # base64 encoded JPEG/PNG

@app.post("/predict")
def predict(request: PredictRequest):
    try:
        # 解码 base64 图像
        image_bytes = base64.b64decode(request.image)
        image = Image.open(BytesIO(image_bytes)).convert("RGB")

        # 执行 YOLO 推理(此处简化,实际应复用已加载模型)
        results = model(image)  # 假设 model 已全局加载

        # 返回结构化结果(符合 Vertex AI 预期格式)
        return {
            "predictions": [
                {
                    "label": result.names[int(box.cls)],
                    "confidence": float(box.conf),
                    "bbox": [int(x) for x in box.xyxy[0].tolist()]
                }
                for result in results
                for box in result.boxes
            ]
        }
    except Exception as e:
        raise HTTPException(status_code=400, detail=f"Inference error: {str(e)}")

⚠️ 关键注意事项:

  • /health 必须返回 200 OK,且不能有重定向、延迟或异步等待;建议在模型加载完成后再启动 Uvicorn(例如在 startup 事件中加载模型,再开放 /health);
  • /predict 是 Vertex AI 唯一识别的推理入口,不可改名或加前缀(如 /api/predict 无效);
  • 请求体必须为 application/json,且结构需与您代码中 PredictRequest 定义一致;Vertex AI 不支持 multipart/form-data 或原始二进制流。

✅ 正确上传模型时声明端点与端口

使用 gcloud ai models upload 时,必须显式指定健康与预测路由及监听端口,否则 Vertex AI 默认使用 / 和 8080,但您的 FastAPI 并未暴露这些路径:

gcloud ai models upload \
  --region=us-central1 \
  --display-name=freshpet-mobile \
  --container-image-uri=us-central1-docker.pkg.dev/my-project/my-repo/yolo26-fastapi:v1 \
  --container-health-route="/health" \
  --container-predict-route="/predict" \
  --container-ports=8080 \
  --container-command="sh" \
  --container-args="-c","exec gunicorn --bind :8080 --workers 1 --worker-class uvicorn.workers.UvicornWorker --timeout 300 'main:app'"

? 为什么 --container-ports=8080 不可省略?
Vertex AI 依赖该参数配置内部负载均衡器与容器的通信通道。即使 Dockerfile 中已声明 EXPOSE 8080,也必须在此显式传入,否则探针无法到达容器。

✅ 查看真实错误日志的正确方式

Vertex AI 默认不会将容器 stdout/stderr 直接透出到 UI 控制台。请通过以下路径定位根本原因:

  1. 进入 Google Cloud Console → Vertex AI → Endpoints → [your-endpoint] → Logs
  2. 在日志过滤器中设置:
    resource.type="aiplatform.googleapis.com/Endpoint"
    resource.labels.endpoint_id="[your-endpoint-id]"
    logName:"logs/cloudaudit.googleapis.com%2Fdata_access"
  3. 或更高效地,在 Cloud Logging 中搜索:
    resource.type="k8s_container"
    resource.labels.cluster_name="vertex-ai-cluster-*"
    jsonPayload.message:"ERROR\|CRITICAL\|Traceback"

常见报错示例及修复:

  • Health check failed: GET http:///health returned 404 → 未实现 /health 或路径拼写错误;
  • Failed to bind to port 8080 → gunicorn 启动命令未指定 --bind :8080,或端口被其他进程占用;
  • CUDA initialization: no CUDA-capable device is detected → GPU 机型未正确启用(检查 --accelerator 参数是否与所选机器匹配,P4 需 type=nvidia-tesla-p4)。

✅ 最佳实践总结

项目 Cloud Run Vertex AI(必需)
健康端点路径 任意(如 /healthz),可自定义探针 固定 /health,且必须返回 200
推理端点路径 任意(如 /v1/predict) 强制 /predict,不可更改
端口声明 自动探测 PORT 环境变量或 8080 必须 --container-ports=8080
GPU 驱动加载 由平台自动注入 需确保基础镜像含 nvidia-container-toolkit 兼容层(推荐 pytorch/pytorch:2.2.0-cuda12.1-cudnn8-runtime)
日志可见性 实时 stdout 显示 仅通过 Cloud Logging 查看,需主动过滤

完成上述配置后,重新构建镜像、推送、上传模型并部署,Vertex AI 将能稳定拉起容器,健康探针通过,推理请求正常流转。这不仅是技术适配,更是将模型服务从“能跑”升级为“可运维、可审计、可演进”的生产级实践——正如智能仓储客户所要求的那样:每个检测框嵌入设备水印、每帧图像哈希落库、每次 GPU 显存占用写入 Splunk。真正的 MLOps,始于一个正确的 /health。

PHP速学视频免费教程(入门到精通)
PHP速学视频免费教程(入门到精通)

PHP怎么学习?PHP怎么入门?PHP在哪学?PHP怎么学才快?不用担心,这里为大家提供了PHP速学教程(入门到精通),有需要的小伙伴保存下载就能学习啦!

下载

相关标签:

本站声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn

相关专题

更多
GoFrame框架Web开发与路由中间件
GoFrame框架Web开发与路由中间件

本专题聚焦GoFrame框架的Web开发,拆解路由注册与匹配规则、请求参数获取、参数校验与中间件执行顺序,说明统一响应、JWT鉴权、文件上传与接口文档生成的落地方式,并补充优雅重启与测试实践。

2026.11.17

20

15

GoFrame框架安装与gf命令行工具
GoFrame框架安装与gf命令行工具

本专题围绕GoFrame框架的安装与工具链配置展开,讲清Go版本要求、gf命令行的安装方式、代理镜像与依赖准备,说明项目初始化、热编译、交叉编译打包的做法,并整理安装阶段的常见报错与验证步骤。

2026.11.17

60

15

GoFrame框架零基础入门
GoFrame框架零基础入门

本专题整理GoFrame框架的入门知识,从模块化设计理念、环境准备到跑通第一个Web服务,讲清目录分层、配置加载、日志与中间件的用法,并对比Gin、Go-Zero的差异,帮助Go开发者建立整体认知。

2026.11.17

60

15

SQLAlchemy 一对多关系怎么建立
SQLAlchemy 一对多关系怎么建立

SQLAlchemy 一对多关系怎么建立?本专题整理父子表外键、relationship 双向映射、关联查询、级联删除和加载优化等相关文章,帮助你理解并实现常见的 ORM 关系建模。

2026.11.17

20

10

SQLAlchemy 如何增删改查
SQLAlchemy 如何增删改查

SQLAlchemy 如何增删改查?本专题整理 ORM 新增记录、条件查询、更新和删除、Session 事务提交与批量处理等实用文章,帮助你掌握 Python 数据库操作流程。

2026.11.17

60

11

SQLAlchemy ORM 模型怎么写
SQLAlchemy ORM 模型怎么写

SQLAlchemy ORM 模型怎么写?本专题整理模型类定义、Mapped 字段映射、主键与约束、表结构创建和常见报错的相关文章,帮助你从基础配置到实际建模逐步掌握 SQLAlchemy。

2026.11.17

40

16

Go-Zero API开发使用教程
Go-Zero API开发使用教程

本专题聚焦Go-Zero的API开发,拆解.api描述文件的语法结构、路由与分组定义、参数绑定与校验规则,说明统一响应体、JWT鉴权、跨域与接口文档生成的落地方式,并给出网关聚合与接口测试的实践建议。

2026.11.12

180

15

Go-Zero安装与goctl环境配置教程
Go-Zero安装与goctl环境配置教程

本专题围绕Go-Zero的安装与工具链配置展开,讲清Go版本要求、goctl安装方式、代理镜像、protoc依赖与环境变量设置,说明多版本共存、升级回退与CI流水线安装的做法,并整理安装阶段的常见报错与验证步骤。

2026.11.12

140

15

Go-Zero零基础入门教程
Go-Zero零基础入门教程

本专题整理Go-Zero的入门知识,从框架定位、环境准备到跑通第一个API服务,讲清目录分层、配置加载、日志与中间件的基本用法,并对比Gin、Kratos的差异,帮助Go开发者建立整体认知,判断它是否适合当前项目。

2026.11.12

160

15

热门下载

更多
网站特效
/
网站源码
/
网站素材
/
前端模板

精品课程

更多
热门推荐
/
最新课程
phpStudy极速入门视频教程
phpStudy极速入门视频教程

共6课时 | 54.7万人学习

独孤九贱(4)_PHP视频教程
独孤九贱(4)_PHP视频教程

共89课时 | 134.3万人学习