Initial: SigLIP2 text-only CPU Space for query encoding

README.md

@@ -1,13 +1,52 @@
 ---
-title: Strands Siglip2 Text Cpu
-emoji: 🏆
-colorFrom: pink
-colorTo: green
+title: SigLIP2 Text Encoding (CPU)
+emoji: "\U0001F4DD"
+colorFrom: indigo
+colorTo: blue
 sdk: gradio
-sdk_version: 6.14.0
-python_version: '3.13'
+sdk_version: "5.16.1"
+python_version: "3.12"
 app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# SigLIP2 Text Encoding Service (CPU)
+
+Text-only sibling of [`rmoxon/strands-embeddings-siglip2`](https://huggingface.co/spaces/rmoxon/strands-embeddings-siglip2).
+
+Same model (`google/siglip2-so400m-patch16-384`), same 1152-dim output, same
+`_unwrap` + L2-norm math — but runs the text tower on CPU so search queries
+don't queue behind the GPU Space's image-batch backfill jobs.
+
+## Why this exists
+
+The GPU Space serves both:
+1. The backfill worker (`process-siglip2-embeddings`) — batches 200 images at a time
+2. User search queries (`embed-and-search-v2`) — single text per call
+
+ZeroGPU PRO permits only one concurrent GPU job per account, so a query that
+arrives mid-batch waits 5–9s for the GPU. Splitting query encoding onto a
+dedicated CPU Space eliminates that queue contention; warm queries land in
+~500–800ms regardless of worker activity.
+
+## API endpoint
+
+| Endpoint | Input | Output |
+|---|---|---|
+| `encode_text` | `text: str` | `{embedding: float[1152], dimensions: 1152}` |
+| `healthz` | (any) | `{status, model, output_dim, device}` |
+
+Use Gradio's `/call/<api_name>` SSE protocol (POST to submit, GET to stream
+results). See `nextJS/supabase/functions/embed-and-search-v2/index.ts` in the
+main Strands repo for the canonical client.
+
+## Hardware
+
+- **Runtime**: CPU Basic (2 vCPU, 16 GB RAM, free tier)
+- **Model footprint**: ~3.6 GB float32 (full `AutoModel`)
+- **Per-call latency (warm)**: ~500–800ms
+- **Cold start**: ~10–20s after model load (Space sleeps after ~48h idle)
+
+Embedding-space identity with the GPU Space is guaranteed by using identical
+model weights, identical processor config (`padding="max_length"`,
+`truncation=True`, `max_length=64`), and identical L2 normalization.

app.py

