Add explicit ZeroGPU spaces dependency

docs/03-dev-schedule.md

@@ -52,12 +52,13 @@
 - [x] 做 JSON repair
 - [x] 加 example gallery
 - [x] 新增 Space VLM 验证脚本
+- [x] 新增 ZeroGPU 兼容装饰器
 - [ ] 缓存示例输出
-- [ ] Space 1x L4 真实图片验证（2026-06-06 已尝试，因 HF `402 Payment Required` 阻塞，已回滚 mock-safe）
+- [ ] Space 真实图片验证（L4 因 HF `402 Payment Required` 阻塞；ZeroGPU 已到 `RUNNING` 但验证请求长时间无返回，已回滚 mock-safe）
 
 验收：上传杯子/键盘/鞋子，模型能识别物品并提取外观特征。
 
-完成记录：MiniCPM-V 2.6 已作为可配置 vision backend 接入，默认仍是 mock vision；`scripts/check_space_vlm.py` 已可用三张临时公开图片验证 Space 端 mug/keyboard/shoe。2026-06-06 已尝试切到 L4，但 Hugging Face 返回 `402 Payment Required`，需要组织 billing/pre-paid credits；随后已执行 mock-safe rollback。文本生成已接入可选 llama.cpp runtime wiring，但最终 GGUF 模型仍未选择/下载。
+完成记录：MiniCPM-V 2.6 已作为可配置 vision backend 接入，默认仍是 mock vision；`scripts/check_space_vlm.py` 已可用三张临时公开图片验证 Space 端 mug/keyboard/shoe。2026-06-06 已尝试切到 L4，但 Hugging Face 返回 `402 Payment Required`，需要组织 billing/pre-paid credits；随后尝试 ZeroGPU，Space 可到 `RUNNING`，但验证请求长时间无返回。两次尝试后均已执行 mock-safe rollback。文本生成已接入可选 llama.cpp runtime wiring，但最终 GGUF 模型仍未选择/下载。
 
 ---
 

docs/DEVELOPMENT_STATUS.md

@@ -18,11 +18,14 @@ Last updated: 2026-06-06
 - Space VLM validation tooling:
   - `scripts/check_space_vlm.py`
   - failed L4 validation report at `docs/SPACE_VLM_REPORT.md`
+- ZeroGPU compatibility:
+  - optional `src/utils/zero_gpu.py`
+  - Gradio generation callback wrapped with `@zero_gpu(duration=180)`
 - Local tests and initial acceptance currently pass.
 
 ## Not Completed
 
-- Hosted Space 1x L4 MiniCPM-V validation with real public mug/keyboard/shoe images. Attempted on 2026-06-06 and blocked by Hugging Face `402 Payment Required` for paid hardware; mock-safe rollback was applied.
+- Hosted Space MiniCPM-V validation with real public mug/keyboard/shoe images. Paid L4 was blocked by Hugging Face `402 Payment Required`; ZeroGPU reached `RUNNING` but the validation request did not return within the practical waiting window; mock-safe rollback was applied.
 - Stable example output caching for real VLM demos.
 - Real GGUF model selection, download/configuration outside Git, and `TEXT_MODEL_PATH` smoke test.
 - Final text model parameter count documentation.
@@ -41,7 +44,7 @@ Last updated: 2026-06-06
 
 ## Next Recommended Gate
 
