SmartWareHouseAI / DEPLOY.md
Pro-Coder's picture
Upload 44 files
4c8ed45 verified
|
Raw History Blame Contribute Delete
6.62 kB

A newer version of the Gradio SDK is available: 6.32.0

Upgrade

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)

# 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:

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.