{"id":22706743,"url":"https://github.com/mbari-org/fastapi-yolov5","last_synced_at":"2025-04-12T11:12:47.680Z","repository":{"id":187972171,"uuid":"649821875","full_name":"mbari-org/fastapi-yolov5","owner":"mbari-org","description":"YOLOv5 Machine Learning API powered by the FastAPI framework","archived":false,"fork":false,"pushed_at":"2024-10-05T16:47:16.000Z","size":9978,"stargazers_count":3,"open_issues_count":2,"forks_count":2,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-12T11:12:38.957Z","etag":null,"topics":["cdk","fastapi","yolov5"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mbari-org.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-05T18:00:43.000Z","updated_at":"2024-10-05T16:47:20.000Z","dependencies_parsed_at":"2024-01-23T03:02:23.040Z","dependency_job_id":"110edbdc-bfc1-4210-a4c3-b85e1ed6c215","html_url":"https://github.com/mbari-org/fastapi-yolov5","commit_stats":null,"previous_names":["mbari-org/fastapi-yolov5"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbari-org%2Ffastapi-yolov5","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbari-org%2Ffastapi-yolov5/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbari-org%2Ffastapi-yolov5/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbari-org%2Ffastapi-yolov5/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mbari-org","download_url":"https://codeload.github.com/mbari-org/fastapi-yolov5/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248557842,"owners_count":21124168,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cdk","fastapi","yolov5"],"created_at":"2024-12-10T10:09:35.404Z","updated_at":"2025-04-12T11:12:47.650Z","avatar_url":"https://github.com/mbari-org.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![MBARI](https://www.mbari.org/wp-content/uploads/2014/11/logo-mbari-3b.png)](http://www.mbari.org)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n![license-GPL](https://img.shields.io/badge/license-GPL-blue)\n[![Python](https://img.shields.io/badge/language-Python-blue.svg)](https://www.python.org/downloads/)\n\n**fastapi-yolov5** code deploys and runs the YOLOv5 model in the Python web framework [FastAPI](https://fastapi.tiangolo.com/) either locally or in AWS.\nIn AWS, the model is deployed with ECS Fargate and exposed with an Application Load Balancer.\n\n![](https://raw.githubusercontent.com/mbari-org/fastapi-yolov5/main/api_example.jpg) \n\n# Requirements\n\n- [Docker](https://docs.docker.com/get-docker/)\n- [Docker Compose](https://docs.docker.com/compose/install/)\n- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)\n\n# Deploy YOLOv5 locally\n\n## Clone the repository\n```shell\ngit clone http://github.com/mbari-org/fastapi-yolov5\ncd fastapi-yolov5\n```\n\n## Download an example model\n\n```shell\ncd src/app/model\naws s3 cp --no-sign-request s3://902005-public/models/Megadetector/best.pt .\naws s3 cp --no-sign-request s3://902005-public/models/Megadetector/labels.txt .\n```\n\n## Start the FastAPI server\n\n```shell\ndocker-compose up\n```\nTo stop the server, run\n```shell\ndocker-compose down\n```\n\n# Running\n\n## Health Check\nCheck the health of the server by going to `http://localhost:8000/health`.  You should see the following response:\n\n```json\n{\"status\":\"ok\"}\n```\n\n## Predict to JSON\n\nSend a POST request to `http://localhost:8000/predict` with an image file in the body to get a prediction returned in JSON format.\nBy default, predictions greater than 0.01 are posted.\n\n```shell\ncurl -X POST \"http://localhost:8000/predict\" -H \"accept: application/json\" -H \"Content-Type: multipart/form-data\" -F \"file=@tests/midwater.png\"\n```\n\n# Predict to an image file\n\nSend a POST request to `http://localhost:8000/image` with an image file in the body to get the predictions displayed on an image.\nBy default, predictions greater than 0.01 are displayed.\n\n```shell\ncurl -X POST \"http://localhost:8000/image\" -H \"accept: application/json\" -H \"Content-Type: multipart/form-data\" -F \"file=@tests/midwater.png\" -o midwater_detect.png\n```\n\n![](https://raw.githubusercontent.com/mbari-org/fastapi-yolov5/main/tests/midwater_predict_to_image.png) \n\n\n# Deploy YOLOv5 in AWS\n\nFastAPI deployed with ECS Fargate and exposed with an Application Load Balancer\n\n```shell\ncdk bootstrap\ncdk deploy\n```\n\nYou should see at the end the exposed endpoint, e.g. **http://FastA-FastA-53HYPWCIRUXS-1905789853.us-west-2.elb.amazonaws.com** below.\n\n\n```shell\nFastAPIStack: deploying... [1/1]\nFastAPIStack: creating CloudFormation changeset...\n\n ✅  FastAPIStack\n\n✨  Deployment time: 369.74s\n\nOutputs:\nFastAPIStack.FastAPIYOLOv5ServiceLoadBalancerDNS68FA283F = FastA-FastA-53HYPWCIRUXS-1905789853.us-west-2.elb.amazonaws.com\nFastAPIStack.FastAPIYOLOv5ServiceServiceURL365F19C7 = http://FastA-FastA-53HYPWCIRUXS-1905789853.us-west-2.elb.amazonaws.com\nStack ARN:\narn:aws:cloudformation:us-west-2:975513124282:stack/FastAPIStack/89fcc790-07d4-11ee-924e-02e23803e407\n\n✨  Total time: 377.69s\n```\n\nTest this by running a test image through the endpoint\n\n```\ncurl -X POST \"http://FastA-FastA-53HYPWCIRUXS-1905789853.us-west-2.elb.amazonaws.com/predict\" -H \"accept: application/json\" -H \"Content-Type: multipart/form-data\" -F \"file=tests/midwater.png\"\n```\n\n## Deploying a custom model locally\n\nTo override the default model, you can mount a local directory to the container and set the MODEL_PATH environment variable.\n\nFor example, if you have a model in the directory `./models/midwater102`, you can mount that directory to the container by adding \nthe following to the `docker-compose.yml` file.\n\n```yaml\napp:\n    volumes:\n      - ./models/midwater102:/src/app/model\n    environment:\n      - MODEL_WEIGHTS=/src/app/model/best.pt\n      - MODEL_LABELS=/src/app/model/labels.txt\n      - MODEL_DESCRIPTION=Megadetector\n```\n \nThe labels file should be in the format of one label per line.\n\n```\n.\n├── models/             # Parent directory for models\n│   │\n│   ├── midwater102/    # Model directory\n│   │   ├── best.pt     #  Model YOLOv5 checkpoint file\n│   │   ├── labels.txt  #  Model YOLOv5 labels file\n\n```\n\n```shell\ndocker-compose up\n```\n\n## Deploying a custom model in AWS from node\n\nSpecify any custom configuration on scaling in `config.yaml` file for the stack resources, e.g. min and max capacity.\n\n```yaml\nMinCapacity: 1\nMaxCapacity: 5\n```\n\nTo override the default model, upload yor model, e.g. `best.pt` file and the labels file `labels.txt` for that model to an S3 bucket.\nThe S3 bucket must be in the same region as the ECS cluster. Define the S3 bucket and the model path in the `config.yml` file.\nThese can be overridden as needed in the AWS console through the ECS task definition as environment variables.\n\n```yaml\nMODEL_WEIGHTS: s3://901103-models-deploy/midwatervars102/best.pt\nMODEL_LABELS: s3://901103-models-deploy/midwatervars102/labels.txt\nMODEL_DESCRIPTION: Megadetector\nMODEL_INPUT_SIZE: 1280\n```\n\nDeploy the stack with the new configuration\n\n```shell\ncdk deploy\n```\n\n## Deploying a custom model in AWS from docker\n\nAssuming model is trained with deepsea-ai package. Can deploy with script below\n\nSet your AWS keys\n```\nexport AWS_ACCESS_KEY_ID=\nexport AWS_SECRET_ACCESS_KEY=\n```\n\n```bash\n#!/bin/bash\nset -x\n# Keep stack output persistent so the cloud formation state doesn't get into a weird state\nmkdir -p stacks/y5x6fastapi\n\n# Create the config file for autoscaling\ncat \u003c\u003c 'EOF' \u003e y5x6fastapi.yaml\nEnvironment: Production\nAuthor: DCline\nRegion: us-west-2\nMinCapacity: 0\nMaxCapacity: 1\nAccount: 975513124282\nProjectName: FastAPI-YOLOv5\nProjectNumber: 901103\nDescription: This stack deploys a Fargate managed ELB environment for creating localized detections from a YOLOv5 model using the FastAPI framework with a Ctenophora sp. A model\nMODEL_WEIGHTS: s3://902005-public/models/Megadetector/best.pt\nMODEL_LABELS: s3://902005-public/models/Megadetector/labels.txt\nMODEL_DESCRIPTION: y5x6ctenospA\nMODEL_INPUT_SIZE: 1280\nEOF\n\n# Run in AWS with\ndocker run -it --rm -e AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID} \\\n            -e AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY} \\\n            -e AWS_REGION=us-west-2 \\\n            -e MODEL_WEIGHTS=s3://901103-models-deploy/y5x6ctenospA/best.pt \\\n            -e MODEL_LABELS=s3://901103-models-deploy/y5x6ctenospA/labels.txt \\\n            -e MODEL_INPUT_SIZE=1280 \\\n            -e MODEL_DESCRIPTION=y5x6ctenospA \\\n\t    -v $PWD/y5x6fastapi.yaml:/app/config.yaml \\\n\t    -v $PWD/stacks/y5x6fastapi:/logs \\\n\t    --name y5x6ctenospAflb \\\n\t    mbari/fastapi-yolov5-fargate-elb /app/config.yaml /logs\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmbari-org%2Ffastapi-yolov5","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmbari-org%2Ffastapi-yolov5","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmbari-org%2Ffastapi-yolov5/lists"}