Migration Wizard

The Migration Wizard guides you through model transitions with analysis, recommendations, and testing tools.

Accessing the Wizard

Via Dashboard

1. Go to Change Management → Migrations
2. Click Start Migration for a deprecating model
3. Or click New Migration for voluntary upgrades

Via API

curl -X POST https://api.gateflow.ai/v1/management/migrations \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source_model": "gpt-4-32k",
    "analyze": true
  }'

Migration Steps

Step 1: Usage Analysis

The wizard analyzes how you use the model:

{
  "migration_id": "mig_abc123",
  "source_model": "gpt-4-32k",
  "analysis": {
    "usage_period": "last_30_days",
    "total_requests": 15420,
    "total_cost": 234.56,
    "avg_input_tokens": 12500,
    "avg_output_tokens": 2100,
    "max_context_used": 28000,
    "features_used": ["chat", "function_calling"],
    "patterns": {
      "long_context": 0.45,
      "short_queries": 0.55
    }
  }
}

Step 2: Replacement Recommendations

Based on your usage, the wizard suggests replacements:

{
  "recommendations": [
    {
      "model": "gpt-4o",
      "score": 95,
      "reasons": [
        "Same capabilities",
        "Larger context (128k vs 32k)",
        "45% cost reduction",
        "Faster inference"
      ],
      "considerations": [
        "Slight output style differences"
      ],
      "estimated_cost_change": -0.45
    },
    {
      "model": "claude-3-5-sonnet",
      "score": 88,
      "reasons": [
        "Similar quality",
        "200k context window",
        "Strong at analysis tasks"
      ],
      "considerations": [
        "Different provider",
        "Slightly higher cost"
      ],
      "estimated_cost_change": 0.12
    }
  ]
}

Step 3: Compatibility Check

Verify the replacement handles your use cases:

curl -X POST https://api.gateflow.ai/v1/management/migrations/mig_abc123/compatibility \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "target_model": "gpt-4o"
  }'

Response:

{
  "compatible": true,
  "checks": [
    {
      "feature": "context_window",
      "status": "pass",
      "detail": "Your max usage (28k) fits in gpt-4o (128k)"
    },
    {
      "feature": "function_calling",
      "status": "pass",
      "detail": "gpt-4o supports function calling"
    },
    {
      "feature": "streaming",
      "status": "pass",
      "detail": "gpt-4o supports streaming"
    }
  ]
}

Step 4: Test Migration

Run sample requests through both models:

curl -X POST https://api.gateflow.ai/v1/management/migrations/mig_abc123/test \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "target_model": "gpt-4o",
    "test_requests": 100,
    "source": "recent_production"
  }'

Response:

{
  "test_id": "test_xyz789",
  "status": "completed",
  "results": {
    "requests_tested": 100,
    "source_model": {
      "model": "gpt-4-32k",
      "avg_latency_ms": 890,
      "avg_cost": 0.0152
    },
    "target_model": {
      "model": "gpt-4o",
      "avg_latency_ms": 456,
      "avg_cost": 0.0084
    },
    "quality_comparison": {
      "semantic_similarity": 0.94,
      "output_length_ratio": 1.02,
      "format_match": 0.98
    },
    "recommendation": "proceed"
  }
}

Step 5: Configure Migration

Set up the migration parameters:

curl -X PATCH https://api.gateflow.ai/v1/management/migrations/mig_abc123 \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "target_model": "gpt-4o",
    "strategy": "canary",
    "canary_percentage": 10,
    "auto_rollback": true,
    "rollback_threshold": {
      "error_rate": 0.05,
      "latency_p99_increase": 2.0
    }
  }'

Step 6: Execute Migration

Start the migration:

curl -X POST https://api.gateflow.ai/v1/management/migrations/mig_abc123/execute \
  -H "Authorization: Bearer gw_prod_admin_key"

Migration Strategies

Instant Switch

All traffic moves immediately:

{
  "strategy": "instant"
}

Best for: Development environments, low-risk migrations.

Canary Deployment

Gradual traffic shift:

{
  "strategy": "canary",
  "canary_percentage": 10,
  "increase_interval_minutes": 60,
  "increase_step": 10
}

Traffic progression: 10% → 20% → 30% → ... → 100%

Best for: Production, risk-averse teams.

Shadow Mode

Run both models, compare results:

{
  "strategy": "shadow",
  "duration_hours": 24
}

Requests go to both models; only source model's response is returned. Results are compared for quality validation.

Best for: High-stakes migrations, validating output quality.

Scheduled

Execute at a specific time:

{
  "strategy": "scheduled",
  "execute_at": "2025-04-15T02:00:00Z"
}

Best for: Planned maintenance windows.

Monitoring Migrations

Migration Status

curl https://api.gateflow.ai/v1/management/migrations/mig_abc123 \
  -H "Authorization: Bearer gw_prod_admin_key"

Response:

{
  "migration_id": "mig_abc123",
  "status": "in_progress",
  "progress": {
    "traffic_on_target": 40,
    "started_at": "2025-04-10T10:00:00Z",
    "estimated_completion": "2025-04-10T16:00:00Z"
  },
  "metrics": {
    "source_error_rate": 0.001,
    "target_error_rate": 0.0008,
    "source_latency_p99": 890,
    "target_latency_p99": 456
  }
}

Migration Events

curl https://api.gateflow.ai/v1/management/migrations/mig_abc123/events \
  -H "Authorization: Bearer gw_prod_admin_key"

Rollback

Manual Rollback

curl -X POST https://api.gateflow.ai/v1/management/migrations/mig_abc123/rollback \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Unexpected output quality issues"
  }'

Automatic Rollback

Configure thresholds:

{
  "auto_rollback": true,
  "rollback_threshold": {
    "error_rate": 0.05,
    "latency_p99_increase": 2.0,
    "quality_score_drop": 0.1
  }
}

Migration Templates

Common migrations have pre-configured settings:

GPT-4-32k to GPT-4o

curl -X POST https://api.gateflow.ai/v1/management/migrations \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "gpt-4-32k-to-gpt-4o"
  }'

Claude 2 to Claude 3

curl -X POST https://api.gateflow.ai/v1/management/migrations \
  -H "Authorization: Bearer gw_prod_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "claude-2-to-claude-3"
  }'

Next Steps

• Automated Fallbacks - Protection during migration
• Zero-Downtime Migrations - Production best practices