Çıkarım için Vertex AI üzerinde Ultralytics ile eğitilmiş bir YOLO modelini dağıtın#

Bu kılavuz, önceden eğitilmiş bir YOLO26 modelini Ultralytics ile nasıl kapsülleyeceğinizi, bunun için bir FastAPI çıkarım sunucusu oluşturacağınızı ve modeli çıkarım sunucusuyla birlikte Google Cloud Vertex AI üzerinde nasıl dağıtacağınızı gösterecektir. Örnek uygulama, YOLO26 için nesne tespiti kullanım senaryosunu kapsayacaktır, 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ız gerekecek. Yeni bir kullanıcı olarak ücretsiz kullanabileceğiniz 300 dolarlık GCP kredisi alırsınız ve bu miktar, daha sonra eğitim veya toplu ve akışlı çıkarım dahil olmak üzere diğer tüm YOLO26 kullanım durumları için genişletebileceğiniz çalışan bir kurulumu test etmek için yeterlidir.

Neler öğreneceksin#

1. FastAPI kullanarak Ultralytics YOLO26 modeli için bir çıkarım arka ucu oluştur.
2. Docker imajını saklamak için bir GCP Artifact Registry deposu oluştur.
3. Modeli içeren Docker imajını derle ve Artifact Registry'ye gönder.
4. Modelini Vertex AI içine aktar.
5. Bir Vertex AI uç noktası oluştur ve modeli dağıt.

Ön koşullar#

1. Bilgisayarına Docker yükle.
2. Google Cloud SDK yükle ve gcloud CLI kullanımı için kimlik doğrulaması yap.
3. Ultralytics için Docker Hızlı Başlangıç Kılavuzu üzerinden geçmen şiddetle tavsiye edilir, çünkü bu kılavuzu takip ederken resmî Ultralytics Docker imajlarından birini genişletmen gerekecektir.

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

Öncelikle, YOLO26 modeli çıkarım isteklerine hizmet verecek bir FastAPI uygulaması oluşturman gerekiyor. Bu uygulama, model yükleme, görüntü ön işleme ve çıkarım (tahmin) mantığını yönetecektir.

Vertex AI Uyumluluk Temelleri#

Vertex AI, kapsayıcınızın iki özel uç noktayı uygulamasını bekler:

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

2. Predict uç noktası (/predict): base64 kodlu görseller ve isteğe bağlı parametreler içeren yapılandırılmış tahmin isteklerini kabul eder. Uç nokta türüne bağlı olarak yük boyutu sınırları geçerlidir.

   /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ı#

Derlememizin büyük kısmı Docker kapsayıcısı içinde gerçekleşecek ve Ultralytics de eğitilmiş bir YOLO26 modelini yükleyeceğinden, 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 birlikte pyproject.toml oluştur#

Projeni rahatça yönetmek için aşağıdaki bağımlılıklara sahip 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ılacaktır.
• pillow görsel işleme için kullanılacaktır, ancak yalnızca PIL görselleriyle sınırlı değilsin — Ultralytics diğer birçok formatı destekler.

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

Proje yapısını ve bağımlılıkları ayarladığına göre, çekirdek YOLO26 çıkarım mantığını uygulayabilirsin. Ultralytics Python API kullanarak model yükleme, görsel 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, model kapsayıcı başladığında bir kez yüklenecek ve model tüm istekler arasında paylaşılacaktır. Modeliniz ağır çıkarım yükünü kaldıracaksa, daha sonraki bir adımda Vertex AI'da model içe aktarırken daha fazla belleğe sahip bir makine türü seçmeniz önerilir.

Sonra, pillow ile girdi ve çıktı görsel işleme için iki yardımcı fonksiyon oluştur. YOLO26, PIL görsellerini 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 olan run_inference fonksiyonunu uygula. Bu örnekte, model tahminlerinden sınırlayıcı kutuları, sınıf adlarını ve güven skorlarını çıkaracağız. Fonksiyon, daha fazla işleme veya etiketleme için tespitleri ve ham sonuçları içeren bir sözlük döndürecektir.

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 yerleşik çizim yöntemini kullanarak görüntüyü sınırlayıcı kutular ve etiketlerle işaretlemek için bir işlev ekleyebilirsiniz. Bu, tahmin yanıtında işaretli görüntüleri döndürmek isterseniz 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ğunuza göre, buna hizmet edecek bir FastAPI uygulaması oluşturabilirsiniz. Bu, Vertex AI tarafından gerekli olan sağlık kontrolü ve tahmin uç noktalarını içerecektir.

Öncelikle içe aktarmaları ekleyin ve Vertex AI için günlüğe kaydetmeyi yapılandırın. Vertex AI, stderr'i hata çıktısı olarak kabul ettiğinden, 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 bir 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. Prodüksiyon dağıtımları için özel Vertex AI uç noktalarını kullanman önerilir. Bu şekilde, sağlam güvenlik ve erişim kontrolünün yanı sıra daha yüksek bir istek yükü sınırına (açık uç noktalar için 1,5 MB yerine 10 MB) sahip olursun.

# 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

İsteklerinizi ve yanıtlarınızı doğrulamak için iki Pydantic modeli ekleyin:

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

class PredictionResponse(BaseModel):
    predictions: list

Modelinin hazırlığını doğrulamak için sağlık kontrolü uç noktasını ekle. Bu, Vertex AI için önemlidir, çünkü özel bir sağlık kontrolü olmadan düzenleyicisi rastgele soketleri ping'leyecek ve modelin çıkarım için hazır olup olmadığını belirleyemeyecektir. Kontrolün, başarı için 200 OK ve hata için 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 her şeye sahipsiniz. Bir görüntü dosyası kabul edecek, çıkarımı çalıştıracak ve sonuçları döndürecektir. Görüntünün base64 kodlu olması gerektiğini unutmayın, bu da yükün boyutunu %33'e kadar artırır.

