FLUX LoRA Training - RunPod Serverless Template

🚀 Production-ready serverless endpoint for FLUX LoRA training on RunPod GPU pods

This template provides a complete serverless solution for training custom FLUX LoRA models using RunPod's GPU infrastructure. Optimized for 24GB VRAM with FluxGym-inspired settings and intelligent image captioning.

🔧 Quick Deployment

1. Deploy to RunPod Serverless

1. Fork/Clone this repository to your GitHub account
2. Go to RunPod Dashboard → Serverless → Templates
3. Create New Template:
   • Template Name: flux-lora-trainer
   • Template Type: Serverless
   • Container Registry: Docker Hub or GitHub Container Registry
   • Repository: 101world/Ray-Train-Master
   • Docker Build Context: flux-runpod-template/
   • Docker File Path: flux-runpod-template/Dockerfile

2. Configure Environment Variables

Set these in your RunPod template configuration:

Required Variables:

AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key  
S3_BUCKET_NAME=your_bucket_name
AWS_S3_ENDPOINT_URL=https://your-s3-endpoint.com
AWS_DEFAULT_REGION=us-east-1

Optional Variables:

TRAINING_STEPS=1000
LEARNING_RATE=8e-4
NETWORK_DIM=4
BATCH_SIZE=1
VRAM=24G

3. GPU Configuration

Recommended GPU Settings:

• Minimum VRAM: 20GB (RTX 4090, A100)
• Preferred VRAM: 24GB+ (RTX 4090, A6000, A100)
• Container Disk: 50GB minimum
• Timeout: 2 hours (7200 seconds)

📡 API Usage

Endpoint Request Format

POST https://api.runpod.ai/v2/your-endpoint-id/runsync
Content-Type: application/json
Authorization: Bearer YOUR_RUNPOD_API_KEY

{
  "input": {
    "dataset_s3_key": "datasets/character-photos.zip",
    "character_name": "alice_wonderland",  
    "trigger_word": "alice",
    "config": {
      "learning_rate": "8e-4",
      "max_train_epochs": 16,
      "network_dim": 4,
      "vram": "24G"
    }
  }
}

Successful Response

{
  "id": "job-12345",
  "status": "COMPLETED",
  "output": {
    "status": "success",
    "character_name": "alice_wonderland",
    "trigger_word": "alice", 
    "image_count": 25,
    "model_s3_key": "models/alice_wonderland/flux_lora_job-12345.safetensors",
    "download_url": "https://presigned-url-to-download",
    "job_id": "job-12345",
    "training_time": 1694123456
  }
}

🛠 Integration Examples

JavaScript/TypeScript (Any Frontend)

async function trainFluxModel(apiKey, endpointId, dataset) {
  const response = await fetch(`https://api.runpod.ai/v2/${endpointId}/runsync`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`
    },
    body: JSON.stringify({
      input: {
        dataset_s3_key: dataset.s3Key,
        character_name: dataset.characterName,
        trigger_word: dataset.triggerWord,
        config: {
          learning_rate: "8e-4",
          max_train_epochs: 16,
          network_dim: 4,
          vram: "24G"
        }
      }
    })
  });
  
  return await response.json();
}

Python Backend Integration

import requests

def train_flux_model(api_key, endpoint_id, dataset_config):
    url = f"https://api.runpod.ai/v2/{endpoint_id}/runsync"
    
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}"
    }
    
    payload = {
        "input": {
            "dataset_s3_key": dataset_config["s3_key"],
            "character_name": dataset_config["character_name"],
            "trigger_word": dataset_config["trigger_word"],
            "config": {
                "learning_rate": "8e-4",
                "max_train_epochs": 16,
                "network_dim": 4,
                "vram": "24G"
            }
        }
    }
    
    response = requests.post(url, json=payload, headers=headers)
    return response.json()

🔧 Configuration Options

VRAM Optimization Levels

Training Parameters

🎯 Features

• ✅ Florence-2 Large Captioning: Intelligent image description generation
• ✅ VRAM Optimized: Supports 12GB to 24GB+ configurations
• ✅ FluxGym Settings: Battle-tested training parameters
• ✅ Multiple Storage: AWS S3, Cloudflare R2, MinIO support
• ✅ Robust Error Handling: Comprehensive logging and cleanup
• ✅ Production Timeouts: 2-hour training, 30-min upload limits
• ✅ Auth Agnostic: Works with any authentication system

🔒 Security & Storage

Supported Storage Providers

• AWS S3: Standard S3 buckets
• Cloudflare R2: Cost-effective S3-compatible
• MinIO: Self-hosted S3-compatible
• Custom S3: Any S3-compatible service

Environment Variables Security

Store sensitive credentials in RunPod's secure environment variable system:

# In RunPod Dashboard -> Template -> Environment Variables
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=secret123...
S3_BUCKET_NAME=my-flux-training

📊 Monitoring & Logs

View Training Progress

Check RunPod logs for real-time training progress:

1. Go to RunPod Dashboard → Serverless → Logs
2. Filter by your endpoint ID
3. Monitor training stages:
   • Dataset download and validation
   • Florence-2 captioning progress
   • FLUX model loading
   • Training epochs and loss
   • Model upload completion

Common Log Messages

[INFO] Starting training job job-12345 for character 'alice' with trigger 'alice'
[INFO] Dataset extracted: 25 images found
[INFO] Starting FLUX LoRA training with 7200s timeout...
[INFO] Training completed successfully
[INFO] Model upload completed successfully

🚨 Troubleshooting

Common Issues & Solutions

Error Response Format

{
  "status": "error",
  "error": "Training timed out after 120 minutes",
  "job_id": "job-12345",
  "error_time": 1694123456
}

🔄 Deployment Updates

Update Your Template

1. Push changes to your repository
2. Rebuild template in RunPod dashboard
3. Update endpoint to use new template version

Version Management

Use git tags for production deployments:

git tag v1.0.0
git push origin v1.0.0

📚 Additional Resources

• VARIABLES.md - Complete environment variable reference
• SETUP.md - Detailed setup instructions
• test_endpoint.py - Local testing script
• Architecture Diagram - System architecture overview

🤝 Support

For issues and questions:

1. Check the troubleshooting section above
2. Review RunPod logs for detailed error messages
3. Ensure all environment variables are correctly set
4. Verify your dataset format matches requirements

---

⚡ Ready to deploy? Follow the Quick Deployment section above to get your FLUX LoRA training endpoint running in minutes!