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

Este guia mostra como colocar num contêiner um modelo YOLO26 pré-treinado com Ultralytics, criar um servidor de inferência FastAPI para o modelo e implementar o modelo com o servidor de inferência no Google Cloud Vertex AI. A implementação de exemplo aborda o caso de uso de deteção de objetos do YOLO26, mas os mesmos princípios aplicam-se ao uso de outros modos YOLO.

Antes de começar, precisas de criar um projeto na Google Cloud Platform (GCP). Como novo utilizador, recebes $300 em créditos GCP para utilizares gratuitamente, e este valor é suficiente para testar uma configuração em execução que podes posteriormente expandir para qualquer outro caso de uso do YOLO26, incluindo treino ou inferência em lote e em fluxo contínuo.

O que vais aprender#

1. Criar um backend de inferência para o modelo Ultralytics YOLO26 usando FastAPI.
2. Criar um repositório do GCP Artifact Registry para armazenar a tua imagem Docker.
3. Criar e enviar a imagem Docker com o modelo para o Artifact Registry.
4. Importar o teu modelo no Vertex AI.
5. Criar um endpoint do 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. É altamente recomendável que consultes o Guia de início rápido do Docker para Ultralytics, porque precisas 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 sirva os pedidos de inferência do modelo YOLO26. Esta aplicação tratará do carregamento do modelo, do pré-processamento de imagens e da lógica de inferência (predição).

Fundamentos de conformidade do Vertex AI#

O Vertex AI espera que o teu contêiner implemente dois endpoints específicos:

1. Endpoint Health (/health): deve devolver o estado HTTP 200 OK quando o serviço estiver pronto.

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

   Os payloads dos pedidos 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 compilação ocorrerá dentro do contêiner Docker, e a Ultralytics também carregará um modelo YOLO26 pré-treinado, por isso podes manter simples a estrutura da pasta local:

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 gerir convenientemente o teu projeto, 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 o processamento de imagens, mas não estás limitado apenas a imagens PIL — a Ultralytics suporta muitos outros formatos.

Criar a 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 principal de inferência do YOLO26. Cria um ficheiro src/app.py que trate do carregamento do modelo, do processamento de imagens e da 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 contêiner for iniciado, e o modelo será partilhado entre todos os pedidos. Se o teu modelo for submetido a uma carga de inferência elevada, recomenda-se que seleciones um tipo de máquina com mais memória ao importar um modelo no Vertex AI numa etapa posterior.

Em seguida, cria duas funções utilitárias para o processamento de imagens 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()

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

def run_inference(input_image: Image.Image, confidence_threshold: float = 0.5) -> Dict[str, Any]:
    """Run inference on an image using YOLO26n model."""
    # 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 da 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 um servidor de inferência HTTP com FastAPI#

Agora que tens a lógica principal de inferência do YOLO26, podes criar uma aplicação FastAPI para a servir. Isto incluirá os endpoints de verificação de estado e de 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 garantir a conformidade completa com o Vertex AI, define os endpoints obrigatórios nas variáveis de ambiente e estabelece o limite de tamanho dos pedidos. Recomenda-se usar endpoints privados do Vertex AI em implementações de produção. Desta forma, terás um limite de payload de pedido superior (10 MB em vez de 1,5 MB para endpoints públicos), juntamente com segurança e controlo de acesso robustos.

# 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 estado para confirmar que o teu modelo está pronto. Isto é importante para o Vertex AI, pois, sem uma verificação de estado dedicada, o seu orquestrador ficará a fazer ping a sockets aleatórios e não conseguirá determinar se o modelo está pronto para a inferência. A tua verificação deve devolver 200 OK em caso de sucesso e 503 Service Unavailable em caso de 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 o que precisas para implementar o endpoint de predição que tratará dos pedidos de inferência. Este aceitará um ficheiro de imagem, executará a inferência e devolverá os resultados. Tem em atenção que a imagem tem de ser codificada em base64, o que aumenta adicionalmente o tamanho do payload 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}")

