如何为HexStellar选对--effort:flash/medium/high搜索预算、延迟SLA与成本控制完整教程
如何为HexStellar选对--effort:flash/medium/high搜索预算、延迟SLA与成本控制完整教程
如果你正在用 HexStellar Python CLI 求解优化与决策问题,那么为每次求解选对 --effort(flash / medium / high)搜索预算,直接决定了你的响应速度、花费和结果质量。本教程带你一次搞懂:三档 --effort 各自的定位与适用场景、如何用 --max-latency-ms 给自己设置延迟 SLA,以及如何用"先估算、再执行"的工具链把成本锁死在预算内——新手照做即可,让每个问题都以合适的速度拿到合适的成本。
先看懂三档搜索预算:flash、medium、high
--effort 的本质是搜索预算(search budget),不是质量开关。每一档的定位如下:
| 档位 | 定位 | 什么时候用 |
|---|---|---|
flash |
延迟最低,约 1 秒内返回 | 第一次验证编码是否正确;记录延迟/成本基线 |
medium |
实测的"质量/成本"平衡点(省略参数时的服务默认值) | 日常规模化运行的主力档 |
high |
搜索最深 | 只在已通过 flash 的实例上跑一次,绝不作为首次尝试 |
三个实用细节:
- 每个响应都会回显
effort、effort_notice和efforts_available(即['flash','medium','high']),你永远知道本次用的是哪档; - 旧拼写
low/med/max仍被接受,但它们只是输入别名(映射到 medium / medium / high),响应与 schema 只使用规范名。归一化逻辑见 hexstellar/_meta.py; - ⚠️ 最常见的误区:更大的 effort 不会把
heuristic(启发式候选)升级为certified(已认证最优)。effort 只决定搜索挖多深,从不动正确性标签。
推荐流程:flash-first 评估(官方默认做法)
HexStellar 的官方规范(AGENT_SPEC.md 与 llms.txt)明确要求"flash-first":任何新公式化的第一次运行都从 flash 开始,而不是一上来就梭哈 high。
推荐的四步流程:
- 免费预检:先跑
--dry-run,完成验证 + 成本估算,零上传、零计费; - flash 首跑:在(缩小的)实例上
--effort flash,记下elapsed_ms、peak_rss_kb、compute_units三项实测数据,这就是你的延迟/成本基线; - 按需升级:只有当"更深搜索值得这笔实测成本"时,才切到
medium或high; - 诚实读数:每次评估都记录"编码、n、effort、certainty、收据、领域残差"。
⚠️ 一个容易踩的坑:省略 --effort 时服务会回退到兼容默认值 medium,但官方明确建议可复现评估中显式写明档位,不要依赖省略。
设置延迟 SLA:--max-latency-ms 让请求永不失联
如果你的调用方(比如一个有 15 秒超时的网关)会在长请求上断连,--max-latency-ms N 就是为你设计的墙钟 SLA,适用于搜索类命令(optimize / feel / want / maxcut / tsp / qap / select / design):
- 预算耗尽时,引擎停止搜索并返回截至此刻找到的最好配置,响应带上
stopped_at_deadline: true——优雅降级,绝不崩溃、绝不丢连接、更绝不伪造certified; - 设置原则:把它设在你自己的超时之下,例如你有 15 秒超时,就设
--max-latency-ms 8000; - 传
0或省略 = 不限制。注意它约束的是搜索阶段,超大问题的解析开销可能让总耗时略超预算。
echo '<问题JSON>' | hexstellar solve maxcut --effort high --max-latency-ms 5000
# → 返回 5 秒内找到的最佳答案,标记 stopped_at_deadline:true,而不是断连
更多语义细节见 AGENT_SPEC.md 中对 --max-latency-ms 的完整说明。
成本控制三板斧:估算、预算护栏、配额警报
HexStellar 把成本控制做成了三道闸,全部围绕"先免费估算,再花钱执行":
1️⃣ 免费估算:--dry-run 与 hexstellar estimate
两者都是零计费的预检:校验输入 + 返回难度、建议 effort、compute_units 估算值。而且估算是 effort 敏感的——hexstellar estimate <command> --effort high 会告诉你"这一档到底值多少钱",让你在真正花钱前对比 flash / medium / high 的价差。
2️⃣ 预算护栏:--max-compute-units N(fail-closed 经济防火墙)
设置后,CLI 会先免费估算(按你请求的 effort),一旦估算超过预算就直接拒绝求解:返回 HXS_BUDGET_EXCEEDED、什么都不计费、solve_started: false。它返回的 next_actions 还贴心地给出菜单:降低 --effort、提高预算、缩小问题规模。护栏实现可看 hexstellar/commands/solve.py——典型用途:在循环或 agent 自动求解时,防止一个意外的 n=3000 大实例烧光当天沙盒配额。
3️⃣ 配额警报:usage_alert 与 hexstellar pricing
hexstellar pricing免登录即可获取定价与计量规则(公共 JSON);- 当你的用量超过每日配额的 50% 后,每个成功响应都会附带
usage_alert(50% / 80% / 95% 三级阶梯:notice → warning → critical),让你在撞上 402 之前就能规划——官方建议此时优先--dry-run复核并考虑调低--effort; - 另外两条省钱机制:计费是幂等的(完全相同的重跑绝不重复扣费),配额按天计算、UTC 00:00 重置。
场景速查表:按场景选参数
| 你的场景 | 推荐参数 |
|---|---|
| 第一次跑新编码,只想验证对不对 | --effort flash |
| 日常 API / 批处理调用 | --effort medium + --max-compute-units 预算 |
| 一次性深挖最优候选 | --effort high(仅限已通过 flash 的实例,且只跑一次) |
| 上游有固定超时(如 15 s) | --max-latency-ms 8000(设为小于自身超时) |
| 循环 / agent 自动求解,怕超支 | --max-compute-units N(fails closed,超预算直接拒绝) |
| 先问价、再决定跑不跑 | hexstellar estimate <cmd> --effort <档位>(免费) |
| 配额已过半,想省一点 | 回退到 flash 或缩小问题规模,盯 usage_alert |
常见误区清单
- ❌ "high 总归更好" → high 从不是首次尝试;flash 才是"验证编码"的第一刀;
- ❌ "effort 越高答案越可信" → effort 绝不升级 assurance,
heuristic候选无论跑多深都要你自行验证; - ❌ "不写 --effort 也没事" → 省略时默认
medium没错,但可复现评估应显式声明; - ❌ "
stopped_at_deadline:true代表失败" → 它恰恰是诚实的"当前最优近似",比一条断掉的连接有价值得多; - ❌ "预算被拒了还能重试绕过" →
HXS_BUDGET_EXCEEDED是本地 fail-closed 拒绝,正确动作是降 effort / 提预算 / 缩小问题。
延伸阅读
- PARAMETERS.md — 一页纸总览所有参数旋钮及其"创意用法"
- AGENT_SPEC.md — 全局 flag(
--effort、--max-latency-ms、--max-compute-units)的完整语义 - AGENTS.md — "What each flag REALLY changes" 速查表
- AI_MANIFEST.json — 机器可读契约:
effort_self_description与minimum_evaluation_protocol - examples/index.json — 本地示例目录,挑一个从
--effort flash开始练手