# 自适应负载均衡指南

AxonHub 提供智能的自适应负载均衡系统，能够根据多个维度自动选择最优的 AI 渠道，确保高可用性和最佳性能。

## 🎯 核心特性

### 智能渠道选择
- **优先级分组** - 候选渠道首先按模型关联的优先级分组（数值越小，优先级越高）
- **会话一致性** - 同一对话的请求优先路由到之前成功的渠道
- **健康状态感知** - 自动避开错误率高的渠道
- **公平分配** - 使用加权轮询（Weighted Round Robin）根据渠道权重比例分配请求
- **延迟感知** - 使用更贴近体验的分流指标：流式请求优先较低首 token 延迟和较高输出吞吐，非流式请求优先较低端到端延迟
- **速率限制感知** - 结合 RPM、TPM、并发占用和 429 `Retry-After` 冷却时间进行排序；未显式配置 `MaxConcurrent` 时，会回退到默认连接跟踪器容量做饱和保护

### 多策略评分系统
负载均衡遵循分层处理流程：首先按**关联优先级**分组，然后在每个优先级组内进行**策略评分**。

| 层级 | 策略 | 评分范围 | 说明 |
|------|------|----------|------|
| **1** | **关联优先级** | 0-N (越小越优) | 模型关联中定义的硬分组 |
| **2** | **会话感知** | 0-1000 分 | 同一会话优先，确保对话连续性 |
| **3** | **错误感知** | 0-200 分 | 基于成功率和错误历史 |
| **4** | **加权轮询** | 10-150 分 | 基于权重和历史负载的比例分配 |
| **5** | **延迟感知** | 0-80 分 | 流式请求看 FTTL + TPS，非流式请求看总时延 |
| **6** | **速率限制感知** | -10000-100 分 | 结合 RPM/TPM/并发占用与 429 冷却时间 |

## 🚀 快速开始

### 1. 配置多个渠道
在管理界面中添加多个相同模型的渠道：

```yaml
# 渠道 A - 主力渠道
name: "openai-primary"
type: "openai"
weight: 100  # 高优先级
base_url: "https://api.openai.com/v1"

# 渠道 B - 备用渠道  
name: "openai-backup"
type: "openai"
weight: 50   # 中等优先级
base_url: "https://api.openai.com/v1"

# 渠道 C - 第三方渠道
name: "openai-third-party"
type: "openai"
weight: 30   # 低优先级
base_url: "https://api.example.com/v1"
```

### 2. 启用负载均衡
负载均衡自动启用，无需额外配置。系统会：

- 自动检测渠道健康状态
- 根据策略评分排序渠道
- 智能选择最优渠道
- 失败时自动切换到下一个渠道

### 3. 发送请求
使用标准的 OpenAI API 格式：

