Forem: Lewis Munyi

Fun with Avatars: Containerize the app for deployment & distribution | Part. 2

Lewis Munyi — Sat, 20 Jan 2024 22:29:13 +0000

Introduction

This article series is structured into four parts:

Part 1: Creating the project, establishing the API, and developing the avatar generation module.
Part 2: Focuses on containerizing the application for deployment.
Part 3: Delves into optimizing the service for cost-effectiveness.
Part 4: Explores the integration of the service into real-life projects.

In Part 1, we successfully set up our app and established an API using FastAPI that generates avatars based on user prompts. Now, in this article, we'll focus on packaging the app into a Docker container for deployment.

You can find the code for this app here.

Docker, containerization & virtualization
- Understanding containerization
- Understanding docker components
Project Setup
- Project structure and dependencies
Understanding the Dockerfile
- Advantages of using Dockerfiles
- Components of a Dockerfile
- Create the Dockerfile
- Optimizing the Dockerfile
Build the docker images
- Build for deployment
- Running the image as a container
- Testing the service
- Build for development
- Understanding Docker Volumes
- Testing the dev service
Publishing to Docker Hub
Conclusion

Docker, containerization & virtualization

Understanding containerization

Containerization is a lightweight form of virtualization that allows you to package and run applications and their dependencies in isolated environments called containers. Containers encapsulate an application and its dependencies, including libraries, runtime, and system tools, ensuring that the application runs consistently across different computing environments.

The key components of containerization include:

Container Engine: A runtime that executes and manages containers. Docker and containerd are popular container engines.
Container Images: Lightweight, standalone, and executable packages that include everything needed to run a piece of software, including the code, runtime, libraries, and system tools.
Container Orchestration tools: These are used to automate the deployment, scaling, monitoring, and management of containerized applications. These tools simplify the complexities of managing and coordinating containers across a cluster of machines. They include Kubernetes, Docker Swarm, Amazon ECS, Microsoft AKS, Google Kubernetes Engine (GKE), etc.

Containerization provides the following advantages:

Portability: Containers encapsulate the application and its dependencies, making it easy to move and run the same containerized application across different environments, such as development, testing, and production.
Consistency: Containers ensure consistency across different environments, reducing the "it works on my machine" problem. Since the environment is encapsulated, you can be confident that the application will behave the same way everywhere.
Isolation: Containers provide process and file system isolation, allowing multiple containers to run on the same host without interfering with each other. This isolation improves security and helps prevent conflicts between different applications.
Resource Efficiency: Containers share the host operating system's kernel, which reduces the overhead compared to traditional virtualization. This results in faster startup times and better utilization of system resources.
Scalability: Containers are designed to be lightweight and can be quickly scaled up or down to meet varying workloads. Container orchestration tools like Kubernetes facilitate the management and scaling of containerized applications.
Versioning and Rollback: Container images can be versioned, making it easy to roll back to a previous version if a new release introduces issues. This is particularly useful for maintaining and updating applications.
DevOps and Continuous Integration/Continuous Deployment (CI/CD): They enable developers to package applications and their dependencies, ensuring consistent deployment across different development lifecycle stages.

We will be using docker to containerize and run the app. Get docker up and running on your OS by following this tutorial.

At this point, we will assume that you have docker all set up and the docker daemon up and running.

Understanding docker components

By understanding these basic Docker components and installing Docker on your OS, you will be ready to containerize and deploy your apps.

Docker Engine : Docker Engine is the core runtime that runs and manages Docker containers. It is responsible for building, running, and managing containers on a host machine. Docker Engine includes several components such as:

Docker Daemon: The Docker Daemon is a background service that runs on the host machine and manages the lifecycle of containers. It listens to the Docker API requests and handles container operations such as starting, stopping, and monitoring containers.
Containerd: A lightweight container runtime that manages low-level container operations, including image handling, container execution, and storage.
Docker CLI: The Docker Command Line Interface (CLI) is a command-line tool used to interact with Docker. It provides a set of commands to manage Docker images, containers, networks, volumes, and other Docker resources.
Docker Images: A Docker image is a read-only template that contains all the dependencies, configuration, and code required to run a Docker container. Images are built using a Dockerfile , which defines the instructions to create the image. Images are stored in a registry , such as Docker Hub or a private registry, and can be pulled and run on any Docker-compatible system.
Docker Containers: A Docker container is a running instance of a Docker image. Containers are isolated environments that encapsulate the application and its dependencies, ensuring consistent behaviour across different environments. Each container runs as an isolated process and has its own filesystem, networking, and process space.
Docker Registry: A Docker registry is a repository that stores Docker images such as Docker Hub. You can also set up private registries to store your custom Docker images securely on the main cloud service providers such as Google Cloud Container Registry, Azure Container registry

Project Setup

Project structure and dependencies

The project so far contains a FastAPI application built on macOS with Uvicorn ASGI server serving the app. The project structure so far looks like this:

.
├── LICENSE
├── README.md
├── README.rst
├── avatars_as_a_service
│   ├── __init__.py
│   └── serializers
│       ├── Avatar.py
│       ├── AvatarFeatures.py
├── main.py
├── poetry.lock
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_avatars_as_a_service.py

[Optional] If you did not use poetry to manage your packages, choosing to use PIP instead, you will have to create a requirements.txt file at the root of the project that will contain all the needed Python packages for the project by running:

pip freeze > requirements.txt

If you used poetry, the poetry.lock file contains all the required packages for us to install.

Understanding the Dockerfile

A Dockerfile is a script used to build a Docker image. Docker images are the executable packages that contain everything needed to run a piece of software, including the code, runtime, libraries, and system tools. The Dockerfile provides a set of instructions for building a Docker image in a consistent and reproducible manner.

Advantages of using Dockerfiles

Some advantages of using Dockerfiles are:

