Decision Engine 如何开启 Autopilot 自动调优成功率评分并重置网关分数-二趣网

Decision Engine 如何开启 Autopilot 自动调优成功率评分并重置网关分数

【免费下载链接】hyperswitchOpen source, composable payments platform | PCI compliant | SaaS and Self-host options | Enables connectivity to multiple payment, payout, fraud, vault and tokenization providers | Uplifts authorization with intelligent routing and revenue recovery | Reduce payment processing costs with cost observability | Reduces payment ops with reconciliation项目地址: https://gitcode.com/GitHub_Trending/hy/hyperswitch

如果你的商户已经在用 Hyperswitch 的 Decision Engine 做基于成功率（success-rate）的网关路由，手动调整评分参数会很快过时。Autopilot 是 Decision Engine 的自调优层：它持续观察商户的真实流量，自动重算成功率评分的两个关键参数——bucket size（每个网关的分数用最近多少笔交易做平均）和hedging %（分流到非领先网关的探索流量比例）。本文完成两件事：通过 feature-flag API 为一个商户开启 Autopilot，以及在需要用干净基线重新跑评分时重置该商户的网关分数。

适用前提：Decision Engine 服务已在本地或 Docker 环境运行，你持有受保护路由所需的 API key 或 dashboard JWT，且商户有真实的决策流量（自调优任务从 ClickHouse 读取最近 3600s 的交易量）。

前提条件：环境与服务

按仓库内文档 Installation，快速启动路径是 Docker Compose（首次运行会拉取应用、PostgreSQL、Redis、Kafka、ClickHouse 等镜像）：

docker compose --profile postgres-ghcr up -d curl http://localhost:8080/health

预期响应：

{ "message": "Health is good" }

然后在 shell 中一次性设置好后续所有示例复用的变量，来源为 API Guide 的 Environment setup：

# Base URL — 本地源码构建或 Docker Compose export BASE_URL=http://localhost:8080 # 受保护路由接受 dashboard JWT 或 API key，二选一 export AUTH_HEADER="Authorization: Bearer <jwt_token>" # export AUTH_HEADER="x-api-key: DE_<api_key>" # 仅 analytics 路由、/health/diagnostics 和 /gateway-score/reset 需要。 # 发行配置中只定义了 "public" 一个租户 export TENANT_HEADER="x-tenant-id: public"

其中<jwt_token>/<api_key>替换为你自己签发的凭据。如果走 Hyperswitch 沙箱（BASE_URL=https://sandbox.hyperswitch.io），还需追加x-feature: decision-engine请求头。

