Implementa um modelo YOLO pré-treinado com Ultralytics no Vertex AI para inferência

Este guia vai mostrar-te como contentorizar um modelo YOLO26 pré-treinado com Ultralytics, construir um servidor de inferência FastAPI para o mesmo, e implementar o modelo com o servidor de inferência no Google Cloud Vertex AI. O exemplo de implementação cobrirá o caso de uso de deteção de objetos para YOLO26, mas os mesmos princípios aplicar-se-ão ao usar outros modos YOLO.

Antes de começares, precisarás de criar um projeto no Google Cloud Platform (GCP). Recebes $300 em créditos GCP para usar gratuitamente como novo utilizador, e este montante é suficiente para testar uma configuração em execução que podes posteriormente expandir para qualquer outro caso de uso de YOLO26, incluindo treino, ou inferência em lote e em tempo real.

O que vais aprender

1. Criar um backend de inferência para o modelo YOLO26 da Ultralytics usando FastAPI.
2. Criar um repositório no Google Cloud Artifact Registry para armazenar a tua imagem Docker.
3. Construir e enviar a imagem Docker com o modelo para o Artifact Registry.
4. Importar o teu modelo no Vertex AI.
5. Criar um endpoint no Vertex AI e implementar o modelo.

Pré-requisitos

1. Instala o Docker na tua máquina.
2. Instala o Google Cloud SDK e autentica-te para usar a CLI gcloud.
3. Recomenda-se vivamente que consultes o Guia de Início Rápido do Docker para Ultralytics, porque precisarás de estender uma das imagens Docker oficiais da Ultralytics ao seguir este guia.

1. Criar um backend de inferência com FastAPI

Primeiro, precisas de criar uma aplicação FastAPI que servirá os pedidos de inferência do modelo YOLO26. Esta aplicação tratará do carregamento do modelo, do pré-processamento de imagem e da lógica de inferência (predição).

Fundamentos de Conformidade do Vertex AI

O Vertex AI espera que o teu contentor implemente dois endpoints específicos:

1. Endpoint de Saúde (/health): Deve devolver o status HTTP 200 OK quando o serviço estiver pronto.

2. Endpoint de Predição (/predict): Aceita pedidos de predição estruturados com imagens codificadas em base64 e parâmetros opcionais. Aplicam-se limites de tamanho de payload dependendo do tipo de endpoint.

   Os payloads de pedido para o endpoint /predict devem seguir esta estrutura JSON:

   {
       "instances": [{ "image": "base64_encoded_image" }],
       "parameters": { "confidence": 0.5 }
   }

Estrutura da pasta do projeto

A maior parte da nossa construção ocorrerá dentro do contentor Docker, e a Ultralytics também carregará um modelo YOLO26 pré-treinado, por isso podes manter a estrutura da pasta local simples:

YOUR_PROJECT/
├── src/
│   ├── __init__.py
│   ├── app.py              # Core YOLO26 inference logic
│   └── main.py             # FastAPI inference server
├── tests/
├── .env                    # Environment variables for local development
├── Dockerfile              # Container configuration
├── LICENSE                 # AGPL-3.0 License
└── pyproject.toml          # Python dependencies and project config

Criar pyproject.toml com dependências

Para gerires o teu projeto de forma conveniente, cria um ficheiro pyproject.toml com as seguintes dependências:

[project]
name = "YOUR_PROJECT_NAME"
version = "0.0.1"
description = "YOUR_PROJECT_DESCRIPTION"
requires-python = ">=3.10,<3.13"
dependencies = [
   "ultralytics>=8.3.0",
   "fastapi[all]>=0.89.1",
   "uvicorn[standard]>=0.20.0",
   "pillow>=9.0.0",
]

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

• uvicorn será usado para executar o servidor FastAPI.
• pillow será usado para processamento de imagem, mas não estás limitado apenas a imagens PIL — a Ultralytics suporta muitos outros formatos.

Criar lógica de inferência com Ultralytics YOLO26