Reproducibility: Dockerfiles provide a clear, script-like representation of the steps required to build a Docker image. This ensures that the image can be reproduced consistently across different environments and by different team members. It helps eliminate the "it works on my machine" problem.
Versioning and History: Dockerfiles are typically stored alongside the source code in version control systems. This allows for versioning of both the application code and its corresponding Dockerfile, making it easy to track changes over time. Docker images also have a layered structure, and each instruction in the Dockerfile contributes to a layer. This layering system enables efficient caching during the build process and provides a clear history of image changes.
Modularity: Dockerfiles support a modular approach to building images. Each instruction in the Dockerfile creates a separate layer, and layers can be reused in other images. This promotes code reuse and helps manage dependencies efficiently.
Automated Builds: Dockerfiles enable automated and scripted builds of Docker images. Continuous Integration (CI) tools can be configured to monitor changes in the source code repository and trigger automated builds whenever updates are pushed. This ensures that the Docker image is always up to date with the latest version of the application.
Consistency: Dockerfiles allow developers and operations teams to define the entire configuration of an application, including dependencies and environment settings, in a single file. This consistency ensures that the application behaves the same way in different environments, such as development, testing, and production.
Collaboration: Dockerfiles are shared configuration files that can be easily shared among team members. This promotes collaboration by providing a standardized way to describe the application's environment and dependencies.
Efficient Image Size: Dockerfiles allow you to optimize the size of the resulting Docker image. By carefully crafting the instructions in the Dockerfile, you can minimize the number of layers and reduce the overall size of the image. This is important for efficient storage, faster image downloads, and quicker container startup times.
Integration with CI/CD: Dockerfiles integrate seamlessly with Continuous Integration and Continuous Deployment (CI/CD) pipelines. CI/CD systems can use Dockerfiles to build, test, and deploy containerized applications automatically.

Components of a Dockerfile

The components of a Dockerfile include:

Base Image: A Dockerfile typically starts with specifying a base image. The base image is an existing image from the Docker Hub or another registry that serves as the starting point for building your custom image. It may include an operating system, runtime, and other dependencies.
Instructions: Dockerfiles consist of a series of instructions that are executed to build the image layer by layer. Some common instructions include:
- RUN: Executes a command in the image.
- COPY and ADD: Copy files from the local file system into the image.
- WORKDIR: Sets the working directory for subsequent instructions.
- ENV: Sets environment variables.
- EXPOSE: Informs Docker that the container will listen on specified network ports at runtime.
- CMD: Provides a default command to run when the container starts.
- LABEL: Adds metadata to an image
Layers: Each instruction in a Dockerfile creates a new layer in the image. Layers are cached, and Docker uses a layered file system to optimize the image-building process. This allows for faster builds and reduces the size of incremental changes.

Create the Dockerfile

Create a file called Dockerfile and paste the following code into it:

# Python base image
FROM python:3.10

LABEL maintainer="Lewis Munyi"

LABEL environment="production"

# https://stackoverflow.com/questions/59812009/what-is-the-use-of-pythonunbuffered-in-docker-file
ENV PYTHONUNBUFFERED=1
ENV POETRY_VERSION=1.7.1

# Set the working directory inside the container
WORKDIR /api

# Copy the application code to the working directory
COPY . .

# Uncomment the following lines if you are using Pip not poetry
# Install the Python dependencies
#RUN pip install -r requirements.txt

# Install poetry & packages
RUN curl -sSL https://install.python-poetry.org | python3 -

# Update path for poetry
ENV PATH="${PATH}:/root/.local/bin"

# https://python-poetry.org/docs/configuration/#virtualenvscreate
RUN poetry config virtualenvs.create false
RUN poetry install --no-root --no-interaction


# Expose the port on which the application will run
EXPOSE 8000

# Run the FastAPI application using uvicorn server
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Next, we need to ignore the .env file because we do not want to ship our API keys with the docker image that will be created.

Create a .dockerignore file at the root of the project and add the following code to it:

# Ignore .env file
.env

# Ignore logs directory
logs/

# Ignore the git and cache folders
.git
.cache