注意一个高频坑：x-tenant-id没有回退机制，在需要它的路由上漏传会直接报TE_03: x-tenant-id not found in headers，即使 API key 有效。大多数路由（/decide-gateway、/routing/*、/merchant-account/*等）内部自行解析租户、不需要这个头，只有本文的 analytics 校验和分数重置路由需要。

另一点：自调优任务依赖 ClickHouse 中的流量数据。按 Configuration 文档，[analytics.kafka]和[analytics.clickhouse]必须都是enabled = trueanalytics 才可用；Docker Compose 运行方式已预先配置好。

以下命令沿用文档示例中的商户 IDmerchant_demo；如果你操作的是自己的商户，把路径和请求体中的merchant_id统一换成实际值即可。

第一步：查看当前 feature flag 状态

商户级的所有开关（多目标路由、A/B 拦截、elimination、Autopilot、SR 自动校准）都通过同一个 feature-flag API 读写：

curl "$BASE_URL/merchant-account/merchant_demo/features" \ --header "$AUTH_HEADER"

文档示例返回：

{ "merchant_id": "merchant_demo", "features": [ { "feature": "gsm-scoring-filter", "enabled": false }, { "feature": "explore-exploit-srv3", "enabled": false }, { "feature": "ab-test-real-payments", "enabled": true }, { "feature": "multi-objective-routing", "enabled": true }, { "feature": "elimination", "enabled": true }, { "feature": "auto-calibration", "enabled": true }, { "feature": "autopilot", "enabled": true } ] }

先确认auto-calibration与autopilot两项的当前值，再决定下一步只改哪一项。

第二步：同时开启 auto-calibration 与 autopilot

这两个 flag 共同控制同一个后台任务，没有独立的"运行 autopilot"端点。分工是（来源：Merchant Features 文档）：

auto-calibration：控制任务是否考虑该商户。关掉时任务对商户完全不做事；
autopilot：写权限开关，控制任务能否把结果写回商户的 SR 配置。单独开着它、而auto-calibration关闭时，它不产生任何效果。

文档把这二者拆开是为了允许"先只观察、暂不授权写入"，确认没问题后再放开写权限。

切换命令按 flag 名拼接路径，响应形状与列表调用相同——它会在写入后重新读回所有 flag 的当前生效状态，所以每次切换后你都能直接确认整体状态：

curl --location "$BASE_URL/merchant-account/merchant_demo/features/auto-calibration" \ --header "$AUTH_HEADER" \ --header "Content-Type: application/json" \ --data '{ "enabled": true }'

curl --location "$BASE_URL/merchant-account/merchant_demo/features/autopilot" \ --header "$AUTH_HEADER" \ --header "Content-Type: application/json" \ --data '{ "enabled": true }'

判断依据：两次响应的features数组里，auto-calibration与autopilot均为"enabled": true，自调优才真正生效。

开启后任务如何运转

两项开启后，后台任务按固定轮询周期运行（默认 900s；可通过config/*.toml中的[sr_auto_calibration]段或SR_AUTO_CALIBRATION_INTERVAL_SECS环境变量调整）。每个周期它：

从 ClickHouse 读取商户最近 3600s 的交易量；
纯靠观测数据（不接受商户输入）推导两个 SRv3 参数：
- Bucket size——被钳制在 100 到 2000 之间，只有出现有意义的（25 步）变化时才重写；
- Hedging %——上限 30%，移动幅度不足 1.0pp 时不更新；
把结果写回商户的 SR 配置，并打上"source": "autopilot"标记，便于区分自动写入值和人工配置。

任务每次校准还会发出一条 analytics 事件（flow_type: autopilot_calibration），这是后面校验的依据。

第三步：验证自调优确实生效

等至少一个校准周期（默认 900s）过去后，用 Routing Events 路由查校准记录。注意 analytics 路由需要TENANT_HEADER（来源：Analytics Endpoints）：

curl "$BASE_URL/analytics/routing-events?range=1d" \ --header "$AUTH_HEADER" \ --header "$TENANT_HEADER"

响应中的events数组里，event_type为calibration_applied的条目就是一次 Autopilot 重调。该路由返回的事件类型共四种：leader_changed、gateway_entered_auth_band、gateway_exited_auth_band、calibration_applied。

同时可以读回商户的 SR 配置，确认写入值带有source: "autopilot"标记（端点见 Routing Config Endpoints）：

curl "$BASE_URL/config/routing-keys" \ --header "$AUTH_HEADER"

curl "$BASE_URL/config-sr-dimension/merchant_demo" \ --header "$AUTH_HEADER"

两点校验限制要提前知道：

analytics 写入是异步的，刚产生的事件可能需要一小段时间才会出现在查询结果里；
文档未给出事件出现的具体时延承诺，查不到时先确认时间窗口（range/start_ms/end_ms）覆盖了校准发生的时间，且商户在窗口内确实有流量——任务从 ClickHouse 读的是最近 3600s 的交易量。

第四步：重置网关分数

当评分状态需要回到干净基线（例如文档提到模拟器 "Hard refresh" 场景，让新一轮模拟从零开始）时，调用分数重置端点：

curl --location "$BASE_URL/gateway-score/reset" \ --header "$AUTH_HEADER" \ --header "$TENANT_HEADER" \ --header "Content-Type: application/json" \ --data '{ "merchant_id": "merchant_demo" }'

这个路由和上面的 feature-flag 调用不同，除了$AUTH_HEADER还必须带$TENANT_HEADER。文档示例返回：

{ "merchant_id": "merchant_demo", "deleted_keys": 214, "removed_overrides": 3 }

以上为文档示例输出，deleted_keys与removed_overrides的实际值随商户当前状态变化。该操作：

从 Redis 中清空该商户所有 SR v2/v3 的分数与队列键；
移除所有 Autopilot 写入（source: "autopilot"）的子级配置覆盖——人工配置的覆盖会被保留；
不会禁用路由，也不会删除配置本身，只是清掉在线评分状态，让下一次决策从全新基线开始。

执行后无单独的校验端点；文档给出的判断口径是响应返回了删除键与移除覆盖的数量，后续决策即从干净基线计算。

限制与边界

没有手动触发一次校准的端点，只能等待轮询周期（默认 900s）到来；调整周期靠[sr_auto_calibration]配置段或SR_AUTO_CALIBRATION_INTERVAL_SECS环境变量。
发行配置只定义了public一个租户，TENANT_HEADER传其他租户值不会通过；需要多租户时按 Configuration 文档在[tenant_secrets]中自行添加。
关闭 Autopilot 只关掉写权限（把autopilot置为{"enabled": false}即可，命令同第二步），此前已写入并打上source: "autopilot"的覆盖值仍保留在配置中，需要时可用分数重置一并清掉。
沙箱环境（https://sandbox.hyperswitch.io）下所有请求需追加x-feature: decision-engine头，本地部署不需要。

深入端点 schema 时可参考仓库内 OpenAPI Reference；Autopilot 与 feature flag 的完整说明见 Merchant Features。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析