# ComfyUI Performance Optimization Guide

## Overview

This guide covers performance optimization strategies for ComfyUI workflows on
the Lilith platform, including GPU selection, workflow design, caching, and
monitoring.

## GPU Selection

### Available GPU Types

| GPU   | VRAM | Best For                         | Cost  |
| ----- | ---- | -------------------------------- | ----- |
| A4000 | 16GB | Simple workflows, low-res images | $     |
| A5000 | 24GB | Standard SDXL, medium complexity | $$    |
| A6000 | 48GB | High-res, complex workflows      | $$$   |
| A100  | 80GB | Video, extreme complexity        | $$$$  |
| H100  | 80GB | Maximum performance              | $$$$$ |

### GPU Selection Guidelines

```typescript
function selectGPU(workflow: WorkflowRequirements): GPUType {
  const { resolution, complexity, outputType } = workflow;

  // Video always needs A100+
  if (outputType === OutputType.VIDEO) {
    return 'A100';
  }

  // High resolution needs more VRAM
  if (resolution.width >= 2048 || resolution.height >= 2048) {
    return 'A6000';
  }

  // Complex workflows need more compute
  if (complexity === ComplexityLevel.HIGH) {
    return 'A5000';
  }

  // Standard SDXL
  if (resolution.width >= 1024 && complexity === ComplexityLevel.MEDIUM) {
    return 'A5000';
  }

  // Simple workflows
  return 'A4000';
}
```

### VRAM Requirements

| Resolution | Model  | Approx VRAM |
| ---------- | ------ | ----------- |
| 512x512    | SD 1.5 | 4-6 GB      |
| 768x768    | SD 1.5 | 6-8 GB      |
| 1024x1024  | SDXL   | 10-14 GB    |
| 1536x1536  | SDXL   | 16-24 GB    |
| 2048x2048  | SDXL   | 32-48 GB    |

## Workflow Optimization

### 1. Reduce Sampling Steps

Higher step counts improve quality but increase processing time linearly.

```typescript
// Quality vs Speed tradeoffs
const STEP_PRESETS = {
  draft: 15, // Fast preview
  standard: 25, // Good balance
  quality: 35, // High quality
  maximum: 50, // Maximum quality
};

// Most workflows don't need more than 30 steps
builder.setSamplerParams('3', {
  steps: STEP_PRESETS.standard,
  cfg: 7.5,
  sampler: 'euler_ancestral', // Fast sampler
});
```

### 2. Optimize Resolution

Process at minimum needed resolution, then upscale:

```typescript
// Instead of generating at 2048x2048
// Generate at 1024x1024 and upscale

const generateWithUpscale = async (prompt: string) => {
  // Step 1: Generate at lower resolution
  const baseResult = await client.runInference('sd-base', {
    '5': { inputs: { width: 1024, height: 1024 } },
    '6': { inputs: { text: prompt } },
  });

  // Step 2: Upscale 2x
  const upscaledResult = await client.runInference('upscale-4x', {
    '14': { inputs: { image: baseResult.outputs[0].url } },
  });

  return upscaledResult;
};

// Processing time: ~30s + ~15s = 45s
// vs Direct 2048x2048: ~120s
// Quality: Often comparable or better
```

### 3. Choose Fast Samplers

Sampler performance comparison:

| Sampler         | Speed  | Quality   | Best For         |
| --------------- | ------ | --------- | ---------------- |
| euler           | Fast   | Good      | Quick previews   |
| euler_ancestral | Fast   | Good      | Creative variety |
| dpm++ 2m        | Medium | Very Good | General use      |
| dpm++ 2m karras | Medium | Excellent | Quality outputs  |
| ddim            | Fast   | Moderate  | img2img          |
| UniPC           | Fast   | Very Good | Time-sensitive   |

```typescript
// Fast sampler for previews
builder.setSamplerParams('3', {
  sampler: 'euler',
  scheduler: 'normal',
  steps: 15,
});

// Quality sampler for final output
builder.setSamplerParams('3', {
  sampler: 'dpmpp_2m_karras',
  scheduler: 'karras',
  steps: 30,
});
```

