AutoHedge：面向API高可用的轻量级自动对冲执行器-平芜编程栈

1. AutoHedge 是什么？一个被误读但极具实操价值的自动化风控工具

AutoHedge 这个名字一出来，很多人第一反应是“哦，又一个套着AI外衣的量化交易噱头”，或者联想到最近满天飞的“OpenAI+AGI+GPT-6”热词，顺手就把它划进“概念炒作”那一栏。但我在过去三年里，亲手在三家不同规模的金融科技团队里落地过五套类似系统，其中两套核心逻辑和 AutoHedge 高度重合——它根本不是什么“用GPT写策略”的玩具，而是一个面向高频API服务调用场景的、轻量级、可插拔、带状态感知的自动对冲（Auto-Hedging）执行器。关键词里的 Swarm、Python、API、OpenAI，其实各自承担明确分工：Swarm 是它的部署底座和弹性调度层；Python 是它的胶水语言和策略脚本载体；API 是它唯一输入源和输出通道；OpenAI 在这里不是用来生成交易信号，而是作为动态风险权重计算器——比如当某条支付通道连续三次返回503 Service Unavailable，它会调用 OpenAI API，把错误日志、上游SLA协议条款、当前流量曲线摘要喂进去，让模型判断“这是瞬时抖动还是架构性崩塌”，再据此决定是切流、降级、还是触发熔断。这不是玄学，而是把传统风控里靠人经验拍板的环节，变成可审计、可回溯、可压测的确定性流程。适合谁？不是想抄底比特币的散户，而是运维着20+个第三方SaaS接口、每天处理30万+次API调用、且SLA违约罚金动辄六位数的中后台技术负责人；是正在把 legacy 系统迁移到云原生架构、却被“下游不稳导致上游雪崩”问题卡住进度的DevOps工程师；也是需要向合规部门提交《API异常处置 SOP》并附上完整决策链路证据的技术风控专员。它解决的不是“怎么赚更多”，而是“怎么不死得那么难看”。

我第一次见到类似设计是在2021年某跨境支付公司的灰度环境里。他们接入了七家不同地区的收单网关，每家都提供RESTful API，但文档质量参差不齐，有的连错误码定义都不全。当时他们的做法是写一堆 if-else 判断 HTTP 状态码和响应体关键词，比如看到"code":"RATE_LIMIT_EXCEEDED"就 sleep(60)，看到"message":"Invalid signature"就重发带新 timestamp 的请求。这种硬编码方式在测试环境跑得挺好，一上生产，某家网关突然把错误码从429改成400，还把"RATE_LIMIT_EXCEEDED"换成了"Throttled by upstream"，结果整个支付链路卡死三小时。AutoHedge 的核心思路，就是把这种“靠猜”的应急响应，变成“可配置、可学习、可验证”的标准动作。它不替代业务逻辑，而是给业务逻辑加一层带记忆和推理能力的“安全气囊”。你不需要懂 LLM 的 attention 机制，但得明白：当你的系统每秒发起200次 API 调用，其中15%会因网络抖动、对方限流、证书过期等非业务原因失败时，人工盯屏或简单重试已经完全失效——这时候 AutoHedge 不是锦上添花，而是生存必需。

2. 整体架构设计：为什么选 Docker Swarm 而不是 Kubernetes？

2.1 核心设计哲学：不做平台，只做插件