```python
from openai import OpenAI

client = OpenAI(
    api_key="your-axonhub-api-key",
    base_url="http://localhost:8090/v1"
)

# 系统会自动选择最优渠道
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

## 📊 负载均衡策略详解

### 模型关联优先级 (Model Association Priority)
- **目的**: 高层级的流量控制和硬分组。
- **机制**: 候选渠道首先按模型关联（Model Association）中的 `priority` 字段排序。
- **规则**: 数值越小，优先级越高。系统会耗尽优先级为 `N` 的所有候选渠道后，才会考虑优先级为 `N+1` 的渠道。
- **应用场景**: 主备渠道分离、A/B 测试（通过设置相同的优先级）。

### 会话感知策略 (TraceAware)
- **目的**: 保持多轮对话的渠道一致性
- **机制**: 如果请求包含 trace ID，优先使用之前成功的渠道
- **优势**: 避免渠道切换导致的初始化延迟
- **评分**: 匹配渠道获得 1000 分，否则 0 分

### 错误感知策略 (ErrorAware)
- **目的**: 避开不健康的渠道
- **基准分**: 健康渠道基准分为 200 分
- **评分因素**:
  - 连续失败：每次 -30 分，并在冷却窗口内随时间衰减
  - 最近失败（5 分钟内）：最多 -40 分，并随时间衰减
- **恢复**: 失败渠道会随时间自动恢复优先级，因为时间衰减惩罚会逐渐减少。

### 加权轮询策略 (Weight Round Robin)
- **目的**: 基于权重和历史负载的比例分配。
- **算法**: 根据渠道权重对历史请求数进行归一化处理。权重较高的渠道在分数下降前可以处理更多请求。
- **评分**: `150 * exp(-归一化请求数 / 150)`
- **范围**: 10-150 分

### 延迟感知策略 (LatencyAware)
- **目的**: 使用更符合用户体感的延迟指标优先选择更快的渠道
- **机制**:
  - **流式请求**: 使用首 token 延迟 FTTL/TTFT 的 EWMA 和输出吞吐 TPS 的 EWMA
  - **非流式请求**: 使用端到端总时延的 EWMA
- **评分**:
  - **流式请求**: `80 * (0.7 * 首 token 分量 + 0.3 * 吞吐分量)`
  - **非流式请求**: `80 * (1 - latency_ewma / 3000)`，结果限制在 `0-80`
- **中性分**: 没有延迟数据时返回 40 分

### 速率限制感知策略 (RateLimitAware)
- **目的**: 尊重上游速率限制并避免 429 或通道饱和
- **机制**: 结合每渠道的 RPM、TPM、并发请求数和 429 `Retry-After` 冷却时间进行打分
- **评分**:
  - 未触发任何限制时最高 100 分
  - 随使用率接近上限按 `100 * (1 - max_usage_ratio)` 线性降分
  - 任一限制耗尽时返回 `-10000`，作为最后兜底候选
- **并发回退**: 如果未显式配置 `MaxConcurrent`，但默认连接跟踪器提供了每渠道容量，系统仍会按当前在途请求数进行降分，并在完全饱和时将该渠道降为兜底候选

## 🔧 高级配置

### 启用调试模式

在测试环境中，可以开启详细的负载均衡调试信息。

```bash
# 设置环境变量
export AXONHUB_DEBUG_LOAD_BALANCER_ENABLED=true
```

```bash
# 查看负载均衡决策
tail -f axonhub.log | grep "Load balancing decision"

# 查看具体渠道评分
tail -f axonhub.log | grep "Channel load balancing details"

# 使用 jq 格式化 JSON 日志
tail -f axonhub.log | jq 'select(.msg | contains("Load balancing"))'
```

## 📈 监控和故障排查

### 关键指标
- **渠道切换频率** - 正常情况下应该较低
- **错误率分布** - 某个渠道错误率过高可能需要检查配置
- **响应时间** - 负载均衡应该优化整体响应时间

### 常见问题

**Q: 为什么请求总是路由到同一个渠道？**
A: 检查是否启用了会话一致性。同一 trace ID 的请求会优先使用相同渠道。

**Q: 渠道不切换怎么办？**
A: 查看错误感知策略的评分。渠道可能仍然健康，或者需要时间恢复。

**Q: 如何验证负载均衡是否工作？**
A: 启用调试模式，查看日志中的渠道评分和排序。

## 🎛️ 最佳实践

### 1. 渠道配置
- 设置不同的权重值体现优先级
- 配置多个不同提供商的渠道提高可用性
- 定期检查渠道健康状态

### 2. 监控设置
- 监控各渠道的错误率和响应时间
- 设置告警当某个渠道持续失败
- 定期分析负载均衡决策日志

### 3. 性能优化
- 根据成本考虑调整渠道优先级
- 使用会话一致性提高用户体验

## 🔗 相关文档

- [请求处理流程指南](../getting-started/request-processing.md)
- [OpenAI API](../api-reference/openai-api.md)
- [Anthropic API](../api-reference/anthropic-api.md)
- [Gemini API](../api-reference/gemini-api.md)
- [渠道管理指南](channel-management.md)
- [追踪和调试](tracing.md)