Разверни предварительно обученную модель YOLO с Ultralytics в Vertex AI для инференса#

В этом руководстве показано, как контейнеризировать предварительно обученную модель YOLO26 с Ultralytics, создать для неё сервер инференса на FastAPI и развернуть модель вместе с сервером инференса в Google Cloud Vertex AI. В примере рассматривается сценарий обнаружения объектов для YOLO26, но те же принципы применимы к использованию других режимов YOLO.

Перед началом тебе потребуется создать проект Google Cloud Platform (GCP). Новому пользователю бесплатно предоставляется $300 кредитов GCP, и этой суммы достаточно, чтобы протестировать работающую конфигурацию, которую позже можно расширить для любых других сценариев использования YOLO26, включая обучение, а также пакетный и потоковый инференс.

Чему ты научишься#

1. Создавать бэкенд инференса для модели Ultralytics YOLO26 с использованием FastAPI.
2. Создавать репозиторий GCP Artifact Registry для хранения Docker-образа.
3. Собирать и отправлять Docker-образ с моделью в Artifact Registry.
4. Импортировать модель в Vertex AI.
5. Создавать конечную точку Vertex AI и развёртывать модель.

Предварительные требования#

1. Установи Docker на свою машину.
2. Установи Google Cloud SDK и аутентифицируйся для использования CLI gcloud.
3. Настоятельно рекомендуем ознакомиться с кратким руководством по Docker для Ultralytics, поскольку в этом руководстве тебе потребуется расширить один из официальных Docker-образов Ultralytics.

1. Создание бэкенда инференса с FastAPI#

Сначала тебе нужно создать приложение FastAPI, которое будет обрабатывать запросы инференса модели YOLO26. Это приложение будет отвечать за загрузку модели, предобработку изображений и логику инференса (предсказания).

Основы соответствия требованиям Vertex AI#

Vertex AI ожидает, что в контейнере будут реализованы две определённые конечные точки:

1. Конечная точка Health (/health): должна возвращать статус HTTP 200 OK, когда сервис готов.

2. Конечная точка Predict (/predict): принимает структурированные запросы предсказаний с изображениями, закодированными в base64, и необязательными параметрами. В зависимости от типа конечной точки действуют ограничения на размер полезной нагрузки.

   Полезные нагрузки запросов к конечной точке /predict должны соответствовать следующей структуре JSON:

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

Структура папок проекта#

Основная часть сборки будет выполняться внутри Docker-контейнера, а Ultralytics также загрузит предварительно обученную модель YOLO26, поэтому локальную структуру папок можно оставить простой:

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

Создание pyproject.toml с зависимостями#

Чтобы удобно управлять проектом, создай файл pyproject.toml со следующими зависимостями:

[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 будет использоваться для запуска сервера FastAPI.
• pillow будет использоваться для обработки изображений, но ты не ограничен только изображениями PIL — Ultralytics поддерживает множество других форматов.

Создание логики инференса с Ultralytics YOLO26#

Теперь, когда структура проекта и зависимости настроены, можно реализовать основную логику инференса YOLO26. Создай файл src/app.py, который будет отвечать за загрузку модели, обработку изображений и предсказания с использованием API Ultralytics для Python.

# 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

Модель будет загружаться один раз при запуске контейнера и использоваться совместно всеми запросами. Если модель будет обрабатывать большую нагрузку инференса, на следующем этапе при импорте модели в Vertex AI рекомендуется выбрать тип машины с большим объёмом памяти.

Затем создай две вспомогательные функции для обработки входных и выходных изображений с помощью pillow. YOLO26 изначально поддерживает изображения PIL.

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()

Наконец, реализуй функцию run_inference, которая будет отвечать за обнаружение объектов. В этом примере мы извлечём из предсказаний модели ограничивающие рамки, названия классов и оценки уверенности. Функция вернёт словарь с обнаружениями и необработанными результатами для дальнейшей обработки или аннотирования.

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}

При желании можно добавить функцию для нанесения на изображение ограничивающих рамок и меток с использованием встроенного метода построения графиков Ultralytics. Это пригодится, если ты захочешь возвращать аннотированные изображения в ответе на предсказание.

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)

Создание HTTP-сервера инференса с FastAPI#

Теперь, когда основная логика инференса YOLO26 готова, можно создать приложение FastAPI для её предоставления. Оно будет включать конечные точки проверки работоспособности и предсказаний, необходимые Vertex AI.

Сначала добавь импорты и настрой журналирование для Vertex AI. Поскольку Vertex AI воспринимает stderr как вывод ошибок, имеет смысл перенаправить журналы в 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")

Для полного соответствия требованиям Vertex AI определи необходимые конечные точки в переменных окружения и задай ограничение размера запросов. Для развёртываний в production рекомендуется использовать приватные конечные точки Vertex AI. Так ты получишь более высокий лимит полезной нагрузки запроса (10 МБ вместо 1,5 МБ для публичных конечных точек), а также надёжные средства безопасности и контроля доступа.

# 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

Добавь две модели Pydantic для проверки запросов и ответов:

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

class PredictionResponse(BaseModel):
    predictions: list

Добавь конечную точку проверки работоспособности, чтобы подтвердить готовность модели. Это важно для Vertex AI, поскольку без отдельной проверки работоспособности его оркестратор будет обращаться к случайным сокетам и не сможет определить, готова ли модель к инференсу. При успехе проверка должна возвращать 200 OK, а при сбое — 503 Service Unavailable:

# 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"}

Теперь у тебя есть всё необходимое для реализации конечной точки предсказаний, которая будет обрабатывать запросы инференса. Она будет принимать файл изображения, выполнять инференс и возвращать результаты. Обрати внимание, что изображение должно быть закодировано в base64, что дополнительно увеличивает размер полезной нагрузки до 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}")