AutoHedge 的定位非常清晰：它不是一个要取代你现有技术栈的“新平台”，而是一个能无缝嵌入你现有 CI/CD 流水线和监控体系的“智能中间件”。所以它的架构设计第一条铁律就是：零侵入式集成。这意味着它不能要求你改业务代码、不能强制你用特定 SDK、不能绑定某个云厂商的托管服务。我们最终选择 Docker Swarm 作为底座，不是因为它比 Kubernetes 更先进，恰恰相反，是因为它更“简陋”、更“可控”、更“透明”。K8s 的 Operator、CRD、Custom Metrics Server 这些强大能力，在 AutoHedge 的场景里全是负担。我们需要的只是：当某台宿主机上的 API 调用失败率超过阈值时，能快速把这个节点从负载均衡池里摘掉；当新版本策略脚本发布后，能滚动更新所有 worker 实例而不中断服务；当某类错误模式被识别出来，能立刻下发新的规则到所有节点。Swarm 的docker service update --force、docker node update --availability drain、docker config这几个原生命令，配合简单的 healthcheck 脚本，就能干净利落地完成全部需求。我做过对比测试：在同等硬件资源下，一个 5 节点 Swarm 集群启动一个新服务实例平均耗时 1.7 秒，而同配置 K8s 集群（启用 metrics-server 和 prometheus-operator）平均耗时 8.3 秒。对于 AutoHedge 这种需要快速响应故障的组件，这 6 秒多的延迟，可能就是避免一次 P0 级事故的关键窗口。

2.2 三层模块化结构：解耦才是稳定的基础

AutoHedge 的内部结构严格遵循“输入-处理-输出”三层解耦：

Input Layer（输入层）：负责监听和采集原始信号。它不直接调用业务 API，而是通过两种方式获取数据：一是订阅你现有的日志系统（如 ELK 或 Loki），过滤出包含http_status、response_time、error_message字段的日志行；二是作为 sidecar 容器，与你的业务服务部署在同一 Pod/Service 下，通过共享 volume 或 Unix socket 接收业务进程主动上报的调用结果。这个设计的关键在于：它永远不成为性能瓶颈。即使日志系统暂时不可用，AutoHedge 会降级为本地内存缓存模式，继续基于最近 5 分钟的统计做决策，而不是整个挂掉。
Engine Layer（引擎层）：这是 AutoHedge 的大脑，由 Python 编写的策略引擎驱动。它包含三个核心子模块：
- State Tracker（状态追踪器）：维护每个被监控 API 的实时健康画像，包括成功率、P95 延迟、错误码分布直方图、最近 10 次失败的上下文快照（request_id, timestamp, upstream_ip）。这个状态不是静态快照，而是带时间衰减因子的滑动窗口计算，确保它能快速响应突发抖动，又不会被偶发噪音带偏。
- Rule Evaluator（规则评估器）：加载 YAML 格式的策略规则文件。一条典型规则长这样：
```
name: "alipay_gateway_throttle_protection" trigger: api_endpoint: "https://openapi.alipay.com/gateway.do" condition: "error_code_distribution['ACQ.TRADE_HAS_CLOSE'] > 0.3 AND success_rate < 0.8" action: type: "circuit_breaker" config: duration: "300s" fallback_response: '{"code":"SERVICE_UNAVAILABLE","msg":"Alipay temporarily unavailable"}'
```
  规则引擎支持布尔逻辑、数值比较、正则匹配，甚至可以调用外部 Python 函数（比如is_holiday()来判断是否节假日流量高峰）。
- LLM Orchestrator（大模型协调器）：这才是 OpenAI 真正发挥作用的地方。当 Rule Evaluator 发现某类错误模式无法被预设规则覆盖（比如错误信息里出现从未见过的新关键词），它会将当前上下文打包成一个 prompt，调用 OpenAI API。Prompt 的设计非常关键，我们不用通用的 chat 模型，而是微调了一个 tiny 版本的gpt-3.5-turbo-instruct，专门用于“错误归因分类”。输入是：“已知错误日志：[...], 上游 SLA 协议中关于‘不可用’的定义是：[...], 当前系统负载：[...]。请仅输出一个类别：NETWORK_TIMEOUT / RATE_LIMIT / AUTH_FAILURE / DATA_CORRUPTION / UNKNOWN”。这个设计把 LLM 的不确定性，约束在了一个极小的、可验证的决策空间里，避免了“幻觉”带来的误操作风险。
Output Layer（输出层）：负责执行 Engine Layer 下达的指令。它支持多种执行器：
- Traffic Router（流量路由）：通过调用你现有的 API 网关（如 Kong、Traefik）的 Admin API，动态修改路由规则，把流量切到备用通道。
- Config Publisher（配置发布）：将新的降级开关、超时阈值写入 Consul 或 Etcd，触发业务服务的配置热更新。
- Alert Dispatcher（告警分发）：不只是发邮件或钉钉，而是生成一条结构化的 incident report，包含决策依据（哪条规则触发、LLM 的归因结果、相关日志片段），直接推送到你的 PagerDuty 或飞书事件中心，供 on-call 工程师快速研判。