# Ignore all markdown and class files
*.md
**/*.class

Optimizing the Dockerfile

Use a minimal base image: Choosing a slim or lightweight base image, like python:3.10-slim, helps reduce the size of the resulting Docker image.
Use a specific version of the base image such as python:3.10 and not python:latest as the latter is non-deterministic and could end up introducing breaking changes once the base image is updated to a different version.
Leverage layer caching: Place the instructions that are least likely to change, such as copying the requirements and installing dependencies, earlier in the Dockerfile. This allows Docker to cache the layers and speeds up subsequent builds.
Use .dockerignore: Create a .dockerignore file in the project directory to specify files and directories that should not be copied into the Docker image. This helps minimize the size of the image and improves build performance.
Avoid running unnecessary commands: Minimize the number of RUN instructions in the Dockerfile to avoid unnecessary layer creation. Combining multiple commands using && or RUN ["command1 && command2"] helps reduce the number of layers.
Clean up after installations: Remove unnecessary files or cleanup commands (apt-get clean or poetry cache clear --all . or pip cache purge) after installing dependencies to minimize the size of the final image.
Use multi-stage builds (optional): If there are build dependencies that are only required during the build process and not in the final image, you can use multi-stage builds to separate the build environment from the runtime environment. This helps reduce the size of the final image.

Build the docker images

Build for deployment

Run the following command to create an image from the Dockerfile:

docker build -t avatars-as-a-service:1.0 .

The build command tells docker that we are about to create a docker image from a Dockerfile
-t avatars-as-a-service:1.0 is the tag name and version (1.0) that will be assigned to our image.
The . points to the directory in which to find the Dockerfile.

After building the image you will see it when you run docker images on the console:

Running the image as a container

You can run the image by running the following commands in your bash console:

> OPENAI_API_KEY=<your-openai-api-key>
> docker run -p 8000:8000 -e OPENAI_API_KEY -d avatars-as-a-service:1.0

OPENAI_API_KEY=<...>: Sets the OpenAI API key as an environment variable
run: tells docker that we want to spin up a container instance from an image
-p 8000:8000: -p is short for --port and it says that we're mapping port 8080 on the local computer to port 8000 on the virtual OS
-e OPENAI_API_KEY: tells docker that we're about to pass some environment variables to the virtual OS on start. Running the command without this line results in the following error:

2023-12-27 03:54:10 The api_key client option must be set either by passing api_key to the client or by setting the OPENAI_API_KEY environment variable

2023-12-27 03:54:10 INFO: 192.168.65.1:42202 - "POST /query HTTP/1.1" 200 OK
-d: Tells docker to run it as a daemon (background service) so it doesn't terminate when we exit the shell
avatars-as-a-service:1.0: The repository and tag (1.0) name of the image that we want to run

We can check if the container is up and running by running:

docker ps

Our container is up and running. Yay! 🎊

Testing the service

Navigate to http://127.0.0.1:8000/docs and you'll see the now familiar swagger API docs page. Sending requests to the API returns correct responses. This shows that the docker service is up and running. Yay! 🎊

Build for development

So far we have successfully containerized the application and run it as a container. However, a drawback has surfaced every time we make changes to project files, we must rebuild the image and recreate the container. While this is manageable for minor adjustments, it could impede active development. To overcome this hurdle, we'll leverage a tool known as Docker Volumes.

Understanding Docker Volumes

Docker volumes offer a solution for persisting and managing data generated by Docker containers. These volumes, represented as directories or filesystems, exist outside the container filesystem but can be mounted into one or more containers. They enable data sharing between containers, ensuring persistence even when containers are removed.

Key Aspects of Docker Volumes:

Data Persistence: Volumes serve as the preferred method for persisting data generated by containers. Using volumes ensures that data remains intact even if the associated container is removed or replaced. This proves particularly valuable for databases, file uploads, log files, and other data types requiring survival across container lifecycle changes.
Sharing Data Between Containers: Volumes can be shared among multiple containers, facilitating access and modification of the same set of data. This promotes communication and collaboration among containers in a multi-container application.
Volume Types:
- Named Volumes: Assigned specific names during creation or container runtime, these volumes are easily managed and shareable among multiple containers.
- Anonymous Volumes: Unnamed volumes automatically receive unique identifiers and are typically utilized for temporary or disposable data.
- Host Bind Mounts: Docker allows mounting a directory directly from the host system into a container, known as a host bind mount and is specified with the -v option.

Implementation

In our project, we will introduce two key changes:

Creation of a new Docker image for development labelled with the dev tag.
Utilization of host bind mount Docker volumes to link the local development directory with the working directory in the virtual OS.

To implement these changes, create a file named development.dockerfile in the root of the directory and paste the below code into it.

# Python base image
FROM python:3.10

LABEL maintainer="Lewis Munyi"

LABEL environment="dev"

# https://stackoverflow.com/questions/59812009/what-is-the-use-of-pythonunbuffered-in-docker-file
ENV PYTHONUNBUFFERED=1
ENV POETRY_VERSION=1.7.1

# Set the working directory inside the container
WORKDIR /api

# Copy the application code to the working directory
COPY . .

# Uncomment the following lines if you are using Pip not poetry
# Copy the requirements file to the working directory
#COPY requirements.txt .

# Install the Python dependencies
#RUN pip install -r requirements.txt

# Install poetry & packages
RUN curl -sSL https://install.python-poetry.org | python3 -

# Update path for poetry
ENV PATH="${PATH}:/root/.local/bin"

# https://python-poetry.org/docs/configuration/#virtualenvscreate
RUN poetry config virtualenvs.create false
RUN poetry install --no-root --no-interaction

# Expose the port on which the application will run
EXPOSE 8000

# Run the FastAPI application using uvicorn server
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

We have added the --reload flag to instruct uvicorn to reload the server on file changes.

Rebuild the image by running

docker build -t avatars-as-a-service:dev -f development.Dockerfile .

A new image will appear with the dev tag

Run the docker container with a mounted volume

docker run -p 8000:8000 -e OPENAI_API_KEY -v .:/api/ avatars-as-a-service:dev

-v .:/api/: This creates a hosted volume that maps the project's root (.) directory to the VM's working directory /api/

Testing the dev service

The server will now reload on any changes

Publishing to Docker Hub

Follow the following tutorial to publish the image on Docker Hub. It will be available for download freely thereafter.

Conclusion

That brings us to the end of this article. We have done a deep dive into containers and docker and have packaged the app for deployment and distribution. The code to this repository can be found freely on my GitHub.

As you may have already noticed, the app must make a new request to OpenAI for each request for an avatar that it receives. This is inefficient and could easily rack up API costs as it scales. We need to find a way to optimize the avatar load times and more importantly, the cost effectiveness. We'll dive into that in Part 3.

Cheers!

lewis-munyi / avatars-as-a-service

A fun approach to generating avatars using AI

Avatars as a Service

A fun approach to generating avatars using AI

This is the accompanying code for the Avatars as a Service series on Hashnode

View on GitHub

Fun with Avatars: Crafting the core engine | Part. 1

Lewis Munyi — Sat, 20 Jan 2024 22:07:27 +0000

Introduction
Pre-requisites
Project Design
Create project
Understanding FastAPI
Create Serializers
Create web routes
App testing
Conclusion

Introduction

In this article series, I will walk you through the development of a service that generates random avatars using cutting-edge AI technology. The service will take specific features and parameters as input and, based on these attributes, deliver a unique avatar to the user. Notably, this project is open source, and available on GitHub. Feel free to fork it, contribute, and enhance its capabilities.

lewis-munyi / avatars-as-a-service

A fun approach to generating avatars using AI

Avatars as a Service

A fun approach to generating avatars using AI

This is the accompanying code for the Avatars as a Service series on Hashnode

View on GitHub

We'll leverage Python's simplicity for accessibility, with potential future translations for broader reach.

Pre-requisites

We will be running this project in Python 3.10 on Mac/Linux, and we will use Poetry to manage our dependencies. Later, we will bundle our app into a container using docker for deployment.

Before diving into the project, ensure you have the following set up:

Python 3.10 installed on Mac/Linux/Windows. Follow these instructions to set it up on your OS.
Poetry installed for managing dependencies. Refer to this article for installation instructions.

Project Design

This is a simple overview of what the full project entails:

This project will be broken down into 4 parts:

Part 1: Creating the project, establishing the API, and developing the avatar generation module.
Part 2: Focuses on containerizing the application for deployment.
Part 3: Delves into optimizing the service for cost-effectiveness.
Part 4: Explores the integration of the service into real-life projects.

Create project

Open your terminal and run the following command to create our working folder and navigate to it.

poetry new avatars-as-a-service && cd avatars-as-a-service

That will create a directory avatars-as-a-service with the necessary files.

.
├── LICENSE
├── README.md
└── avatars-as-a-service
    ├── README.rst
    ├── avatars_as_a_service
    │   └── __init__.py
    ├── pyproject.toml
    └── tests
        ├── __init__.py
        └── test_avatars_as_a_service.py

Optionally, initialize a git repository for version tracking. This will create a .git folder in our project if there is none already.

git init

Start a shell session in our virtual environment by running:

poetry shell

Understanding FastAPI

We will create our API using FastAPI, a modern high-performance web framework for building fast APIs with Python. It is designed to be easy to use, efficient, and highly scalable. Some key features of FastAPI include:

Speed: FastAPI is built on Starlette, an asynchronous web framework, allowing it to handle high loads with incredible speed and efficiency. It is really fast.
Type Annotations: FastAPI utilizes Pythons type hinting system to provide automatic request/response validation, resulting in enhanced reliability and fewer bugs.
API Documentation: FastAPI generates interactive documentation with Swagger UI and ReDoc, making exploring and understanding API endpoints effortless.
Security: FastAPI supports various authentication methods, including OAuth2, API key validation, and JWT tokens, enabling secure API development.
Asynchronous Support: FastAPI is designed to take advantage of Python's async and await syntax, enabling efficient handling of I/O-bound operations.

FastAPI uses Uvicorn, an ASGI (Asynchronous Server Gateway Interface) web server implementation for Python.

Install them and other required dependencies by running:

poetry add fastapi 'uvicorn[standard]'

Next, create a main.py file at the root of our project with the following code.

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World!"}

Start the Uvicorn server by running:

uvicorn main:app --reload

Thereload flag ensures that our server reloads on any changes.

Once the server is up navigate to the address http://127.0.0.1:8000 to see the following JSON response.

{"message": "Hello World!"}

Visit http://127.0.0.1:8000/docs for the Swagger-powered API documentation. We will also use it to interact with our API.

Create Serializers

The Avatar properties will be a set of pre-selected choices that will be easier to work with. Let us go ahead and create the file to hold the Enums we are going to need. In ./avatars_as_a_service/serializers/ create a file called AvatarFeatures.py

mkdir ./avatars_as_a_service/serializers/ && touch ./avatars_as_a_service/serializers/AvatarFeatures.py

Add the following code to it:

from enum import Enum

# Will be used to specify whether to create a cartoon-y avatar or something less fun :/
class Mood(Enum):
    FUN = "fun"
    OFFICIAL = "official"

class HeadShape(Enum):
    OVAL = 'oval'
    ROUND = 'round'
    SQUARE = 'square'
    HEART = 'heart'
    TRIANGULAR = 'triangular'

class SkinTone(Enum):
    FAIR = 'fair'
    MEDIUM = 'medium'
    DARK = 'dark'

class SmileType(Enum):
    WIDE = 'wide'
    FULL = 'full'
    CLOSED_LIP = 'closed-lip'
    OPEN_LIP = 'open-lip'
    TEETH_BARING = 'teeth-baring'
    SMIRK = 'smirk'

class NoseType(Enum):
    STRAIGHT = 'straight'
    ROMAN = 'roman'
    BUTTON = 'button'
    SNUB = 'snub'
    WIDE = 'wide'
    NARROW = 'narrow'

class EyeColor(Enum):
    BROWN = 'brown'
    BLUE = 'blue'
    AMBER = 'amber'
    HAZEL = 'hazel'
    GREEN = 'green'
    GREY = 'grey'

Next, Create the Avatar Serializer. This file will hold the Avatar properties, Request, Response and other classes.

touch ./avatars_as_a_service/serializers/Avatar.py

Add the following code to it:

import os

from pydantic import BaseModel
from typing import Union
from openai import OpenAI
from dotenv import load_dotenv

from app.serializers.AvatarFeatures import Mood, HeadShape, EyeColor, SkinTone, SmileType, NoseType

load_dotenv()

class Avatar(BaseModel):
    skin_tone: Union[SkinTone, None]
    head_shape: Union[HeadShape, None] = None
    eye_color: Union[EyeColor, None] = None
    smile_type: Union[SmileType, None] = None
    nose_type: Union[NoseType, None] = None
    glasses: Union[bool, None] = False
    mood: Union[Mood, None] = Mood.FUN
    description: Union[str, None] = None

    # Method used to generate a prompt string from the various properties supplied
    def generate_prompt(self) -> str:
        if self.description and self.description != '':  # If a description is provided then it will override the other Avatar properties
            return self.description

        prompt = 'create an avatar for a person with the following description: '

        if self.skin_tone:
            prompt += f'{self.skin_tone.value} skin color/complexion, '

        if self.head_shape:
            prompt += f'a {self.head_shape.value} head, '

        if self.eye_color:
            prompt += f'{self.eye_color.value} eyes, '

        if self.smile_type:
            prompt += f'a {self.smile_type.value} smile, '

        if self.nose_type:
            prompt += f'a {self.nose_type.value} nose, '

        if self.glasses:
            prompt += f'and with a pair of glasses, '

        if self.mood:
            if self.mood.value == 'fun':
                prompt += f'and make it fun and/or cartoon-y.'
            else:
                prompt += f'and make it official and/or office appropriate.'

        return prompt

    def dall_e_2_search(self):
        try:
            client = OpenAI(api_key=os.getenv('OPENAI_API_KEY'), )
            response = client.images.generate(
                model="dall-e-2",
                prompt=self.generate_prompt(),
                size="256x256",
                quality="standard",
                n=1,
            )

            res = AvatarResult()
            res.image_url = response.data[0].url
            return res

        except Exception as e:
            print(str(e))

class AvatarResult(BaseModel):
    image_url: str = None

class AvatarRequest(BaseModel):
    properties: Avatar

class AvatarResponse(BaseModel):
    data: AvatarResult = None
    prompt: str = None

We will be using Dall-E 2 to generate our avatars. Don't forget to grab an OpenAI API key and paste it into your .env file at the root (/) of your project by running the below command:

echo "OPENAI_API_KEY=<paste-api-key-here>" > .env

Install OpenAI's Python library by running:

poetry add openai

Create web routes

We're now ready to create our first web route. Open the main.py file and paste the following code:

from fastapi import FastAPI
from avatars_as_a_service.serializers.Avatar import AvatarRequest, AvatarResponse

app = FastAPI()

@app.post("/query")
def search(req: AvatarRequest) -> AvatarResponse:
    avatar = req.properties

    res = AvatarResponse()
    res.data = avatar.dall_e_2_search()  # Get OpenAi Payload Image URL
    res.prompt = avatar.generate_prompt()

    return res

The route above takes an AvatarRequest object and returns an AvatarResponse object. The AvatarRequest object takes in the following parameters:

// AvatarRequest
{
  "properties": {
    "skin_tone": "",
    "head_shape": "",
    "eye_color": "",
    "smile_type": "",
    "nose_type": "",
    "glasses": bool,
    "mood": "",
    "description": "" // Optional
  }
}

The AvatarResponse object returns the following:

// AvatarResponse
{
  "data": {
    "image_url": "string" // Our avatar
  },
  "prompt": "string" // The prompt that was sent to OpenAI
}

App testing

Once that's done our app is ready for testing. Head to our API docs and click 'Try it out' to customize the query object.

The description we've entered overrides all the selected(default) avatar properties. This is the image generated for the prompt(description) spongebob laughing

But that's not quite the type of avatar we want. Let's build one with the correct properties.

The above query does run correctly, and it returns an AI-generated avatar. Yay! 🎉

Conclusion

We've finally reached the end of Part 1. Our app creates fun avatars based on several features provided. In Part 2, we will package the app to run on docker containers for easy deployment and distribution.

Cheers!

Fun with Avatars: Optimizing the service for cost-effectiveness | Part. 3

Lewis Munyi — Tue, 16 Jan 2024 22:56:20 +0000

This article series is split into four parts:

Part 1: Involves creating the project, establishing the API, and developing the avatar generation module.
Part 2: Focuses on containerizing the application for development and deployment.
Part 3: Delves into optimizing the service for cost-effectiveness.
Part 4: Explores the integration of the service into real-life projects.

Intro
Optimizing the service
- Project Re-organization
- Database design
- Enhanced Database Design
Create Database
- Install python dependencies
- Create connection file
Create SQL Alchemy models
Hashing methods and properties
Update Request/Response classes
Create search methods
- Write to cache function
- Search DALL-E function
- Search Cache function
- Main search function
Update the main route file
App testing
Conclusion

Intro

In Part 1 of this series, we established the API and avatar generation module. During this phase, we configured our application to utilize FastAPI, enabling the API to produce avatars based on supplied prompts. While this addressed the immediate need, it introduced a subsequent challenge. With each incoming request, our API initiated a new request to OpenAI's DALL-E service. Given that this service is not free, our approach proved cost-ineffective, especially in scenarios where users might share similar facial features, leading to redundant requests.

In this article, our focus shifts to implementing a caching mechanism for previous requests. This enhancement aims to prevent redundant calls to DALL-E by storing and reusing previous responses. If the API identifies an existing request, it retrieves and returns the cached response; otherwise, it initiates a request to DALL-E, captures the response, and caches it for future optimization. The following image provides an overview of the implementation covered in this article.

Optimizing the service

Project Re-organization

To make this project more reader-friendly We will reorganize it before making any changes.

Start by renaming the avatars_as_a_service/serializers/Avatar.py file to avatars_as_a_service/serializers/schemas.py and move it to the avatars_as_a_service/ directory. Run the following:

cp avatars_as_a_service/serializers/Avatar.py avatars_as_a_service/schemas.py && rm -r avatars_as_a_service/serializers/

Create an enums directory in avatars_as_a_service/ and move the avatars_as_a_service/serializers/AvatarFeatures.py to it.

mkdir avatars_as_a_service/enums && cp avatars_as_a_service/serializers/AvatarFeatures.py avatars_as_a_service/enums/

Delete the avatars_as_a_service/serializers/ directory

rm -r avatars_as_a_service/serializers

Update the main.py file imports

from fastapi import FastAPI
from avatars_as_a_service.schemas import AvatarRequest, AvatarResponse

Update the schemas.py imports:

from fastapi import FastAPI
from avatars_as_a_service.schemas import AvatarRequest, AvatarResponse

The project directory should look like this:

.
├── Dockerfile
├── LICENSE
├── README.md
├── README.rst
├── avatars_as_a_service
│   ├── __init__.py
│   ├── enums
│   │   └── AvatarFeatures.py
│   └── schemas.py
├── development.Dockerfile
├── main.py
├── poetry.lock
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_avatars_as_a_service.py

Database design

The primary avatars table will encompass all user-selected features and the images retrieved from DALL-E. Its structure will resemble the following:

While the current table serves its purpose adequately, there is room for further optimization.

Let's calculate the combinations of our AvatarFeatures to estimate the number of rows expected in our table:

Mood: 2 options (FUN or OFFICIAL)

HeadShape: 5 options (OVAL, ROUND, SQUARE, HEART, TRIANGULAR)

SkinTone: 3 options (FAIR, MEDIUM, DARK)

SmileType: 6 options (WIDE, FULL, CLOSED_LIP, OPEN_LIP, TEETH_BARING, SMIRK)

NoseType: 6 options (STRAIGHT, ROMAN, BUTTON, SNUB, WIDE, NARROW)

EyeColor: 6 options (BROWN, BLUE, AMBER, HAZEL, GREEN, GREY)

Therefore, we can have 5400 (2 x 5 x 3 x 6 x 6 x 6) combinations for the provided features, resulting in a maximum of 5400 rows.

Data type space consumption for SQL:

INT: 4 bytes

VARCHAR: Length of the stored data + 2 bytes = 12 + 2 = 14 bytes

TIMESTAMP: 8 bytes

TEXT: Length of the stored data + 2 bytes = 500 (average) + 2 = 502 bytes

In our current design, a single row consumes (4 bytes 1) + (14 bytes 7) + (8 bytes 1) + (502 bytes 1) = 612 bytes. The entire table will be roughly 612 bytes 5400 rows = 3,304,800 bytes (approximately 3225 KB or 3.15 MB).

Enhanced Database Design

We could further optimize this design by hashing the values for the AvatarFeatures class and storing the unique hash string representing the features against the image URL. This optimization brings several benefits, including:

Reduced query times due to a smaller dataset
Flexibility to increase features in the Avatar class without modifying the avatars table structure

The final design will take this form:

This refined design will only consume (4 1) + (14 1) + (8 1) + (502 1) = 528 bytes per row , totalling 528 bytes 5400 rows = 2,851,200 bytes (2782 KB or 2.718 MB) across the entire table. This represents a 13.7% improvement , with further enhancements expected as the number of features increases.

For this article, I will employ an SQLite database hosted within the container to cache our images. You can seamlessly replace the database connection string with a custom one suitable for PostgreSQL, MySQL, SQLite, Oracle, etc. This flexibility arises from two key considerations:

Size Efficiency: Our bundled SQLite database imposes minimal impact on container size (4MB max).
User Flexibility: Users can provide database connection strings for their external custom databases.

Create Database

Install python dependencies

Don't forget to install SQLAlchemy and other needed dependencies

poetry add sqlalchemy pymysql cryptography psycopg2

Create connection file

Create a file named connection.py in a avatars_as_a_service/database/ directory.

mkdir avatars_as_a_service/database && touch avatars_as_a_service/database/connection.py

Add the following code to it

import os

from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker, Session

if db_string := os.getenv('DB_STRING'):
    if 'sqlite' in db_string:
        engine = create_engine(db_string, connect_args={"check_same_thread": False})
    else:
        engine = create_engine(db_string)
else:  # Default to sqlite if there is no DB string supplied
    db_string = "sqlite:///./avatars_as_a_service/database/fun-avatars.sqlite.db"
    engine = create_engine(db_string, connect_args={"check_same_thread": False})

SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

Base = declarative_base()


async def init_db():  # checkfirst option to make sure that tables are only created if they don't exist
    Base.metadata.create_all(bind=engine, checkfirst=True)


def get_db() -> Session:
    db: Session = SessionLocal()
    try:
        yield db
    finally:
        db.close()

The code above will check for a DB_STRING environment variable on app startup. If found it will attempt to connect to the supplied DB URL. It will create a default SQLite db if no DB_STRING is found.

The init_db() function will attempt to create the avatar table with its appropriate columns if no table is found so ensure that the database user provided has table creation rights, or that the table exists beforehand.

The get_db() function will yield an initialized database session

Create SQL Alchemy models

Create a avatars_as_a_service/models.py file with the following code:

from datetime import datetime
from sqlalchemy import Integer, DateTime, Column, String, Text
from sqlalchemy.orm import DeclarativeBase, mapped_column, Mapped
from sqlalchemy.ext.declarative import declarative_base

from avatars_as_a_service.database.connection import Base


class Avatar(Base):
    __tablename__ = "avatar"

    id = Column(Integer, primary_key=True, autoincrement=True, index=True)
    created_at = Column(DateTime, default=datetime.now(), nullable=False)
    image_hash = Column(String(30), nullable=False)
    image_url = Column(Text, nullable=False)

Hashing methods and properties

Create the hashing method of the Avatar schema

def hash_avatar(self) -> str:
    if self.description:
        return ''

    features = f'{self.head_shape}+{self.eye_color}+{self.skin_tone}+{self.glasses}+{self.smile_type}+{self.nose_type}+{self.mood}'
    return str(hash(features))

Update the AvatarResult schema to include the image_hash field

class AvatarResult(BaseModel):
    image_hash: str = None
    image_url: str = None

Update the dall_e_search() method of the Avatar schema to populate the hash field:

        def dall_e_search(self):
        try:
            client = OpenAI(api_key=os.getenv('OPENAI_API_KEY'), )
            response = client.images.generate(
                model="dall-e-2",
                prompt=self.generate_prompt(),
                size="256x256",
                quality="standard",
                n=1,
            )

            res = AvatarResult()
            res.image_url = response.data[0].url
            res.image_hash = self.hash_avatar()
            return res
        except Exception as e:
            print(str(e))

Update Request/Response classes

In the avatars_as_a_service/schemas.py file update the AvatarRequest class to include the cache flag.

class AvatarRequest(BaseModel):
    properties: Avatar
    disable_cache: bool = False # Default to querying the cache before OpenAI

Add a cache_hit flag to the AvatarResponse schema

class AvatarResponse(BaseModel):
    data: AvatarResult = None
    cache_hit: bool = False # Has the resulkt been returned from the cache
    prompt: str = None

Create search methods

Create a file avatars_as_a_service/search.py file with the following code and functions:

from typing import Any
from sqlalchemy.orm import Session

from avatars_as_a_service.models import Avatar
from avatars_as_a_service.schemas import Avatar as AvatarSchema, AvatarResult, AvatarRequest, AvatarResponse

Write to cache function

# Commit the OpenAI result to the cache
def write_to_cache(result: AvatarResult, db: Session) -> bool:
    try:
        avatar_model = Avatar(**dict(result))
        db.add(avatar_model)
        db.commit()
    except Exception as e:
        raise RuntimeError("An unexpected DB error occurred: " + str(e))

Search DALL-E function

This is the function that will request Dall-e for an avatar given a prompt/features

def search_dall_e(avatar: AvatarSchema, cache=True) -> AvatarResult:
    result = avatar.dall_e_search()

    if avatar.description is not None:  # Directly search for description without caching
        return result

    if cache:
        try:
            write_to_cache(result)
        except:
            print("Unable to cache result")
        pass

    return result

Search Cache function

This function attempts to find a cached Avatar and return it

# Return the query result or None
def search_cache(avatar: AvatarSchema, db: Session, skip: int = 0, limit: int = 100) -> Any:
    return db.query(Avatar).filter(Avatar.image_hash == avatar.hash_avatar()).first()

Main search function

This function takes an AvatarRequest object and returns a AvatarResponse object.

def avatar_search(request: AvatarRequest, db: Session) -> AvatarResponse:
    search_result: AvatarResult
    cache_hit: bool = False
    prompt: str = request.properties.generate_prompt()

    if request.disable_cache:  # Search dall-e and don't cache the result
        search_result: AvatarResult = search_dall_e(avatar=request.properties, db=db, cache=False)

    else:  # Search cache
        query_result = search_cache(avatar=request.properties, db=db)
        if query_result is None:  # Cache miss: Browse image and attempt to cache the result
            search_result: AvatarResult = search_dall_e(avatar=request.properties, db=db, cache=True)
        else:  # Cache hit
            cache_hit: bool = True
            search_result = AvatarResult()
            search_result.image_hash = query_result.image_hash
            search_result.image_url = query_result.image_url

    result = AvatarResponse()
    result.data = search_result
    result.cache_hit = cache_hit
    result.prompt = prompt
    return result

Update the main route file

import os

from fastapi import FastAPI, Depends
from avatars_as_a_service.database.connection import get_db, init_db
from avatars_as_a_service.search import avatar_search
from avatars_as_a_service.schemas import AvatarRequest, AvatarResponse
from sqlalchemy.orm import Session

app = FastAPI()

@app.on_event("startup")
async def startup_event():
    await init_db()


@app.post("/query")
def search(req: AvatarRequest, db: Session = Depends(get_db)) -> AvatarResponse:
    return avatar_search(request=req, db=db)

The app directory now looks like this:

.
├── Dockerfile
├── LICENSE
├── README.md
├── README.rst
├── avatars_as_a_service
│   ├── __init__.py
│   ├── database
│   │   └── connection.py
│   ├── enums
│   │   ├── AvatarFeatures.py
│   ├── models.py
│   ├── schemas.py
│   └── search.py
├── development.Dockerfile
├── docker-compose.yml
├── main.py
├── poetry.lock
├── pyproject.toml
└── tests
    ├── __init__.py
    ├── create-testing-database.sql
    └── test_avatars_as_a_service.py

The app request flow goes somewhat like this:

App testing

Make sure to pass a DB_STRING env to your container when starting it up or add it to the .env file if you are running it from docker-compose

export DB_STRING='mysql+pymysql://user:password@host:port/db_name?[params]'
docker run -p 8000:8000 -e OPENAI_API_KEY -e DB_STRING -v .:/api/ avatars-as-a-service:dev

Sending a request with a custom description sends the request directly to OpenAI.

Making a first-time request with the cache flag set to true will cause it to search OpenAI then cache persist the result to the database. Similar subsequent results will not query OpenAI but return the cached result instead. Subsequent requests have much lower response latency.

Requests made with the disable_cache set to true will return results directly from OpenAI.

Conclusion

In conclusion, we delved into the optimization of our Avatars as a Service project by implementing a caching mechanism for previous requests. Recognizing the cost-inefficiency of redundant calls to OpenAI's DALL-E service, we introduced a streamlined approach. This enhancement involves storing and reusing previous responses, significantly reducing the load on external services. The reorganization of the project structure, optimization of the database design, and the implementation of an SQLite database for caching contribute to a more efficient and scalable solution. By incorporating these improvements, we not only enhance the performance of our avatar generation service but also pave the way for future expansions and feature additions. All the code for this project can be found below:

Cheers!

lewis-munyi / avatars-as-a-service

A fun approach to generating avatars using AI

Avatars as a Service

A fun approach to generating avatars using AI

This is the accompanying code for the Avatars as a Service series on Hashnode

View on GitHub

Auto-deploy docker images to Docker Hub using GitHub actions

Lewis Munyi — Fri, 29 Dec 2023 09:00:00 +0000

Introduction
Project Setup
Workflows
- Components of a workflow file
- Workflow: Latest tag
- Workflow: Release tag
Testing
Conclusion

Introduction

This tutorial assumes that you are already familiar with Docker and creating Dockerfiles. If not, see this tutorial from the series Fun with Avatars to get yourself up to speed. It also assumes you have a Dockerfile ready for deployment, and a Docker Hub and Github account set up.

I will be using an existing project to walk you through the process. In Part. 2 of the series, we containerized the app created but we encountered a few problems:

While the image would build successfully, any changes made to the app's files would not reflect in containers until the image was rebuilt and the containers recreated.
- We fixed this problem by having separate dockerfiles for development and production, and by mounting our host drive to the docker VM using docker volumes.
We have to publish any new tags we build to Docker Hub manually. This works fine for a few changes but would quickly disrupt our workflow on active development.
- We will employ Github actions to alleviate this by rebuilding and redeploying the prod image to Docker Hub for every update to our main branch on Github.

Project Setup

The service we are auto-deploying is a FastAPI service for creating avatars. This is the current project structure:

.
├── Dockerfile
├── LICENSE
├── README.md
├── README.rst
├── avatars_as_a_service
│   ├── __init__.py
│   ├── database
│   │   ├── aaas.sqlite.db
│   │   └── connection.py
│   ├── enums
│   │   └── AvatarFeatures.py
│   ├── models.py
│   ├── schemas.py
│   └── search.py
├── development.Dockerfile
├── main.py
├── poetry.lock
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_avatars_as_a_service.py

The Dockerfile:

# Python base image
FROM python:3.10

LABEL maintainer="Lewis Munyi"

LABEL environment="production"

# https://stackoverflow.com/questions/59812009/what-is-the-use-of-pythonunbuffered-in-docker-file
ENV PYTHONUNBUFFERED=1
ENV POETRY_VERSION=1.7.1

# Set the working directory inside the container
WORKDIR /api

# Copy the application code to the working directory
COPY . .

# Uncomment the following lines if you are using Pip not poetry
# Install the Python dependencies
#RUN pip install -r requirements.txt

# Install poetry & packages
RUN curl -sSL https://install.python-poetry.org | python3 -

# Update path for poetry
ENV PATH="${PATH}:/root/.local/bin"

# https://python-poetry.org/docs/configuration/#virtualenvscreate
RUN poetry config virtualenvs.create false
RUN poetry install --no-root --no-interaction

# Create app database
RUN mkdir -p avatars_as_a_service/database
RUN touch avatars_as_a_service/database/aaas.sqlite.db

# Expose the port on which the application will run
EXPOSE 8000

# Run the FastAPI application using uvicorn server
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Workflows

GitHub actions are executed by workflows specified in YAML files. Below are the main components of the file:

Components of a workflow file

The YAML file contains the specifications for running our workflow and building our image. These are some of the components we will be using along with their purpose:

name

This is the name of the workflow. It will be displayed on the Github actions tab

name: Publish latest prod docker image

Specifies the events that trigger the workflow such as a push to a specific branch or a new release. See a list of supported Github events here.

# Configures this workflow to run every time a change is pushed to the branch called `master`.
on:
  push:
    branches: ['master']

jobs

Specifies the job that's running as part of the workflow. You can have many jobs running as part of a workflow such as compiling an app package, deploying it to a registry and also deploying containers to different registries in one workflow.

build-and-push-image:

runs-on

Specifies the OS environment in which the workflow will run eg ubuntu, Debian, etc.

runs-on: ubuntu-latest

steps

Contains a sequence of tasks to be executed as part of the job. The steps will contain a name and the GitHub action it uses to perform an action

Workflow: `Latest` tag

Create a file called publish-latest-to-docker-hub.yml in the directory .github/workflows/:

mkdir -p .github/workflows && touch .github/workflows/publish-latest-to-docker-hub.yml

Add the following code to it:

name: Publish latest prod image

# Configures this workflow to run every time a change is pushed to the branch called `master`.
on:
  push:
    branches: ['master']

jobs:
  build-and-push-image:
    name: Push latest docker image to Docker Hub
    runs-on: ubuntu-latest
    steps:
      - name: Check out the repo
        uses: actions/checkout@v4

      - name: Log in to Docker Hub
        uses: docker/login-action@f4ef78c080cd8ba55a85445d5b36e214a81df20a
        with:
          # Set these on your Github Settings page under repository secrets
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
        with:
          images: my-docker-hub-namespace/my-docker-hub-repository

      - name: Build and push Docker image
        uses: docker/build-push-action@3b5e8027fcad23fda98b2e3ac259d8d67585f671
        with:
          context: .
          file: ./Dockerfile
          push: true
          tags: my-docker-hub-namespace/my-docker-hub-repository:latest
          labels: ${{ steps.meta.outputs.labels }}

Workflow: `Release` tag

Lastly, create a workflow file that will publish specific releases once published:

touch .github/workflows/publish-release-to-docker-hub.yml

Add the following code to it:

name: Publish release to Docker Hub

# Configures this workflow to run every time a release is published.
on:
  release:
    types: [published]

jobs:
  build-and-push-image:
    name: Push docker image to Docker Hub
    runs-on: ubuntu-latest
    steps:
      - name: Check out the repo
        uses: actions/checkout@v4

      - name: Log in to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_HUB_USERNAME }}
          password: ${{ secrets.DOCKER_HUB_PASSWORD }}

      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
        with:
          images: ${{ secrets.DOCKER_HUB_USERNAME }}/avatars-as-a-service

      - name: Set Docker tag
        id: set_tag
        run: echo ::set-output name=tag::$(echo $GITHUB_REF | awk 'BEGIN{FS="/"} {print $3}')

      - name: Build Docker Image
        run: docker build -t ${{ steps.set_tag.outputs.tag }} .

      - name: Tag Docker Image
        run: docker tag ${{ steps.set_tag.outputs.tag }} ${{ secrets.DOCKER_HUB_USERNAME }}/avatars-as-a-service:${{ steps.set_tag.outputs.tag }}

      - name: Push Docker Image
        run: docker push ${{ secrets.DOCKER_HUB_USERNAME }}/avatars-as-a-service:${{ steps.set_tag.outputs.tag }}

Testing

Workflows now publish new versions to Docker Hub automatically when run. Yay! 🎊

Conclusion

That brings us to the end of this article. In the next article, we will learn how to pull and run the service on a web application.

Cheers!

Forem: Lewis Munyi

Fun with Avatars: Containerize the app for deployment & distribution | Part. 2

Introduction

Table of Contents

Docker, containerization & virtualization

Understanding containerization

Understanding docker components

Project Setup

Project structure and dependencies

Understanding the Dockerfile

Advantages of using Dockerfiles

Components of a Dockerfile

Create the Dockerfile

Optimizing the Dockerfile

Build the docker images

Build for deployment

Running the image as a container

Testing the service

Build for development

Understanding Docker Volumes

Testing the dev service

Publishing to Docker Hub

Conclusion

lewis-munyi / avatars-as-a-service

A fun approach to generating avatars using AI

Avatars as a Service

A fun approach to generating avatars using AI

Fun with Avatars: Crafting the core engine | Part. 1

Table of Contents

Introduction

lewis-munyi / avatars-as-a-service

A fun approach to generating avatars using AI

Avatars as a Service

A fun approach to generating avatars using AI

Pre-requisites

Project Design

Create project

Understanding FastAPI

Create Serializers

Create web routes

App testing

Conclusion

Fun with Avatars: Optimizing the service for cost-effectiveness | Part. 3

Table of Contents

Intro

Optimizing the service

Project Re-organization

Database design

Enhanced Database Design

Create Database

Install python dependencies

Create connection file

Create SQL Alchemy models

Hashing methods and properties

Update Request/Response classes

Create search methods

Write to cache function

Search DALL-E function

Search Cache function

Main search function

Update the main route file

App testing

Conclusion

lewis-munyi / avatars-as-a-service

A fun approach to generating avatars using AI

Avatars as a Service

A fun approach to generating avatars using AI

Auto-deploy docker images to Docker Hub using GitHub actions

Table of Contents

Introduction

Project Setup

Workflows

Components of a workflow file

Workflow: Latest tag

Workflow: Release tag

Testing

Conclusion

Workflow: `Latest` tag

Workflow: `Release` tag