Наконец, добавь точку входа приложения для запуска сервера 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)

Теперь у тебя есть полноценное приложение FastAPI, способное обрабатывать запросы инференса YOLO26. Ты можешь протестировать его локально, установив зависимости и запустив сервер, например с помощью uv.

# Install dependencies
uv pip install -e .

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

Чтобы протестировать сервер, можно отправить запросы к обеим конечным точкам /health и /predict с помощью cURL. Помести тестовое изображение в папку tests. Затем выполни в терминале следующие команды:

# 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

В ответе должен прийти JSON с обнаруженными объектами. При первом запросе ожидай небольшую задержку, поскольку Ultralytics необходимо загрузить модель YOLO26.

2. Расширение Docker-образа Ultralytics своим приложением#

Ultralytics предоставляет несколько Docker-образов, которые можно использовать в качестве основы для образа приложения. Docker установит Ultralytics и необходимые драйверы GPU.

Чтобы использовать все возможности моделей Ultralytics YOLO, для инференса на GPU следует выбрать образ, оптимизированный для CUDA. Однако если для твоей задачи достаточно инференса на CPU, можно сэкономить вычислительные ресурсы, выбрав образ только для CPU:

• Dockerfile: образ, оптимизированный для CUDA, для обучения и инференса YOLO26 на одной или нескольких GPU.
• Dockerfile-cpu: образ только для CPU для инференса YOLO26.

Создание Docker-образа приложения#

Создай файл Dockerfile в корне проекта со следующим содержимым:

# 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"]

В примере официальный Docker-образ Ultralytics ultralytics:latest используется в качестве основы. Он уже содержит модель YOLO26 и все необходимые зависимости. Точка входа сервера такая же, как при локальном тестировании приложения FastAPI.

Сборка и тестирование Docker-образа#

Теперь можно собрать Docker-образ с помощью следующей команды:

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

Замени IMAGE_NAME и IMAGE_VERSION нужными значениями, например yolo26-fastapi:0.1. Обрати внимание, что для развёртывания в Vertex AI образ необходимо собирать для архитектуры linux/amd64. Параметр --platform необходимо явно задать, если образ собирается на Mac с Apple Silicon или любой другой архитектуре, отличной от x86.

После завершения сборки образа можно протестировать Docker-образ локально:

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

Теперь в Docker-контейнере работает сервер FastAPI на порту 8080, готовый принимать запросы инференса. Можно протестировать обе конечные точки /health и /predict с помощью тех же команд cURL, что и ранее:

# 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. Загрузка Docker-образа в GCP Artifact Registry#

Чтобы импортировать контейнеризированную модель в Vertex AI, необходимо загрузить Docker-образ в Google Cloud Artifact Registry. Если у тебя ещё нет репозитория Artifact Registry, сначала потребуется его создать.

Создание репозитория в Google Cloud Artifact Registry#

Открой страницу Artifact Registry в Google Cloud Console. Если ты используешь Artifact Registry впервые, система может сначала предложить включить API Artifact Registry.

1. Выбери Create Repository.
2. Введи название репозитория. Выбери нужный регион, а для остальных параметров используй настройки по умолчанию, если нет особой необходимости их изменять.

1. После создания репозитория сохрани PROJECT_ID, Location (Region) и Repository Name в хранилище секретов или файле .env. Позже они понадобятся для добавления тега и отправки Docker-образа в Artifact Registry.

Аутентификация Docker в Artifact Registry#

Аутентифицируй Docker-клиент в только что созданном репозитории Artifact Registry. Выполни следующую команду в терминале:

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

Добавление тега и отправка образа в Artifact Registry#

Добавь тег и отправь Docker-образ в Google Artifact Registry.

Добавь к образу тег с URL репозитория Artifact Registry. Замени заполнители значениями, сохранёнными ранее.

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

Отправь образ с тегом в репозиторий Artifact Registry.

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

Дождись завершения процесса. Теперь образ должен отображаться в репозитории Artifact Registry.

Более подробные инструкции по работе с образами в Artifact Registry смотри в документации Artifact Registry: отправка и загрузка образов.

4. Импорт модели в Vertex AI#

Теперь можно импортировать модель в Vertex AI, используя только что отправленный Docker-образ.

1. В меню навигации Google Cloud перейди в Vertex AI > Model Registry. Также можно найти "Vertex AI" в строке поиска в верхней части Google Cloud Console.

5. Создание конечной точки Vertex AI и развёртывание модели#

Чтобы развернуть модель, необходимо создать конечную точку в Vertex AI.

1. В меню навигации Vertex AI перейди в Endpoints. Выбери регион, который использовался при импорте модели. Нажми Create.

1. После выбора типа машины можно нажать Continue. На этом этапе можно включить мониторинг модели в Vertex AI — дополнительный сервис, который будет отслеживать производительность модели и предоставлять сведения о её поведении. Это необязательно и влечёт дополнительные расходы, поэтому выбери нужный вариант с учётом своих потребностей. Нажми Create.

Vertex AI потребуется несколько минут (в некоторых регионах до 30 минут), чтобы развернуть модель. После завершения развёртывания ты получишь уведомление по электронной почте.

6. Тестирование развёрнутой модели#

После завершения развёртывания Vertex AI предоставит пример интерфейса API для тестирования модели.

Для тестирования удалённого инференса можно использовать предоставленную команду cURL или создать другую клиентскую библиотеку на Python, которая будет отправлять запросы к развёрнутой модели. Помни, что перед отправкой на конечную точку /predict изображение необходимо закодировать в base64.

Ты успешно развернул предварительно обученную модель YOLO26 с Ultralytics в Google Cloud Vertex AI.

Часто задаваемые вопросы#