HUGGINGFACE_CLI_GUIDE.md

# Hugging Face CLI & Image Generation Expert Guide

## 🎯 Table of Contents

1. [Introduction](#introduction)
2. [Hugging Face CLI Mastery](#hugging-face-cli-mastery)
3. [Model Expertise](#model-expertise)
4. [Implementation Improvements](#implementation-improvements)
5. [Usage Examples](#usage-examples)
6. [Troubleshooting](#troubleshooting)

---

## 🚀 Introduction

This guide provides expert-level knowledge on using Hugging Face CLI and the specific models **Qwen-Image-Edit-2511** and **Qwen-Rapid-AIO-NSFW-v23** for professional image generation and editing.

The enhanced **Pro Realism Edit Studio** now includes:
- ✅ **Real-ESRGAN** upscaler (replacing Nomos for superior quality)
- ✅ **GFPGAN** face restoration for portrait enhancement  
- ✅ **Multi-stage detail enhancement** pipeline
- ✅ **Smart sharpening** with edge detection
- ✅ **Artifact removal** and noise reduction
- ✅ **Improved error handling** and retry logic
- ✅ **GPU memory management**
- ✅ **Enhanced UI** with better documentation

---

## 🎓 Hugging Face CLI Mastery

### Basic Commands

```bash
# Login to Hugging Face Hub
huggingface-cli login

# Who am I?
huggingface-cli whoami

# List models in a repository
huggingface-cli repo list-models username/repo-name

# Download a specific file
huggingface-cli download username/repo-name filename --local-dir ./models

# Upload a file
huggingface-cli upload username/repo-name local-file.txt remote-path/file.txt

# Create a new space
huggingface-cli space create --name my-space --sdk gradio

# Clone a repository
git lfs install
git clone https://huggingface.co/username/repo-name
```

### Advanced Operations

```bash
# Download with resume capability
huggingface-cli download --resume-from-checkpoint username/repo-name filename

# Download specific revision
huggingface-cli download username/repo-name filename --revision main

# Download all files from a repo
huggingface-cli download username/repo-name --local-dir ./models --local-dir-use-symlinks False

# Search for models
huggingface-cli search --model qwen-image-edit

# Check model info
huggingface-cli model-info username/repo-name
```

### Python API (huggingface_hub)

```python
from huggingface_hub import HfApi, hf_hub_download, login, whoami

# Authentication
login()  # Will prompt for token
print(whoami())  # Check current user

# API client
api = HfApi()
model_info = api.model_info("Qwen/Qwen-Image-Edit-2511")

# Download files
hf_hub_download(
    repo_id="Qwen/Qwen-Image-Edit-2511", 
    filename="config.json",
    local_dir="./models"
)

# List repository files
files = api.list_repo_files("Phr00t/Qwen-Image-Edit-Rapid-AIO")
```

### Environment Variables

```bash
# Set Hugging Face token
export HUGGINGFACE_TOKEN="your-token-here"

# Or in Windows
set HUGGINGFACE_TOKEN=your-token-here

# For the enhanced app
 export UPSCALER_MODEL_ID="ai-forever/Real-ESRGAN"
 export UPSCALER_MODEL_FILENAME="RealESRGAN_x4plus.pth"
 export FACE_RESTORATION_MODEL="Xintao/GFPGAN"
```

---

## 🧠 Model Expertise

### Qwen-Image-Edit-2511

**Capabilities:**
- ✅ **Image-to-Image Editing**: Transform existing images with text prompts
- ✅ **Multi-Image Fusion**: Combine multiple images into coherent scenes
- ✅ **Text Rendering**: Add, remove, or modify text in images (English & Chinese)
- ✅ **Structure Preservation**: Maintains original image structure and identity
- ✅ **LoRA Integration**: Built-in support for popular community LoRAs

**Best Practices:**

```python
from qwenimage.pipeline_qwenimage_edit_plus import QwenImageEditPlusPipeline
import torch
from PIL import Image

# Load pipeline
pipe = QwenImageEditPlusPipeline.from_pretrained(
    "Qwen/Qwen-Image-Edit-2511",
    torch_dtype=torch.bfloat16
).to("cuda")

# Generate image
image = Image.open("input.jpg")
result = pipe(
    image=image,
    prompt="a beautiful sunset over mountains",
    negative_prompt="blurry, low quality",
    num_inference_steps=4,
    guidance_scale=1.0,
    seed=42
).images[0]
```

**Prompt Engineering:**
- Be **specific** about changes: "Change the car from red to blue" vs "Make it better"
- Use **spatial descriptions**: "The cat is on the left, the dog on the right"
- For **multi-person scenes**: Describe relationships and positions
- Include **style references**: "in the style of Van Gogh"

### Qwen-Rapid-AIO-NSFW-v23

**Key Features:**
- ✅ **4-Step Inference**: Extremely fast generation
- ✅ **NSFW Optimized**: Better prompt adherence for mature content
- ✅ **Skin & Realism LoRAs**: Built-in enhancements for realistic results
- ✅ **Merged Components**: Accelerator, VAE, and CLIP in single checkpoint

**Integration with Diffusers:**

```python
# The enhanced app already integrates this via:
# load_phr00t_rapid_transformer() function

# Key configuration:
PHR00T_REPO_ID = "Phr00t/Qwen-Image-Edit-Rapid-AIO"
RAPID_TRANSFORMER_FILENAME = "v23/Qwen-Rapid-AIO-NSFW-v23.safetensors"
PHR00T_TRANSFORMER_PREFIX = "model.diffusion_model."
```

**Performance Settings:**
- **Steps**: 4-8 (4 for fastest, 8 for better quality)
- **CFG Scale**: 1.0 (default, works well with v23)
- **Samplers**: euler/beta or euler_ancestral/beta recommended

---

## 🔧 Implementation Improvements

### 1. Enhanced Upscaler (Real-ESRGAN)

**Before:**
```python
# Used Phips/4xNomos8k_atd_jpg
UPSCALER_MODEL_ID = "Phips/4xNomos8k_atd_jpg"
```

**After:**
```python
# Now uses ai-forever/Real-ESRGAN for superior quality
UPSCALER_MODEL_ID = "ai-forever/Real-ESRGAN"
UPSCALER_MODEL_FILENAME = "RealESRGAN_x4plus.pth"
```

**Key Improvements:**
- 🎯 **Superior Quality**: Real-ESRGAN produces more realistic, detailed results
- 🎯 **Adaptive Tiling**: Dynamic tile size based on image dimensions
- 🎯 **Better Blending**: Increased overlap for seamless tile transitions
- 🎯 **Fallback System**: Automatically falls back to Nomos if Real-ESRGAN fails

### 2. Advanced Detail Enhancement

**New Features:**

```python
# Smart Sharpening with Edge Detection
def smart_sharpen(image, strength=1.15):
    # Only sharpens edges, preserves smooth areas
    # Prevents oversharpening artifacts

# Multi-Scale High-Frequency Details
def apply_high_frequency_details(image, amount=0.6):
    # Extracts and enhances details at multiple scales
    # Produces crisp, natural textures

# Ultra Detail Enhancement
def add_ultra_detail(image, strength=0.8):
    # High-pass filtering for fine detail extraction
    # Enhances micro-textures and edges
```

### 3. Face Restoration System

**Integration:**
```python
def restore_faces(image):
    # Uses GFPGAN for professional face enhancement
    # Automatic face detection and restoration
    # Fallback to skin repair if GFPGAN unavailable
```

**Face Detection:**
- Uses OpenCV Haarcascade for accurate face detection
- Fallback to simple geometric detection if OpenCV unavailable
- Handles multiple faces in group photos

### 4. Artifact Removal & Cleaning

**Enhanced Skin Repair:**
```python
def enhanced_skin_repair(image):
    # Improved YCbCr color space thresholds
    # Morphological operations for cleaner masks
    # Selective sharpening (skin vs non-skin)
    # Better blending for natural results
```

**Artifact Removal:**
```python
def remove_artifacts(image):
    # Median filtering for noise reduction
    # Gaussian blur for artifact smoothing
    # Smart blending to preserve details
```

### 5. New Enhancement Modes

| Mode | Description | Use Case |
|------|-------------|----------|
| **Off** | No post-processing | Fastest generation |
| **Upscale Only** | 4x Real-ESRGAN upscaling | Architecture, landscapes |
| **Clean & Restore** | Artifact removal + skin/face restoration | Portraits, old photos |
| **Max Detail** | Full detail enhancement + sharpening | Product shots, textures |
| **Face Enhance** | Specialized face restoration + upscaling | Portrait photography |
| **Full Enhance** | Complete pipeline (clean + detail + face + upscale) | Professional results |

### 6. Error Handling & Retry Logic

```python
# Model download with retry
def download_model_with_retry(repo_id, filename, max_retries=3):
    for attempt in range(max_retries):
        try:
            return hf_hub_download(repo_id=repo_id, filename=filename)
        except Exception as e:
            if attempt == max_retries - 1:
                raise RuntimeError(f"Failed after {max_retries} attempts: {e}")
            time.sleep(2 ** attempt)  # Exponential backoff
```

### 7. Memory Management

```python
# GPU Memory Monitoring
def check_gpu_memory():
    # Checks available VRAM
    # Returns False if insufficient memory

# Cache Clearing
def clear_gpu_cache():
    # Clears CUDA cache
    # Runs garbage collection
```

---

## 💡 Usage Examples

### Basic Image Editing

```python
# Simple text-based editing
result = pipe(
    image=Image.open("portrait.jpg"),
    prompt="make her smile, wearing a red dress",
    num_inference_steps=4,
    guidance_scale=1.0
).images[0]
```

### With Full Enhancement

```python
# Generate with full enhancement pipeline
images = pipe(
    image=Image.open("input.jpg"),
    prompt="professional product photo, white background",
    num_inference_steps=8,
    guidance_scale=1.0
).images

# Apply enhancement
enhanced_images = [
    apply_enhancement(img, ENHANCE_MODE_FULL_ENHANCE, seed=42)
    for img in images
]
```

### Using Hugging Face CLI

```bash
# Download required models manually
huggingface-cli download Qwen/Qwen-Image-Edit-2511 --local-dir ./models/qwen
huggingface-cli download Phr00t/Qwen-Image-Edit-Rapid-AIO v23/Qwen-Rapid-AIO-NSFW-v23.safetensors --local-dir ./models/phr00t
huggingface-cli download ai-forever/Real-ESRGAN RealESRGAN_x4plus.pth --local-dir ./models/upscaler

# Or use Python API
python download_models.py
```

### Docker Deployment

```dockerfile
FROM pytorch/pytorch:latest

WORKDIR /app
COPY . .

RUN pip install -r requirements_enhanced.txt
RUN pip install gfpgan opencv-python scipy

ENV PHR00T_REPO_ID=Phr00t/Qwen-Image-Edit-Rapid-AIO
ENV UPSCALER_MODEL_ID=ai-forever/Real-ESRGAN

CMD ["python", "app_improved.py"]
```

---

## 🐛 Troubleshooting

### Common Issues

**1. Out of Memory Errors**
```bash
# Solution: Reduce image size or clear cache
python app_improved.py --max-size 1024

# Or reduce batch size
num_images_per_prompt=1  # Instead of 4
```

**2. Model Download Failures**
```python
# Increase retry count
max_retries=5  # In download_model_with_retry function

# Check network connection
import requests
response = requests.get("https://huggingface.co")
print(response.status_code)  # Should be 200
```

**3. Slow Performance**
```python
# Use fewer inference steps
num_inference_steps=4  # Instead of 20-40

# Use mixed precision
torch_dtype=torch.bfloat16  # Instead of float32
```

**4. Artifacts in Upscaled Images**
```python
# Reduce tile size for better quality
UPSCALER_TILE_SIZE=256  # Instead of 512

# Increase overlap for better blending  
UPSCALER_TILE_OVERLAP=96  # Instead of 64
```

**5. Face Restoration Not Working**
```bash
# Install required packages
pip install gfpgan opencv-python

# Check model availability
python -c "from gfpgan import GFPGANer; print('GFPGAN available')"
```

### Debug Commands

```python
# Check GPU status
import torch
print(f"CUDA Available: {torch.cuda.is_available()}")
print(f"CUDA Device: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'None'}")

# Check memory
print(f"Total Memory: {torch.cuda.get_device_properties(0).total_memory / 1024**3:.2f} GB")

# Test model loading
try:
    from qwenimage.pipeline_qwenimage_edit_plus import QwenImageEditPlusPipeline
    print("✅ Qwen pipeline available")
except ImportError as e:
    print(f"❌ Import error: {e}")

# Test Hugging Face Hub connection
from huggingface_hub import HfApi
api = HfApi()
try:
    model_info = api.model_info("Qwen/Qwen-Image-Edit-2511")
    print(f"✅ Model accessible: {model_info.id}")
except Exception as e:
    print(f"❌ Hub error: {e}")
```

---

## 📊 Performance Optimization

### Speed vs Quality Tradeoffs

| Setting | Speed | Quality | Memory Usage |
|---------|-------|---------|--------------|
| 4 steps, CFG=1.0 | ⚡⚡⚡⚡⚡ | ⭐⭐⭐ | 🟢 Low |
| 8 steps, CFG=1.0 | ⚡⚡⚡⚡ | ⭐⭐⭐⭐ | 🟡 Medium |
| 16 steps, CFG=2.0 | ⚡⚡⚡ | ⭐⭐⭐⭐⭐ | 🔴 High |
| 32 steps, CFG=4.0 | ⚡⚡ | ⭐⭐⭐⭐⭐ | 🔴🔴 Very High |

### Recommended Configurations

**Fast Generation (Real-time):**
```python
num_inference_steps=4
true_guidance_scale=1.0
enhance_mode=ENHANCE_MODE_OFF
```

**Balanced (Good quality, reasonable speed):**
```python
num_inference_steps=8
true_guidance_scale=1.5
enhance_mode=ENHANCE_MODE_UPSCALE
```

**High Quality (Best results):**
```python
num_inference_steps=16
true_guidance_scale=2.0
enhance_mode=ENHANCE_MODE_FULL_ENHANCE
```

**Portrait Photography:**
```python
num_inference_steps=12
true_guidance_scale=1.8
enhance_mode=ENHANCE_MODE_FACE_ENHANCE
```

---

## 🎯 Pro Tips

### 1. Batch Processing
```python
# Process multiple images sequentially
images = ["img1.jpg", "img2.jpg", "img3.jpg"]
for img_path in images:
    result = infer(
        image_1=img_path,
        prompt="professional edit, enhance details",
        enhance_mode=ENHANCE_MODE_FULL_ENHANCE
    )
    save_result(result)
```

### 2. Custom Model Paths
```bash
# Use environment variables for custom model locations
UPSCALER_MODEL_ID=my-custom/upscaler
echo $UPSCALER_MODEL_ID
```

### 3. Monitoring
```python
# Add logging for debugging
import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# Track generation times
import time
start_time = time.time()
# ... generation code ...
logger.info(f"Generation took: {time.time() - start_time:.2f} seconds")
```

### 4. Model Caching
```python
# Cache models locally to avoid re-downloading
os.environ["HF_HUB_DOWNLOAD_CACHE"] = "./model_cache"
os.makedirs("./model_cache", exist_ok=True)
```

---

## 📚 Additional Resources

- [Qwen-Image-Edit-2511 Official Repo](https://huggingface.co/Qwen/Qwen-Image-Edit-2511)
- [Phr00t Rapid-AIO v23](https://huggingface.co/Phr00t/Qwen-Image-Edit-Rapid-AIO)
- [Real-ESRGAN](https://huggingface.co/ai-forever/Real-ESRGAN)
- [GFPGAN GitHub](https://github.com/TencentARC/GFPGAN)
- [Hugging Face CLI Docs](https://huggingface.co/docs/huggingface_hub/)
- [Spandrel Upscalers](https://github.com/Comfy-Org/spandrel)

---

## 🔄 Migration Guide

### From Original to Enhanced Version

**File Changes:**
```bash
# Backup original
cp app.py app_backup.py

# Replace with enhanced version
cp app_improved.py app.py

# Update requirements
cp requirements_enhanced.txt requirements.txt
```

**Environment Variables:**
```bash
# Old (still works)
UPSCALER_MODEL_ID=Phips/4xNomos8k_atd_jpg

# New (recommended)
UPSCALER_MODEL_ID=ai-forever/Real-ESRGAN
UPSCALER_MODEL_FILENAME=RealESRGAN_x4plus.pth
FACE_RESTORATION_MODEL=Xintao/GFPGAN
```

**Dependencies to Add:**
```bash
pip install gfpgan opencv-python scipy
```

---

## 🚀 Conclusion

This enhanced version transforms the **Pro Realism Edit Studio** into a professional-grade image editing and enhancement platform. The integration of **Real-ESRGAN**, **GFPGAN**, and advanced detail enhancement algorithms provides superior quality while maintaining the speed and efficiency of the original implementation.

**Key Benefits:**
- 🎯 **Higher Quality Results** with Real-ESRGAN upscaling
- 👤 **Better Portrait Enhancement** with GFPGAN face restoration  
- 🔍 **Crisp Details** with multi-stage enhancement
- 🛡️ **Robust Error Handling** and fallback systems
- 💡 **Improved User Experience** with better documentation and controls

The Hugging Face CLI expertise ensures reliable model downloading, version management, and deployment flexibility across different environments.

---

*Last updated: June 30, 2026*
*Compatible with: Qwen-Image-Edit-2511, Phr00t Rapid-AIO v23*