这个三层结构的好处是，你可以单独升级 Engine Layer 的策略逻辑，而不影响 Input 和 Output 的对接方式；也可以把 Output Layer 的 Traffic Router 换成你自研的网关 SDK，只要它实现相同的接口契约就行。我在一家电商公司落地时，他们用的是自研的 Java 网关，我们就只替换了 Output Layer 的一个 jar 包，其他部分完全不动。

2.3 为什么 Python 是不可替代的语言选择？

有人会问：既然要高性能，为什么不选 Go 或 Rust？答案很实在：AutoHedge 的性能瓶颈从来不在计算，而在 I/O 和决策复杂度。它的核心工作不是每秒处理百万请求，而是每分钟做几次“该不该切流”的判断。Python 的优势在这里被放大到极致：

生态即生产力：处理 JSON 日志、解析 YAML 规则、调用 RESTful API、连接 Redis 做状态缓存、甚至调用 OpenAI SDK——所有这些，在 Python 里都有成熟、稳定、文档齐全的库（requests,pyyaml,redis-py,openai）。用 Go 写，你得自己处理 HTTP client 的 timeout 重试、JSON unmarshal 的字段缺失、OpenAI response 的 streaming 解析，这些琐碎工作会吃掉 70% 的开发时间。而 Python 一行response = openai.ChatCompletion.create(...)就搞定。
策略即代码，代码即策略：AutoHedge 的规则引擎允许用户用纯 Python 写自定义函数。比如某家银行要求“当错误信息包含‘CVV’且发生在周末晚上 8 点到 10 点，必须立即触发风控工单”。这条规则用 YAML 很难表达，但用 Python 就是一段几行的函数：
```
def is_cvv_weekend_risk(log): return ("CVV" in log.get("error_message", "")) and \ (datetime.now().weekday() >= 5) and \ (20 <= datetime.now().hour <= 22)
```
这种灵活性，是任何声明式 DSL 都无法比拟的。而且，这段代码可以直接在单元测试里 mock 输入日志进行验证，保证策略上线前 100% 可靠。
调试友好性：当线上出现诡异问题，比如“为什么这条规则没触发？”，你可以在容器里直接docker exec -it autohedge-worker-1 bash，然后python -c "from engine.rules import load_rules; print(load_rules())"查看实际加载的规则，或者import pdb; pdb.set_trace()插入断点。这种即时调试能力，在 Go 或 Rust 里需要复杂的交叉编译和符号表管理，成本太高。

当然，Python 的 GIL（全局解释器锁）在 CPU 密集型任务里是短板，但 AutoHedge 里根本没有 CPU 密集型任务。它 95% 的时间都在等网络 I/O（调 OpenAI、查 Redis、发 HTTP 请求）。我们用asyncio+aiohttp重构了所有 I/O 操作，实测单个 worker 实例并发处理 500 个日志事件/秒毫无压力。所以，选择 Python 不是妥协，而是精准匹配场景的最优解。

3. 核心细节解析：从零搭建一个可用的 AutoHedge 实例

3.1 环境准备：Swarm 集群的最小可行配置

别被“集群”吓到，AutoHedge 对 Swarm 的要求极低。一个单节点 Swarm（也就是你本机docker swarm init）就能跑通全部功能，非常适合本地验证。生产环境推荐至少 3 节点（1 manager + 2 worker），以保证 manager 故障时集群仍可管理。以下是初始化一个 3 节点 Swarm 的实操步骤，我全程在 Ubuntu 22.04 上验证：

所有节点安装 Docker CE 24.0+：这是硬性要求，因为旧版 Swarm 对docker config的支持不完善。执行：

curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER # 重启终端或执行 newgrp docker

初始化 Manager 节点：

# 在计划作为 manager 的机器上执行 docker swarm init --advertise-addr 192.168.1.100 # 输出类似：docker swarm join --token SWMTKN-1-abcde... 192.168.1.100:2377 # 记下这个 token，后面 worker 节点要用

加入 Worker 节点：

# 在另外两台机器上，用上一步得到的 token 执行 docker swarm join --token SWMTKN-1-abcde... 192.168.1.100:2377

验证集群状态：

docker node ls # 应该看到 3 个节点，STATUS 都是 Ready，AVAILABILITY 是 Active

提示：生产环境务必配置--data-path-port和--listen-addr参数，避免默认端口冲突。如果节点在不同内网网段，需确保 2377（manager 通信）、7946（node 通信）、4789（overlay 网络）端口互通。防火墙规则宁可开宽一点，也别让 Swarm 自己发现不了节点。

3.2 AutoHedge 服务定义：Docker Compose vs Stack 文件

AutoHedge 使用docker stack deploy部署，因为它原生支持 Swarm 的 secrets、configs、networks 等高级特性。我们不使用docker-compose.yml，而是编写stack.yml文件。以下是精简后的核心部分（完整版见 GitHub 仓库）：

version: '3.8' services: # Input Layer: 日志监听器 log-listener: image: python:3.11-slim command: python /app/listen.py volumes: - /var/log/myapp:/logs:ro # 挂载业务日志目录 networks: - autohedge-net deploy: mode: replicated replicas: 2 placement: constraints: [node.role == worker] # Engine Layer: 核心策略引擎 engine: image: myorg/autohedge-engine:latest environment: - OPENAI_API_KEY=${OPENAI_API_KEY} - REDIS_URL=redis://redis:6379/0 secrets: - openai_api_key configs: - source: rules_config target: /app/rules.yaml depends_on: - redis networks: - autohedge-net deploy: mode: global # 每个 worker 节点运行一个实例，保证低延迟 placement: constraints: [node.role == worker] # Output Layer: 流量路由执行器 router: image: myorg/autohedge-router:latest environment: - KONG_ADMIN_URL=http://kong:8001 networks: - autohedge-net deploy: mode: replicated replicas: 1 placement: constraints: [node.role == manager] # 只在 manager 上运行，集中管理 # 依赖服务：Redis 用于状态共享 redis: image: redis:7-alpine networks: - autohedge-net deploy: placement: constraints: [node.role == manager] networks: autohedge-net: driver: overlay secrets: openai_api_key: file: ./openai.key # 本地文件，内容仅为 API key 字符串 configs: rules_config: file: ./rules.yaml

这个文件的关键点在于：

deploy.mode: global：确保 Engine 层在每个 worker 节点都有一个实例。因为 State Tracker 需要本地快速访问 Redis，如果只部署一个副本，跨节点网络延迟会让状态更新变慢，影响决策实时性。
secrets和configs：把敏感的 API Key 和可变的规则配置，从镜像里剥离出来，用 Swarm 原生机制管理。docker secret create和docker config create命令会加密存储，比环境变量安全得多。
placement.constraints：精确控制服务部署位置。Router 必须在 manager 上，因为它要调用 Swarm 的 API；Log Listener 和 Engine 必须在 worker 上，因为它们要访问业务日志和本地资源。

部署命令极其简单：

# 创建 secret 和 config echo "sk-xxx" | docker secret create openai_api_key - docker config create rules_config rules.yaml # 部署 stack docker stack deploy -c stack.yml autohedge

注意：rules.yaml文件必须存在且格式正确，否则docker stack deploy会静默失败。建议先用python -m yaml检查语法：python -c "import yaml; print(yaml.safe_load(open('rules.yaml')))"。

3.3 规则引擎详解：如何写出既安全又灵活的策略

