Civitai LoRA Training Guide

import {
  LoraTrainingProvider,
  createLoraTrainingProvider,
} from '@oshun/civitai-training';

const training = createLoraTrainingProvider(process.env.CIVITAI_API_KEY);

// Train a character LoRA
const job = await training.trainCharacterLoRA(
  'my-character', // name
  images, // dataset images
  'mycharacter', // trigger word
  { epochs: 15 } // optional customization
);

console.log('Training started:', job.id);
console.log('Estimated cost:', job.cost, 'Buzz');

import type { DatasetImage, DatasetConfig } from '@oshun/civitai-training';

// Prepare images
const images: DatasetImage[] = [
  {
    image: 'https://example.com/image1.jpg', // URL or base64
    caption: 'mycharacter, woman, portrait, looking at camera',
    repeats: 5, // higher repeats for important images
  },
  {
    image: 'https://example.com/image2.jpg',
    caption: 'mycharacter, woman, full body, standing',
    repeats: 3,
  },
  // Add 10-50 images for best results
];

// Dataset configuration
const dataset: DatasetConfig = {
  name: 'my-character-dataset',
  images,
  triggerWord: 'mycharacter',
  classWord: 'woman', // for regularization
  captionMode: 'caption', // 'tag', 'caption', or 'auto'
  autoCaption: false, // use AI captioning
  resolution: 1024, // training resolution
  bucketResolutionSteps: 64, // aspect ratio bucketing
  enableCropping: true,
  flipProbability: 0.5, // horizontal flip augmentation
};

import type { DatasetVideo } from '@oshun/civitai-training';

const videos: DatasetVideo[] = [
  {
    video: 'https://example.com/clip1.mp4',
    caption: 'smooth camera pan, cinematic motion',
    startTime: 0,
    endTime: 4, // seconds
  },
  {
    video: 'https://example.com/clip2.mp4',
    caption: 'zooming in, dynamic movement',
  },
  // Add 10+ clips for motion LoRAs
];

// Train with preset
const job = await training.startTrainingWithPreset(
  'character-sdxl', // preset name
  dataset, // dataset config
  'my-character-lora', // training name
  {
    // Optional: override specific settings
    epochs: 20,
    learningRate: {
      unetLR: 0.00005,
    },
  }
);

// Character SDXL preset configuration
const characterSDXL = {
  network: { rank: 128, alpha: 64, dropout: 0.05 },
  learningRate: {
    unetLR: 0.00007,
    textEncoderLR: 0.000035,
    scheduler: 'cosine_with_warmup',
    warmup: 0.1,
  },
  optimizer: 'AdamW8bit',
  batchSize: 2,
  epochs: 15,
  mixedPrecision: 'bf16',
  gradientCheckpointing: true,
  xformers: true,
};

// Style SDXL preset configuration
const styleSDXL = {
  network: { rank: 32, alpha: 16, dropout: 0.1 },
  learningRate: {
    unetLR: 0.0001,
    textEncoderLR: 0.00005,
    scheduler: 'cosine',
    warmup: 0.05,
  },
  optimizer: 'AdamW8bit',
  batchSize: 4,
  epochs: 10,
  mixedPrecision: 'bf16',
};

import type {
  TrainingConfig,
  TrainingHyperparams,
} from '@oshun/civitai-training';

const hyperparams: TrainingHyperparams = {
  network: {
    rank: 64, // Network dimension (4-256)
    alpha: 32, // Scaling factor (usually rank or rank/2)
    dropout: 0.05, // Dropout for regularization
    convRank: 32, // For LoCon (optional)
    convAlpha: 16, // For LoCon (optional)
  },
  learningRate: {
    unetLR: 0.0001, // U-Net learning rate
    textEncoderLR: 0.00005, // Text encoder learning rate
    scheduler: 'cosine_with_warmup',
    warmup: 0.1, // 10% warmup steps
    minLR: 0.00001, // Minimum LR at end
    numCycles: 1, // For cosine_with_restarts
  },
  optimizer: 'AdamW8bit', // Memory-efficient optimizer
  batchSize: 2,
  epochs: 15,
  maxSteps: undefined, // Override epochs with fixed steps
  gradientAccumulationSteps: 1,
  mixedPrecision: 'bf16', // bf16 for newer GPUs, fp16 otherwise
  gradientCheckpointing: true,
  xformers: true,
  seed: 42,
  cacheLatents: true,
  noiseOffset: 0.1, // For better blacks/whites
  priorPreservationWeight: 1.0, // For DreamBooth
};

const config: TrainingConfig = {
  name: 'my-custom-lora',
  baseModel: 'sdxl',
  trainingType: 'lora',
  dataset,
  hyperparams,
  outputPath: '/trained-loras/',
  callbackUrl: 'https://api.myapp.com/webhooks/training',
  saveEveryNEpochs: 5,
  sampleEveryNEpochs: 5,
  samplePrompts: [
    'mycharacter, portrait, high quality',
    'mycharacter, full body, standing',
  ],
};

const job = await training.startTraining(config);

// Quick character training
const job = await training.trainCharacterLoRA('john-doe', images, 'johndoe', {
  epochs: 20,
  network: { rank: 128 },
});

// Style training with lower rank
const job = await training.trainStyleLoRA(
  'watercolor-style',
  images,
  'watercolor',
  {
    network: { rank: 32 },
  }
);

// Video motion training
const job = await training.trainMotionLoRA(
  'smooth-pan',
  videoClips,
  'smoothpan',
  {
    epochs: 25,
  }
);

// Character for Hunyuan video
const job = await training.trainHunyuanLoRA(
  'my-character-hunyuan',
  images,
  'mychar'
);