Por fim, 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 capaz de servir pedidos de inferência do YOLO26. Podes testá-la localmente instalando as dependências e executando o servidor, por exemplo, com o uv.

# Install dependencies
uv pip install -e .

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

Para testar o servidor, podes consultar 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

Deves receber uma resposta JSON com os objetos detetados. No primeiro pedido, é normal ocorrer um pequeno atraso, pois a Ultralytics precisa de transferir 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 controladores de GPU necessários.

Para usar todas as capacidades dos modelos Ultralytics YOLO, 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, também podes poupar recursos computacionais selecionando a imagem apenas para CPU:

• Dockerfile: imagem otimizada para CUDA para treino e inferência do YOLO26 com uma ou várias GPU.
• Dockerfile-cpu: imagem apenas para CPU para inferência do 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 Docker oficial da Ultralytics ultralytics:latest é usada como base. 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 localmente a aplicação FastAPI.

Criar e testar a imagem Docker#

Agora podes criar a imagem Docker com o seguinte comando:

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

Substitui IMAGE_NAME e IMAGE_VERSION pelos valores pretendidos, por exemplo, yolo26-fastapi:0.1. Tem em atenção que tens de criar a imagem para a arquitetura linux/amd64 se a estiveres a implementar no Vertex AI. O parâmetro --platform tem de ser definido explicitamente se estiveres a criar a imagem num Mac com Apple Silicon ou noutra arquitetura não x86.

Quando a criação da imagem estiver concluída, podes testar localmente a imagem Docker:

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

O teu contêiner Docker está agora a executar um servidor FastAPI na porta 8080, pronto para aceitar pedidos de inferência. Podes testar os endpoints /health e /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 num contêiner para o Vertex AI, precisas de enviar a imagem Docker para o Google Cloud Artifact Registry. Se ainda não tens um repositório do Artifact Registry, primeiro precisas de criar um.

Criar um repositório no Google Cloud Artifact Registry#

Abre a página do Artifact Registry na Google Cloud Console. Se estiveres a usar o Artifact Registry pela primeira vez, poderá ser-te pedido que atives primeiro a API do Artifact Registry.

1. Seleciona Create Repository.
2. Introduz o nome do teu repositório. Seleciona a região pretendida e usa as predefinições para as outras opções, salvo se precisares especificamente de as alterar.

1. Quando o repositório for criado, guarda o teu PROJECT_ID, a localização (região) e o nome do repositório no teu cofre de segredos ou no ficheiro .env. Precisarás destes dados mais tarde para etiquetar 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

Etiquetar e enviar a tua imagem para o Artifact Registry#

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

Etiqueta a tua imagem com o URL do repositório do Artifact Registry. Substitui os marcadores de posição 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 etiquetada 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 a conclusão do processo. Deves agora ver a imagem no teu repositório do Artifact Registry.

Para obter instruções mais específicas sobre como trabalhar com imagens no Artifact Registry, consulta a documentação do Artifact Registry: Enviar e obter 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 da Google Cloud, vai a Vertex AI > Model Registry. Em alternativa, pesquisa por "Vertex AI" na barra de pesquisa na parte superior da Google Cloud Console.

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 menu de navegação do Vertex AI, vai a Endpoints. Seleciona a região que usaste ao importar o teu modelo. Clica em Create.

1. Depois de selecionares o tipo de máquina, podes clicar em Continue. Neste momento, podes optar por ativar a monitorização de modelos no Vertex AI — um serviço adicional que acompanha o desempenho do teu modelo e fornece informações sobre o seu comportamento. Isto é opcional e implica custos adicionais, por isso seleciona de acordo com as tuas necessidades. Clica em Create.

O Vertex AI demorará vários minutos (até 30 minutos em algumas regiões) a implementar o modelo. Receberás uma notificação por email quando a implementação estiver concluída.

6. Testar o teu modelo implementado#

Quando 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 cliente Python que envie pedidos para o modelo implementado. Lembra-te de que tens de codificar a tua imagem em base64 antes de a enviares para o endpoint /predict.

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

Perguntas frequentes#