AutoHedge 的灵魂在于规则。一个糟糕的规则，比没有规则更危险。我见过最典型的反面案例：某团队写了一条规则 “当http_status == 500时，立即关闭所有支付通道”。结果上游一个无关紧要的用户头像服务挂了，返回 500，导致整个支付系统被误杀。所以，规则设计必须遵循“最小权限、最大上下文”原则。

3.3.1 基础规则结构解析

一条规则的核心是trigger和action两部分。trigger定义“什么情况下启动”，action定义“启动后做什么”。trigger又分为api_endpoint（目标 API）、condition（触发条件）和window（时间窗口）。condition支持丰富的表达式：

数值比较：success_rate < 0.7、p95_latency > 2000（毫秒）
集合操作：error_codes['429'] > 0.5（429 错误占比超 50%）
字符串匹配：'Invalid token' in error_message
复合逻辑：(error_codes['401'] > 0.3 AND success_rate < 0.5) OR (p95_latency > 5000)

window参数至关重要，默认是60s，但你可以根据业务节奏调整。对支付类 API，60 秒太短，可能把正常的瞬时抖动当成故障；对搜索类 API，60 秒又太长，用户已经流失了。我们通常按如下经验设置：

支付/转账类：300s（5 分钟）
登录/认证类：120s（2 分钟）
搜索/推荐类：30s

3.3.2 高级技巧：用 Python 函数扩展规则能力

YAML 规则无法覆盖所有场景，这时就要用 Python 函数。AutoHedge 会自动扫描/app/functions/目录下的.py文件，并将其注册为可调用函数。例如，创建functions/holiday_checker.py：

import datetime import json import requests # 中国法定节假日 API，返回 {date: "2024-01-01", name: "元旦", type: "holiday"} HOLIDAY_API = "https://api.devtools.123.com/holidays" def is_chinese_holiday(date_str): """ 判断指定日期是否为中国法定节假日 :param date_str: YYYY-MM-DD 格式字符串 :return: bool """ try: resp = requests.get(f"{HOLIDAY_API}?date={date_str}", timeout=2) data = resp.json() return data.get("type") == "holiday" except: return False def is_peak_hour(): """判断当前是否为业务高峰期（晚 8-10 点）""" now = datetime.datetime.now() return 20 <= now.hour <= 22

然后在rules.yaml中就可以这样用：

name: "payment_peak_hour_protection" trigger: api_endpoint: "https://api.pay.example.com/v1/charge" condition: "is_peak_hour() AND success_rate < 0.9" window: "60s" action: type: "throttle" config: rate_limit: "100/minute"

提示：所有自定义函数必须是纯函数（无副作用），且必须有明确的return类型注解（如-> bool）。AutoHedge 启动时会做静态检查，如果函数签名不合法，会拒绝加载整条规则，并在日志里报错。这保证了规则的可预测性。

3.3.3 LLM 协调器的 Prompt 工程实践

LLM 不是万能的，但用对了就是神器。我们的gpt-3.5-turbo-instruct微调模型，输入 prompt 固定为以下结构：

你是一个专业的 API 故障归因专家。请根据以下信息，严格按格式输出一个类别。 【错误日志】 {log_message} 【上游 SLA 协议摘要】 {sla_summary} 【当前系统指标】 {metrics_snapshot} 【可选归因类别】 NETWORK_TIMEOUT: 网络连接超时或丢包 RATE_LIMIT: 被上游限流，错误码含 429 或关键词 'rate limit' AUTH_FAILURE: 认证失败，错误码含 401/403 或关键词 'invalid token' DATA_CORRUPTION: 数据格式错误，错误码含 400 或关键词 'invalid json' UNKNOWN: 以上均不符合，无法归因 请只输出一个类别，不要任何解释、不要换行、不要标点。

这个 prompt 的设计要点：

角色定义清晰：开头就锚定模型的角色，减少发散。
信息结构化：用【】分隔不同信息源，让模型更容易 parse。
输出格式绝对刚性：最后一句是“红线”，确保输出可被程序直接解析。我们实测，这个 prompt 在 1000 条真实生产错误日志上的归因准确率达到 92.3%，远高于通用 chat 模型的 68%。

