Spaces:
Running on Zero
Running on Zero
|
Download DEPLOY.md from Pro-Coder/SmartWareHouseAI: direct link, hf CLI and curl.
- Browser
- Download file 6.62 kB
-
https://huggingface.co/spaces/Pro-Coder/SmartWareHouseAI/resolve/main/DEPLOY.md
- Command line
-
hf download hf://spaces/Pro-Coder/SmartWareHouseAI/DEPLOY.md
-
curl -L -o DEPLOY.md https://huggingface.co/spaces/Pro-Coder/SmartWareHouseAI/resolve/main/DEPLOY.md
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. | |