HUGGINGFACE_CLI_GUIDE.md

Hugging Face CLI & Image Generation Expert Guide

🎯 Table of Contents

1. Introduction
2. Hugging Face CLI Mastery
3. Model Expertise
4. Implementation Improvements
5. Usage Examples
6. 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

# 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

# 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)

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

# 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:

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:

# 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:

# Used Phips/4xNomos8k_atd_jpg
UPSCALER_MODEL_ID = "Phips/4xNomos8k_atd_jpg"

After:

# 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:

# 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:

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:

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:

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

# 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

# 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

# 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

# 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

# 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

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

# 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

# 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

# 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

# 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

# Install required packages
pip install gfpgan opencv-python

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

Debug Commands

# 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):

num_inference_steps=4
true_guidance_scale=1.0
enhance_mode=ENHANCE_MODE_OFF

Balanced (Good quality, reasonable speed):

num_inference_steps=8
true_guidance_scale=1.5
enhance_mode=ENHANCE_MODE_UPSCALE

High Quality (Best results):

num_inference_steps=16
true_guidance_scale=2.0
enhance_mode=ENHANCE_MODE_FULL_ENHANCE

Portrait Photography:

num_inference_steps=12
true_guidance_scale=1.8
enhance_mode=ENHANCE_MODE_FACE_ENHANCE

---

🎯 Pro Tips

1. Batch Processing

# 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

# Use environment variables for custom model locations
UPSCALER_MODEL_ID=my-custom/upscaler
echo $UPSCALER_MODEL_ID

3. Monitoring

# 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

# 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
• Phr00t Rapid-AIO v23
• Real-ESRGAN
• GFPGAN GitHub
• Hugging Face CLI Docs
• Spandrel Upscalers

---

🔄 Migration Guide

From Original to Enhanced Version

File Changes:

# 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:

# 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:

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