4. 实操过程：从部署到上线的全流程记录

4.1 第一步：本地验证（5 分钟）

在你自己的笔记本上，用单节点 Swarm 快速验证 AutoHedge 是否能跑起来。这是最关键的一步，能避免后续在生产环境踩坑。

准备模拟日志：创建一个test.log文件，内容如下（模拟一个失败的 API 调用）：

{"timestamp": "2024-05-20T10:00:00Z", "api_endpoint": "https://api.example.com/v1/pay", "http_status": 429, "response_time_ms": 120, "error_message": "Rate limit exceeded for key 'abc123'"}

编写最简规则rules.yaml：

rules: - name: "test_rate_limit_rule" trigger: api_endpoint: "https://api.example.com/v1/pay" condition: "http_status == 429" action: type: "log_only" config: message: "Rate limit detected! Check your quota."

构建并运行：

# 创建 secret（随便填个假 key，本地验证不影响） echo "fake-key" | docker secret create openai_api_key - # 部署 stack docker stack deploy -c stack.yml autohedge-test # 查看日志，应该能看到 Engine 容器输出 "Rate limit detected! ..." docker service logs autohedge-test_engine --tail 10

如果这一步成功，说明你的基础环境和规则语法都没问题。失败的话，90% 的原因是stack.yml里路径写错，或者rules.yaml有语法错误（用前面提到的python -m yaml检查）。

4.2 第二步：对接真实日志源（30 分钟）

本地验证通过后，就要接入真实的业务日志。我们以最常见的 ELK（Elasticsearch + Logstash + Kibana）为例。

Logstash 配置改造：在你的 Logstash pipeline 中，添加一个if判断，只把包含http_status和api_endpoint字段的日志发送给 AutoHedge。在output部分增加：

if [http_status] and [api_endpoint] { http { url => "http://autohedge-log-listener:8000/log" http_method => "post" format => "json" mapping => { "timestamp" => "%{[@timestamp]}" "api_endpoint" => "%{[api_endpoint]}" "http_status" => "%{[http_status]}" "response_time_ms" => "%{[response_time_ms]}" "error_message" => "%{[error_message]}" } } }

AutoHedge Input Layer 适配：修改log-listener服务的listen.py，让它能接收 HTTP POST 请求。核心代码：

from flask import Flask, request, jsonify import redis import json app = Flask(__name__) r = redis.Redis(host='redis', port=6379, db=0) @app.route('/log', methods=['POST']) def receive_log(): try: log_data = request.get_json() # 标准化字段名，兼容不同日志源 standardized = { 'timestamp': log_data.get('timestamp') or log_data.get('@timestamp'), 'api_endpoint': log_data.get('api_endpoint'), 'http_status': int(log_data.get('http_status', 200)), 'response_time_ms': int(log_data.get('response_time_ms', 0)), 'error_message': log_data.get('error_message', '') } # 发布到 Redis channel，供 Engine 层消费 r.publish('autohedge:logs', json.dumps(standardized)) return jsonify({"status": "ok"}), 200 except Exception as e: return jsonify({"error": str(e)}), 400 if __name__ == '__main__': app.run(host='0.0.0.0', port=8000)

验证对接：在 Kibana 里触发一次已知会失败的 API 调用（比如故意传错 token），然后docker service logs autohedge_engine，应该能看到 Engine 处理这条日志并触发规则的记录。

注意：生产环境务必给 Logstash 的 HTTP output 配置重试和死信队列（DLQ），避免 AutoHedge 临时不可用导致日志丢失。我们通常设置retry_failed => true和dead_letter_queue_enable => true。

4.3 第三步：上线首个生产规则（2 小时）

选择一个风险最低、价值最高的场景作为首发。我们强烈推荐从“第三方短信网关降级”开始。原因有三：第一，短信不是核心支付链路，失败影响有限；第二，短信网关 API 稳定性普遍较差，是天然的练兵场；第三，降级方案明确（切到备用通道或返回“稍后重试”），没有歧义。

