Model Redirect
Model redirect allows you to transparently map model names in requests to other models without modifying client code, enabling version management, flexible switching, and access control.
Core Value
Version Management
Centrally manage model versions and switch globally used model versions with one click
Flexible Switching
Freely switch between different providers or models with similar capabilities, maintaining business continuity
Simplified Naming
Create memorable aliases for complex model version numbers
Access Control
Strictly limit available model scope through whitelist mode
Configuration Guide
Configuration Location
- Log in to GPT-Load admin console
- Navigate to "Group Management" page
- Click "Edit" button for the target group
- Find "Model Redirect Rules" configuration area in the form
Configuration Format
⚠️ Important Note
In JSON configuration, key is the available model name for users (after redirect), value is the actual model name requested to upstream
{
"gpt-4": "gpt-4-turbo-2024-04-09",
"gpt-4o": "gpt-4o-2024-05-13",
"claude-opus": "claude-3-opus-20240229"
}Configuration Effect:
- Client requests gpt-4 → Actually calls gpt-4-turbo-2024-04-09
- Client requests gpt-4o → Actually calls gpt-4o-2024-05-13
- Client requests gpt-3.5-turbo → Directly passed through (not configured)
Policy Modes
Loose Mode (Default)
Configured models are redirected, unconfigured models are passed through to upstream service. Suitable for general proxy scenarios, maintaining maximum compatibility.
Configuration rule: {"gpt-4": "gpt-4-turbo"}
gpt-4 → gpt-4-turbo (redirect)
gpt-3.5-turbo → gpt-3.5-turbo (pass-through)
claude-3 → claude-3 (pass-through)
Strict Mode
Only allows source model names in configuration rules, unconfigured model requests return 400 error. Suitable for whitelist control and strict cost management.
Configuration rule: {"allowed-model": "gpt-4-turbo"}
allowed-model → gpt-4-turbo (redirect)
gpt-4 → 400 error ❌
gpt-3.5-turbo → 400 error ❌
Typical Use Cases
Scenario 1: Unified Model Version Management
Multiple internal projects use gpt-4, need to uniformly upgrade to the latest version. No need to modify project code, centrally switch versions at proxy layer.
{
"gpt-4": "gpt-4-turbo-2024-04-09",
"gpt-4-32k": "gpt-4-turbo-2024-04-09"
}Scenario 2: Flexible Provider Switching
Switch between models with similar capabilities from different providers, or dynamically adjust based on availability, region, etc. Seamless migration while maintaining business continuity.
{
"gpt-4": "claude-3-opus-20240229",
"default-chat": "gemini-2.0-flash"
}Scenario 3: Creating Short Aliases
Simplify complex model version numbers to improve development experience. Cleaner client code, only need to modify configuration when upgrading versions.
{
"gpt5": "gpt-5-2025-08-07",
"flash": "gemini-2.5-flash-preview",
"opus": "claude-3-opus-20240229"
}Scenario 4: Aggregate Groups Model Unification
When aggregate groups contain sub-groups of the same channel type but connecting to different service providers, configure model redirect in each sub-group to allow clients to use a unified model name across different providers.
Sub-group A (OpenAI Official): {"gpt-4": "gpt-4-turbo"}
Sub-group B (Azure OpenAI): {"gpt-4": "gpt-35-turbo"}
Sub-group C (OpenRouter): {"gpt-4": "openai/gpt-4-turbo"}Important Notes
Configuration Limitations
- • Aggregate groups themselves don't support model redirect, but their sub-groups (standard groups) do
- • Must be valid JSON format
- • Keys and values must be non-empty strings
- • Regular expressions or wildcards not supported
Usage Recommendations
- • Recommend loose mode for production environments
- • Use strict mode in test environments to control costs
- • Regularly audit redirect logs
- • Clean up expired redirect rules promptly
Feature Summary
Model redirect executes transparently in the request chain, imperceptible to clients. Configuration supports hot updates without service restart.