casterpollux-MiniMax-bmo/AUTO_DOWNLOAD_GUIDE.md

🤖 Auto-Download Feature Guide

Overview

The MiniMax-Remover node now includes automatic model downloading and path detection, making it incredibly easy to get started without manual setup!

✨ Key Features

1. Zero-Configuration Setup

• Models download automatically when needed
• Paths are detected and populated automatically
• No manual configuration required for basic usage

2. Intelligent Path Detection

• Searches multiple standard locations for existing models
• Uses the best available location automatically
• Falls back gracefully if auto-download fails

3. Smart Caching

• Downloads models once and reuses them
• Shares models across multiple ComfyUI installations
• Efficient storage management

🚀 How It Works

Default Experience (Recommended)

When you first use the node:

1. Auto-Detection: Node checks for existing models in standard locations
2. Auto-Download: If models aren't found, automatically downloads them (~25GB)
3. Auto-Configure: Paths are set automatically
4. Ready to Use: Node loads and processes your video

Node Parameters

The node interface now includes:

Auto-Download (Enabled by default)

• ✅ auto_download: True - Automatic model management
• ❌ auto_download: False - Manual path configuration only

Path Settings (Auto by default)

• vae_path: "auto" - Automatically detected VAE path
• transformer_path: "auto" - Automatically detected Transformer path
• scheduler_path: "auto" - Automatically detected Scheduler path

📁 Model Storage Locations

The auto-download system tries these locations in order:

1. Project Directory (Preferred)

MiniMax-Remover/
└── models/
    ├── vae/
    ├── transformer/
    └── scheduler/

2. ComfyUI Models Directory

ComfyUI/
└── models/
    ├── vae/
    ├── transformer/
    └── scheduler/

3. User Cache Directory

~/.cache/minimax-remover/
└── models/
    ├── vae/
    ├── transformer/
    └── scheduler/

🎯 Usage Examples

Example 1: Zero-Configuration (Default)

# Everything is automatic!
result = minimax_node.process_video(
    images=your_video_frames,
    masks=your_masks,
    # All other parameters use smart defaults
)

What happens:

1. Node detects no models exist
2. Automatically downloads models (~25GB, one-time)
3. Processes your video
4. Future runs use cached models instantly

Example 2: Custom Paths with Auto-Download

# Use custom paths but still auto-download if needed
result = minimax_node.process_video(
    images=your_video_frames,
    masks=your_masks,
    auto_download=True,
    vae_path="/my/custom/vae/path",
    transformer_path="auto",  # Auto-detect transformer
    scheduler_path="auto"     # Auto-detect scheduler
)

Example 3: Manual Configuration (Traditional)

# Disable auto-download for full manual control
result = minimax_node.process_video(
    images=your_video_frames,
    masks=your_masks,
    auto_download=False,
    vae_path="./models/vae/",
    transformer_path="./models/transformer/",
    scheduler_path="./models/scheduler/"
)

📊 First-Time Setup Experience

What You'll See

Step 1: Model Detection

🔍 Checking for MiniMax-Remover models...
📥 Models not found locally. Starting automatic download...

Step 2: Automatic Download

🌐 Downloading MiniMax-Remover models to: ./models
📊 Expected download size: ~25-30 GB
⏳ This may take several minutes depending on your connection...

Step 3: Download Progress

The download includes progress indicators and status updates.

Step 4: Auto-Configuration

🎉 Models downloaded successfully!
🎯 Auto-resolved paths:
   VAE: ./models/vae
   Transformer: ./models/transformer
   Scheduler: ./models/scheduler

Step 5: Ready to Use

✅ BMO MiniMax-Remover models loaded successfully!
🚀 Running BMO MiniMax-Remover

🛠️ Advanced Configuration

Environment Variables

You can set preferred download locations:

# Set custom cache directory
export MINIMAX_CACHE_DIR="/my/preferred/cache"

# Set custom ComfyUI models path
export COMFYUI_MODELS_PATH="/custom/comfyui/models"

Manual Override

Even with auto-download enabled, you can specify exact paths:

# Mix auto and manual paths
result = minimax_node.process_video(
    images=your_video_frames,
    masks=your_masks,
    auto_download=True,
    vae_path="/fast/ssd/vae/",      # Custom VAE location
    transformer_path="auto",         # Auto-detect transformer
    scheduler_path="/shared/scheduler/" # Custom scheduler location
)

🔧 Troubleshooting

Download Issues

Network Problems

❌ Auto-download failed: Network connection error
🔧 Manual download options:
1. Run: python download_models.py
2. Run: huggingface-cli download zibojia/minimax-remover --local-dir ./models
3. See MODEL_DOWNLOAD_GUIDE.md for detailed instructions

Solutions:

• Check internet connection
• Try downloading manually using provided commands
• Use VPN if behind firewall

Disk Space Issues

❌ Auto-download failed: No space left on device

Solutions:

• Free up ~30GB disk space
• Download to external drive using custom path
• Use manual download to specific location

Permission Issues

❌ Auto-download failed: Permission denied
📁 Using cache directory for models: /home/user/.cache/minimax-remover/models

Solutions:

• Auto-switches to user cache directory
• Check file permissions in project directory
• Run with appropriate permissions

Path Resolution Issues

Models Not Found

⚠️ Auto-download failed, falling back to manual paths
❌ Missing model paths:
   VAE: ./models/vae

Solutions:

• Enable auto-download: auto_download=True
• Check manually downloaded model structure
• Verify model files exist and are complete

💡 Best Practices

For New Users

1. Use defaults: Let auto-download handle everything
2. Stable connection: Ensure reliable internet for first download
3. Sufficient space: Have ~30GB free disk space

For Power Users

1. Share models: Download once, symlink to multiple ComfyUI instances
2. SSD storage: Place models on fast storage for better performance
3. Custom locations: Use environment variables for system-wide configuration

For Shared Systems

1. Central storage: Download to shared location accessible by all users
2. Symlinks: Link to shared models instead of duplicating
3. Permissions: Ensure read access for all users

🔄 Migration from Manual Setup

If you already have models downloaded manually:

Option 1: Let Auto-Detection Find Them

• Models in standard locations will be found automatically
• No migration needed

Option 2: Move to Standard Location

# Move existing models to standard location
mv /old/path/models ./models

Option 3: Use Custom Paths

• Set paths to your existing model locations
• Disable auto-download if you prefer manual control

📈 Performance Benefits

First Run

• Download: One-time ~25GB download
• Time: 10-30 minutes depending on connection
• Storage: ~30GB total

Subsequent Runs

• Loading: Models load from local cache
• Time: ~10-30 seconds for model loading
• Storage: No additional space needed

🆘 Support

If auto-download isn't working:

1. Check logs: Enable verbose logging to see detailed error messages
2. Try manual: Use python download_models.py as fallback
3. Check space: Ensure sufficient disk space
4. Verify connection: Test internet connectivity
5. Report issues: Include auto-download logs in bug reports

🎉 Summary

The auto-download feature makes MiniMax-Remover plug-and-play:

• ✅ Zero configuration for most users
• ✅ Automatic model management
• ✅ Intelligent path detection
• ✅ Graceful fallbacks when issues occur
• ✅ Compatible with existing setups

Just drag the node into ComfyUI, connect your inputs, and it works! 🚀