Ultralytics ile Vertex AI üzerinde çıkarım için önceden eğitilmiş bir YOLO modeli dağıtma#

Bu kılavuzda, Ultralytics ile önceden eğitilmiş bir YOLO26 modelini nasıl konteynerleştireceğini, bunun için bir FastAPI çıkarım sunucusu oluşturacağını ve modeli çıkarım sunucusuyla Google Cloud Vertex AI üzerinde nasıl dağıtacağını öğreneceksin. Örnek uygulamada YOLO26 için nesne tespiti kullanım senaryosu ele alınacak, ancak aynı ilkeler diğer YOLO modlarını kullanırken de geçerli olacaktır.

Başlamadan önce bir Google Cloud Platform (GCP) projesi oluşturman gerekir. Yeni kullanıcı olarak ücretsiz kullanabileceğin 300 $ GCP kredisi alırsın ve bu tutar, daha sonra eğitim veya toplu ve akış çıkarımı dahil diğer YOLO26 kullanım senaryoları için genişletebileceğin çalışan bir kurulumu test etmek için yeterlidir.

Öğreneceklerin#

1. FastAPI kullanarak Ultralytics YOLO26 modeli için bir çıkarım arka ucu oluşturma.
2. Docker imajını depolamak için bir GCP Artifact Registry deposu oluşturma.
3. Modelin bulunduğu Docker imajını oluşturup Artifact Registry'ye gönderme.
4. Modelini Vertex AI'ye içe aktarma.
5. Bir Vertex AI uç noktası oluşturup modeli dağıtma.

Ön koşullar#

1. Makinenize Docker yükle.
2. Google Cloud SDK'yi yükle ve gcloud CLI'yi kullanmak için kimlik doğrulaması yap.
3. Bu kılavuzu izlerken resmi Ultralytics Docker imajlarından birini genişletmen gerekeceği için Ultralytics için Docker Hızlı Başlangıç Kılavuzu'nu incelemen önemle önerilir.

1. FastAPI ile bir çıkarım arka ucu oluştur#

Öncelikle YOLO26 modeli çıkarım isteklerine hizmet verecek bir FastAPI uygulaması oluşturman gerekir. Bu uygulama modelin yüklenmesini, görüntü ön işlemesini ve çıkarım (tahmin) mantığını yönetecek.

Vertex AI Uyumluluk Temelleri#

Vertex AI, konteynerinin iki özel uç nokta uygulamasını bekler:

1. Health uç noktası (/health): Hizmet hazır olduğunda HTTP 200 OK durumunu döndürmelidir.

2. Predict uç noktası (/predict): base64 ile kodlanmış görüntüler ve isteğe bağlı parametreler içeren yapılandırılmış tahmin isteklerini kabul eder. Uç nokta türüne bağlı olarak Payload boyutu sınırları uygulanır.

   /predict uç noktası için istek yükleri şu JSON yapısını izlemelidir:

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

Proje klasörü yapısı#

Derlemenin büyük bölümü Docker konteynerinin içinde gerçekleşecek ve Ultralytics önceden eğitilmiş bir YOLO26 modeli de yükleyecek; bu nedenle yerel klasör yapısını basit tutabilirsin:

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

Bağımlılıklarla pyproject.toml oluştur#

Projenizi kolayca yönetmek için aşağıdaki bağımlılıkları içeren bir pyproject.toml dosyası oluştur:

[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 sunucusunu çalıştırmak için kullanılacak.
• pillow, görüntü işleme için kullanılacak; ancak yalnızca PIL görüntüleriyle sınırlı değilsin — Ultralytics birçok başka formatı destekler.

Ultralytics YOLO26 ile çıkarım mantığı oluştur#

Artık proje yapısını ve bağımlılıkları ayarladığına göre temel YOLO26 çıkarım mantığını uygulayabilirsin. Ultralytics Python API'sini kullanarak model yükleme, görüntü işleme ve tahmini yönetecek bir src/app.py dosyası oluştur.

# 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

Bu işlem, konteyner başlatıldığında modeli bir kez yükleyecek ve model tüm istekler arasında paylaşılacak. Modelin yoğun çıkarım yükünü işleyecekse sonraki bir adımda modeli Vertex AI'ye aktarırken daha fazla belleğe sahip bir makine türü seçmen önerilir.

Ardından pillow ile giriş ve çıkış görüntüsü işleme için iki yardımcı işlev oluştur. YOLO26, PIL görüntülerini yerel olarak destekler.

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

Son olarak nesne tespitini yönetecek run_inference işlevini uygula. Bu örnekte model tahminlerinden sınırlayıcı kutuları, sınıf adlarını ve güven skorlarını çıkaracağız. İşlev, daha ileri işleme veya açıklama ekleme için tespitleri ve ham sonuçları içeren bir sözlük döndürecek.

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}