// Get job by ID
const job = training.getJob(jobId);

console.log('Status:', job.status);
console.log('Progress:', job.progress?.progress * 100, '%');
console.log('Current epoch:', job.progress?.currentEpoch);
console.log('Current step:', job.progress?.currentStep);
console.log('Loss:', job.progress?.loss.currentLoss);

queued → preparing → training → completed
                             → failed
                             → cancelled

// Listen for training events
training.on('training:started', ({ job }) => {
  console.log('Training started:', job.id);
});

training.on('training:progress', ({ jobId, progress }) => {
  console.log(`${jobId}: ${progress.progress * 100}%`);
  console.log(`Loss: ${progress.loss.currentLoss}`);
  console.log(`ETA: ${progress.estimatedTimeRemaining}s`);
});

training.on('training:sample', ({ jobId, sample }) => {
  console.log(`Sample generated at step ${sample.step}:`);
  console.log(`URL: ${sample.imageUrl}`);
});

training.on('training:checkpoint', ({ jobId, checkpoint }) => {
  console.log(`Checkpoint saved at epoch ${checkpoint.epoch}`);
  console.log(`Download: ${checkpoint.downloadUrl}`);
});

training.on('training:completed', ({ job }) => {
  console.log('Training completed!');
  console.log('LoRA URL:', job.loraUrl);
});

training.on('training:failed', ({ jobId, error }) => {
  console.error('Training failed:', error);
});

const progress = job.progress;

// Loss tracking
console.log('Current loss:', progress.loss.currentLoss);
console.log('Average loss:', progress.loss.averageLoss);
console.log('Best loss:', progress.loss.bestLoss);
console.log('Best loss step:', progress.loss.bestLossStep);

// Loss history
for (const point of progress.loss.lossHistory) {
  console.log(`Step ${point.step}: ${point.loss}`);
}

// Wait with default timeout
const completedJob = await training.waitForTraining(jobId);
console.log('LoRA URL:', completedJob.loraUrl);

// Wait with custom timeout (2 hours)
const job = await training.waitForTraining(jobId, 7200000);

import {
  estimateTrainingCost,
  calculateTotalSteps,
} from '@oshun/civitai-training';

// Calculate total steps
const totalSteps = calculateTotalSteps(
  50, // imageCount
  5, // repeats per image
  2, // batchSize
  15 // epochs
);
// (50 * 5) / 2 * 15 = 1875 steps

// Estimate cost
const cost = estimateTrainingCost('sdxl', totalSteps);
console.log('Estimated cost:', cost, 'Buzz');

import { estimateTrainingTime } from '@oshun/civitai-training';

// Estimate time (default 0.5 steps/second)
const timeSeconds = estimateTrainingTime(1875);
console.log('Estimated time:', timeSeconds / 60, 'minutes');

// With custom speed
const timeWithSpeed = estimateTrainingTime(1875, 0.8);

import { validateDataset } from '@oshun/civitai-training';

const validation = validateDataset(dataset);

if (!validation.valid) {
  console.error('Dataset errors:', validation.errors);
  // [
  //   'Minimum 4 images required for effective training',
  //   'Dataset must contain at least one image or video'
  // ]
}

import { validateHyperparams } from '@oshun/civitai-training';

const validation = validateHyperparams(hyperparams);

if (!validation.valid) {
  console.error('Errors:', validation.errors);
}

if (validation.warnings.length > 0) {
  console.warn('Warnings:', validation.warnings);
  // [
  //   'Alpha is typically equal to or less than rank',
  //   'More than 50 epochs may lead to overfitting'
  // ]
}

import { calculateOptimalLR } from '@oshun/civitai-training';

// Calculate optimal LR based on rank
const optimalLR = calculateOptimalLR(
  128, // rank
  0.0001 // base LR
);
// Scales based on rank^-0.84

await training.cancelJob(jobId);

const allJobs = training.getAllJobs();

for (const job of allJobs) {
  console.log(`${job.id}: ${job.status}`);
  if (job.progress) {
    console.log(`  Progress: ${job.progress.progress * 100}%`);
  }
}

// Download completed LoRA
const { url, filename } = await training.downloadLoRA(jobId);
console.log('Download URL:', url);
console.log('Filename:', filename);

import { LoraTrainingError } from '@oshun/civitai-training';

try {
  const job = await training.startTraining(config);
  const completed = await training.waitForTraining(job.id);
} catch (error) {
  if (error instanceof LoraTrainingError) {
    switch (error.code) {
      case 'INSUFFICIENT_BUZZ':
        console.error('Not enough Buzz. Please top up.');
        break;
      case 'INVALID_DATASET':
        console.error('Dataset issues:', error.details);
        break;
      case 'TRAINING_FAILED':
        console.error('Training failed:', error.message);
        break;
      default:
        console.error('Error:', error.message);
    }
  }
}

// Graceful shutdown - cancels running jobs
await training.shutdown();

import type {
  // Dataset Types
  DatasetImage,
  DatasetVideo,
  DatasetConfig,
  DatasetStats,

  // Training Configuration
  TrainingConfig,
  TrainingHyperparams,
  NetworkParams,
  LearningRateParams,

  // Base Models
  TrainingBaseModel,
  TrainingType,
  TrainingPreset,

  // Job Types
  TrainingJob,
  TrainingStatus,
  TrainingProgress,

  // Progress Types
  LossMetrics,
  TrainingSample,
  TrainingCheckpoint,

  // Configuration
  LoraTrainingConfig,
  OptimizerType,
  LRScheduler,
  CaptionMode,
} from '@oshun/civitai-training';