SmartWareHouseAI / DEPLOY.md
Pro-Coder's picture
Upload 44 files
4c8ed45 verified
|
Raw History Blame Contribute Delete
6.62 kB
# Deploying to Hugging Face Spaces
## A note on hardware / ZeroGPU
This app is **CPU-only by design** β€” all local ML (intent classifier,
anomaly detector, TF-IDF retrieval) runs on scikit-learn, and the LLM
call goes to the remote HF Inference API rather than running locally.
If your account only offers the **ZeroGPU** hardware tier (some free/new
accounts can't select CPU-basic for new Spaces), that's fine: `app.py`
includes a small `@spaces.GPU`-decorated health-check function purely so
the platform's ZeroGPU compatibility check passes at startup. It's never
called on the actual request path, so it adds no latency or GPU cost β€”
you can safely select ZeroGPU hardware when creating the Space.
Two ways to deploy: the web UI (easiest, no git needed) or the CLI/git route.
## Option A β€” Web UI upload (fastest)
1. Go to https://huggingface.co/new-space
2. Fill in:
- **Space name:** e.g. `smart-warehouse-ai`
- **License:** MIT (or your choice)
- **Select the Space SDK:** **Gradio**
- **Space hardware:** CPU basic (free tier is enough for this app)
- Visibility: **Public** (so you can share the link with recruiters/employers)
3. Click **Create Space**.
4. On the new Space page, click **Files β†’ Add file β†’ Upload files**, and
upload the *entire project folder contents* (keep the folder structure:
`app.py`, `requirements.txt`, `README.md`, `src/`, `models/`, `data/`,
`assets/`). Drag-and-drop the whole folder works in most browsers.
5. Wait for the Space to build (check the **Logs** tab if it fails β€” almost
always a missing/incompatible package version).
6. Once it shows "Running", your demo is live at:
`https://huggingface.co/spaces/<your-username>/smart-warehouse-ai`
## Option B β€” git (recommended if you'll keep iterating)
```bash
# 1. Install the CLI and log in (needs a token with "write" scope)
pip install huggingface_hub
huggingface-cli login
# 2. Create the Space (or create it via the web UI first, then just clone it)
huggingface-cli repo create smart-warehouse-ai --type space --space_sdk gradio
# 3. Clone it, copy in the project files, and push
git clone https://huggingface.co/spaces/<your-username>/smart-warehouse-ai
cd smart-warehouse-ai
cp -r /path/to/this/project/* .
git add .
git commit -m "Initial commit: Smart Warehouse AI Assistant"
git push
```
The Space will automatically build from `requirements.txt` and launch
`app.py` (as declared in the README's YAML front matter: `sdk: gradio`,
`app_file: app.py`).
## Enabling the LLM (recommended before sharing this project)
By default the Space runs in **retrieval-only fallback mode** β€” it still works, but answers are extractive
rather than LLM-generated. To turn on real LLM responses:
1. Create a **free** API key at https://console.groq.com (Groq has a free plan and an OpenAI-compatible API).
2. In your Space: **Settings β†’ Variables and secrets β†’ New secret**, name `GROQ_API_KEY`, value = your key.
3. (Optional) add `LLM_MODEL` to choose another Groq model if the default (`llama-3.1-8b-instant`) is ever retired.
4. Restart the Space, open **AI Assistant β†’ LLM connection diagnostics β†’ Test LLM connection**.
**Why not just use the Hugging Face token?** The app still supports `HF_TOKEN` (via HF's router), but two real
problems showed up in practice:
- `402 Payment Required` β€” Hugging Face Inference Providers bills against account credits, and free accounts
get almost none (a public demo exhausts it quickly). No code change can fix that.
- `Provider 'featherless-ai' not supported` β€” an old `InferenceClient` pinned in `requirements.txt` didn't know
providers that HF's router had started using. The client now speaks plain OpenAI-compatible HTTP instead of
the SDK, so there is no provider list to go stale.
Any other OpenAI-compatible service (OpenRouter, Together, Cerebras…) works with `LLM_API_KEY` + `LLM_BASE_URL`
+ `LLM_MODEL`. A 402/401 stops further attempts on that backend immediately; other errors (rate limit, unknown
model, server error, timeout) move on to the next candidate.
## Re-training / updating the models
The Space **loads pre-built artifacts** from `models/` and `data/` β€” it
does not retrain on startup, so boot time stays fast. If you change
`src/data_generation.py`, `src/intent_model.py`, or `src/anomaly_model.py`,
regenerate everything locally before pushing:
```bash
python build_artifacts.py
git add models/ data/ assets/
git commit -m "Retrain models"
git push
```
## Sharing this project
Once it's live, share the Space URL directly:
```
https://huggingface.co/spaces/<your-username>/smart-warehouse-ai
```
Consider also linking the **Model Evaluation** tab specifically in your
application/cover letter, since it's the clearest evidence of rigorous,
reproducible ML work rather than just a UI demo. Since everything here is
built on synthetic, self-generated data, this same Space link works as-is
for applications to multiple companies β€” no company-specific data or
branding needs to change.
## Optional secrets
| Secret | Purpose |
|---|---|
| `HF_TOKEN` (or `Smart_Warehouse`, see `src/llm_client.py`) | Enables LLM-generated answers (otherwise retrieval-only fallback) |
| `SLACK_WEBHOOK_URL` | Makes the Predictive Maintenance "Send Slack alert" option actually post to Slack (otherwise it shows a labelled preview) |
**Dependency note:** `requirements.txt` pins `pydantic==2.10.6`. Gradio 5.9.1's API-schema generation
crashes on newer pydantic releases (`TypeError: argument of type 'bool' is not iterable`), which would
make the Space fail to start after a rebuild. Don't remove the pin unless you also upgrade Gradio.
## Visual Inventory Scan (real photos): deployment notes
- `requirements.txt` adds `ultralytics`, `opencv-python`, and Ultralytics' `CLIP` package (from GitHub).
PyTorch is already present on Hugging Face Spaces images. I could not run a Space build from my
environment, so **check the build log after pushing**.
- **If that build fails**, delete the last block of `requirements.txt` (`ultralytics`, `ftfy`, `regex`,
`git+https://github.com/ultralytics/CLIP.git`) but keep `opencv-python`. I tested this degraded mode:
the whole app still works, and the real-photo tab explains that the detector isn't available.
- Memory: open-vocabulary mode keeps a ~600 MB text encoder plus the model in RAM; fine on the free
16 GB CPU tier. The first request in that mode takes ~1–2 minutes (weight download).
- The app calls `device="cpu"` explicitly, so it also runs on ZeroGPU hardware without a GPU.
- Licence: Ultralytics is AGPL-3.0 β€” see README.