@@ -0,0 +1,123 @@
+import os
+import json
+import logging
+from transformers import AutoModel, AutoProcessor
+import torch
+import numpy as np
+import gradio as gr
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Text-only sibling of `rmoxon/strands-embeddings-siglip2`. Mirrors that Space's
+# model config and `_unwrap` + `l2_normalize` math exactly so query embeddings
+# produced here are interchangeable with embeddings produced by the GPU Space
+# (same `search_embeddings.embedding_v2` cache, same `model_version` key).
+MODEL_NAME = "google/siglip2-so400m-patch16-384"
+OUTPUT_DIM = 1152
+MODEL_VERSION = "siglip2-so400m-1152-v1"
+
+logger.info(f"Loading SigLIP2 model on CPU: {MODEL_NAME}")
+try:
+    # float32 on CPU — bf16 is slow without AVX-512 BF16 (most CPU Basic instances
+    # don't have it). Full model footprint at f32 is ~3.6GB; well under CPU Basic's
+    # 16GB. We use the full AutoModel rather than just .text_model so we can call
+    # `get_text_features` identically to the GPU Space.
+    siglip_model = AutoModel.from_pretrained(
+        MODEL_NAME,
+        torch_dtype=torch.float32,
+    )
+    siglip_model.eval()
+
+    siglip_processor = AutoProcessor.from_pretrained(
+        MODEL_NAME,
+        use_fast=True,
+    )
+
+    model_loaded = True
+    logger.info(f"SigLIP2 model loaded (output dim={OUTPUT_DIM}, model={MODEL_NAME})")
+except Exception as e:
+    logger.error(f"Failed to load SigLIP2 model: {e}")
+    siglip_model = None
+    siglip_processor = None
+    model_loaded = False
+
+
+def l2_normalize(features: torch.Tensor) -> torch.Tensor:
+    """L2-normalize so cosine similarity equals dot product."""
+    return features / features.norm(dim=-1, keepdim=True)
+
+
+def _unwrap(output) -> torch.Tensor:
+    """Coerce transformers output into a pooled tensor.
+
+    Some transformers versions return `BaseModelOutputWithPooling` from
+    `get_text_features` instead of a raw tensor. Identical to the GPU Space.
+    """
+    if isinstance(output, torch.Tensor):
+        return output
+    if hasattr(output, "pooler_output") and output.pooler_output is not None:
+        return output.pooler_output
+    if hasattr(output, "last_hidden_state"):
+        return output.last_hidden_state.mean(dim=1)
+    raise TypeError(f"Cannot extract pooled tensor from {type(output).__name__}")
+
+
+def sanitize_vec(arr: np.ndarray) -> list:
+    arr = np.nan_to_num(arr, nan=0.0, posinf=0.0, neginf=0.0)
+    return arr.tolist()
+
+
+def encode_text(text: str) -> str:
+    """Encode a single text string → L2-normalized SigLIP2 embedding."""
+    logger.info(f"Processing text: {text[:60]}...")
+
+    processed = siglip_processor(
+        text=[text], return_tensors="pt",
+        padding="max_length", truncation=True, max_length=64,
+    )
+    input_ids = processed['input_ids']
+
+    with torch.no_grad():
+        text_features = _unwrap(siglip_model.get_text_features(input_ids=input_ids))
+        text_features = l2_normalize(text_features)
+
+    emb = text_features.cpu().numpy().flatten()
+    return json.dumps({"embedding": sanitize_vec(emb), "dimensions": OUTPUT_DIM})
+
+
+def health_check_handler(_unused: str = "") -> str:
+    if not model_loaded:
+        return json.dumps({"status": "unhealthy", "model": MODEL_VERSION, "error": "Service failed to initialize"})
+    return json.dumps({
+        "status": "healthy",
+        "model": MODEL_VERSION,
+        "output_dim": OUTPUT_DIM,
+        "device": "cpu",
+        "service": "ready",
+        "runtime": "gradio-cpu",
+    })
+
+
+with gr.Blocks(title="SigLIP2 Text Encoding (CPU)") as demo:
+    gr.Markdown(
+        f"# SigLIP2 Text Encoding Service (CPU)\n"
+        f"Text-only sibling of `rmoxon/strands-embeddings-siglip2`. "
+        f"Produces {OUTPUT_DIM}-dim SigLIP2-So400m embeddings for search queries.\n\n"
+        f"Use Gradio's `/call/encode_text` protocol for API access."
+    )
+
+    with gr.Tab("Text Encoding"):
+        text_input = gr.Textbox(label="Text", placeholder="a beautiful sunset over mountains")
+        text_output = gr.Textbox(label="Result", lines=4)
+        text_btn = gr.Button("Encode Text", variant="primary")
+        text_btn.click(fn=encode_text, inputs=text_input, outputs=text_output, api_name="encode_text")
+
+    health_input = gr.Textbox(visible=False)
+    health_output = gr.Textbox(visible=False)
+    health_btn = gr.Button(visible=False)
+    health_btn.click(fn=health_check_handler, inputs=health_input, outputs=health_output, api_name="healthz")
+
+
+demo.queue(max_size=20, default_concurrency_limit=2)
+demo.launch(server_name="0.0.0.0", server_port=7860)

requirements.txt

@@ -0,0 +1,7 @@
+torch>=2.4.0
+transformers>=4.49.0
+sentencepiece>=0.2.0
+Pillow>=9.5.0
+requests>=2.31.0
+numpy<2.0.0
+gradio>=5.16.1