Pull checkpoint from a HF model repo at startup

Add FACEANYTHING_CHECKPOINT_REPO (+ _FILE/_REPO_TYPE/_REVISION, HF_TOKEN) so the
~15 GB checkpoint lives in a separate HF model repo and is fetched once via
hf_hub_download on the CPU node at startup (never spending ZeroGPU seconds).
Falls back to an explicit local path or checkpoints/checkpoint.pt. README documents
the recommended storage + Persistent Storage / HF_HOME setup.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -49,32 +49,58 @@ tracks, output FPS, and a frame cap.
 
 The Gradio code (`app.py`) and the model source (`src/faceanything`,
 `src/depth_anything_3`) are included here. To make the Space runnable you still
-need the **checkpoint** (~15 GB), which is not committed:
-
-1. Add the checkpoint with Git LFS at `checkpoints/checkpoint.pt`:
-   ```bash
-   git lfs install
-   git lfs track "checkpoints/*.pt"
-   mkdir -p checkpoints
-   # copy or download checkpoint.pt into checkpoints/
-   git add .gitattributes checkpoints/checkpoint.pt
-   ```
-   Or point the app elsewhere with the `FACEANYTHING_CHECKPOINT` env var (Space
-   *Settings → Variables and secrets*), or fetch it at startup.
-
-2. Pick the hardware. This needs a CUDA GPU. On **ZeroGPU**, `@spaces.GPU` is used
-   automatically; raise `FACEANYTHING_GPU_DURATION` (seconds, default 180) if long
-   clips time out. On a dedicated GPU Space, `spaces` degrades to a no-op.
-
-3. The DA3 backbone config/architecture is pulled from the public model
-   `depth-anything/DA3-GIANT-1.1` on first run (its weights are then overwritten by
-   the checkpoint). Set `HF_HOME` to reuse a local cache.
+need the **checkpoint** (~15 GB), which is not committed.
+
+### Checkpoint storage (recommended: a separate HF model repo)
+
+Don't commit 15 GB into the Space repo. Upload the checkpoint to its own Hugging
+Face **model** repo once, and let the app pull it at startup:
+
+```bash
+# one-time upload (make the repo private and add an HF_TOKEN secret if you like)
+hf upload UmutKocasari/FaceAnything-weights /path/to/checkpoint.pt checkpoint.pt --repo-type=model
+```
+
+Then set on the Space (*Settings → Variables and secrets*):
+
+```
+FACEANYTHING_CHECKPOINT_REPO = UmutKocasari/FaceAnything-weights
+HF_TOKEN = hf_...            # only if the repo is private
+HF_HOME  = /data/.huggingface   # with Persistent Storage enabled (see below)
+```
+
+`hf_hub_download` caches the file, so it transfers once (and is HF-internal, so
+fast). The app resolves the checkpoint at **startup on the CPU node**, so the
+download never eats into ZeroGPU compute time.
+
+**Enable Persistent Storage** on the Space and point `HF_HOME` at it
+(`/data/.huggingface`) so the 15 GB cache survives restarts instead of
+re-downloading on every cold start.
+
+*Alternatives:* commit it via Git LFS at `checkpoints/checkpoint.pt` (simplest,
+but bloats the Space repo and slows clones — fine only if you accept that), or
+set `FACEANYTHING_CHECKPOINT` to an already-present local path.
+
+### Hardware
+
+This needs a CUDA GPU. On **ZeroGPU**, `@spaces.GPU` is used automatically; raise
+`FACEANYTHING_GPU_DURATION` (seconds, default 180) if long clips time out. On a
+dedicated GPU Space, `spaces` degrades to a no-op.
+
+The DA3 backbone config/architecture is pulled from the public model
+`depth-anything/DA3-GIANT-1.1` on first run (its weights are then overwritten by
+the checkpoint); it lands in the same `HF_HOME` cache.
 
 ### Environment variables
 
 | Variable | Default | Purpose |
 |---|---|---|
-| `FACEANYTHING_CHECKPOINT` | `checkpoints/checkpoint.pt` | path to the weights |
+| `FACEANYTHING_CHECKPOINT_REPO` | — | HF repo id to download the checkpoint from |
+| `FACEANYTHING_CHECKPOINT_FILE` | `checkpoint.pt` | filename within that repo |
+| `FACEANYTHING_CHECKPOINT_REPO_TYPE` | `model` | `model` / `dataset` / `space` |
+| `FACEANYTHING_CHECKPOINT_REVISION` | — | branch/tag/commit to pin |
+| `HF_TOKEN` | — | token for a private checkpoint repo |
+| `FACEANYTHING_CHECKPOINT` | `checkpoints/checkpoint.pt` | explicit local path (overrides the repo download if it exists) |
 | `FACEANYTHING_ROOT` | the app dir | root holding `src/` and `checkpoints/` |
 | `FACEANYTHING_BASE_MODEL` | `depth-anything/DA3-GIANT-1.1` | DA3 backbone id |
 | `FACEANYTHING_GPU_DURATION` | `180` | ZeroGPU seconds per request |

app.py

@@ -33,12 +33,11 @@ import numpy as np
 
 
 # --------------------------------------------------------------------------- #
-# Locate the published FaceAnything source + checkpoint.
+# Locate the published FaceAnything source.
 #