Agora que tens a estrutura do projeto e as dependências configuradas, podes implementar a lógica central de inferência do YOLO26. Cria um ficheiro src/app.py que lidará com o carregamento do modelo, processamento de imagem e predição, usando a API Python da Ultralytics.

# src/app.py

from ultralytics import YOLO

# Model initialization and readiness state
model_yolo = None
_model_ready = False

def _initialize_model():
    """Initialize the YOLO model."""
    global model_yolo, _model_ready

    try:
        # Use pretrained YOLO26n model from Ultralytics base image
        model_yolo = YOLO("yolo26n.pt")
        _model_ready = True

    except Exception as e:
        print(f"Error initializing YOLO model: {e}")
        _model_ready = False
        model_yolo = None

# Initialize model on module import
_initialize_model()

def is_model_ready() -> bool:
    """Check if the model is ready for inference."""
    return _model_ready and model_yolo is not None

Isto carregará o modelo uma vez quando o contentor iniciar, e o modelo será partilhado entre todos os pedidos. Se o teu modelo for lidar com uma carga de inferência pesada, recomenda-se selecionar um tipo de máquina com mais memória ao importar um modelo no Vertex AI num passo posterior.

Em seguida, cria duas funções utilitárias para processamento de imagem de entrada e saída com pillow. O YOLO26 suporta imagens PIL nativamente.

def get_image_from_bytes(binary_image: bytes) -> Image.Image:
    """Convert image from bytes to PIL RGB format."""
    input_image = Image.open(io.BytesIO(binary_image)).convert("RGB")
    return input_image

def get_bytes_from_image(image: Image.Image) -> bytes:
    """Convert PIL image to bytes."""
    return_image = io.BytesIO()
    image.save(return_image, format="JPEG", quality=85)
    return_image.seek(0)
    return return_image.getvalue()

Finalmente, implementa a função run_inference que lidará com a deteção de objetos. Neste exemplo, vamos extrair caixas delimitadoras, nomes de classes e pontuações de confiança das predições do modelo. A função devolverá um dicionário com deteções e resultados brutos para posterior processamento ou anotação.

def run_inference(input_image: Image.Image, confidence_threshold: float = 0.5) -> Dict[str, Any]:
    """Run inference on an image using YOLO26n model."""
    global model_yolo

    # Check if model is ready
    if not is_model_ready():
        print("Model not ready for inference")
        return {"detections": [], "results": None}

    try:
        # Make predictions and get raw results
        results = model_yolo.predict(
            imgsz=640, source=input_image, conf=confidence_threshold, save=False, augment=False, verbose=False
        )

        # Extract detections (bounding boxes, class names, and confidences)
        detections = []
        if results and len(results) > 0:
            result = results[0]
            if result.boxes is not None and len(result.boxes.xyxy) > 0:
                boxes = result.boxes

                # Convert tensors to numpy for processing
                xyxy = boxes.xyxy.cpu().numpy()
                conf = boxes.conf.cpu().numpy()
                cls = boxes.cls.cpu().numpy().astype(int)

                # Create detection dictionaries
                for i in range(len(xyxy)):
                    detection = {
                        "xmin": float(xyxy[i][0]),
                        "ymin": float(xyxy[i][1]),
                        "xmax": float(xyxy[i][2]),
                        "ymax": float(xyxy[i][3]),
                        "confidence": float(conf[i]),
                        "class": int(cls[i]),
                        "name": model_yolo.names.get(int(cls[i]), f"class_{int(cls[i])}"),
                    }
                    detections.append(detection)

        return {
            "detections": detections,
            "results": results,  # Keep raw results for annotation
        }
    except Exception as e:
        # If there's an error, return empty structure
        print(f"Error in YOLO detection: {e}")
        return {"detections": [], "results": None}

Opcionalmente, podes adicionar uma função para anotar a imagem com caixas delimitadoras e etiquetas usando o método de plotagem integrado da Ultralytics. Isto será útil se quiseres devolver imagens anotadas na resposta de predição.

