AI 应用API网关LLM 网关后端前端【免费下载链接】axonhub⚡️ Open-source AI Gateway — Use any SDK to call 100 LLMs. Built-in failover, load balancing, cost control end-to-end tracing.项目地址https://gitcode.com/gh_mirrors/ax/axonhub点击查看免费下载AxonHub 是一款开源 AI 网关其内置的自适应负载均衡系统能够在多个同模型渠道之间自动选择最优通道保障高可用与最佳性能。本文以官方文档 docs/en/guides/load-balance.md 为核心骨架结合 internal/server/orchestrator/ 目录下的负载均衡器实现与 integration_test/openai/chat/load_balance/ 集成测试深入讲解六层分级打分体系、各策略的精确公式与参数、调试与监控方法以及真实场景下的最佳实践。读完本文你将能为同一模型配置多渠道并理解选路顺序精确解释每个策略的评分区间与触发条件通过环境变量与日志快速定位为什么请求总是走某一条通道。负载均衡在请求处理链路中的位置在 AxonHub 中一个请求进入网关后会经历「模型解析 → 候选渠道筛选 → 负载均衡排序 → 发起上游调用 → 失败重试」的完整链路。候选选择器实现 负责第一步先根据模型关联Model Association解析出所有支持该模型的已启用渠道再通过LoadBalancedSelector装饰器把候选集交给LoadBalancer排序。整个流程的核心是 LoadBalancer 主体它持有多个LoadBalanceStrategy并对每个候选渠道求和各策略得分后降序排列。排序结果决定两件事首次尝试用哪个渠道发起请求失败重试时按得分顺序依次尝试后续渠道即回退候选。值得注意的是负载均衡采用分层处理先按**模型关联优先级Association Priority**做硬分组优先级数值更小的组永远先被耗尽只有同一个优先级组内部的渠道才进入策略打分排序。这一逻辑在 candidates.go 的 sortCandidates 中实现——先按Priority分桶、升序取组组内调用loadBalancer.SortWithoutTracking打分。多策略分级打分体系总览负载均衡遵循「先按关联优先级再按策略打分」的层级过程。同一优先级组内六个层级按序生效层级策略得分区间说明1关联优先级Association Priority0-N越小越优模型关联中定义的硬分组2会话一致性Trace Aware0-1000 分同会话请求优先路由到此前成功渠道3错误感知Error Aware0-200 分基于成功率与错误历史4加权轮询Weight Round Robin0-150 分基于权重与滑动窗口负载按比例分发5延迟感知Latency Aware0-80 分流式请求用 FTTLTPS非流式用端到端延迟6限流感知Rate Limit Aware-10000~100 分尊重 RPM/TPM/并发限制与 429 Retry-After说明会话一致性在网关中对应Trace Sticky机制它不是打分型策略而是在打分排序之前把缓存的上一次成功渠道钉在首位。这一设计在 LoadBalancedSelector.Select 中可见命中 sticky 渠道时直接pinStickyCandidate仅对剩余候选做排序。从实现层面看默认的自适应负载均衡器biz.LoadBalancerStrategyAdaptive由以下策略组合而成与 load-balancing.md 及测试中的构造一致loadBalancer : NewLoadBalancer( NewErrorAwareStrategy(channelService), // 健康度0-200 NewWeightRoundRobinStrategy(channelService), // 公平性 管理权重0-150 NewLatencyAwareStrategy(channelService), // 流式 FTTL/TPS 或非流式延迟0-80 NewRateLimitAwareStrategy(rateLimitTracker, connectionTracker), // 限流 并发回退-10000~100 )NewLoadBalancer内部通过读取环境变量AXONHUB_DEBUG_LOAD_BALANCER_ENABLED决定是否启用调试路径生产路径与调试路径的打分逻辑完全一致只是调试路径额外记录明细见 load_balancer.go#L126-L138。快速上手三分钟让负载均衡跑起来第一步为同一模型配置多个渠道在管理界面为同一个模型添加多个渠道权重weight用于表达渠道的优先级倾向# Channel A - 主渠道 name: openai-primary type: openai weight: 100 # 高优先级 base_url: https://api.openai.com/v1 # Channel B - 备用渠道 name: openai-backup type: openai weight: 50 # 中优先级 base_url: https://api.openai.com/v1 # Channel C - 第三方渠道 name: openai-third-party type: openai weight: 30 # 低优先级 base_url: https://api.example.com/v1这里的weight对应代码中的OrderingWeight字段权重值存储于渠道配置管理界面可编辑。从 WeightRoundRobinStrategy.calculateScore 可以看到非正权重会被归一化为默认有效权重 100以保证评分尺度与健康度、延迟等信号保持相对一致。第二步启用负载均衡负载均衡默认自动启用无需额外配置。系统会自动检测渠道健康状态按策略得分对渠道排序智能选择最优渠道失败时自动切换到下一个渠道。网关层面还支持在重试策略Retry Policy中显式指定load_balancer_strategy可选值包括adaptive自适应默认、weighted、failover、round-robin等。负载均衡器按需取前 K 个候选K 1 MaxChannelRetries重试关闭时 K1并使用部分排序partial sort只排前 K 个减少大规模候选集的排序开销见 calculateTopK。第三步发送请求客户端无需任何改动使用标准 OpenAI API 格式即可from openai import OpenAI client OpenAI( api_keyyour-axonhub-api-key, base_urlhttp://localhost:8090/v1 ) # 系统将自动选择最优渠道 response client.chat.completions.create( modelgpt-4, messages[{role: user, content: Hello!}] )集成测试 load_balance_test.go 中的TestWeightBasedLoadBalancing通过关闭 trace/thread 上下文DisableTrace true、DisableThread true发送 60 个请求验证高权重渠道80-100获得约 50-60% 流量、中权重40-60约 25-35%、低权重10-30约 10-15% 的比例分发效果。各策略原理与精确评分公式1. 模型关联优先级最高层的硬分组目的高层级的流量控制与硬分组。机制候选先按模型关联Model Association中的priority字段排序。规则数值越小优先级越高优先级组 N 中所有候选被耗尽之前不会考虑组 N1 中的任何候选。典型场景主/备渠道分离A/B 测试给两组渠道设置相同优先级。实现上resolvedAssociationCandidate保留关联级元数据渠道、优先级、模型列表、When 条件经aggregateChannelModelCandidates按「渠道 ID 优先级」聚合成候选参见 candidates.go#L551-L607。2. 会话一致性Trace Sticky多轮对话不断线目的维持多轮会话的渠道一致性避免切换渠道导致的初始化延迟。机制请求若携带 trace ID优先路由到此前成功的渠道读取顺序为trace 优先、thread 兜底且仅在路由缓存routing cache有效期内生效。得分匹配渠道 1000 分否则 0 分。关键实现细节Sticky 渠道不是靠加分实现的而是在排序前被直接钉在首位resolveStickyChannelID。缓存过期或未命中时直接回落到正常负载均衡绝不查询历史请求这保证了该机制的低开销。集成测试 TestTraceStickyRouting 验证了同 trace 内 5 个连续请求全部路由到同一渠道。3. 错误感知Error Aware避开不健康渠道基础分健康渠道 200 分。扣分因子连续失败每次失败 -30 分且随时间衰减近期失败5 分钟内最多 -40 分随时间衰减。恢复机制随着时间衰减惩罚递减失败渠道自动恢复优先级。源码实现见 ErrorAwareStrategy。扣分公式为cooldownRatio 1 - (距上次失败分钟数 / 5) // 仅当距上次失败 5 分钟 penalty 连续失败次数 × 30 × cooldownRatio 40 × cooldownRatio score max(200 - penalty, 0)值得强调的是该策略只扣分、不因成功而加分——代码注释明确说明这是为了避免马太效应高绩效渠道持续垄断流量同时刻意排除了历史成功率让渠道在稳定运行后能快速恢复而不是被过往错误永久标记。4. 加权轮询Weight Round Robin按权重比例分发目的基于权重与滑动窗口负载的比例分发。算法用滑动窗口请求数除以渠道权重做归一化。权重越高得分下降前能承载的请求越多配置权重 ≤ 0 时使用默认有效权重 100以保持与健康度、延迟信号的评分尺度一致。评分公式score 150 / (1 normalizedRequestCount / 150)其中normalizedCount requestCount / (weight / 100.0)。范围大于 0、最多 150 分分数随请求数严格递减没有请求数上限或最低分钳制。实现与示例见 WeightRoundRobinStrategy.calculateScore源码注释给出了直观例证weight8080 个请求 → normalized100 → score90weight2020 个请求 → normalized100 → score90weight800 个请求 → normalized0 → score150weight200 个请求 → normalized0 → score150即所有渠道起点相同150 分但高权重渠道在得分下降前能处理更多请求从而达成比例分发权重 80/50/20/10 的渠道大约分别获得 50%/31%/12.5%/6.25% 的流量。旧负载由共享滑动窗口自然过期策略本身不再叠加第二次闲置衰减。5. 延迟感知Latency Aware匹配真实用户体验目的用与用户实际体验匹配的延迟信号优选渠道。机制流式请求按 EWMA 首 token 延迟FTTL/TTFT与 EWMA 输出吞吐每秒 tokens打分非流式请求按 EWMA 端到端延迟打分。评分公式流式80 × (0.7 × firstTokenComponent 0.3 × throughputComponent)非流式80 × (1 - latencyEWMA / 3000)钳制在 [0, 80]EWMA 平滑系数 α0.3近期请求权重更高。中性分无延迟数据的渠道获得 40 分中性分。范围0-80 分。实现细节见 LatencyAwareStrategy。请求类型通过上下文中的 stream 标志区分requestStreamFromContext常量定义见文件顶部首 token 延迟基准 3000ms、吞吐量钳制区间 [5, 100] tokens/s、非流式延迟基准 3000ms。子分量归一化函数clampNormalizedInverse与clampNormalized分别把「越小越好」延迟与「越大越好」吞吐映射到 [0,1]。6. 限流感知Rate Limit Aware尊重上游限制、规避 429目的尊重上游提供方的限流避免触发 429 错误。机制使用 1 分钟滑动窗口跟踪每个渠道的 RPM每分钟请求数、TPM每分钟 token 数与并发请求数。评分无显式限流且无默认连接饱和信号时得满分100 分用量接近上限时线性递减100 × (1 - maxUsageRatio)任何限制耗尽时得 -10000 分作为回退候选排到最后。429 Retry-After渠道返回带Retry-After头的 HTTP 429 时渠道进入冷却期冷却结束前得 -10000 分。配置在管理界面Rate Limit设置中按渠道配置 RPM、TPM、Max Concurrent。并发回退若未配置MaxConcurrent但默认连接跟踪器具备每渠道容量自适应负载均衡仍会惩罚在途请求过多的渠道并把完全饱和的渠道视为已耗尽的回退候选。源码方面-10000 常量定义 的注释明确说明该惩罚必须压过所有其他策略的正分之和使耗尽渠道稳定排在最后、但仍可作为回退候选。评分器 score 方法 按「冷却 → RPM/TPM → 并发」三级短路任一维度耗尽立即返回 -10000。并发子评分还区分了三种模式scoreConcurrency低于容量得分落在[0.3×100, 100]区间按在途/容量比线性递减有界队列QueueSize 0得分上限钳制在 30 分并随队列深度衰减队列满时才判为耗尽无界队列QueueSize 0永不判耗尽多余请求阻塞等待但随等待深度陡降得分让空闲渠道被强烈优先。限流字段定义见 ChannelRateLimit 结构包含rpm、tpm、maxConcurrent、queueSize、queueTimeoutMs五个可空字段nil 表示不限。ValidateRateLimit 强制约束所有数值字段必须 ≥ 0且queueSize 0时要求maxConcurrent 0。RPM/TPM 计数由 ChannelRequestTracker 以固定自然分钟桶now.Truncate(time.Minute)维护冷却表同样存放在该结构中。调试模式看清每一次选路决策开启调试模式通过环境变量开启负载均衡决策日志# 设置环境变量需重启服务生效 export AXONHUB_DEBUG_LOAD_BALANCER_ENABLEDtrue开启后LoadBalancer.sort 会走sortWithDebug调试路径为每个候选记录各策略得分、执行耗时与最终排名并输出结构化 JSON 日志。日志由 logDecision 写入两类条目决策摘要Load balancing decision completed含渠道总数、选定数、是否启用重试、最大渠道重试次数、耗时、最优渠道 ID/名称/得分、模型名渠道明细Channel load balancing details每个渠道的总分、最终排名及strategy_breakdown各策略得分与耗时。查看决策日志# 查看负载均衡决策 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))调试模式下还可以按策略名过滤例如grep ErrorAwareStrategy查看错误感知策略的全部惩罚计算、grep WeightRoundRobinStrategy查看权重归一化明细。若日志级别未开到 debug至少应保证LOG_LEVELinfo以看到 warn 级告警如指标不可用时使用中性分的降级提示。集成测试 TestLoadBalancingDebugMode 专门验证了调试模式下每个渠道的得分、总分、排名与耗时均被完整记录。监控与排障关键指标渠道切换频率正常工况下应相对较低trace sticky 会保证同会话内不切错误率分布某渠道错误率异常偏高可能意味着配置问题密钥、限流、端点响应时间负载均衡应当优化整体响应时间若整体变慢需检查是否大量渠道处于冷却或饱和状态。常见问题Q为什么请求总是路由到同一个渠道A检查会话一致性trace sticky是否生效。携带相同 trace ID 的请求会优先路由到同一渠道若想验证纯打分结果可在测试中禁用 trace/thread 上下文对应集成测试中的DisableTrace/DisableThread开关。Q渠道不切换怎么办A检查错误感知策略打分。该渠道可能仍然健康200 分满额或正处于 5 分钟冷却窗口内的恢复期——惩罚会随时间线性衰减需等待冷却结束才能逐步恢复优先级。Q如何验证负载均衡在工作A开启调试模式环境变量或请求级 debug 上下文查看日志中的渠道打分与排序结果确认总分与排名符合预期。集成测试 TESTING_GUIDE.md 提供了详细的验证清单。Q请求触发大量 429 怎么办A检查限流感知策略。渠道返回 429 且带Retry-After头时会进入冷却期并得 -10000 分应在管理界面为渠道配置合理的 RPM/TPM/MaxConcurrent必要时设置queueSize走有界队列模式避免请求被直接拒绝。最佳实践1. 渠道配置设置不同的 weight 值以表达优先级注意 ≤ 0 会被当作默认权重 100为同一模型配置多个不同提供方的渠道提升整体可用性定期检查各渠道健康状态及时下线长期异常渠道为主渠道配置限流RPM/TPM/MaxConcurrent让限流感知策略有据可依。2. 监控建设监控每个渠道的错误率与响应时间尤其关注流式请求的首 token 延迟渠道连续失败时设置告警错误感知策略会将其排在末尾但要确认告警确实被触发定期分析负载均衡决策日志排查某渠道长期零流量或频繁切换等异常模式。3. 性能优化结合成本因素调整渠道优先级权重与关联优先级善用会话一致性trace sticky提升多轮对话的用户体验理解 Top-K 部分排序机制K 1 MaxChannelRetries渠道很多时并不会全量排序重试次数设置应克制避免不必要的候选计算。进一步阅读请求处理指南负载均衡在完整请求链路中的位置OpenAI API / Anthropic API / Gemini API各协议接入格式渠道管理指南渠道创建、权重与限流配置链路追踪与调试trace/thread 上下文如何驱动会话一致性内部实现说明架构、默认策略组合与结构化日志样例负载均衡单元测试各策略的边界行为验证负载均衡集成测试trace 一致性、权重分发、并发与故障转移的端到端验证赞分享AI 应用API网关LLM 网关后端前端【免费下载链接】axonhub⚡️ Open-source AI Gateway — Use any SDK to call 100 LLMs. Built-in failover, load balancing, cost control end-to-end tracing.项目地址https://gitcode.com/gh_mirrors/ax/axonhub点击查看免费下载相关推荐AxonHub Orchestrator 深度解析AI 网关请求管线与多策略负载均衡内核AxonHub Orchestrator 深度解析AI 网关请求管线与多策略负载均衡内核 本文以 internal/server/orchestrator/RAI 应用API网关LLM 网关后端前端Wereader测试与部署指南确保浏览器扩展稳定运行的完整流程Wereader测试与部署指南确保浏览器扩展稳定运行的完整流程 Wereader是一款专为微信读书用户设计的浏览器扩展特别适合习惯使用Markdown做笔记前端DotNetGuide负载均衡策略深度解析DotNetGuide负载均衡策略深度解析 前言为什么负载均衡是现代应用的核心需求 在当今高并发的互联网环境中单台服务器早已无法满足业务需求。你是否遇到过文档教程知识库上一篇claude-seo 的 seo-unlighthouse 技能用 Unlighthouse CLI 实现全站多页面 Lighthouse 审计与 CWV 回归检测下一篇QOwnNotes 在 Funtoo Linux 上的安装指南emerge 安装与 Keychain 密钥环排错创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考