İsteğe bağlı olarak, Ultralytics'in yerleşik çizim yöntemini kullanarak görüntüye sınırlayıcı kutular ve etiketler ekleyen bir işlev de ekleyebilirsin. Tahmin yanıtında açıklama eklenmiş görüntüler döndürmek istiyorsan bu yararlı olacaktır.

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)

FastAPI ile HTTP çıkarım sunucusu oluştur#

Artık temel YOLO26 çıkarım mantığına sahip olduğuna göre buna hizmet edecek bir FastAPI uygulaması oluşturabilirsin. Bu uygulama, Vertex AI'nin gerektirdiği sistem durumu denetimi ve tahmin uç noktalarını içerecek.

Öncelikle içe aktarmaları ekle ve Vertex AI için günlük kaydını yapılandır. Vertex AI stderr'yi hata çıktısı olarak değerlendirdiği için günlükleri stdout'a yönlendirmek mantıklıdır.

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

Eksiksiz Vertex AI uyumluluğu için gerekli uç noktaları ortam değişkenlerinde tanımla ve istekler için boyut sınırını ayarla. Üretim dağıtımları için özel Vertex AI uç noktalarının kullanılması önerilir. Böylece güçlü güvenlik ve erişim denetimiyle birlikte daha yüksek bir istek yükü sınırına sahip olursun (genel uç noktalar için 1,5 MB yerine 10 MB).

# 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

İsteklerini ve yanıtlarını doğrulamak için iki Pydantic modeli ekle:

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

class PredictionResponse(BaseModel):
    predictions: list

Modelinin hazır olduğunu doğrulamak için sistem durumu denetimi uç noktasını ekle. Bu, Vertex AI için önemlidir; özel bir sistem durumu denetimi olmadığında orkestratörü rastgele yuvalara ping gönderecek ve modelin çıkarıma hazır olup olmadığını belirleyemeyecektir. Denetimin başarılı durumda 200 OK, başarısız durumda ise 503 Service Unavailable döndürmelidir:

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

Artık çıkarım isteklerini yönetecek tahmin uç noktasını uygulamak için gereken her şeye sahipsin. Bu uç nokta bir görüntü dosyasını kabul edecek, çıkarımı çalıştıracak ve sonuçları döndürecek. Görüntünün base64 ile kodlanması gerektiğini ve bunun yükün boyutunu ek olarak %33'e kadar artırdığını unutma.

@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}")

Son olarak FastAPI sunucusunu çalıştırmak için uygulama giriş noktasını ekle.

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)

Artık YOLO26 çıkarım isteklerine hizmet verebilen eksiksiz bir FastAPI uygulaman var. Bağımlılıkları yükleyip sunucuyu örneğin uv ile çalıştırarak uygulamayı yerel olarak test edebilirsin.

# Install dependencies
uv pip install -e .

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

Sunucuyu test etmek için hem /health hem de /predict uç noktalarını cURL kullanarak sorgulayabilirsin. tests klasörüne bir test görüntüsü koy. Ardından Terminal'inde şu komutları çalıştır:

# 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

Tespit edilen nesneleri içeren bir JSON yanıtı almalısın. İlk isteğinde kısa bir gecikme bekle; Ultralytics'in YOLO26 modelini çekip yüklemesi gerekir.

2. Ultralytics Docker imajını uygulamanla genişlet#

Ultralytics, uygulama imajın için temel olarak kullanabileceğin çeşitli Docker imajları sağlar. Docker, Ultralytics'i ve gerekli GPU sürücülerini yükler.

Ultralytics YOLO modellerinin tüm özelliklerinden yararlanmak için GPU çıkarımı amacıyla CUDA için optimize edilmiş imajı seçmelisin. Ancak görevin için CPU çıkarımı yeterliyse yalnızca CPU kullanan imajı seçerek işlem kaynaklarından da tasarruf edebilirsin:

• Dockerfile: YOLO26 tek GPU'lu/çok GPU'lu eğitim ve çıkarım için CUDA için optimize edilmiş imaj.
• Dockerfile-cpu: YOLO26 çıkarımı için yalnızca CPU kullanan imaj.

Uygulaman için Docker imajı oluştur#

Projenin kök dizininde aşağıdaki içeriğe sahip bir Dockerfile oluştur:

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

Örnekte resmi Ultralytics Docker imajı ultralytics:latest temel olarak kullanılıyor. Bu imaj zaten YOLO26 modelini ve gerekli tüm bağımlılıkları içeriyor. Sunucunun giriş noktası, FastAPI uygulamasını yerel olarak test etmek için kullandığımız giriş noktasıyla aynı.

Docker imajını oluştur ve test et#