def get_annotated_image(results: list) -> Image.Image:
    """Get annotated image using Ultralytics built-in plot method."""
    if not results or len(results) == 0:
        raise ValueError("No results provided for annotation")

    result = results[0]
    # Use Ultralytics built-in plot method with PIL output
    return result.plot(pil=True)

Criar servidor de inferência HTTP com FastAPI

Agora que tens a lógica central de inferência do YOLO26, podes criar uma aplicação FastAPI para a servir. Isto incluirá os endpoints de verificação de saúde e predição exigidos pelo Vertex AI.

Primeiro, adiciona as importações e configura o registo para o Vertex AI. Como o Vertex AI trata o stderr como saída de erro, faz sentido encaminhar os registos para o stdout.

import sys

from loguru import logger

# Configure logger
logger.remove()
logger.add(
    sys.stdout,
    colorize=True,
    format="<green>{time:HH:mm:ss}</green> | <level>{message}</level>",
    level=10,
)
logger.add("log.log", rotation="1 MB", level="DEBUG", compression="zip")

Para uma conformidade total com o Vertex AI, define os endpoints necessários em variáveis de ambiente e define o limite de tamanho para os pedidos. Recomenda-se o uso de endpoints privados do Vertex AI para implementações em produção. Desta forma, terás um limite de payload de pedido mais alto (10 MB em vez de 1.5 MB para endpoints públicos), juntamente com segurança robusta e controlo de acesso.

# Vertex AI environment variables
AIP_HTTP_PORT = int(os.getenv("AIP_HTTP_PORT", "8080"))
AIP_HEALTH_ROUTE = os.getenv("AIP_HEALTH_ROUTE", "/health")
AIP_PREDICT_ROUTE = os.getenv("AIP_PREDICT_ROUTE", "/predict")

# Request size limit (10 MB for private endpoints, 1.5 MB for public)
MAX_REQUEST_SIZE = 10 * 1024 * 1024  # 10 MB in bytes

Adiciona dois modelos Pydantic para validar os teus pedidos e respostas:

# Pydantic models for request/response
class PredictionRequest(BaseModel):
    instances: list
    parameters: Optional[Dict[str, Any]] = None

class PredictionResponse(BaseModel):
    predictions: list

Adiciona o endpoint de verificação de saúde para verificar a prontidão do teu modelo. Isto é importante para o Vertex AI, pois sem uma verificação de saúde dedicada, o seu orquestrador tentará contactar sockets aleatórios e não conseguirá determinar se o modelo está pronto para inferência. A tua verificação deve devolver 200 OK para sucesso e 503 Service Unavailable para falha:

# Health check endpoint
@app.get(AIP_HEALTH_ROUTE, status_code=status.HTTP_200_OK)
def health_check():
    """Health check endpoint for Vertex AI."""
    if not is_model_ready():
        raise HTTPException(status_code=503, detail="Model not ready")
    return {"status": "healthy"}

Agora tens tudo para implementar o endpoint de predição que tratará dos pedidos de inferência. Ele aceitará um ficheiro de imagem, executará a inferência e devolverá os resultados. Nota que a imagem deve estar codificada em base64, o que aumenta adicionalmente o tamanho do payload em até 33%.

