模型健康探测与恢复

本页阅读位置

完成第一轮对话后，按当前业务需求深入。Spring 常规声明优先使用 RegistrationManifest 与注解；本页的底层 register / publish 或直连方法供协议细化与兼容集成参考。

在管理页面操作

进入「模型绑定」，在已发布版本点击「模型健康」。先阅读当前状态、最后结果和探测范围，再勾选检查项、填写原因，点击「开始受限探测」。文本连接必选，可同时验证工具调用协议、原生文本流和结构化输出。已撤销绑定可查看历史，不能进行新探测。应用暂停或归档后，手动与自动探测均不发送供应商请求；草稿应用可在启用业务前验证连接。

探测会调用真实供应商，可能产生费用；每项最多 32 输出 Token（受模型声明上限进一步限制），每次最多四项、总时间上限 20 秒。工具检查只验证虚拟 health_echo 调用协议，绝不执行真实函数、读取业务知识或提交业务写入。探测使用固定合成输入，不携带业务主体、会话正文或业务 Context。

「请求恢复探测」需填写原因，只把模型置为待恢复隔离，不直接标记健康；恢复必须由探测证明连接可用。密钥被拒绝时先在部署环境修复密钥/权限，再请求恢复。探测或恢复修订冲突时重新打开页面读取当前记录，不能盲目重试。

状态与证据

状态	含义与操作
CLOSED	允许业务流量；初始状态也为 CLOSED，未探测不代表服务和能力已验证
OPEN	连续瞬时错误已隔离；后续业务候选拒绝发送，可按路由允许的 MODEL_CIRCUIT_OPEN 切换
HALF_OPEN	单个恢复探测占用中；业务流量仍隔离，不用真实用户请求试探
BLOCKED	供应商凭据被拒绝；业务直接失败，不自动切换掩盖配置错误；修复后主动探测

业务成功清理连续错误；服务不可用、超时和供应商限流在配置窗口达到阈值后隔离。收到部分文字或工具参数仍遵守禁止切换的规则。已开始的请求可能继续结束，旧请求的成功不能覆盖后来进入的隔离状态。作用域是「消费应用 + 模型作用域 + 模型/供应商精确版本」，一个应用的健康操作不会改变另一应用的共享模型状态。

租约与发布状态仍独立检查；租约有效不等于服务可用。探测结果为 SYNTHETIC_PROBE，只证明该时间、协议、合成输入和检查范围，不能作为所有提示词/数据的认证；不会修改已发布的能力声明。需要更新声明时创建并发布新模型版本。

看懂探测记录

单项状态为 PENDING、PASSED、UNSUPPORTED、FAILED、UNKNOWN 或 SKIPPED；整体 COMPLETED 仅表示程序结束，不表示所有能力通过。认证拒绝使用 MODEL_AUTH_FAILED；工具/结构化检查未符合合成契约显示 MODEL_FEATURE_UNSUPPORTED；原生流协议错误单独显示 MODEL_PROTOCOL_ERROR。REMOTE 流按 REMOTE 1.0 事件验证；未实现流的适配器返回明确错误，不能宣称已验证。

记录包含检查范围、开始/发送/结束时间、协议版本引用、固定价目、原始供应商用量、配置费用与结果代码，不保存供应商密钥、服务地址或生成全文。SENT 只证明进入发送边界，可能已被供应商接受；未收到用量时保持未知。探测费用单独记录，不并入业务 Run 的账本，不能用零代替未知费用或与不同币种相加。

失联探测占用到期后登记 UNKNOWN 和 PROBE_RESULT_LOST，保留已经收到的证据并回到隔离状态。人工恢复使旧探测 SUPERSEDED，迟到结果不能重新放行流量。历史分页默认 20，1..100；offset 默认 0，最大 1000000。页面每次加载 10 条。

配置部署预算