收集基线数据：用 Prometheus 抓取你当前短信网关的http_status和response_time_ms指标，持续观察 24 小时，记录正常情况下的success_rate（通常 99.5%+）、p95_latency（通常 < 800ms）、常见错误码（如400表示参数错误，429表示限流，503表示服务不可用）。

编写生产规则sms-fallback.yaml：

rules: - name: "sms_gateway_503_fallback" trigger: api_endpoint: "https://sms.provider.com/api/v1/send" condition: "http_status == 503 AND success_rate < 0.8" window: "300s" action: type: "traffic_router" config: target_service: "sms-backup-gateway" weight: 1.0 duration: "600s" - name: "sms_gateway_429_throttle" trigger: api_endpoint: "https://sms.provider.com/api/v1/send" condition: "error_codes['429'] > 0.3" window: "120s" action: type: "config_publisher" config: key: "/sms/throttle_enabled" value: "true" ttl: "300s"

灰度发布：先在 10% 的流量上启用规则。通过在你的 API 网关（如 Kong）里配置 canary release，把 10% 的/sms/send请求路由到一个特殊的 headerX-AutoHedge-Enabled: true，然后在 AutoHedge 的engine服务里，只处理带这个 header 的日志。观察 1 小时，确认规则触发逻辑和 fallback 行为符合预期。
全量上线与监控：灰度没问题后，移除 header 限制，全量启用。同时，在 Grafana 里创建一个 Dashboard，监控：
- autohedge_rule_triggered_total{rule="sms_gateway_503_fallback"}：规则触发次数
- autohedge_action_executed_total{action="traffic_router"}：流量路由执行次数
- sms_gateway_success_rate：主通道成功率（应平稳）
- sms_backup_gateway_success_rate：备用通道成功率（应略低但可用）

4.4 第四步：集成 OpenAI 进行智能归因（1 天）

这一步是 AutoHedge 的“高光时刻”，但务必谨慎。我们建议在规则上线稳定运行 1 周后，再开启 LLM 功能。

获取并配置 OpenAI API Key：从 OpenAI 官网获取 key，用docker secret create注入：

# 从官网复制 key，保存为 openai.key 文件 docker secret create openai_api_key openai.key

启用 LLM 协调器：在stack.yml的engine服务里，取消注释environment中的OPENAI_API_KEY，并确保secrets部分已包含openai_api_key。

编写 LLM 触发规则：创建一条专门用于未知错误的规则：

- name: "sms_unknown_error_analysis" trigger: api_endpoint: "https://sms.provider.com/api/v1/send" condition: "error_message != '' AND error_code not in ['400','429','503']" window: "60s" action: type: "llm_orchestrator" config: model: "gpt-3.5-turbo-instruct" max_tokens: 10

监控与调优：重点监控openai_api_requests_total和openai_api_errors_total。初期可能会遇到429（调用频次超限），这时要调整window时间或增加rate_limit配置。我们最终的生产配置是：每分钟最多 30 次 LLM 调用，每次调用max_tokens=10，保证响应在 200ms 内。

5. 常见问题与排查技巧实录

5.1 规则不触发？先查这五个地方

AutoHedge 最常见的问题是“明明日志里有错误，规则却不触发”。这不是 Bug，99% 是配置问题。按以下顺序排查：

日志字段名是否匹配？AutoHedge 默认期望日志里有api_endpoint、http_status、error_message字段。如果你的日志是url、status_code、err_msg，规则肯定不生效。解决方案：在log-listener的listen.py里做字段映射，或者在 Logstash 里用mutatefilter 重命名字段。
api_endpoint的 URL 是否完全一致？规则里写的https://api.example.com/v1/pay，和日志里记录的https://api.example.com/v1/pay?source=web是不同的。解决方案：在规则trigger里用正则匹配，api_endpoint: "https://api.example.com/v1/pay.*"。
时间窗口window是否太短？如果你的业务是低频调用（比如每小时才调一次），而window: "60s"，那永远凑不够触发条件。解决方案：把window改成3600s（1 小时）或86400s（1 天），并相应调整condition中的阈