深入LiteLLM架构：Router系统与智能路由策略
项目地址: https://gitcode.com/GitHub_Trending/li/litellm LiteLLM的Router系统是其核心组件，作为统一的LLM网关，负责智能地管理和路由LLM API请求到不同的模型部署。该系统通过模块化架构实现了多模型管理、智能路由、故障转移和性能优化等关键功能，包括Router主类、双级缓存系统(DualCache)、多种路由策略体系以及严格的请求处理流程，确保高可用性和性能。
LiteLLM Router系统架构解析
LiteLLM的Router系统是其核心组件之一，负责智能地管理和路由LLM API请求到不同的模型部署。作为一个统一的LLM网关，Router系统通过精心设计的架构实现了多模型管理、智能路由、故障转移和性能优化等关键功能。
核心架构设计
LiteLLM Router采用模块化的设计理念，将路由功能分解为多个独立的组件，每个组件负责特定的职责：
核心组件详解
1. Router主类
Router类是系统的入口点，负责初始化和管理所有路由组件：
class Router:
def __init__(
self,
model_list: Optional[List[DeploymentTypedDict]] = None,
redis_url: Optional[str] = None,
cache_responses: Optional[bool] = False,
routing_strategy: Literal[
"simple-shuffle", "least-busy", "usage-based-routing",
"latency-based-routing", "cost-based-routing", "usage-based-routing-v2"
] = "simple-shuffle",
num_retries: Optional[int] = None,
timeout: Optional[float] = None,
# ... 其他参数
):
# 初始化缓存系统
self.cache = self._initialize_cache(redis_url, redis_host, redis_port)
# 初始化路由策略
self.routing_strategy = self._initialize_routing_strategy(
routing_strategy, routing_strategy_args
)
# 初始化部署列表
self.model_names = self._process_model_list(model_list)
# 初始化调度器
self.scheduler = Scheduler(polling_interval, default_priority)
2. 缓存系统 (DualCache)
Router使用双级缓存架构，结合内存缓存和Redis缓存：
class DualCache:
def __init__(self, redis_url=None, redis_host=None, redis_port=None):
self.memory_cache = InMemoryCache()
if redis_url or redis_host:
self.redis_cache = RedisCache(redis_url, redis_host, redis_port)
else:
self.redis_cache = None
async def async_get(self, key: str) -> Optional[Any]:
# 首先检查内存缓存
result = self.memory_cache.get(key)
if result is not None:
return result
# 然后检查Redis缓存
if self.redis_cache:
result = await self.redis_cache.async_get(key)
if result is not None:
# 回填到内存缓存
self.memory_cache.set(key, result)
return result
return None
3. 路由策略体系
LiteLLM提供了多种路由策略，每种策略针对不同的使用场景：
| 策略类型 | 描述 | 适用场景 |
|---|---|---|
| Simple Shuffle | 简单随机轮询 | 基础负载均衡 |
| Least Busy | 最少繁忙路由 | 实时性能优化 |
| Lowest TPM/RPM | 最低使用率路由 | 配额管理 |
| Lowest Latency | 最低延迟路由 | 响应时间敏感 |
| Lowest Cost | 最低成本路由 | 成本优化 |
# 最低TPM路由策略示例
class LowestTPMLoggingHandler:
def __init__(self, router_cache: DualCache, model_list: list):
self.cache = router_cache
self.model_list = model_list
async def async_get_available_deployments(
self,
model_group: str,
healthy_deployments: list,
messages: Optional[List[Dict[str, str]]] = None,
input: Optional[Union[str, List]] = None,
):
# 获取所有部署的当前TPM使用情况
tpm_keys = [f"{deployment['model_name']}:tpm" for deployment in healthy_deployments]
tpm_values = await self.cache.async_batch_get(tpm_keys)
# 选择TPM使用率最低的部署
available_deployments = []
for deployment, tpm_value in zip(healthy_deployments, tpm_values):
if tpm_value is None or tpm_value < deployment.get('tpm_limit', float('inf')):
available_deployments.append(deployment)
return available_deployments
请求处理流程
Router系统的请求处理遵循严格的流程，确保高可用性和性能：
4. 故障转移与重试机制
Router系统内置了强大的故障转移和重试机制：
class Router:
async def _async_completion_with_retries(
self,
model: str,
messages: List[Dict[str, str]],
**kwargs
):
retries = kwargs.get('num_retries', self.num_retries)
fallbacks = kwargs.get('fallbacks', [])
for attempt in range(retries + 1):
try:
deployment = await self._select_deployment(model, messages, kwargs)
response = await self._call_deployment(deployment, messages, kwargs)
# 记录成功指标
await self.routing_strategy.async_log_success_event(
kwargs, response, start_time, time.time()
)
return response
except Exception as e:
if attempt == retries:
# 尝试所有回退模型
for fallback_model in fallbacks:
try:
return await self._async_completion_with_retries(
fallback_model, messages,
**{**kwargs, 'num_retries': 0}
)
except Exception:
continue
raise
# 等待重试间隔
await asyncio.sleep(self.retry_after * (2 ** attempt))
5. 统计指标收集
Router系统实时收集各种性能指标，用于智能路由决策：
class RouterMetrics:
def __init__(self, cache: DualCache):
self.cache = cache
async def track_deployment_metrics(
self,
deployment: Dict,
response: ModelResponse,
start_time: float,
end_time: float
):
model_name = deployment['model_name']
latency = end_time - start_time
token_usage = response.usage.total_tokens if response.usage else 0
# 更新TPM/RPM指标
tpm_key = f"{model_name}:tpm"
rpm_key = f"{model_name}:rpm"
await self.cache.async_increment(tpm_key, token_usage, ttl=60)
await self.cache.async_increment(rpm_key, 1, ttl=60)
# 更新延迟指标
latency_key = f"{model_name}:latency"
await self.cache.async_set(
latency_key,
latency,
ttl=300 # 5分钟窗口
)
配置与管理
Router系统支持灵活的配置选项，可以通过代码或配置文件进行管理：
# 示例配置
router_config = {
"model_list": [
{
"model_name": "gpt-4",
"litellm_params": {
"model": "openai/gpt-4",
"api_key": os.getenv("OPENAI_API_KEY")
},
"tpm_limit": 10000,
"rpm_limit": 100
},
{
"model_name": "claude-sonnet",
"litellm_params": {
"model": "anthropic/claude-sonnet-4-20250514",
"api_key": os.getenv("ANTHROPIC_API_KEY")
},
"tpm_limit": 15000,
"rpm_limit": 120
}
],
"routing_strategy": "lowest-latency",
"cache_responses": True,
"redis_url": "redis://localhost:6379",
"num_retries": 2,
"timeout": 30.0
}
# 初始化Router
router = Router(**router_config)
通过这种架构设计，LiteLLM Router系统能够有效地管理多个LLM提供商和模型部署，提供高性能、高可用的LLM服务网关。其模块化的设计使得系统易于扩展和维护，同时提供了丰富的配置选项来满足不同场景的需求。
多模型负载均衡与故障转移机制
LiteLLM的Router系统提供了强大的多模型负载均衡和智能故障转移能力，让企业能够构建高可用、高性能的LLM应用架构。本节将深入探讨其核心机制、实现原理和最佳实践。
负载均衡策略体系
LiteLLM支持多种负载均衡策略，每种策略针对不同的业务场景优化：
1. 最少繁忙策略 (Least-Busy)
最少繁忙策略基于实时请求流量进行智能分发，确保系统负载均衡：
from litellm import Router
# 配置最少繁忙路由策略
model_list = [
{"model_name": "gpt-4", "litellm_params": {"model": "openai/gpt-4"}},
{"model_name": "claude-3", "litellm_params": {"model": "anthropic/claude-3"}},
{"model_name": "llama-3", "litellm_params": {"model": "replicate/llama-3"}}
]
router = Router(
model_list=model_list,
routing_strategy="least-busy",
num_retries=3,
timeout=30.0
)
实现机制：
- 实时追踪每个部署的请求计数
- 通过缓存系统维护请求状态
- 选择当前请求数最少的部署
- 支持同步和异步请求处理
2. 延迟优化策略 (Latency-Based)
基于历史延迟数据进行智能路由选择：
router = Router(
model_list=model_list,
routing_strategy="latency-based-routing",
routing_strategy_args={
"history_size": 100, # 保留最近100次请求的延迟数据
"decay_factor": 0.9, # 历史数据衰减因子
"warmup_requests": 10 # 预热请求数量
}
)
3. 成本优化策略 (Cost-Based)
根据模型定价进行成本最优路由：
router = Router(
model_list=model_list,
routing_strategy="cost-based-routing",
routing_strategy_args={
"budget_limit": 100.0, # 月度预算限制
"cost_preference": 0.7 # 成本偏好权重(0-1)
}
)
故障转移与重试机制
LiteLLM的故障转移系统设计精巧，确保服务的高可用性：
1. 智能重试策略
router = Router(
model_list=model_list,
num_retries=3, # 最大重试次数
retry_after=2, # 重试等待时间(秒)
max_fallbacks=2, # 最大回退次数
cooldown_time=60, # 冷却时间(秒)
allowed_fails=5 # 允许的失败次数
)
2. 异常处理与冷却机制
系统根据异常类型智能决定是否触发冷却：
| 异常类型 | HTTP状态码 | 是否触发冷却 | 冷却时间 |
|---|---|---|---|
| 速率限制 | 429 | ✅ | 动态调整 |
| 认证错误 | 401 | ✅ | 300秒 |
| 超时错误 | 408 | ✅ | 60秒 |
| 资源不存在 | 404 | ✅ | 300秒 |
| 客户端错误 | 4xx | ❌ | - |
| 服务器错误 | 5xx | ✅ | 120秒 |
def _is_cooldown_required(exception_status: Union[str, int], exception_str: str) -> bool:
"""判断是否需要触发冷却机制"""
if exception_status == 429: # 速率限制
return True
elif exception_status == 401: # 认证错误
return True
elif exception_status == 408: # 超时
return True
elif exception_status == 404: # 资源不存在
return True
elif exception_status >= 500: # 服务器错误
return True
return False
3. 部署健康检查
系统实时监控部署健康状况：
async def _async_get_healthy_deployments(
self, model: str, parent_otel_span: Optional[Span]
) -> Tuple[List[Dict], List[Dict]]:
"""获取健康部署列表"""
# 过滤处于冷却状态的部署
cooldown_deployments = await self._async_get_cooldown_deployments(parent_otel_span)
healthy_deployments = [
d for d in all_deployments
if d["model_info"]["id"] not in cooldown_deployments
]
return healthy_deployments, all_deployments
性能指标监控
LiteLLM提供详细的性能监控指标：
| 指标类型 | 监控内容 | 应用场景 |
|---|---|---|
| 请求成功率 | 成功/失败请求比例 | 服务质量评估 |
| 平均延迟 | 请求处理时间 | 性能优化 |
| 吞吐量 | TPM/RPM限制 | 容量规划 |
| 错误分布 | 异常类型统计 | 故障诊断 |
| 成本统计 | 按模型成本分析 | 预算管理 |
# 性能监控数据示例
performance_metrics = {
"success_rate": 0.98,
"avg_latency_ms": 1250,
"current_tpm": 45000,
"error_breakdown": {
"rate_limit": 12,
"timeout": 5,
"auth_error": 2,
"server_error": 8
},
"cost_analysis": {
"gpt-4": 45.67,
"claude-3": 32.15,
"llama-3": 12.43
}
}
高级配置选项
1. 自定义重试策略
from litellm.types import RetryPolicy
custom_retry_policy = RetryPolicy(
max_retries=5,
backoff_factor=2.0,
retryable_status_codes=[429, 500, 503],
retryable_exceptions=[TimeoutError, ConnectionError]
)
router = Router(
model_list=model_list,
retry_policy=custom_retry_policy,
model_group_retry_policy={
"gpt-4": RetryPolicy(max_retries=3),
"claude-3": RetryPolicy(max_retries=5)
}
)
2. 智能回退配置
router = Router(
model_list=model_list,
fallbacks=["gpt-4", "claude-3", "llama-3"], # 主回退链
context_window_fallbacks=["claude-3", "gpt-4"], # 上下文长度回退
content_policy_fallbacks=["llama-3", "claude-3"] # 内容策略回退
)
最佳实践建议
- 多区域部署：在不同地理区域部署模型副本，减少网络延迟
- 混合提供商：组合使用多个LLM提供商，避免单点故障
- 渐进式回退：从高性能模型开始，逐步回退到经济型模型
- 监控告警：设置合理的监控阈值和告警机制
- 容量规划：基于历史数据预测资源需求，提前扩容
# 多区域部署配置示例
multi_region_config = [
{
"model_name": "gpt-4",
"litellm_params": {
"model": "openai/gpt-4",
"api_base": "https://api.us-east-1.openai.com"
},
"region": "us-east-1"
},
{
"model_name": "gpt-4",
"litellm_params": {
"model": "openai/gpt-4",
"api_base": "https://api.eu-west-1.openai.com"
},
"region": "eu-west-1"
}
]
通过这套完善的负载均衡和故障转移机制，LiteLLM能够为企业级应用提供99.9%以上的服务可用性，同时优化成本和性能表现。
智能路由策略配置与优化
LiteLLM的智能路由系统提供了多种路由策略，每种策略针对不同的业务场景和性能需求进行了优化。通过合理的配置和调优，可以实现高效的模型部署管理和资源利用率最大化。
路由策略类型及适用场景
LiteLLM支持以下主要路由策略：
| 策略类型 | 标识符 | 适用场景 | 核心优势 |
|---|---|---|---|
| 简单轮询 | simple-shuffle | 基础负载均衡 | 实现简单，无状态 |
| 最低负载 | least-busy | 实时流量分发 | 动态负载均衡 |
| 基于用量路由 | usage-based-routing | TPM/RPM限制管理 | 精确用量控制 |
| 基于用量路由v2 | usage-based-routing-v2 | 分布式环境用量控制 | 跨实例一致性 |
| 基于延迟路由 | latency-based-routing | 性能敏感应用 | 响应时间优化 |
| 基于成本路由 | cost-based-routing | 成本控制场景 | 费用最小化 |
路由策略配置详解
1. 基于用量的路由策略（TPM/RPM）
基于用量的路由策略是LiteLLM中最常用的智能路由方式，支持两种版本：
from litellm import Router
# 使用usage-based-routing-v2（推荐用于生产环境）
router = Router(
model_list=[...],
routing_strategy="usage-based-routing-v2",
routing_strategy_args={"ttl": 60} # 缓存过期时间（秒）
)
# 使用usage-based-routing（传统版本）
router = Router(
model_list=[...],
routing_strategy="usage-based-routing"
)
v2版本的核心改进：
- 跨实例的用量一致性保证
- 批量Redis操作优化性能
- 更精确的用量统计和限制检查
2. 最低延迟路由策略
对于对响应时间敏感的应用，最低延迟路由策略能够自动选择历史延迟最低的部署：
router = Router(
model_list=[...],
routing_strategy="latency-based-routing",
routing_strategy_args={
"window_size": 100, # 统计窗口大小
"weight": 0.7 # 最新延迟的权重
}
)
3. 最低成本路由策略
成本优化场景下，可以选择最低成本路由策略：
router = Router(
model_list=[...],
routing_strategy="cost-based-routing"
)
路由策略性能优化
缓存配置优化
router = Router(
model_list=[...],
redis_url="redis://localhost:6379",
cache_kwargs={
"socket_timeout": 5,
"socket_connect_timeout": 5,
"retry_on_timeout": True,
"max_connections": 100
}
)
并发控制配置
router = Router(
model_list=[...],
default_max_parallel_requests=50, # 默认最大并发数
cooldown_time=30, # 失败部署冷却时间
allowed_fails=3 # 允许失败次数
)
高级路由配置示例
混合路由策略
通过组合不同的路由策略，可以实现更复杂的路由逻辑：
class HybridRoutingStrategy:
def __init__(self, router):
self.router = router
self.cost_strategy = LowestCostLoggingHandler(router.router_cache, router.model_list)
self.latency_strategy = LowestLatencyLoggingHandler(router.router_cache, router.model_list)
async def get_optimal_deployment(self, model_group, healthy_deployments, **kwargs):
# 首先基于成本筛选
cost_filtered = await self.cost_strategy.async_get_available_deployments(
model_group, healthy_deployments, **kwargs
)
# 在低成本部署中选择延迟最低的
if cost_filtered:
latency_optimized = await self.latency_strategy.async_get_available_deployments(
model_group, cost_filtered, **kwargs
)
return latency_optimized
return cost_filtered
自定义路由策略
实现自定义路由策略需要继承BaseRoutingStrategy：
from litellm.router_strategy.base_routing_strategy import BaseRoutingStrategy
from litellm.caching.caching import DualCache
class CustomRoutingStrategy(BaseRoutingStrategy):
def __init__(self, router_cache: DualCache, model_list: list, config: dict = {}):
super().__init__(router_cache, should_batch_redis_writes=True)
self.model_list = model_list
self.config = config
async def async_get_available_deployments(self, model_group, healthy_deployments, **kwargs):
# 自定义路由逻辑
deployments = []
for deployment in healthy_deployments:
if self._meets_custom_criteria(deployment):
deployments.append(deployment)
return deployments if deployments else None
def _meets_custom_criteria(self, deployment):
# 实现自定义选择标准
return True
路由策略监控和调试
性能监控配置
router = Router(
model_list=[...],
set_verbose=True,
debug_level="DEBUG",
alerting_config={
"slack_webhook_url": "https://hooks.slack.com/...",
"alert_threshold": 5 # 失败次数阈值
}
)
实时指标收集
最佳实践建议
- 生产环境推荐使用usage-based-routing-v2，提供更好的分布式一致性
- 合理设置TTL值，根据业务特点调整用量统计的时间窗口
- 监控路由性能指标，包括选择时间、命中率、错误率等
- 实现渐进式部署，新策略先在小流量环境测试
- 配置适当的告警机制，及时发现路由异常
通过合理的路由策略配置和持续的优化调整，LiteLLM能够为大型语言模型应用提供稳定、高效、智能的流量分发能力，显著提升系统的整体性能和可靠性。
部署管理与健康检查实现
LiteLLM的Router系统通过智能的健康检查机制和部署状态管理，确保LLM服务的稳定性和高可用性。本节将深入探讨部署管理的核心架构、健康检查的实现原理以及相关的状态维护机制。
部署状态管理架构
LiteLLM使用基于缓存的部署状态管理系统，通过CooldownCache和DualCache机制来维护部署的健康状态：
class CooldownCache:
def __init__(self, cache: DualCache, default_cooldown_time: float):
self.cache = cache
self.default_cooldown_time = default_cooldown_time
def add_deployment_to_cooldown(
self,
model_id: str,
original_exception: Exception,
exception_status: int,
cooldown_time: Optional[float],
):
# 将部署添加到冷却状态
cooldown_time = cooldown_time or self.default_cooldown_time
cooldown_until = time.time() + cooldown_time
cache_value = CooldownCacheValue(
exception_status=exception_status,
cooldown_until=cooldown_until,
exception_message=str(original_exception)
)
cache_key = self.get_cooldown_cache_key(model_id)
self.cache.async_set_cache(
key=cache_key,
value=cache_value,
ttl=cooldown_time
)
健康检查流程
Router系统通过异步健康检查机制来筛选可用的部署：
健康检查的核心逻辑在_async_get_healthy_deployments方法中实现：
async def _async_get_healthy_deployments(
self, model: str, parent_otel_span: Optional[Span]
) -> Tuple[List[Dict], List[Dict]]:
"""获取健康的部署列表，排除处于冷却状态的部署"""
# 获取所有部署
all_deployments = self._get_all_deployments(model)
# 获取冷却中的部署
cooldown_deployments = await _async_get_cooldown_deployments(
self, parent_otel_span
)
# 过滤健康部署
healthy_deployments = [
dep for dep in all_deployments
if dep["model_id"] not in cooldown_deployments
]
return healthy_deployments, all_deployments
冷却机制实现
冷却机制通过异常状态码和失败策略来管理部署的可用性：
def _should_cooldown_deployment(
litellm_router_instance: LitellmRouter,
deployment: str,
exception_status: Union[str, int],
original_exception: Any,
) -> bool:
"""判断是否应该将部署置于冷却状态"""
# 检查异常状态码
exception_status_int = cast_exception_status_to_int(exception_status)
# 5xx错误通常需要冷却
if 500 <= exception_status_int < 600:
return True
# 检查自定义失败策略
if litellm_router_instance.allowed_fails_policy:
return should_cooldown_based_on_allowed_fails_policy(
litellm_router_instance, deployment, original_exception
)
return False
部署状态监控指标
LiteLLM通过Prometheus指标来监控部署的健康状态：
| 指标名称 | 类型 | 描述 |
|---|---|---|
deployment_successes | Counter | 部署成功次数 |
deployment_failures | Counter | 部署失败次数 |
deployment_cooldown | Gauge | 当前处于冷却状态的部署数量 |
deployment_health_status | Gauge | 部署健康状态（0=不健康，1=健康） |
指标收集的实现：
def increment_deployment_successes_for_current_minute(
litellm_router_instance: LitellmRouter,
deployment_id: str,
) -> str:
"""增加部署成功次数的指标"""
current_minute = int(time.time() / 60)
cache_key = f"deployment_success:{deployment_id}:{current_minute}"
litellm_router_instance.cache.async_incr(cache_key, ttl=120)
return cache_key
def get_deployment_successes_for_current_minute(
litellm_router_instance: LitellmRouter,
deployment_id: str,
) -> int:
"""获取当前分钟内的部署成功次数"""
current_minute = int(time.time() / 60)
cache_key = f"deployment_success:{deployment_id}:{current_minute}"
successes = litellm_router_instance.cache.async_get_cache(cache_key) or 0
return int(successes)
智能重试与回退策略
基于健康状态的智能重试机制：
def should_retry_this_error(
self,
error: Exception,
healthy_deployments: Optional[List] = None,
all_deployments: Optional[List] = None,
context_window_fallbacks: Optional[List] = None,
content_policy_fallbacks: Optional[List] = None,
regular_fallbacks: Optional[List] = None,
) -> bool:
"""判断是否应该重试当前错误"""
# 检查错误类型
error_type = type(error).__name__
# 可重试的错误类型
retryable_errors = {
'APIConnectionError',
'APIError',
'RateLimitError',
'Timeout',
'ServiceUnavailableError'
}
# 如果有健康部署可用，允许重试
if healthy_deployments and len(healthy_deployments) > 0:
return error_type in retryable_errors
return False
部署健康状态的可视化
通过mermaid状态图展示部署的生命周期：
配置与管理
部署健康检查的配置参数：
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
cooldown_time | float | 60.0 | 冷却时间（秒） |
allowed_fails | int | 3 | 允许的失败次数 |
num_retries | int | 2 | 重试次数 |
retry_after | int | 0 | 重试前等待时间 |
配置示例：
router = Router(
model_list=model_list,
cooldown_time=30.0, # 30秒冷却时间
allowed_fails=5, # 允许5次失败
num_retries=3, # 最多重试3次
retry_after=1, # 重试前等待1秒
routing_strategy="least-busy"
)
性能优化策略
为了确保健康检查的高性能，LiteLLM实现了以下优化：
- 缓存健康状态：部署的健康状态在缓存中维护，减少重复检查
- 异步检查：所有健康检查操作都是异步执行，避免阻塞主线程
- 批量处理：多个部署的健康状态检查可以批量执行
- 智能过期：健康状态信息具有合理的TTL，确保数据的时效性
# 健康状态缓存的实现
def _cached_health_check(
self,
deployment_id: str,
force_check: bool = False
) -> bool:
"""带缓存的健康检查"""
cache_key = f"health_check:{deployment_id}"
if not force_check:
# 检查缓存
cached_status = self.cache.async_get_cache(cache_key)
if cached_status is not None:
return bool(cached_status)
# 执行实际健康检查
is_healthy = self._perform_health_check(deployment_id)
# 缓存结果（30秒有效期）
self.cache.async_set_cache(
key=cache_key,
value=int(is_healthy),
ttl=30
)
return is_healthy
通过这种综合的部署管理和健康检查机制，LiteLLM能够确保LLM服务的高可用性和稳定性，为生产环境提供了可靠的智能路由基础。
总结
LiteLLM的Router系统通过智能的健康检查机制和部署状态管理，确保了LLM服务的稳定性和高可用性。其综合的部署管理架构包括基于缓存的CooldownCache和DualCache机制、异步健康检查流程、智能冷却机制以及详细的监控指标收集。通过配置合理的冷却时间、重试策略和性能优化措施，系统能够为生产环境提供可靠的智能路由基础，保证99.9%以上的服务可用性，同时实现成本和性能的最优化平衡。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
