Fix ZeroGPU SAM3 runtime and request diagnostics

README.md

@@ -7,6 +7,7 @@ pinned: false
 short_description: SAM3 open-vocabulary panoptic concept segmentation API
 ---
 
-`api_panoptic(image, concepts, confidence, mask_threshold)` returns JSON
-detections with base64-encoded PNG masks. The Space requires an `HF_TOKEN`
-secret with access to `facebook/sam3`.
+`api_panoptic(image, concepts, confidence, mask_threshold)` returns a compressed
+`.json.gz` file containing detections with base64-encoded PNG masks. File
+transport avoids blocking Gradio's event channel with large inline mask JSON.
+The Space requires an `HF_TOKEN` secret with access to `facebook/sam3`.

app.py

@@ -3,8 +3,11 @@
 from __future__ import annotations
 
 import base64
+import gzip
 import io
+import json
 import os
+import tempfile
 import traceback
 
 import gradio as gr
@@ -33,6 +36,14 @@ def _encode_mask(mask_bool: np.ndarray) -> str:
     return base64.b64encode(buffer.getvalue()).decode("ascii")
 
 
+def _write_response_file(payload: dict) -> str:
+    descriptor, path = tempfile.mkstemp(prefix="sam3_", suffix=".json.gz")
+    os.close(descriptor)
+    with gzip.open(path, "wt", encoding="utf-8", compresslevel=6) as handle:
+        json.dump(payload, handle, separators=(",", ":"))
+    return path
+
+
 def _gpu_duration(image, concepts, conf, mask_threshold=0.5) -> int:
     del image, conf, mask_threshold
     concept_count = len(
@@ -44,20 +55,24 @@ def _gpu_duration(image, concepts, conf, mask_threshold=0.5) -> int:
 @spaces.GPU(duration=_gpu_duration)
 def api_panoptic(image, concepts, conf, mask_threshold=0.5):
     if image is None:
-        return {"error": "no image provided", "detections": []}
+        return _write_response_file(
+            {"error": "no image provided", "detections": []}
+        )
     image = image.convert("RGB")
     width, height = image.size
     concept_list = [
         value.strip() for value in str(concepts or "").split(",") if value.strip()
     ]
     if not concept_list:
-        return {
-            "version": "4",
-            "model": MODEL_ID,
-            "width": width,
-            "height": height,
-            "detections": [],
-        }
+        return _write_response_file(
+            {
+                "version": "5",
+                "model": MODEL_ID,
+                "width": width,
+                "height": height,
+                "detections": [],
+            }
+        )
 
     print(
         f"SAM3 request: size={width}x{height} concepts={len(concept_list)}",
@@ -114,21 +129,30 @@ def api_panoptic(image, concepts, conf, mask_threshold=0.5):
         traceback.print_exc()
         raise
 
-    print(f"SAM3 response: detections={len(detections)}", flush=True)
-    return {
-        "version": "4",
-        "model": MODEL_ID,
-        "width": width,
-        "height": height,
-        "detections": detections,
-    }
+    response_path = _write_response_file(
+        {
+            "version": "5",
+            "model": MODEL_ID,
+            "width": width,
+            "height": height,
+            "detections": detections,
+        }
+    )
+    print(
+        f"SAM3 response: detections={len(detections)} "
+        f"transport_bytes={os.path.getsize(response_path)}",
+        flush=True,
+    )
+    return response_path
 
 
 with gr.Blocks(title="SAM3 Panoptic") as demo:
     gr.Markdown("# SAM3 Panoptic API")
     with gr.Row():
         input_image = gr.Image(type="pil", label="Image")
-        output_json = gr.JSON(label="Detections")
+        output_file = gr.File(
+            type="filepath", label="Compressed detections (.json.gz)"
+        )
     concept_text = gr.Textbox(
         label="Concepts",
         value="person, car, road, building, tree",
@@ -142,7 +166,7 @@ with gr.Blocks(title="SAM3 Panoptic") as demo:
     gr.Button("Segment").click(
         api_panoptic,
         [input_image, concept_text, confidence, mask_threshold],
-        output_json,
+        output_file,
         api_name="api_panoptic",
     )