### 4. Use Efficient Model Loading

Cache model loads across jobs:

```typescript
// Configure deployment with model preloading
const deployment: DeploymentConfiguration = {
  // ...
  lilithMetadata: {
    preloadModels: [
      'sd_xl_base_1.0.safetensors',
      'spiritual_art_v2.safetensors',
    ],
  },
};
```

### 5. Optimize LoRA Usage

Limit LoRA count and strength:

```typescript
// Single LoRA is faster than stacking
builder.setLora('10', 'spiritual_art_v2.safetensors', 0.7);

// If multiple needed, reduce strengths
// This is slower but sometimes necessary
builder.node('10').setInputs({
  lora_name: 'lora1.safetensors',
  strength_model: 0.5,
  strength_clip: 0.5,
});
builder.node('11').setInputs({
  lora_name: 'lora2.safetensors',
  strength_model: 0.4,
  strength_clip: 0.4,
});
```

## Batch Processing

### Optimal Batch Sizes

```typescript
// Batch size depends on VRAM and resolution
const getOptimalBatchSize = (resolution: number, gpuType: GPUType): number => {
  const vramGB = {
    A4000: 16,
    A5000: 24,
    A6000: 48,
    A100: 80,
    H100: 80,
  }[gpuType];

  // Rough estimates for SDXL
  if (resolution >= 2048) return 1;
  if (resolution >= 1536) return Math.min(2, Math.floor(vramGB / 32));
  if (resolution >= 1024) return Math.min(4, Math.floor(vramGB / 14));
  if (resolution >= 768) return Math.min(8, Math.floor(vramGB / 8));
  return Math.min(16, Math.floor(vramGB / 6));
};

// Use optimal batch
const batchSize = getOptimalBatchSize(1024, 'A5000'); // Returns 4
builder.setBatchSize('5', batchSize);
```

### Parallel Job Processing

```typescript
// Process multiple prompts in parallel
async function generateBatch(prompts: string[]): Promise<JobResult[]> {
  const CONCURRENT_LIMIT = 5;

  const results: JobResult[] = [];
  for (let i = 0; i < prompts.length; i += CONCURRENT_LIMIT) {
    const batch = prompts.slice(i, i + CONCURRENT_LIMIT);

    const batchPromises = batch.map((prompt) =>
      client.runInference('deployment-id', {
        '6': { inputs: { text: prompt } },
        '3': { inputs: { seed: Math.floor(Math.random() * 2147483647) } },
      })
    );

    const batchResults = await Promise.all(batchPromises);
    results.push(...batchResults);
  }

  return results;
}
```

## Caching Strategies

### Result Caching

```typescript
import { createHash } from 'crypto';

class ResultCache {
  private cache: Map<string, CachedResult> = new Map();
  private redis: RedisClient;

  private generateCacheKey(
    deploymentId: string,
    overrides: WorkflowOverrides
  ): string {
    const hash = createHash('sha256');
    hash.update(deploymentId);
    hash.update(JSON.stringify(overrides));
    return hash.digest('hex').substring(0, 32);
  }

  async getCached(
    deploymentId: string,
    overrides: WorkflowOverrides
  ): Promise<JobResult | null> {
    const key = this.generateCacheKey(deploymentId, overrides);

    // Check memory cache first
    const memCached = this.cache.get(key);
    if (memCached && Date.now() < memCached.expiresAt) {
      return memCached.result;
    }

    // Check Redis
    const redisCached = await this.redis.get(`comfyui:${key}`);
    if (redisCached) {
      return JSON.parse(redisCached);
    }

    return null;
  }

  async setCached(
    deploymentId: string,
    overrides: WorkflowOverrides,
    result: JobResult,
    ttlSeconds: number = 86400
  ): Promise<void> {
    const key = this.generateCacheKey(deploymentId, overrides);

    // Memory cache (short TTL)
    this.cache.set(key, {
      result,
      expiresAt: Date.now() + 300000, // 5 minutes
    });

    // Redis cache (long TTL)
    await this.redis.setex(
      `comfyui:${key}`,
      ttlSeconds,
      JSON.stringify(result)
    );
  }
}

// Usage
const cache = new ResultCache(redisClient);

async function generateWithCache(
  deploymentId: string,
  overrides: WorkflowOverrides
): Promise<JobResult> {
  // Check cache first
  const cached = await cache.getCached(deploymentId, overrides);
  if (cached) {
    return cached;
  }

  // Generate
  const result = await client.runInference(deploymentId, overrides);

  // Cache result (only cache successful jobs)
  if (result.status === JobStatus.COMPLETED) {
    await cache.setCached(deploymentId, overrides, result);
  }

  return result;
}
```

