HostingKangasOnHuggingFaceSpaces

Hosting Kangas on HuggingFace Spaces

What are HuggingFace's Spaces?

Hugging Face Spaces offer a simple way to host ML demo apps directly on your profile or your organization’s profile. This allows you to create your ML portfolio, showcase your projects at conferences or to stakeholders, and work collaboratively with other people in the ML ecosystem.

The fastest way to deploy a hosted Kangas instance, preloaded with your DataGrid, to a Hugging Face Space is to use Kangas' Python integration with Hugging Face:

from kangas.integrations import deploy_to_huggingface

deploy_to_huggingface(path="NAME-OF-HUGGINGFACE-SPACE", name="NAME-OF-DATAGRID.datagrid")

This method will automatically clone our template Space to your target Hugging Face repository (specified in the path parameter), populate the space with your DataGrid file (specified in the name parameter), and initiate the build process. If you do not have your Hugging Face credentials configured in your environment, you will be prompted to login.

With the rest of this guide, we'll cover the process for manually deploying a DataGrid without using the built-in Python.

This set of instructions will show you how to host a Kangas DataGrid with either a pre-loaded DataGrid, or dynamically download one using streamlit and build your own pipeline.

For the first, you run kangas directly. See instructions below.

To run with a framework like streamlit or gradio, you'll need an additional component (nginx).

Here are examples of the two styles of Kangas hosting:

1. https://huggingface.co/spaces/comet-team/kangas-datagrid
2. https://huggingface.co/spaces/CalebCometML/kangas-demo

But first, you'll need to setup your Space.

Setup Instructions

1. Create an account on https://huggingface.co (pick an easy to type password, as you'll be entering it from the command-line too)
2. Confirm email, and define your organization
3. Create a new space: https://huggingface.co/spaces
4. Fill in the form, and select Docker, select "Blank" SDK
5. Back in a console on your computer, clone your space:

git clone https://huggingface.co/spaces/YOUR-ORG/SPACE-NAME

6. cd SPACE-NAME

If you will be saving binary data (such as a datagrid) you'll need lfs.

See: https://git-lfs.com/

On Ubuntu:

sudo apt install git-lfs

Finally, let git know that you'll be using lfs:

git lfs install
git lfs track "*.datagrid"
git add .gitattributes
git commit -m "Added lfs"
git push

Use your huggingface email address and password from step 1.

Running Kangas Directly

Dockerfile should contain:

FROM python:3.9
WORKDIR /code
COPY ./requirements.txt /code/requirements.txt
RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
COPY . .
CMD kangas server --frontend-port=7860

requirements.txt should contain:

kangas
datasets

Copy (or create) any datagrid files you would like to host at huggingface to this repo.

Here is an example of how to get a huggingface dataset, and map the annotations in the column "options" to kangas-style annotations:

kangas import --huggingface cppe-5 cppe-5.datagrid \
   --options split=test labels=objects:category \
             bbox=objects:bbox:xywh ids=objects:id

Finally, add the datagrids to git:

1. git add *.datagrid
2. git commit -m "Added datagrids"
3. git push

Back at huggingface.co, you should see your app is "Building". Once finished, under "App" you can select a datagrid and see it running, like:

https://huggingface.co/spaces/comet-team/kangas-datagrid

Running Kangas with Streamlit

Please see the example at:

https://huggingface.co/spaces/CalebCometML/kangas-demo

Feel free to duplicate the space, and change to your liking.