Skip to content

MULTI_PROVIDER_GUIDE.md

Latest commit

 

History

History
356 lines (284 loc) · 7.89 KB

MULTI_PROVIDER_GUIDE.md

File metadata and controls

356 lines (284 loc) · 7.89 KB
Raw

Multi-Provider AI Image Generation System

🎯 Overview

This system provides a unified interface for generating AI images across multiple providers, with automatic fallback and load balancing capabilities. Currently supports:

  • Runware - High-quality, fast image generation (paid)
  • AI Horde - Free, community-driven image generation

🚀 Quick Start

1. Setup API Keys

Option A: Using the Setup Script

python setup_ai_horde.py

Option B: Manual Configuration

Edit config/providers.json:

{
  "providers": {
    "runware": {
      "api_key": "your_runware_api_key_here"
    },
    "ai_horde": {
      "api_key": "your_ai_horde_api_key_here"
    }
  }
}

Option C: Environment Variables

export RUNWARE_API_KEY="your_runware_api_key"
export AI_HORDE_API_KEY="your_ai_horde_api_key"

2. Test the System

python test_multi_provider.py

3. Generate NFT Collections

python nft_collection_generator.py --theme pepe_frog --subject "Pepe the Frog" --count 10

🏗️ Architecture

Core Components

  1. ProviderManager - Orchestrates multiple AI providers
  2. AIProvider - Abstract base class for all providers
  3. RunwareProvider - Runware API implementation
  4. AIHordeProvider - AI Horde API implementation
  5. GenerationRequest - Standardized request format
  6. GenerationResult - Standardized result format

Provider Configuration

{
  "primary_provider": "runware",
  "fallback_providers": ["ai_horde"],
  "providers": {
    "runware": {
      "enabled": true,
      "api_key": "your_key",
      "priority": 1,
      "max_concurrent": 4,
      "models": {
        "default": "runware:97@2",
        "anime": "civitai:102438@133677"
      }
    },
    "ai_horde": {
      "enabled": true,
      "api_key": "your_key",
      "priority": 2,
      "max_concurrent": 2,
      "models": {
        "default": "stable_diffusion",
        "anime": "stable_diffusion_xl"
      }
    }
  }
}

🔧 Usage Examples

Basic Image Generation

from ai_providers import ProviderManager, GenerationRequest

# Initialize with config
config = {
    "primary_provider": "ai_horde",
    "ai_horde": {"api_key": "your_key"}
}
manager = ProviderManager(config)

# Generate single image
request = GenerationRequest(
    prompt="A cute cat wearing a wizard hat",
    width=512,
    height=512,
    steps=20
)

result = await manager.generate_single_image(request)
if result.success:
    print(f"Generated: {result.local_path}")

NFT Collection Generation

from nft_collection_generator import NFTCollectionGenerator

# Initialize with provider config
generator = NFTCollectionGenerator()

# Generate collection
collection_path = await generator.generate_collection(
    theme="pepe_frog",
    subject="Pepe the Frog",
    collection_name="My Pepe Collection",
    count=10,
    ollama_model="llama3.2:latest"
)

🎨 Provider Features

Runware

  • Speed: Sub-second inference times
  • Quality: High-quality models (FLUX, Stable Diffusion)
  • Cost: Pay-per-use credits
  • Models: Custom models via CivitAI
  • Features: Upscaling, background removal, ControlNet

AI Horde

  • Cost: Free (community-driven)
  • Models: 166+ models available
  • Speed: Variable (depends on available workers)
  • Features: Text-to-image, image-to-image, inpainting
  • Community: Volunteer workers

🔄 Fallback Strategy

The system automatically handles provider failures:

  1. Primary Provider: Tries the configured primary provider first
  2. Fallback Providers: If primary fails, tries fallback providers in order
  3. Error Handling: Graceful degradation with detailed error reporting
  4. Retry Logic: Configurable retry attempts per provider

Fallback Configuration

{
  "fallback_strategy": {
    "enable_fallback": true,
    "fallback_on_credits": true,
    "fallback_on_error": true,
    "fallback_on_timeout": true,
    "max_fallback_attempts": 2
  }
}

📊 Monitoring & Statistics

The system tracks comprehensive statistics:

# Provider usage statistics
stats = {
    "provider_usage": {
        "runware": 5,
        "ai_horde": 3
    },
    "generation_times": [2.1, 1.8, 3.2],
    "failed_generations": 1,
    "total_images_generated": 8
}

🛠️ Configuration Options

Global Settings

{
  "global_settings": {
    "max_retries": 3,
    "retry_delay": 5,
    "timeout": 300,
    "image_format": "webp",
    "image_quality": 95,
    "save_metadata": true,
    "output_directory": "generated_images"
  }
}

Rate Limiting

{
  "rate_limit": {
    "requests_per_minute": 60,
    "requests_per_hour": 1000
  }
}

Load Balancing

{
  "load_balancing": {
    "enable_load_balancing": false,
    "strategy": "round_robin",
    "weight_runware": 70,
    "weight_ai_horde": 30
  }
}

🔍 Troubleshooting

Common Issues

  1. "All providers failed"

    • Check API keys are valid
    • Verify network connectivity
    • Check provider status pages

  2. "insufficientCredits" (Runware)

    • Add credits to your Runware account
    • Switch to AI Horde as primary provider

  3. "No workers available" (AI Horde)

  4. Slow generation times

    • AI Horde depends on volunteer workers
    • Consider using Runware for faster results

Debug Mode

Enable detailed logging:

import logging
logging.basicConfig(level=logging.DEBUG)

Provider Status Check

# Check all provider status
credits = await manager.check_all_credits()
models = await manager.get_available_models()

📁 File Structure

runware/
├── ai_providers.py              # Multi-provider system
├── config/
│   └── providers.json           # Provider configuration
├── nft_collection_generator.py  # NFT collection generator
├── test_multi_provider.py       # Test suite
├── setup_ai_horde.py           # AI Horde setup script
└── generated_images/            # Output directory
    ├── 001.webp
    ├── 002.webp
    └── ...

🚀 Advanced Features

Custom Provider Integration

To add a new provider:

  1. Create a new class inheriting from AIProvider

  2. Implement required methods:

    • connect()
    • disconnect()
    • generate_single_image()
    • generate_batch()
    • get_available_models()
    • check_credits()

  3. Add provider configuration to providers.json

  4. Update ProviderManager to include the new provider

Batch Processing

# Generate multiple images efficiently
requests = [
    GenerationRequest(prompt="Cat 1", width=512, height=512),
    GenerationRequest(prompt="Cat 2", width=512, height=512),
    GenerationRequest(prompt="Cat 3", width=512, height=512)
]

results = await manager.generate_batch(requests)

Model Selection

# Use specific models per provider
request = GenerationRequest(
    prompt="Anime style cat",
    model="stable_diffusion_xl",  # AI Horde model
    width=1024,
    height=1024
)

💡 Best Practices

  1. API Key Security: Use environment variables for production
  2. Rate Limiting: Respect provider rate limits
  3. Error Handling: Always check result.success
  4. Resource Management: Disconnect providers when done
  5. Monitoring: Track usage and costs
  6. Fallback Strategy: Configure multiple providers for reliability

🔗 Useful Links

📝 Changelog

v1.0.0 - Multi-Provider System

  • ✅ Added AI Horde provider
  • ✅ Implemented fallback strategy
  • ✅ Added provider management
  • ✅ WEBP image optimization
  • ✅ Comprehensive error handling
  • ✅ Usage statistics tracking