Lab 1: Handwritten Digits - FastAPI

8. Lab 1: Handwritten Digits - FastAPI#

In ICE 2 we made a model. Now it’s time to serve it so others can use it!

Objective: one device (the server) expose an API that accepts POST HTTP requests containing an image; the method returns the inferred label of the digit in that image. A second device (the client) makes requests to the server’s API using pre-produced images.

8.1. Collaboration Policy#

This Lab may be done in teams of two.

Large Language Models (such as ChatGPT or Claude) are authorized for clarifying questions and how to do very specific things, but you cannot ask for a large chunk of the program. Furthermore, you must document in your README.md by:

  1. Stating your primary query AND

  2. Providing a link to the entire conversation.

For example, this is ok:

“In a FastAPI POST function how should I accept a PNG image?”

But this is not ok:

“Write a FastAPI app with a POST method that feeds an image into a Keras model.”

Warning

You really, really, need to be careful taking code from LLMs.

A better approach might be “I have this simple FastAPI method, but am new to using the package. Can you help explain and critique it for me?”

8.2. Setup#

You can complete this lab on your Raspberry Pi (recommended) or on a Linux VM of your choice.

  1. Make your own copy of the template repository: USAFA-ECE/ece386-lab1

  2. Add and commit your Keras neural network model for predicting digits into server/digits.keras

  3. Make ten images of handwritten digits (one for each digit) place them into client/img/.

    • You can use Paint or any application you want

    • Pay attention to how many pixels these images should be

    • Try to make them resemble images in the original dataset

    • Save the image with the correct digit as the filename

    • Use PNG format

8.3. Lab#

This lab will require significant self-learning! You’ll absolutely need to spend time reading documentation.

Important

Remember to use type hints on function definitions and global variables!

Server#

For the server you may either use a Raspberry Pi or the DFEC AI Server.

All the code for the server will be located in the server/ directory of your repository.

  1. Clone your repository.

  2. Create and activate a virtual environment.

  3. Use server/requirements.txt to install packages.

  4. Serve the model with fastapi run digits.py

The app should simply:

  • Open the previously saved Keras model.

  • Accept a POST request to /predict.

  • Reshape and grayscale the image to work with the model’s input expectations.

  • Conduct inference on the image and return an integer of the predicted class.

Client#

For your client, you can use any machine with Python and on the same network as the Pi. This can include another Raspberry Pi or your laptop. All the code for the client will be in the client/ directory of your repository.

  1. Clone your repository.

  2. Create and activate a virtual environment.

  3. Use client/requirements.txt to install packages.

  4. Run client.py "xxx.xxx.xxx.xxx", where the X’s are the IP address of the server.

  5. client.py prompts the user for a path to an image. After hitting “enter” the client makes an HTTP POST request to the server, waits for the response, then displays the integer to the user.

  6. The client continues to prompt the user until the user exits with CTRL+C.

Tip

The requests package is easier to use than the built-in urllib.

Deliverables#

  • Demonstrate your client-server exchange.

  • Complete the three README’s in the repository (root, client, server).

  • Push your code and submit to Gradescope.