@app.post(AIP_PREDICT_ROUTE, response_model=PredictionResponse)
async def predict(request: PredictionRequest):
    """Prediction endpoint for Vertex AI."""
    try:
        predictions = []

        for instance in request.instances:
            if isinstance(instance, dict):
                if "image" in instance:
                    image_data = base64.b64decode(instance["image"])
                    input_image = get_image_from_bytes(image_data)
                else:
                    raise HTTPException(status_code=400, detail="Instance must contain 'image' field")
            else:
                raise HTTPException(status_code=400, detail="Invalid instance format")

            # Extract YOLO26 parameters if provided
            parameters = request.parameters or {}
            confidence_threshold = parameters.get("confidence", 0.5)
            return_annotated_image = parameters.get("return_annotated_image", False)

            # Run inference with YOLO26n model
            result = run_inference(input_image, confidence_threshold=confidence_threshold)
            detections_list = result["detections"]

            # Format predictions for Vertex AI
            detections = []
            for detection in detections_list:
                formatted_detection = {
                    "class": detection["name"],
                    "confidence": detection["confidence"],
                    "bbox": {
                        "xmin": detection["xmin"],
                        "ymin": detection["ymin"],
                        "xmax": detection["xmax"],
                        "ymax": detection["ymax"],
                    },
                }
                detections.append(formatted_detection)

            # Build prediction response
            prediction = {"detections": detections, "detection_count": len(detections)}

            # Add annotated image if requested and detections exist
            if (
                return_annotated_image
                and result["results"]
                and result["results"][0].boxes is not None
                and len(result["results"][0].boxes) > 0
            ):
                import base64

                annotated_image = get_annotated_image(result["results"])
                img_bytes = get_bytes_from_image(annotated_image)
                prediction["annotated_image"] = base64.b64encode(img_bytes).decode("utf-8")

            predictions.append(prediction)

        logger.info(
            f"Processed {len(request.instances)} instances, found {sum(len(p['detections']) for p in predictions)} total detections"
        )

        return PredictionResponse(predictions=predictions)

    except HTTPException:
        # Re-raise HTTPException as-is (don't catch and convert to 500)
        raise
    except Exception as e:
        logger.error(f"Prediction error: {e}")
        raise HTTPException(status_code=500, detail=f"Prediction failed: {e}")

Finalmente, adiciona o ponto de entrada da aplicação para executar o servidor FastAPI.

if __name__ == "__main__":
    import uvicorn

    logger.info(f"Starting server on port {AIP_HTTP_PORT}")
    logger.info(f"Health check route: {AIP_HEALTH_ROUTE}")
    logger.info(f"Predict route: {AIP_PREDICT_ROUTE}")
    uvicorn.run(app, host="0.0.0.0", port=AIP_HTTP_PORT)

Agora tens uma aplicação FastAPI completa que pode servir pedidos de inferência do YOLO26. Podes testá-la localmente instalando as dependências e executando o servidor, por exemplo, com uv.

# Install dependencies
uv pip install -e .

# Run the FastAPI server directly
uv run src/main.py

Para testar o servidor, podes consultar ambos os endpoints /health e /predict usando cURL. Coloca uma imagem de teste na pasta tests. Depois, no teu Terminal, executa os seguintes comandos:

# Test health endpoint
curl http://localhost:8080/health

# Test predict endpoint with base64 encoded image
curl -X POST -H "Content-Type: application/json" -d "{\"instances\": [{\"image\": \"$(base64 -i tests/test_image.jpg)\"}]}" http://localhost:8080/predict

Deverás receber uma resposta JSON com os objetos detetados. No teu primeiro pedido, espera um curto atraso, pois a Ultralytics precisa de extrair e carregar o modelo YOLO26.

2. Estender a imagem Docker da Ultralytics com a tua aplicação

A Ultralytics fornece várias imagens Docker que podes usar como base para a imagem da tua aplicação. O Docker instalará a Ultralytics e os drivers GPU necessários.

Para usar todas as capacidades dos modelos YOLO da Ultralytics, deves selecionar a imagem otimizada para CUDA para inferência em GPU. No entanto, se a inferência em CPU for suficiente para a tua tarefa, podes poupar recursos computacionais selecionando também a imagem apenas para CPU:

• Dockerfile: Imagem otimizada para CUDA para treino e inferência YOLO26 em GPU única/múltiplas.
• Dockerfile-cpu: Imagem apenas para CPU para inferência YOLO26.

Criar uma imagem Docker para a tua aplicação

Cria um Dockerfile na raiz do teu projeto com o seguinte conteúdo:

# Extends official Ultralytics Docker image for YOLO26
FROM ultralytics/ultralytics:latest

ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1

# Install FastAPI and dependencies
RUN uv pip install fastapi[all] uvicorn[standard] loguru