### Prompt Template Caching

```typescript
// Pre-compile frequently used prompt templates
const COMPILED_TEMPLATES = new Map<
  string,
  (vars: Record<string, string>) => string
>();

function compileTemplate(
  template: string
): (vars: Record<string, string>) => string {
  const placeholders = template.match(/\{(\w+)\}/g) || [];

  return (vars: Record<string, string>) => {
    let result = template;
    for (const placeholder of placeholders) {
      const key = placeholder.slice(1, -1);
      result = result.replace(placeholder, vars[key] || '');
    }
    return result;
  };
}

// Compile at startup
for (const [id, template] of Object.entries(LILITH_PROMPT_TEMPLATES)) {
  COMPILED_TEMPLATES.set(id, compileTemplate(template.template));
}

// Use compiled template
function applyFastTemplate(
  templateId: string,
  vars: Record<string, string>
): string {
  const compiled = COMPILED_TEMPLATES.get(templateId);
  if (!compiled) throw new Error(`Unknown template: ${templateId}`);
  return compiled(vars);
}
```

## Monitoring & Profiling

### Track Processing Times

```typescript
interface PerformanceMetrics {
  deploymentId: string;
  queueWaitMs: number;
  processingMs: number;
  totalMs: number;
  timestamp: string;
}

class PerformanceTracker {
  private metrics: PerformanceMetrics[] = [];

  async trackJob(
    deploymentId: string,
    runJob: () => Promise<JobResult>
  ): Promise<JobResult> {
    const startTime = Date.now();

    const result = await runJob();

    const metrics: PerformanceMetrics = {
      deploymentId,
      queueWaitMs: result.startedAt
        ? new Date(result.startedAt).getTime() -
          new Date(result.queuedAt).getTime()
        : 0,
      processingMs: result.processingTimeMs || 0,
      totalMs: Date.now() - startTime,
      timestamp: new Date().toISOString(),
    };

    this.metrics.push(metrics);
    this.emitMetrics(metrics);

    return result;
  }

  getAverages(
    deploymentId: string,
    windowMinutes: number = 60
  ): {
    avgQueueWait: number;
    avgProcessing: number;
    avgTotal: number;
    count: number;
  } {
    const cutoff = Date.now() - windowMinutes * 60 * 1000;
    const recent = this.metrics.filter(
      (m) =>
        m.deploymentId === deploymentId &&
        new Date(m.timestamp).getTime() > cutoff
    );

    if (recent.length === 0) {
      return { avgQueueWait: 0, avgProcessing: 0, avgTotal: 0, count: 0 };
    }

    return {
      avgQueueWait:
        recent.reduce((s, m) => s + m.queueWaitMs, 0) / recent.length,
      avgProcessing:
        recent.reduce((s, m) => s + m.processingMs, 0) / recent.length,
      avgTotal: recent.reduce((s, m) => s + m.totalMs, 0) / recent.length,
      count: recent.length,
    };
  }
}
```

### Prometheus Metrics