-# For a real deployment, vendor the model code and weights into this Space:
-#   * copy the source repo's `src/` here  (or `pip install` the package), and
-#   * place the checkpoint at `checkpoints/checkpoint.pt` (Git LFS).
-# For local testing against the source checkout, point FACEANYTHING_ROOT at it:
+# The model code (`src/faceanything`, `src/depth_anything_3`) is vendored into
+# this Space. For local testing against a source checkout, point FACEANYTHING_ROOT
+# at it instead:
 #   export FACEANYTHING_ROOT=/cluster/eriador/ukocasari/projects/FaceAnything
 # --------------------------------------------------------------------------- #
 APP_DIR = os.path.dirname(os.path.abspath(__file__))
@@ -59,14 +58,59 @@ def _ensure_faceanything_importable():
 
 _ensure_faceanything_importable()
 
-CHECKPOINT = os.environ.get(
-    "FACEANYTHING_CHECKPOINT", os.path.join(FA_ROOT, "checkpoints", "checkpoint.pt")
-)
 BASE_MODEL = os.environ.get("FACEANYTHING_BASE_MODEL", "depth-anything/DA3-GIANT-1.1")
 GPU_DURATION = int(os.environ.get("FACEANYTHING_GPU_DURATION", "180"))
 MAX_IMAGES = int(os.environ.get("FACEANYTHING_MAX_IMAGES", "40"))
 
 
+# --------------------------------------------------------------------------- #
+# Checkpoint (~15 GB). Recommended storage: a separate HF *model* repo, pulled
+# once with `hf_hub_download` and cached (point HF_HOME at persistent storage,
+# e.g. /data/.huggingface, so it survives restarts). Resolution order:
+#   1. FACEANYTHING_CHECKPOINT — an explicit local file (used if it exists)
+#   2. FACEANYTHING_CHECKPOINT_REPO — download <FILE> from this HF repo
+#      (private repos: set the HF_TOKEN secret)
+#   3. checkpoints/checkpoint.pt next to the app (e.g. committed via Git LFS)
+# --------------------------------------------------------------------------- #
+def _resolve_checkpoint():
+    explicit = os.environ.get("FACEANYTHING_CHECKPOINT")
+    if explicit and os.path.exists(explicit):
+        return explicit
+
+    repo = os.environ.get("FACEANYTHING_CHECKPOINT_REPO")
+    if repo:
+        from huggingface_hub import hf_hub_download
+
+        return hf_hub_download(
+            repo_id=repo,
+            filename=os.environ.get("FACEANYTHING_CHECKPOINT_FILE", "checkpoint.pt"),
+            repo_type=os.environ.get("FACEANYTHING_CHECKPOINT_REPO_TYPE", "model"),
+            revision=os.environ.get("FACEANYTHING_CHECKPOINT_REVISION") or None,
+            token=os.environ.get("HF_TOKEN") or None,
+        )
+
+    default = os.path.join(FA_ROOT, "checkpoints", "checkpoint.pt")
+    if os.path.exists(default):
+        return default
+
+    raise FileNotFoundError(
+        "No checkpoint found. Set FACEANYTHING_CHECKPOINT to a local file, or "
+        "FACEANYTHING_CHECKPOINT_REPO to a Hugging Face repo id (add the HF_TOKEN "
+        "secret if it is private), or place checkpoint.pt under checkpoints/."
+    )
+
+
+# Resolve (and download, if from a repo) at startup — on the CPU node, so the
+# 15 GB transfer never counts against ZeroGPU compute time. A failure here is
+# non-fatal: the UI still builds and the clear error surfaces on first run.
+try:
+    CHECKPOINT = _resolve_checkpoint()
+    print(f"[faceanything] checkpoint ready: {CHECKPOINT}", flush=True)
+except Exception as _ckpt_err:  # noqa: BLE001
+    CHECKPOINT = None
+    print(f"[faceanything] checkpoint not ready yet: {_ckpt_err}", flush=True)
+
+
 # --------------------------------------------------------------------------- #
 # ZeroGPU decorator — falls back to a no-op when `spaces` is unavailable
 # (e.g. running on a plain GPU box / cluster), so the same file runs anywhere.
@@ -98,17 +142,15 @@ _MODEL_DEVICE = None
 
 
 def _get_model(device: str):
-    global _MODEL, _MODEL_DEVICE
+    global _MODEL, _MODEL_DEVICE, CHECKPOINT
     if _MODEL is not None and _MODEL_DEVICE == device:
         return _MODEL
     from faceanything.model import load_model
 
-    if not os.path.exists(CHECKPOINT):
-        raise FileNotFoundError(
-            f"Checkpoint not found at '{CHECKPOINT}'. Set FACEANYTHING_CHECKPOINT or "
-            f"place checkpoint.pt under checkpoints/ (see README)."
-        )
-    _MODEL = load_model(CHECKPOINT, base_model=BASE_MODEL, device=device)
+    # Re-resolve if the startup attempt failed (e.g. env was set afterwards).
+    ckpt = CHECKPOINT or _resolve_checkpoint()
+    CHECKPOINT = ckpt
+    _MODEL = load_model(ckpt, base_model=BASE_MODEL, device=device)
     _MODEL_DEVICE = device
     return _MODEL