WORKDIR /app
COPY src/ ./src/
COPY pyproject.toml ./

# Install the application package
RUN uv pip install -e .

RUN mkdir -p /app/logs
ENV PYTHONPATH=/app/src

# Port for Vertex AI
EXPOSE 8080

# Start the inference server
ENTRYPOINT ["python", "src/main.py"]

No exemplo, a imagem oficial Docker da Ultralytics ultralytics:latest é usada como base. Ela já contém o modelo YOLO26 e todas as dependências necessárias. O ponto de entrada do servidor é o mesmo que usámos para testar a aplicação FastAPI localmente.

Construir e testar a imagem Docker

Agora podes construir a imagem Docker com o seguinte comando:

docker build --platform linux/amd64 -t IMAGE_NAME:IMAGE_VERSION .

Substitui IMAGE_NAME e IMAGE_VERSION pelos teus valores desejados, por exemplo, yolo26-fastapi:0.1. Nota que deves construir a imagem para a arquitetura linux/amd64 se estiveres a implementar no Vertex AI. O parâmetro --platform precisa de ser explicitamente definido se estiveres a construir a imagem num Mac com Apple Silicon ou qualquer outra arquitetura não-x86.

Assim que a construção da imagem estiver concluída, podes testar a imagem Docker localmente:

docker run --platform linux/amd64 -p 8080:8080 IMAGE_NAME:IMAGE_VERSION

O teu contentor Docker está agora a executar um servidor FastAPI na porta 8080, pronto para aceitar pedidos de inferência. Podes testar tanto o endpoint /health como o /predict com os mesmos comandos cURL de antes:

# Test health endpoint
curl http://localhost:8080/health

# Test predict endpoint with base64 encoded image
curl -X POST -H "Content-Type: application/json" -d "{\"instances\": [{\"image\": \"$(base64 -i tests/test_image.jpg)\"}]}" http://localhost:8080/predict

3. Enviar a imagem Docker para o GCP Artifact Registry

Para importar o teu modelo contentorizado no Vertex AI, precisas de enviar a imagem Docker para o Google Cloud Artifact Registry. Se ainda não tiveres um repositório no Artifact Registry, precisarás de criar um primeiro.

Criar um repositório no Google Cloud Artifact Registry

Abre a página do Artifact Registry na consola do Google Cloud. Se estiveres a usar o Artifact Registry pela primeira vez, poderás ser solicitado a ativar a API do Artifact Registry primeiro.

1. Seleciona Criar Repositório.
2. Introduz o nome do teu repositório. Seleciona a região desejada e usa as definições predefinidas para outras opções, a menos que precises de alterá-las especificamente.

1. Assim que o repositório for criado, guarda o teu PROJECT_ID, Localização (Região) e Nome do Repositório no teu cofre de segredos ou ficheiro .env. Precisarás deles mais tarde para marcar e enviar a tua imagem Docker para o Artifact Registry.

Autenticar o Docker no Artifact Registry

Autentica o teu cliente Docker no repositório do Artifact Registry que acabaste de criar. Executa o seguinte comando no teu terminal:

gcloud auth configure-docker YOUR_REGION-docker.pkg.dev

Marcar e enviar a tua imagem para o Artifact Registry

Marca e envia a imagem Docker para o Google Artifact Registry.

Marca a tua imagem com o URL do repositório do Artifact Registry. Substitui os marcadores pelos valores que guardaste anteriormente.

docker tag IMAGE_NAME:IMAGE_VERSION YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/YOUR_REPOSITORY_NAME/IMAGE_NAME:IMAGE_VERSION

Envia a imagem marcada para o repositório do Artifact Registry.

docker push YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/YOUR_REPOSITORY_NAME/IMAGE_NAME:IMAGE_VERSION

Aguarda que o processo termine. Deves agora ver a imagem no teu repositório do Artifact Registry.

Para instruções mais específicas sobre como trabalhar com imagens no Artifact Registry, consulta a documentação do Artifact Registry: Enviar e receber imagens.

4. Importar o teu modelo no Vertex AI

