如何为HexStellar选对--effort:flash/medium/high搜索预算、延迟SLA与成本控制完整教程

原创2026-10-11 19:02:531,673 阅读

如何为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。

推荐的四步流程:

  1. 免费预检:先跑 --dry-run,完成验证 + 成本估算,零上传、零计费;
  2. flash 首跑:在(缩小的)实例上 --effort flash,记下 elapsed_ms、peak_rss_kb、compute_units 三项实测数据,这就是你的延迟/成本基线;
  3. 按需升级:只有当"更深搜索值得这笔实测成本"时,才切到 medium 或 high;
  4. 诚实读数:每次评估都记录"编码、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 开始练手
登录后查看全文
hexstellar