Upload HF_SPACES_SECRETS.md with huggingface_hub

HF_SPACES_SECRETS.md

@@ -0,0 +1,226 @@
+# HF Spaces Secrets Configuration Guide
+
+## Overview
+All sensitive credentials (API keys, model names, endpoints) are configured via **Hugging Face Spaces Secrets**, not hardcoded in the code.
+
+This document explains how to set up secrets for your HF Space.
+
+## Available Secrets
+
+| Secret Name | Purpose | Required | Example Value |
+|---|---|---|---|
+| `QWEN_API_KEY` | Alibaba Qwen VL API Key | Yes | `sk-...` |
+| `QWEN_BASE_URL` | Qwen API Endpoint | No | `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` |
+| `QWEN_MODEL` | Qwen Model Name | No | `qwen-vl-max` |
+
+## Method 1: Web UI (Simple)
+
+### Steps:
+1. Go to your Space: https://huggingface.co/spaces/YOUR_USERNAME/omniparsev2-ui-detector
+2. Click **Settings** (⚙️ icon) in top right
+3. Scroll down to **Secrets**
+4. Click **Add a secret**
+5. Enter:
+   - **Key**: `QWEN_API_KEY`
+   - **Value**: `sk-your-api-key-here`
+6. Replace the value with your actual Qwen API key
+7. Click **Save**
+
+### Repeat for other secrets (optional):
+- `QWEN_BASE_URL` (usually not needed - uses default)
+- `QWEN_MODEL` (usually not needed - uses `qwen-vl-max`)
+
+## Method 2: API (Programmatic)
+
+### Python Script
+```python
+import requests
+import json
+
+HF_TOKEN = "hf_YOUR_HF_TOKEN_HERE"
+SPACE_ID = "YOUR_USERNAME/omniparsev2-ui-detector"
+
+def add_space_secret(key: str, value: str):
+    """Add a secret to HF Space via API"""
+    headers = {"Authorization": f"Bearer {HF_TOKEN}"}
+    
+    url = f"https://huggingface.co/api/spaces/{SPACE_ID}/secrets"
+    data = {"key": key, "value": value}
+    
+    response = requests.post(url, json=data, headers=headers)
+    
+    if response.status_code == 200:
+        print(f"✓ Secret '{key}' added successfully")
+    else:
+        print(f"✗ Error: {response.status_code} - {response.text}")
+    
+    return response.status_code == 200
+
+# Add secrets
+add_space_secret("QWEN_API_KEY", "sk-your-api-key-here")
+add_space_secret("QWEN_BASE_URL", "https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
+add_space_secret("QWEN_MODEL", "qwen-vl-max")
+```
+
+### Using cURL
+```bash
+HF_TOKEN="hf_YOUR_HF_TOKEN_HERE"
+SPACE_ID="YOUR_USERNAME/omniparsev2-ui-detector"
+
+curl -X POST \
+  "https://huggingface.co/api/spaces/${SPACE_ID}/secrets" \
+  -H "Authorization: Bearer ${HF_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "key": "QWEN_API_KEY",
+    "value": "sk-your-api-key-here"
+  }'
+```
+
+## Method 3: Bash Script (Automated)
+
+```bash
+#!/bin/bash
+
+# Configuration
+HF_TOKEN="hf_YOUR_HF_TOKEN"
+SPACE_ID="YOUR_USERNAME/omniparsev2-ui-detector"
+QWEN_KEY="sk-your-api-key"
+
+# Add QWEN_API_KEY
+echo "Adding QWEN_API_KEY..."
+curl -X POST \
+  "https://huggingface.co/api/spaces/${SPACE_ID}/secrets" \
+  -H "Authorization: Bearer ${HF_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{\"key\": \"QWEN_API_KEY\", \"value\": \"${QWEN_KEY}\"}" \
+  && echo "✓ Added" || echo "✗ Failed"
+
+# Add QWEN_BASE_URL
+echo "Adding QWEN_BASE_URL..."
+curl -X POST \
+  "https://huggingface.co/api/spaces/${SPACE_ID}/secrets" \
+  -H "Authorization: Bearer ${HF_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"key": "QWEN_BASE_URL", "value": "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"}' \
+  && echo "✓ Added" || echo "✗ Failed"
+```
+
+## How It Works in the Code
+
+### Reading Secrets
+```python
+import os
+
+# In caption_cropped_images.py
+QWEN_API_KEY = os.environ.get("QWEN_API_KEY")
+QWEN_BASE_URL = os.environ.get("QWEN_BASE_URL", "https://dashscope-intl.aliyuncs.com/compatible-mode/v1")
+QWEN_MODEL = os.environ.get("QWEN_MODEL", "qwen-vl-max")
+
+# In app_hf_spaces_server.py
+from caption_cropped_images import qwen_client
+CAPTIONS_ENABLED = qwen_client is not None  # Only enabled if API key is set
+```
+
+### Fallback Behavior
+- If `QWEN_API_KEY` is not set → Captions disabled, system still works
+- If `QWEN_BASE_URL` is not set → Uses default DashScope endpoint
+- If `QWEN_MODEL` is not set → Uses `qwen-vl-max` by default
+
+## Security Best Practices
+
+✅ **DO:**
+- Use HF Spaces Secrets for all API keys
+- Never commit keys to git
+- Rotate keys periodically
+- Use minimal required permissions
+
+❌ **DON'T:**
+- Hardcode API keys in source code
+- Commit `.env` files to git
+- Share secrets in logs or error messages
+- Use personal/test keys in production
+
+## Verification
+
+### Check if Secrets are Set
+```python
+import os
+
+print(f"QWEN_API_KEY: {'SET' if os.environ.get('QWEN_API_KEY') else 'NOT SET'}")
+print(f"QWEN_BASE_URL: {'SET' if os.environ.get('QWEN_BASE_URL') else 'NOT SET'}")
+print(f"QWEN_MODEL: {os.environ.get('QWEN_MODEL', 'DEFAULT (qwen-vl-max)')}")
+```
+
+### Check Space Logs
+After deploying, check the Space logs to verify secrets are loaded:
+1. Go to your Space
+2. Click **Logs** (or view app output)
+3. Look for: `✓ Qwen configured: qwen-vl-max`
+
+## Getting Your Qwen API Key
+
+1. Sign up: https://dashscope.console.aliyun.com/
+2. Navigate to API Keys
+3. Copy your API key (format: `sk-...`)
+4. Keep it safe!
+
+## Local Development (Optional)
+
+If you want to test locally with captions:
+
+```bash
+# Set environment variables
+export QWEN_API_KEY="sk-your-key"
+export QWEN_BASE_URL="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
+export QWEN_MODEL="qwen-vl-max"
+
+# Run the app
+python app_hf_spaces_server.py
+```
+
+## Troubleshooting
+
+### Captions show "unavailable"
+Check that `QWEN_API_KEY` is set in Space Secrets:
+1. Go to Settings → Secrets
+2. Verify `QWEN_API_KEY` exists
+3. Restart the Space
+
+### API errors in logs
+Common issues:
+- Invalid API key → Regenerate at dashscope.console.aliyun.com
+- Rate limited → Add delay between requests
+- Endpoint wrong → Use default (leave blank)
+
+### How to update a secret
+1. Go to Settings → Secrets
+2. Find the secret
+3. Click delete (🗑️)
+4. Add new one with same name
+
+## Example Configuration for New Space
+
+```bash
+#!/bin/bash
+# Complete setup for new space
+
+HF_TOKEN="hf_..."
+SPACE_ID="username/omniparsev2-ui-detector"
+
+# Step 1: Add API Key
+curl -X POST "https://huggingface.co/api/spaces/${SPACE_ID}/secrets" \
+  -H "Authorization: Bearer ${HF_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"key": "QWEN_API_KEY", "value": "sk-your-key-here"}'
+
+echo "✓ Space secrets configured!"
+echo "  Visit: https://huggingface.co/spaces/${SPACE_ID}"
+```
+
+## Next Steps
+
+1. Get your Qwen API key
+2. Add it to Space Secrets (via Web UI)
+3. Deploy the updated code
+4. Captions will work automatically!