-Unblock Hugging Face paid hardware access or choose another available GPU option, then rerun the hosted Space VLM validation:
+Unblock Hugging Face paid hardware access, or debug the ZeroGPU queue/request path with a smaller probe model, then rerun the hosted Space VLM validation:
 
 ```bash
 .venv/bin/python -B scripts/check_space_vlm.py \

docs/EXTERNAL_SETUP.md

@@ -98,7 +98,10 @@ The validation script must not print Hugging Face tokens. It uses three temporar
 - `--configure-space` was run for `l4x1`.
 - Hugging Face returned `402 Payment Required` for paid hardware on the `build-small-hackathon` organization.
 - Mock-safe rollback was run afterward.
-- Next unblock step: enable billing/pre-paid credits or choose an available free GPU option before rerunning validation.
+- ZeroGPU compatibility was added and uploaded to the Space.
+- `--configure-space --hardware zero-a10g` reached `RUNNING`, and `/config` was reachable, but the validation request did not return within the practical waiting window.
+- Mock-safe rollback was run afterward and confirmed at `cpu-basic`.
+- Next unblock step: enable billing/pre-paid credits, or debug ZeroGPU with a smaller probe before retrying full MiniCPM-V validation.
 
 ## Safety Notes
 

docs/SPACE_VLM_REPORT.md

@@ -1,42 +1,50 @@
 # Space VLM Validation Report
 
-- Generated at: 2026-06-06 04:25 UTC
+- Generated at: 2026-06-06 04:55 UTC
 - Space URL: https://huggingface.co/spaces/build-small-hackathon/ObjectverseDiary
 - Space repo: `build-small-hackathon/ObjectverseDiary`
 - Overall status: FAIL
 - Vision backend expected: `minicpm-v`
 - Text backend expected: `mock`
 
-## Space Configuration
+## Attempt 1: Paid L4
 
 - Requested configuration:
   - `hardware`: `l4x1`
   - `OBJECTVERSE_VISION_BACKEND`: `minicpm-v`
   - `VISION_MODEL_ID`: `openbmb/MiniCPM-V-2_6`
   - `OBJECTVERSE_TEXT_BACKEND`: `mock`
+- Result: failed before validation.
+- Error: `HfHubHTTPError: 402 Payment Required`
+- Meaning: Hugging Face requires billing or pre-paid credits for the `build-small-hackathon` organization before it can use paid `l4x1` hardware.
+- Safety outcome: mock-safe rollback was run after the failed hardware request.
 
-- Rollback configuration applied:
-  - `hardware`: `cpu-basic`
-  - `OBJECTVERSE_VISION_BACKEND`: `mock`
-  - `OBJECTVERSE_TEXT_BACKEND`: `mock`
-
-## Configuration Error
+## Attempt 2: ZeroGPU
 
-- Error: `HfHubHTTPError: 402 Payment Required`
-- Meaning: Hugging Face requires pre-paid credits or billing access for the `build-small-hackathon` organization before the Space can use paid `l4x1` hardware.
-- Impact: Remote MiniCPM-V validation did not run. No mug / keyboard / shoe image inference results were produced.
-- Safety outcome: Mock-safe rollback was run after the failed hardware request.
+- Local compatibility update:
+  - Added optional `@spaces.GPU` support through `src/utils/zero_gpu.py`.
+  - Wrapped the Gradio generation callback with `@zero_gpu(duration=180)`.
+  - Uploaded the ZeroGPU-compatible app code to the Space.
+- Requested configuration:
+  - `hardware`: `zero-a10g`
+  - `OBJECTVERSE_VISION_BACKEND`: `minicpm-v`
+  - `VISION_MODEL_ID`: `openbmb/MiniCPM-V-2_6`
+  - `OBJECTVERSE_TEXT_BACKEND`: `mock`
+- Result: Space reached `RUNNING` on `zero-a10g`, and `/config` was reachable, but the validation request did not return within the practical waiting window.
+- Observed logs: app startup only; no model load or inference error was shown in the fetched Space logs.
+- Safety outcome: the stuck local validation process was terminated, then mock-safe rollback was run.
 - Post-rollback runtime check: Space is `RUNNING` with `hardware=cpu-basic` and `requested_hardware=cpu-basic`.
 
 ## Results
 
-- Coffee mug: NOT RUN
-- Computer keyboard: NOT RUN
-- Running shoe: NOT RUN
+- Coffee mug: NOT RUN to completion
+- Computer keyboard: NOT RUN to completion
+- Running shoe: NOT RUN to completion
 
 ## Notes
 
 - Test images are temporary public Wikimedia Commons assets and are not committed.
 - Text generation remains mock during this validation plan.
 - No tokens, secrets, or private file paths are recorded in this report.
-- Next unblock step: enable billing/pre-paid credits for the Hugging Face organization or choose an available free GPU option, then rerun `scripts/check_space_vlm.py`.
+- The validation script now has configuration-failure reporting, Gradio config retry, rollback-on-validation-failure, and per-prediction timeout protection.
+- Next unblock step: enable billing/pre-paid credits for the Hugging Face organization, or debug the ZeroGPU queue/request path with a smaller VLM or a minimal ZeroGPU probe before retrying full MiniCPM-V validation.

docs/SUBMISSION_GUIDE.md

@@ -18,7 +18,7 @@
 - Runtime boundary: `docs/RUNTIME.md`
 - Dataset plan and preview workflow: `docs/DATASET.md`
 - External setup checklist: `docs/EXTERNAL_SETUP.md`
-- Space VLM validation report: `docs/SPACE_VLM_REPORT.md` currently failed because `l4x1` hardware returned `402 Payment Required`.
+- Space VLM validation report: `docs/SPACE_VLM_REPORT.md` currently failed because `l4x1` hardware returned `402 Payment Required`; ZeroGPU reached `RUNNING` but the validation request did not return.
 - Public mock traces: `data/traces/samples/`
 - Optional llama.cpp runtime wiring: `src/models/llama_cpp_runner.py`
 
@@ -31,7 +31,7 @@
 
 ## Not Completed Yet
 
-- Hosted Space L4 MiniCPM-V validation for mug, keyboard, and shoe; attempted and blocked by Hugging Face paid hardware billing.
+- Hosted Space MiniCPM-V validation for mug, keyboard, and shoe; L4 is blocked by Hugging Face paid hardware billing, and ZeroGPU needs further debugging.
 - Real GGUF `TEXT_MODEL_PATH` smoke test and final text model parameter count.
 - Real model traces, curated dataset, LoRA training, model/dataset publishing.
 - Field Notes article, demo video, social post, final submission package.
@@ -39,7 +39,7 @@
 ## Final Checks
 
 - [ ] Space is under the official organization.
-- [ ] Space MiniCPM-V validation passes for mug, keyboard, and shoe. Current status: blocked by paid hardware billing.
+- [ ] Space MiniCPM-V validation passes for mug, keyboard, and shoe. Current status: L4 blocked by paid hardware billing; ZeroGPU request path unresolved.
 - [ ] Demo video is under 2 minutes.
 - [ ] README includes model parameter counts.
 - [ ] No commercial cloud AI APIs are used.

pyproject.toml

@@ -12,6 +12,7 @@ dependencies = [
     "Pillow",
     "sentencepiece",
     "accelerate",
+    "spaces>=0.30",
 ]
 
 [tool.objectverse-diary]

requirements.txt

@@ -6,3 +6,4 @@ transformers>=4.40,<5
 Pillow
 sentencepiece
 accelerate
+spaces>=0.30

scripts/check_space_vlm.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import signal
 import sys
 import time
 import urllib.request
@@ -28,6 +29,7 @@ DEFAULT_HARDWARE = "l4x1"
 MOCK_SAFE_HARDWARE = "cpu-basic"
 GENERATE_API_NAME = "/generate_object_file"
 REQUEST_TIMEOUT_SECONDS = 45
+PREDICTION_TIMEOUT_SECONDS = 360
 
 SPACE_VARIABLES = {
     "OBJECTVERSE_VISION_BACKEND": "minicpm-v",
@@ -181,11 +183,11 @@ def run_space_validation(
     timeout_seconds: int = 900,
     assets: list[ValidationAsset] | None = None,
 ) -> list[ValidationResult]:
-    from gradio_client import Client, handle_file
+    from gradio_client import handle_file
 
     selected_assets = assets or TEST_ASSETS
     paths = download_validation_assets(asset_dir, selected_assets)
-    client = Client(space_url, verbose=False)
+    client = _build_gradio_client(space_url, timeout_seconds=timeout_seconds)
     results: list[ValidationResult] = []
     started = time.monotonic()
     for asset in selected_assets:
@@ -193,11 +195,12 @@ def run_space_validation(
         if remaining <= 0:
             raise TimeoutError(f"Validation exceeded timeout of {timeout_seconds}s")
         try:
-            response = client.predict(
+            response = _predict_with_timeout(
+                client,
                 handle_file(str(paths[asset.key])),
                 asset.description,
                 asset.mode,
-                api_name=GENERATE_API_NAME,
+                timeout_seconds=min(PREDICTION_TIMEOUT_SECONDS, remaining),
             )
             results.append(validate_prediction(asset, paths[asset.key], response))
         except Exception as exc:
@@ -221,6 +224,47 @@ def run_space_validation(
     return results
 
 
+def _predict_with_timeout(
+    client: Any,
+    image: Any,
+    description: str,
+    mode: str,
+    *,
+    timeout_seconds: int,
+) -> Any:
+    def _raise_timeout(_signum: int, _frame: Any) -> None:
+        raise TimeoutError(f"Gradio prediction did not finish within {timeout_seconds}s")
+
+    previous_handler = signal.signal(signal.SIGALRM, _raise_timeout)
+    signal.alarm(max(1, timeout_seconds))
+    try:
+        return client.predict(
+            image,
+            description,
+            mode,
+            api_name=GENERATE_API_NAME,
+        )
+    finally:
+        signal.alarm(0)
+        signal.signal(signal.SIGALRM, previous_handler)
+
+
+def _build_gradio_client(space_url: str, *, timeout_seconds: int) -> Any:
+    from gradio_client import Client
+
+    deadline = time.monotonic() + timeout_seconds
+    last_error: Exception | None = None
+    while time.monotonic() < deadline:
+        try:
+            return Client(space_url, verbose=False)
+        except Exception as exc:
+            last_error = exc
+            time.sleep(10)
+    if last_error is None:
+        raise TimeoutError(f"Could not create Gradio client for {space_url}")
+    raise TimeoutError(f"Could not fetch Gradio config for {space_url}: {type(last_error).__name__}: {last_error}")
+
+
 def validate_prediction(
     asset: ValidationAsset,
     image_path: Path,
@@ -450,11 +494,22 @@ def main() -> None:
 
     results: list[ValidationResult] = []
     if not args.skip_validation and not configuration_error:
-        results = run_space_validation(
-            space_url=args.space_url,
-            asset_dir=args.asset_dir,
-            timeout_seconds=args.timeout_seconds,
-        )
+        try:
+            results = run_space_validation(
+                space_url=args.space_url,
+                asset_dir=args.asset_dir,
+                timeout_seconds=args.timeout_seconds,
+            )
+        except Exception as exc:
+            configuration_error = f"{type(exc).__name__}: {exc}"
+            if args.rollback_to_mock and rollback is None:
+                try:
+                    rollback = rollback_space_to_mock(repo_id)
+                except Exception as rollback_exc:
+                    configuration_error = (
+                        f"{configuration_error}; rollback failed with "
+                        f"{type(rollback_exc).__name__}: {rollback_exc}"
+                    )
 
     if args.rollback_to_mock and rollback is None:
         rollback = rollback_space_to_mock(repo_id)