聚合分组
多密钥池整合与智能负载均衡解决方案
功能概述
什么是聚合分组？
聚合分组（Aggregate Group）是 GPT-Load 提供的一种高级分组类型，允许您将多个标准分组组合成一个逻辑分组。通过聚合分组，您可以统一管理多个密钥池，实现智能负载均衡和高可用性。
统一管理多个密钥池
将不同的密钥池整合到一个接入点
智能负载均衡
基于权重自动分配请求流量到各个子分组
提高可用性
当某个子分组无可用密钥时，自动切换到其他子分组
灵活流量控制
动态调整各子分组的流量占比
使用场景
多密钥池负载均衡
将多个标准分组的密钥池聚合，实现流量均衡分配
资源隔离与聚合
不同部门的密钥池独立管理，但可以通过聚合分组统一对外提供服务
弹性扩容
快速添加新的密钥池到现有聚合分组，无需修改客户端配置
金丝雀发布
通过调整权重控制新密钥池的流量占比，实现渐进式切换
高可用架构
当主密钥池耗尽时，自动切换到备用密钥池
核心概念
聚合分组
一种特殊的分组类型，本身不包含密钥，而是引用其他标准分组，通过智能算法实现多个密钥池的统一管理和负载均衡。
子分组
被聚合分组引用的标准分组，实际存储和管理 API 密钥。每个子分组可以独立配置和维护。
权重
决定子分组在负载均衡中的流量占比，取值范围 0-1000。权重越高，分配的流量越多；权重为 0 表示临时禁用该子分组。
状态
子分组的运行状态包括有效（权重 > 0 且有可用密钥）、禁用（权重 = 0）、无效（权重 > 0 但无可用密钥）三种类型。
状态管理
| 权重 | 可用密钥 | 状态 | 说明 |
|---|---|---|---|
| > 0 | 有 | 有效 | 正常参与负载均衡 |
| = 0 | - | 禁用 | 不参与负载均衡（临时禁用） |
| > 0 | 无 | 无效 | 尝试选中时会自动跳过 |
设计原理
负载均衡算法
GPT-Load 使用平滑加权轮询（Smooth Weighted Round-Robin）算法进行子分组选择，该算法具有以下特点：
平滑分布：流量分配更加均匀，避免突发流量
精确权重：严格按照配置的权重比例分配流量
高性能：O(n) 时间复杂度，适合高并发场景
子分组选择逻辑
计算候选分组
根据加权轮询算法计算下一个候选子分组
检查可用性
检查该子分组是否有可用密钥
选择或跳过
有密钥则使用该子分组，无密钥则标记为已尝试，继续下一个候选
失败处理
如果所有子分组都无可用密钥，返回错误
关键特性
- •智能跳过：自动跳过无可用密钥的子分组
- •快速失败：遍历所有子分组后仍无可用密钥时，立即返回错误
- •无状态：每个请求独立决策，不依赖外部状态
使用规则
子分组限制
不能嵌套
渠道类型一致
验证端点一致
权重配置规则
取值范围
0-1000
特殊值 0
禁用该子分组（不参与负载均衡）
百分比计算
子分组占比 = 子分组权重 / 所有子分组权重之和 × 100%
推荐实践
使用整百数值（如 100、200、500）便于理解和维护
最佳实践
等比分配
多个密钥池容量相近，希望平均分配流量
子分组 A: 100 子分组 B: 100 子分组 C: 100
优势
- ✓简单直观，流量均衡
- ✓适用于多个同等重要的密钥池
容量比例分配
密钥池容量差异较大，按容量比例分配
子分组 A（50个密钥）: 500 # 50% 子分组 B（30个密钥）: 300 # 30% 子分组 C（20个密钥）: 200 # 20%
优势
- ✓密钥利用率均衡
- ✓避免小池过载
主备模式
主密钥池优先使用，备用密钥池作为保险
子分组 A（主）: 900 # 90% 子分组 B（备）: 100 # 10%
优势
- ✓优先消耗主池
- ✓备池作为缓冲
金丝雀发布
测试新密钥池的稳定性，逐步切换流量
阶段 1: 旧(980) / 新(20) 阶段 2: 旧(800) / 新(200) 阶段 3: 旧(200) / 新(800)
优势
- ✓风险可控
- ✓问题影响范围小
配合模型重定向
当聚合分组包含多个相同渠道类型但对接不同服务商的子分组时，可在每个子分组配置模型重定向，实现客户端统一模型名访问。
应用示例
聚合分组包含三个 OpenAI 格式的子分组，对接不同服务商，客户端统一使用 gpt-4 模型名：
子分组A (OpenAI官方): {"gpt-4": "gpt-4-turbo"}子分组B (Azure OpenAI): {"gpt-4": "gpt-35-turbo"}子分组C (OpenRouter): {"gpt-4": "openai/gpt-4-turbo"}客户端只需使用 gpt-4，聚合分组会根据权重分配流量，每个子分组自动将其映射到实际支持的模型。
故障排查
请求返回 "No available sub-groups"
原因
所有子分组都无可用密钥、所有子分组都被禁用（权重为 0）、或聚合分组未添加子分组
解决方法
- 1检查子分组列表，查看状态
- 2进入"无效"状态的子分组，验证和补充密钥
- 3恢复被禁用子分组的权重
- 4确保至少有一个子分组处于"有效"状态
流量分配不符合权重配置
原因
部分子分组无可用密钥被自动跳过、权重配置最近刚修改需要观察更长时间、或请求量太少统计学上不具有代表性
解决方法
- 1检查所有子分组是否都有可用密钥
- 2在日志页面统计更长时间段（如 1 小时）的流量分布
- 3确认权重配置已保存并生效
无法修改标准分组的渠道类型
原因
该标准分组正被一个或多个聚合分组引用为子分组
解决方法
- 1在该标准分组详情页面查看"被引用的聚合分组"列表
- 2从列表中的每个聚合分组移除该子分组
- 3修改渠道类型
- 4如需要，重新添加到聚合分组