DEPLOYMENT.md

Deployment Guide - New HF Space

Step 1: Create New HF Space

1. Go to https://huggingface.co/new-space

2. Fill in details:

   • Space name: game-asset-generator-pro-v2 (or your choice)
   • License: MIT
   • SDK: Gradio
   • Hardware: L4 GPU (24GB VRAM)
   • Visibility: Public or Private

3. Click "Create Space"

Step 2: Clone the Space Repository

# Clone your new space
git clone https://huggingface.co/spaces/YOUR_USERNAME/game-asset-generator-pro-v2
cd game-asset-generator-pro-v2

Step 3: Copy Files

# Copy all files from huggingface-space-v2
Copy-Item -Recurse D:\KIRO\Projects\XStudios\huggingface-space-v2\* .

# Verify files
Get-ChildItem -Recurse

Step 4: Configure Space

Create README.md header (HF Space metadata):

---
title: 3D Asset Generator Pro V2
emoji: 🎮
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false
license: mit
hardware: l4
---

Step 5: Push to HF Space

# Initialize git (if not already)
git init

# Add all files
git add .

# Commit
git commit -m "Initial deployment - Streamlined architecture"

# Add remote (if not already added)
git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/game-asset-generator-pro-v2

# Push
git push -u origin main

Step 6: Monitor Deployment

1. Go to your Space URL: https://huggingface.co/spaces/YOUR_USERNAME/game-asset-generator-pro-v2
2. Watch the build logs
3. Wait for "Running" status (~5-10 minutes)

Step 7: Test the Space

Basic Test

1. Enter prompt: "medieval knight"
2. Select quality: "Fast"
3. Click "Generate Asset"
4. Verify 3D model appears

Full Test Suite

• All quality presets work
• Caching works (same prompt twice)
• Error handling works (invalid inputs)
• Blender optimization works
• Rate limiting works
• UI is responsive

Troubleshooting

Build Fails

Check logs for:

• Missing dependencies → Update requirements.txt
• Import errors → Check module structure
• Blender not found → Verify Dockerfile

Common fixes:

# Update requirements
pip freeze > requirements.txt

# Test imports locally
python -c "from core import AssetPipeline"

Runtime Errors

Check Space logs:

1. Click "Logs" tab in HF Space
2. Look for error messages
3. Check GPU memory usage

Common issues:

• OOM errors → Reduce quality preset
• Timeout errors → Increase GPU duration
• API errors → Check Hunyuan3D Space status

Blender Not Working

Verify Blender installation:

# In Space terminal (if available)
which blender
blender --version

If missing:

• Update Dockerfile to install Blender
• Or disable Blender optimization (will skip post-processing)

Configuration Options

Environment Variables

Add to Space settings:

• BLENDER_PATH=/usr/bin/blender
• PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True

Hardware Settings

Recommended:

• GPU: L4 (24GB VRAM) - Optimal for FLUX + Hunyuan3D
• CPU: 8 cores
• RAM: 32GB
• Storage: 50GB

Minimum:

• GPU: T4 (16GB VRAM) - May have OOM issues
• CPU: 4 cores
• RAM: 16GB
• Storage: 20GB

Performance Tuning

If Generation is Slow

1. Reduce quality presets:

   • Edit core/config.py
   • Lower flux_steps and hunyuan_steps

2. Disable Blender optimization:

   • Comment out Blender processing in core/pipeline.py

3. Increase GPU duration:

   • Edit @spaces.GPU(duration=X) decorators
   • Increase from 35s/90s to higher values

If OOM Errors Occur

1. Enable CPU offload:

   • Edit generators/flux.py
   • Add pipe.enable_sequential_cpu_offload()

2. Reduce batch size:

   • Lower texture resolution in presets
   • Reduce octree resolution

3. Clear cache more frequently:

   • Edit utils/cache.py
   • Reduce CACHE_EXPIRY_HOURS

Monitoring

Check Space Health

Metrics to monitor:

• Generation success rate
• Average generation time
• GPU memory usage
• Cache hit rate
• Error rate

HF Space dashboard shows:

• Total requests
• Active users
• GPU usage
• Build status

User Feedback

Collect feedback on:

• Generation quality
• Speed/performance
• UI usability
• Error messages
• Feature requests

Maintenance

Regular Tasks

Daily:

• Check error logs
• Monitor GPU usage
• Verify cache is working

Weekly:

• Clean old cache files
• Update dependencies
• Review user feedback

Monthly:

• Update models (FLUX, Hunyuan3D)
• Optimize performance
• Add new features

Updates

To update the Space:

# Make changes locally
# Test changes
python app.py

# Commit and push
git add .
git commit -m "Update: description of changes"
git push

Comparison with Old Space

Feature	Old Space	New Space	Status
Code Size	2,481 lines	960 lines	✅ 61% reduction
Architecture	Monolithic	Modular	✅ Improved
Type Safety	None	Full	✅ Added
Error Handling	Basic	Comprehensive	✅ Improved
Dependencies	20+	10	✅ 50% reduction
Maintainability	Low	High	✅ Much better

Success Criteria

Space is successful if:

• ✅ Builds without errors
• ✅ Generates assets successfully
• ✅ No OOM errors
• ✅ Cache works (60% quota savings)
• ✅ UI is responsive
• ✅ Error messages are clear
• ✅ Performance is good (<90s for High quality)

Next Steps

After successful deployment:

1. Share Space URL with team
2. Collect user feedback
3. Monitor performance for 24 hours
4. Optimize based on real usage
5. Consider migrating old Space if all goes well

Support

If you need help:

1. Check HF Space logs
2. Review error messages
3. Test locally first
4. Check GPU memory with nvidia-smi
5. Review MIGRATION_GUIDE.md

Common resources:

• HF Spaces docs: https://huggingface.co/docs/hub/spaces
• Gradio docs: https://gradio.app/docs
• FLUX docs: https://huggingface.co/black-forest-labs/FLUX.1-dev
• Hunyuan3D docs: https://huggingface.co/tencent/Hunyuan3D-2.1