Skip to content

README.md

Latest commit

 

History

History
120 lines (95 loc) · 4.31 KB

README.md

File metadata and controls

120 lines (95 loc) · 4.31 KB
Raw

Production-Ready Edge AI: YOLOv8 Inference API with FastAPI and Docker

This repository contains a production-ready, enterprise-grade deployment framework that wraps an Ultralytics YOLOv8 object detection model into a high-performance FastAPI web service, completely containerized using Docker.

Instead of treating machine learning as an isolated research script, this project demonstrates how to transform a computer vision model into a globally accessible, scalable microservice optimized for cloud servers or resource-constrained edge hardware.

🛠️ System Architecture

The pipeline architecture ensures optimal memory management and decoupling of concerns:

  • The Client Layer: Sends a standard multipart/form-data HTTP POST request containing a raw image (.jpg or .png).
  • The Translator Layer (FastAPI): Validates input file streams, handles concurrency, and routes incoming data without requiring frontend systems to understand Python or ML frameworks.
  • The Inference Engine (YOLOv8): The model weights are cached in memory upon container startup to eliminate model-loading latency bottlenecks during subsequent active API calls.
  • The Serialization Layer: Raw tensor outputs and boundary coordinates are parsed into a clean, standard JSON payload format.

🚀 Key Production Optimization Features

  • Memory-Efficient Architecture: The YOLOv8 model is loaded exactly once into memory when the application initializes. It remains cached to ensure sub-second inference latency, preventing memory leaks caused by reloading the network on every API call.
  • Streamlined Layered Docker Blueprint: Developed utilizing a python:3.10-slim base image. Unnecessary build caches are cleared out during setup, and specific system dependencies required for OpenCV (ffmpeg, libsm6, libxext6) are explicitly targeted to optimize the final container footprint.
  • Framework Agnostic Data Pipeline: The backend accepts raw binary images natively, processes them using PIL memory buffers, and outputs structured, standard JSON boundaries (bbox). This makes the service immediately compatible with any modern frontend framework, mobile app, or IoT device.

📂 Project Directory Structure

yolo-fastapi-docker/
│
├── app/
│   ├── __init__.py
│   ├── main.py          # FastAPI application routing & validation logic
│   └── model_utils.py   # YOLOv8 cache loading and tensor parsing logic
│
├── Dockerfile           # Minimal, layered container configuration
├── requirements.txt     # Python production-level dependencies
└── README.md            # System deployment guide

💻 Quick Start & Deployment

  • Local Development Setup If you want to test and run the pipeline locally outside of a container:

Install dependencies:

pip install -r requirements.txt

Spin up the Uvicorn live server:

uvicorn app.main:app --reload

Verify Health Check: Open http://127.0.0.1:8000/ in your browser.

*Docker Production Deployment To containerize and isolate the application to deploy reliably on any remote cloud machine or edge gateway:

Build the optimized Docker Image:

docker build -t yolo-fastapi-app .

Run the containerized microservice:

docker run -d --name vision-container -p 8000:8000 yolo-fastapi-app

📊 API Specification & Testing Sandbox

FastAPI automatically provisions an interactive Swagger UI documentation platform. Navigate to http://localhost:8000/docs to test live inference seamlessly.

Endpoint: POST /predict

Input Format: multipart/form-data containing an image file.

JSON Output Response

JSON
{
  "filename": "test_image.jpg",
  "detections": [
    {
      "class": "bus",
      "confidence": 0.87,
      "bbox": [22.9, 231.3, 805.0, 756.8]
    },
    {
      "class": "person",
      "confidence": 0.87,
      "bbox": [48.6, 398.6, 245.3, 902.7]
    },
    {
      "class": "person",
      "confidence": 0.85,
      "bbox": [669.5, 392.2, 809.7, 877.0]
    },
    {
      "class": "person",
      "confidence": 0.83,
      "bbox": [221.5, 405.8, 345.0, 857.5]
    },
    {
      "class": "person",
      "confidence": 0.26,
      "bbox": [0.0, 550.5, 63.0, 873.4]
    },
    {
      "class": "stop sign",
      "confidence": 0.26,
      "bbox": [0.1, 254.5, 32.6, 324.9]
    }
  ]
}