Şimdi Docker imajını şu komutla oluşturabilirsin:

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

IMAGE_NAME ve IMAGE_VERSION değerlerini istediğin değerlerle, örneğin yolo26-fastapi:0.1 ile değiştir. Vertex AI üzerinde dağıtım yapıyorsan imajı linux/amd64 mimarisi için oluşturman gerektiğini unutma. İmajı Apple Silicon Mac veya x86 olmayan başka bir mimaride oluşturuyorsan --platform parametresi açıkça ayarlanmalıdır.

İmaj oluşturma tamamlandığında Docker imajını yerel olarak test edebilirsin:

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

Docker konteynerin artık 8080 bağlantı noktasında bir FastAPI sunucusu çalıştırıyor ve çıkarım isteklerini kabul etmeye hazır. Hem /health hem de /predict uç noktalarını öncekiyle aynı cURL komutlarını kullanarak test edebilirsin:

# 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 imajını GCP Artifact Registry'ye yükle#

Konteynerleştirilmiş modelini Vertex AI'ye aktarmak için Docker imajını Google Cloud Artifact Registry'ye yüklemen gerekir. Henüz bir Artifact Registry depon yoksa önce bir tane oluşturmalısın.

Google Cloud Artifact Registry'de depo oluştur#

Google Cloud Console'da Artifact Registry sayfasını aç. Artifact Registry'yi ilk kez kullanıyorsan önce Artifact Registry API'sini etkinleştirmen istenebilir.

1. Create Repository'yi seç.
2. Deponun adını gir. İstediğin bölgeyi seç ve özellikle değiştirmen gerekmiyorsa diğer seçenekler için varsayılan ayarları kullan.

1. Depo oluşturulduktan sonra PROJECT_ID, Location (Region) ve Repository Name değerlerini gizli bilgiler kasana veya .env dosyana kaydet. Docker imajını Artifact Registry'ye etiketleyip göndermek için bunlara daha sonra ihtiyacın olacak.

Docker'ın Artifact Registry'de kimlik doğrulamasını yap#

Docker istemcinin kimliğini az önce oluşturduğun Artifact Registry deposunda doğrula. Terminal'inde şu komutu çalıştır:

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

İmajını Artifact Registry'ye etiketle ve gönder#

Docker imajını Google Artifact Registry'ye etiketle ve gönder.

İmajını Artifact Registry depo URL'siyle etiketle. Yer tutucuları daha önce kaydettiğin değerlerle değiştir.

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

Etiketlenmiş imajı Artifact Registry deposuna gönder.

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

İşlemin tamamlanmasını bekle. Artık imajı Artifact Registry depon içinde görmelisin.

Artifact Registry'de imajlarla çalışma hakkında daha özel talimatlar için Artifact Registry belgelerine bak: İmajları gönderme ve çekme.

4. Modelini Vertex AI'ye aktar#

Az önce gönderdiğin Docker imajını kullanarak modeli artık Vertex AI'ye aktarabilirsin.

1. Google Cloud gezinme menüsünde Vertex AI > Model Registry'ye git. Alternatif olarak Google Cloud Console'un üst kısmındaki arama çubuğunda "Vertex AI" için arama yap.

5. Bir Vertex AI Endpoint oluştur ve modelini dağıt#

Bir modeli dağıtmak için Vertex AI'de bir Endpoint oluşturman gerekir.

1. Vertex AI gezinme menünde Endpoints'e git. Modelini aktarırken kullandığın bölgeyi seç. Create'e tıkla.

1. Makine türü seçildikten sonra Continue'e tıklayabilirsin. Bu noktada Vertex AI'de model izlemeyi etkinleştirmeyi seçebilirsin; bu ek hizmet modelinin performansını takip eder ve davranışı hakkında içgörüler sunar. Bu seçenek isteğe bağlıdır ve ek maliyet oluşturur; bu nedenle ihtiyaçlarına göre seçim yap. Create'e tıkla.

Vertex AI'nin modeli dağıtması birkaç dakika sürecek (bazı bölgelerde 30 dakikaya kadar). Dağıtım tamamlandığında e-posta bildirimi alacaksın.

6. Dağıtılmış modelini test et#

Dağıtım tamamlandığında Vertex AI, modelini test etmen için örnek bir API arayüzü sağlayacak.

Uzak çıkarımı test etmek için sağlanan cURL komutunu kullanabilir veya dağıtılmış modele istek gönderecek başka bir Python istemci kitaplığı oluşturabilirsin. Görüntünü /predict uç noktasına göndermeden önce base64'e kodlaman gerektiğini unutma.

Önceden eğitilmiş bir YOLO26 modelini Ultralytics ile Google Cloud Vertex AI üzerinde başarıyla dağıttın.

SSS#