环境变量	默认值与范围
SPARKTIDE_MODEL_FAILURE_THRESHOLD	3，1..20，连续瞬时错误阈值
SPARKTIDE_MODEL_FAILURE_WINDOW_SECONDS	60，10..3600，错误窗口
SPARKTIDE_MODEL_OPEN_SECONDS	30，1..3600，自动恢复等待期
SPARKTIDE_MODEL_PROBE_INTERVAL_SECONDS	30，10..3600，同一模型最小探测间隔
SPARKTIDE_MODEL_PROBE_TIMEOUT_SECONDS	5，1..10，单项探测超时，仍受 20 秒总预算限制
SPARKTIDE_MODEL_PROBES_PER_MINUTE	6，1..60，每消费应用每分钟最多探测批次
SPARKTIDE_MODEL_AUTO_PROBE	false；true 开启周期扫描到期隔离模型的文本恢复探测

平台同时最多两个探测批次、每分钟总上限 120 批次；数据库预留实现多实例共同限额，单进程也最多两个并发。人工重置不清除探测间隔或分钟预算。默认关闭周期探测，开启前为供应商费用预留预算；自动恢复仅 TEXT 连接检查，不宣称复验所有能力。多实例使用一致的运维配置。服务原点和密钥仍遵守部署白名单/归属规则，不允许任意探测地址。

API 与 Java/Kotlin

管理凭据调用固定版本绑定下的入口：

方法与路径后缀	返回
GET /health	当前健康状态、policy、recentFailures、最后结果与合成验证范围
GET /probes?limit=20&offset=0	items、total、limit、offset 的历史分页
POST /probes	正文 checks 与 reason；返回 probe 与 health
POST /health/reset	正文 reason，If-Match 是健康 revision；返回隔离后的健康状态

完整前缀为 /v1/apps/{app}/model-bindings/{bindingId}/versions/{version}，不是模型服务地址。普通业务用户不能调用这些管理入口。管理身份读取、探测开始/结束和恢复都有审计。

Java

var request = new ModelProbeRequest(
    List.of(ModelProbeRequest.Check.TEXT, ModelProbeRequest.Check.TOOL_CALLING),
    "验证供应商升级后的协议支持");
var result = client.probeModel("business-model", "1.0.0", request)
    .toCompletableFuture().get();
var health = client.modelHealth("business-model", "1.0.0")
    .toCompletableFuture().get();
var history = client.modelProbes("business-model", "1.0.0", 20, 0)
    .toCompletableFuture().get();
client.resetModelHealth("business-model", "1.0.0", "修复凭据后申请复验",
    ((Number) health.get("revision")).longValue());

Kotlin

val result = client.performModelProbe("business-model", "1.0.0",
    ModelProbeRequest(listOf(ModelProbeRequest.Check.TEXT), "恢复连接验证"))
val health = client.getModelHealth("business-model", "1.0.0")
val history = client.listModelProbes("business-model", "1.0.0")
client.requestModelRecovery("business-model", "1.0.0", "修复后再探测",
    (health["revision"] as Number).toLong())

代码放在管理后台；Kotlin 包装从 dev.sparktide.sdk.kotlin 导入，在协程中调用。恢复方法 Java 返回 CompletionStage，按业务需要等待完成。SDK 不自动重试探测写请求；客户端超时后先查询历史确认原请求。409 可表示已有探测/已撤销/应用停用；412 表示修订变化；429 表示间隔、分钟或并发预算；供应商错误作为单项报告返回，HTTP 200 不能当作能力成功。

路由默认将 MODEL_CIRCUIT_OPEN 视为可切换错误；显式配置旧白名单会保持原规则，需自行加入此项才能避开隔离候选。认证错误、协议错误和请求拒绝仍不允许自动切换。

升级、验证与回退

升级前备份数据库，V11 新建健康与探测表，不回填历史故障。完整平台/SDK 构建、故障注入、并发代际、费用和控制台证据以交付记录为准；本地测试替身不能代替生产厂商协议验收。回退前关闭周期探测，保留 V10/V11 财务与健康证据；旧程序可能重新向故障供应商放行流量，需由网关或业务运维限制。不要删除证据、强改发布声明或重放未知调用。

文档来源与验证记录

字段	内容
状态	已确认
日期	2026-09-30
来源	ModelHealth、固定模型路由、V11 迁移与健康测试
责任人	SparkTide 维护者
关联任务	M03