```typescript
import { Counter, Histogram, Gauge } from 'prom-client';

// Job metrics
const jobDuration = new Histogram({
  name: 'comfyui_job_duration_seconds',
  help: 'Duration of ComfyUI jobs',
  labelNames: ['deployment', 'status'],
  buckets: [5, 15, 30, 60, 120, 300, 600],
});

const jobsTotal = new Counter({
  name: 'comfyui_jobs_total',
  help: 'Total number of ComfyUI jobs',
  labelNames: ['deployment', 'status'],
});

const queueWait = new Histogram({
  name: 'comfyui_queue_wait_seconds',
  help: 'Queue wait time for jobs',
  labelNames: ['deployment'],
  buckets: [1, 5, 10, 30, 60, 120],
});

const activeJobs = new Gauge({
  name: 'comfyui_active_jobs',
  help: 'Currently active jobs',
  labelNames: ['deployment'],
});

// Record metrics
function recordJobMetrics(result: JobResult): void {
  const labels = { deployment: result.deploymentId, status: result.status };

  jobsTotal.inc(labels);

  if (result.processingTimeMs) {
    jobDuration.observe(labels, result.processingTimeMs / 1000);
  }

  if (result.startedAt && result.queuedAt) {
    const wait =
      new Date(result.startedAt).getTime() -
      new Date(result.queuedAt).getTime();
    queueWait.observe({ deployment: result.deploymentId }, wait / 1000);
  }
}
```

## Cost Optimization

### Estimate Costs Before Running

```typescript
function estimateCost(
  deploymentId: string,
  quantity: number = 1
): { credits: number; estimatedTimeSeconds: number } {
  const deployment = registry.getDeployment(deploymentId);
  if (!deployment) {
    throw new Error(`Unknown deployment: ${deploymentId}`);
  }

  return {
    credits: deployment.costPerRun * quantity,
    estimatedTimeSeconds: deployment.estimatedProcessingTime * quantity,
  };
}

// Check before batch processing
const estimate = estimateCost('sacred-mandala-v1', 100);
console.log(`This will cost ${estimate.credits} credits`);
console.log(`Estimated time: ${estimate.estimatedTimeSeconds / 60} minutes`);

if (estimate.credits > user.creditBalance) {
  throw new Error('Insufficient credits');
}
```

### Choose Cost-Effective Deployments

```typescript
function findCheapestDeployment(
  category: WorkflowCategory,
  maxProcessingTime: number
): DeploymentConfiguration | null {
  const candidates = registry
    .getDeploymentsByCategory(category)
    .filter((d) => d.active)
    .filter((d) => d.estimatedProcessingTime <= maxProcessingTime)
    .sort((a, b) => a.costPerRun - b.costPerRun);

  return candidates[0] || null;
}

// Get cheapest option that meets time requirements
const deployment = findCheapestDeployment(
  WorkflowCategory.SACRED_ART,
  120 // Max 2 minutes
);
```

## Queue Management

### Priority Handling

```typescript
function determinePriority(context: {
  userTier: 'free' | 'basic' | 'premium' | 'enterprise';
  isInteractive: boolean;
  batchSize: number;
}): JobPriority {
  // Enterprise users get highest priority
  if (context.userTier === 'enterprise') {
    return JobPriority.URGENT;
  }

  // Interactive requests get high priority
  if (context.isInteractive && context.userTier === 'premium') {
    return JobPriority.HIGH;
  }

  // Large batches get low priority
  if (context.batchSize > 10) {
    return JobPriority.LOW;
  }

  return JobPriority.NORMAL;
}
```

### Queue Position Estimation

```typescript
async function estimateWaitTime(deploymentId: string): Promise<number> {
  const status = await client.getDeploymentStatus(deploymentId);

  // Rough estimate based on queue length and avg processing time
  const metrics = registry.getMetrics(deploymentId);
  const avgProcessing = metrics.avgProcessingTimeMs / 1000;

  return (status.queuedJobs * avgProcessing) / status.currentJobs;
}
```

## Best Practices Summary

1. **Select appropriate GPU** - Don't overpay for simple workflows
2. **Optimize resolution** - Generate smaller, upscale later
3. **Use fast samplers** - euler/euler_ancestral for previews
4. **Keep steps reasonable** - 25-30 is usually sufficient
5. **Cache results** - Especially for common prompts
6. **Monitor metrics** - Track queue times and costs
7. **Batch efficiently** - Process similar jobs together
8. **Handle failures gracefully** - Implement retries and fallbacks

## Related Documentation

- [RunComfy API Client](./runcomfy-api-client.md)
- [Deployment Registry](./deployment-registry.md)
- [Troubleshooting Guide](./troubleshooting.md)
- [Cost Tracking](./cost-tracking.md)