@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ı ekleyin.

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 edebilen eksiksiz bir FastAPI uygulamanız var. Bağımlılıkları yükleyip sunucuyu, örneğin uv ile çalıştırarak yerel olarak test edebilirsiniz.

# Install dependencies
uv pip install -e .

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

Sunucuyu test etmek için, cURL kullanarak hem /health hem de /predict uç noktalarını sorgulayabilirsin. tests klasörüne bir test görseli koy. Ardından Terminalinde ş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

Algılanan nesneleri içeren bir JSON yanıtı almalısınız. İlk isteğinizde, Ultralytics'in YOLO26 modelini çekmesi ve yüklemesi gerektiğinden kısa bir gecikme bekleyin.

Ultralytics Docker imajını uygulamanızla genişletin#

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

Ultralytics YOLO modellerinin tüm yeteneklerini kullanmak için GPU çıkarımı için CUDA ile optimize edilmiş imajı seçmelisiniz. Ancak, göreviniz için CPU çıkarımı yeterliyse, sadece CPU imajını seçerek de bilgi işlem kaynaklarından tasarruf edebilirsiniz:

• Dockerfile: YOLO26 tekli/çoklu GPU eğitimi ve çıkarımı için CUDA optimizasyonlu imaj.
• Dockerfile-cpu: YOLO26 çıkarımı için yalnızca CPU imajı.

Uygulamanız için bir Docker imajı oluşturun#

Projelerinin 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, temel olarak resmî Ultralytics Docker imajı ultralytics:latest kullanılmıştır. Bu imaj halihazırda YOLO26 modelini ve tüm gerekli bağımlılıkları içermektedir. Sunucunun giriş noktası, FastAPI uygulamasını yerel olarak test etmek için kullandığımızla aynıdır.

Docker imajını derleyin ve test edin#

Artık Docker imajını aşağıdaki komutla derleyebilirsiniz:

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ı bir Apple Silicon Mac veya başka bir x86 dışı mimari üzerinde oluşturuyorsan --platform parametresinin açıkça ayarlanması gerekir.

İmaj derleme işlemi tamamlandığında, Docker imajını yerel olarak test edebilirsiniz:

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

Docker kapsayıcın şu anda 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ç noktasını daha öncekiyle aynı cURL komutlarıyla 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

Docker imajını GCP Artifact Registry'ye yükleyin#

Kapsayıcıya aldığınız modeli Vertex AI'da içe aktarmak için Docker imajını Google Cloud Artifact Registry'ye yüklemeniz gerekir. Henüz bir Artifact Registry deponuz yoksa, önce bir tane oluşturmanız gerekecektir.

Google Cloud Artifact Registry'de bir depo oluşturun#

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

1. Depo Oluştur (Create Repository) seçeneğini seçin.
2. Deponuzun adını girin. İstediğiniz bölgeyi seçin ve özel olarak değiştirmeniz gerekmiyorsa diğer seçenekler için varsayılan ayarları kullanın.

1. Depo oluşturulduktan sonra PROJECT_ID, Konum (Bölge) ve Depo Adı değerlerini sır kasana veya .env dosyana kaydet. Docker imajını Artifact Registry'ye etiketlemek ve göndermek için bunlara daha sonra ihtiyacın olacak.

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

Docker istemcinizin, az önce oluşturduğunuz Artifact Registry deposu için kimlik doğrulamasını yapın. Terminalinizde aşağıdaki komutu çalıştırın:

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

İmajınızı etiketleyin ve Artifact Registry'ye gönderin#

Docker imajını etiketleyin ve Google Artifact Registry'ye gönderin.

İmajınızı Artifact Registry depo URL'si ile etiketleyin. Yer tutucuları daha önce kaydettiğiniz değerlerle değiştirin.

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

Etiketli imajı Artifact Registry deposuna gönderin.

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

İşlemin tamamlanmasını bekleyin. Artık imajı Artifact Registry deponuzda görmelisiniz.

Artifact Registry'deki imajlarla çalışmaya ilişkin daha spesifik talimatlar için Artifact Registry belgelerine bakın: İmajları gönderme ve çekme.

Modelini Vertex AI içine aktar#

Az önce gönderdiğiniz Docker imajını kullanarak, artık modeli Vertex AI'ya aktarabilirsiniz.

1. Google Cloud gezinme menüsünde Vertex AI > Model Registry bölümüne gidin. Alternatif olarak, Google Cloud Console'un üst kısmındaki arama çubuğunda "Vertex AI" araması yapın.

Bir Vertex AI Uç Noktası oluştur ve modelini dağıt#

Bir modeli dağıtmak için Vertex AI'da bir Uç Nokta oluşturmanız gerekir.

1. Vertex AI gezinme menünüzde Uç Noktalar (Endpoints) bölümüne gidin. Modelinizi içe aktarırken kullandığınız bölgeyi seçin. Oluştur (Create) seçeneğine tıklayın.

1. Makine türü seçildikten sonra Devam'a tıklayabilirsiniz. Bu aşamada, Vertex AI'da model izlemeyi etkinleştirmeyi seçebilirsiniz; bu, modelinizin performansını takip edecek ve davranışına ilişkin bilgiler sağlayacak ekstra bir hizmettir. Bu isteğe bağlıdır ve ek maliyet gerektirir, bu yüzden ihtiyaçlarınıza göre seçin. Oluştur'a tıklayın.

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

Dağıtılan modelini test et#

Dağıtım tamamlandıktan sonra Vertex AI, modelinizi test etmeniz için size örnek bir API arayüzü sağlayacaktır.

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

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

SSS#