Deploying a model on Hugging Face Spaces

This post summarises how to deploy an application that uses an ML model (such as Grounding DINO in Nutri-AI) on Hugging Face Spaces: what Spaces is, what options exist, concrete steps, and requirements that the Nutri-AI project fulfils. For how Nutri-AI is packaged with Docker (Dockerfile, build, run), see Docker — Overview, basic implementation, and use in Nutri-AI.

1. What is Hugging Face Spaces?

Hugging Face Spaces is a Hugging Face service for hosting and running applications (demos, APIs, UIs) that often use ML models. Each Space is a repository with code and configuration; Hugging Face builds and runs the app on its infrastructure and gives you a public URL.

• Free (with usage and resource limits).
• Integrated with the Hub: you can use models and datasets from the Hub in the same ecosystem.
• Several SDKs: Gradio, Streamlit, or Docker (your own container). For a FastAPI API plus a heavy model (PyTorch, etc.), the usual choice is Docker.

2. Deploy options on Spaces

For a REST API with FastAPI and a model loaded in memory (like Grounding DINO in Nutri-AI), Docker is the right option: same environment as local, same port and environment variables.

3. How to deploy with Docker (summary)

3.1 Create the Space

1. Go to huggingface.co/spaces.
2. Create new Space.
3. Choose:
   • Name of the Space (e.g. your-username/food-ingredients-detection).
   • SDK: Docker.
   • Visibility (public/private).
4. Create. An empty repo is created (or with a default README).

3.2 Configure the Space for Docker

Hugging Face expects:

• A Dockerfile at the root of the Space repo.
• A README.md with YAML frontmatter at the top that specifies sdk: docker and the app port.

Example start of README.md:

---
title: Food Ingredients Detection API
emoji: 🍽️
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
---

• sdk: docker — tells HF to build and run with Docker.
• app_port: 7860 — port your app listens on inside the container; HF routes public traffic to that port.

The rest of the README is the documentation users will see (endpoints, usage, etc.).

3.3 Files the Space repo should have

At the root (or the structure your Dockerfile expects):

Only what the Dockerfile needs is uploaded; .dockerignore avoids uploading cache, .venv, etc.

3.4 Dockerfile requirements for Spaces

Hugging Face runs the container with constraints; it is best to comply with:

If your Dockerfile already meets these (like Nutri-AI’s), you do not need to change it.

3.5 Upload the code

• Option A: Clone the Space repo, copy your project (Dockerfile, README.md, main.py, detection/, requirements.txt, etc.), commit and push.
• Option B: Upload files from the Hugging Face web UI (upload in the Space repo).

After push (or upload), Hugging Face detects changes, rebuilds the image with your Dockerfile and restarts the container. The first build can take several minutes (pip install torch, transformers, etc.).

3.6 Environment variables and secrets

To avoid hardcoding model ID or thresholds:

1. On the Space page → Settings → Variables and secrets.
2. Add variables (e.g. GROUNDING_DINO_MODEL_ID, GROUNDING_DINO_BOX_THRESHOLD, GROUNDING_DINO_TEXT_THRESHOLD).
3. In the container they are available as os.environ.get("NAME"); your code can use them (as in Nutri-AI’s detection/config.py).

Secrets are variables HF does not show in the UI; useful for API keys (Nutri-AI does not use them).

3.7 URL and usage

• The Space URL is: https://huggingface.co/spaces/<org-or-user>/<space-name>.
• Hugging Face often provides a direct link to the app (e.g. to test the API). It is usually shown on the Space tab.
• For an API: GET /docs for Swagger, POST /detect to send the image (same as local, with the host replaced by the Space URL).

4. How this applies to Nutri-AI

4.1 What was deployed

• API: FastAPI (main.py) with endpoints /, /health, /docs, /detect, /detect/image.
• Model: Grounding DINO (zero-shot) loaded in memory on the first request to /detect; it is downloaded from the Hub the first time the container runs.

4.2 Files in the Nutri-AI Space

• Dockerfile — Python 3.10-slim image, libgl1/libglib2.0-0, user user (UID 1000), pip install from requirements.txt, copy of main.py and detection/, CMD with uvicorn on port 7860.
• README.md — frontmatter with sdk: docker, app_port: 7860, title and emoji; rest is API documentation.
• requirements.txt — FastAPI, uvicorn, transformers, torch, torchvision, Pillow, python-multipart.
• main.py — FastAPI application.
• detection/ — detection module (config, grounding_dino).

4.3 Nutri-AI README frontmatter

---
title: Food Ingredients Detection API
emoji: 🍽️
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
---

4.4 Optional variables in Settings

• GROUNDING_DINO_MODEL_ID — model on the Hub (default: IDEA-Research/grounding-dino-tiny).
• GROUNDING_DINO_BOX_THRESHOLD — box threshold (default 0.30).
• GROUNDING_DINO_TEXT_THRESHOLD — text–image threshold (default 0.25).

4.5 Deploy flow for Nutri-AI

1. Create a Space with SDK Docker.
2. Upload Dockerfile, README.md (with frontmatter), requirements.txt, main.py, detection/.
3. HF builds the image and starts the container; the app listens on port 7860.
4. First request to /detect: the code downloads the model from the Hub (if not cached) and responds; later requests use the already-loaded model.

5. Summary steps

This post describes how to deploy an ML-backed app like Nutri-AI (FastAPI API + model from the Hugging Face Hub) on Hugging Face Spaces using Docker. For packaging Nutri-AI with Docker locally, see Docker — Overview, basic implementation, and use in Nutri-AI.