Usando a imagem Docker que acabaste de enviar, podes agora importar o modelo no Vertex AI.

1. No menu de navegação do Google Cloud, vai a Vertex AI > Registo de Modelos. Alternativamente, pesquisa por "Vertex AI" na barra de pesquisa no topo da consola do Google Cloud.

5. Criar um Endpoint do Vertex AI e implementar o teu modelo

Para implementar um modelo, precisas de criar um Endpoint no Vertex AI.

1. No teu menu de navegação do Vertex AI, vai a Endpoints. Seleciona a região que usaste ao importar o teu modelo. Clica em Criar.

1. Assim que o tipo de máquina for selecionado, podes clicar em Continuar. Neste ponto, podes escolher ativar a monitorização de modelos no Vertex AI — um serviço extra que acompanhará o desempenho do teu modelo e fornecerá informações sobre o seu comportamento. Isto é opcional e acarreta custos adicionais, por isso seleciona de acordo com as tuas necessidades. Clica em Criar.

O Vertex AI levará vários minutos (até 30 min em algumas regiões) para implementar o modelo. Receberás uma notificação por e-mail assim que a implementação estiver concluída.

6. Testar o teu modelo implementado

Assim que a implementação estiver concluída, o Vertex AI fornecer-te-á uma interface de API de exemplo para testares o teu modelo.

Para testar a inferência remota, podes usar o comando cURL fornecido ou criar outra biblioteca de cliente Python que enviará pedidos para o modelo implementado. Lembra-te que precisas de codificar a tua imagem em base64 antes de a enviares para o endpoint /predict.

Implementaste com sucesso um modelo YOLO26 pré-treinado com Ultralytics no Google Cloud Vertex AI.

FAQ

Posso usar modelos YOLO da Ultralytics no Vertex AI sem Docker?

Sim; no entanto, precisarás primeiro de exportar o modelo para um formato compatível com o Vertex AI, como TensorFlow, Scikit-learn ou XGBoost. O Google Cloud fornece um guia sobre como executar modelos .pt no Vertex com uma visão geral completa do processo de conversão: Executar modelos PyTorch no Vertex AI.

Tem em atenção que a configuração resultante dependerá apenas da camada de serviço padrão do Vertex AI e não suportará as funcionalidades avançadas do framework Ultralytics. Como o Vertex AI suporta totalmente modelos contentorizados e pode escalá-los automaticamente de acordo com a tua configuração de implementação, isto permite-te aproveitar todas as capacidades dos modelos YOLO da Ultralytics sem precisares de os converter para um formato diferente.

Por que o FastAPI é uma boa escolha para servir inferência com YOLO26?

O FastAPI oferece alto rendimento para cargas de trabalho de inferência. O suporte a async permite lidar com múltiplas solicitações simultâneas sem bloquear a thread principal, o que é importante ao servir modelos de visão computacional.

A validação automática de request/response com FastAPI reduz erros de tempo de execução em serviços de inferência em produção. Isso é particularmente valioso para APIs de detecção de objetos onde a consistência do formato de entrada é crítica.

O FastAPI adiciona um overhead computacional mínimo ao seu pipeline de inferência, deixando mais recursos disponíveis para a execução do modelo e tarefas de processamento de imagem.

O FastAPI também oferece suporte a SSE (Server-Sent Events), que é útil para cenários de inferência em streaming.

Por que preciso selecionar uma região tantas vezes?

Na verdade, esse é um recurso de versatilidade do Google Cloud Platform, onde você precisa selecionar uma região para cada serviço que utiliza. Para a tarefa de implantar um modelo conteinerizado no Vertex AI, sua seleção de região mais importante é a do Model Registry. Ela determinará a disponibilidade de tipos de máquina e cotas para a implantação do seu modelo.

Além disso, se você for estender a configuração e armazenar dados de previsão ou resultados no Cloud Storage ou BigQuery, precisará usar a mesma região do Model Registry para minimizar a latência e garantir alto rendimento no acesso aos dados.