# Provider 与能力健康状态

本文对应 **Iris 0.2.7**，本页检测入口从 0.2.6 起提供。包含能力检测、目录与模型可用性；沿用短时限流冷却、明确额度/预算耗尽停用及持久健康证据。发布状态见 [README](../README.md)。

工作台的“能力状态与检测”与 [功能模型池](FUNCTION_MODEL_POOLS.md) 配套；以下健康证据规则继续适用。

## 工作台检测入口

能力检测默认折叠，只展示六项能力的近期成功与调用受阻摘要；点击“展开检测”后查看图片、视频、语音、音乐、转写、视觉六张能力卡及候选覆盖，例如“2个可用 · 1/2近期成功”。点卡片展开候选模型、最近验证时间和检测操作；供应商中的中文能力标签会直接展开检测区并打开对应详情。桌面随面板宽度排列，手机单列，适配宿主深浅主题。

工作台统一分区、标题、按钮和表单样式。功能池、创作工具、快捷偏好、诊断和历史按需展开，运行中及需要处理的任务直接展示；检测跳转会展开对应的功能设置或创作工具分区。折叠不取消正在执行的实测，也不清空已经返回的结果；未提交的实测确认在折叠时关闭，重新展开后需再次确认。

“检查配置”只读取当前分配、供应商元数据及历史健康状态，不调用模型，不把连接存在或模型名称当作实测成功。旧服务端缺少新策略字段时暂停实测，提示重新加载 DSH。真实实测先展示测试内容、具体模型及可能费用，确认后只调用这一项；提交前重新检查当前范围，停用、移出池、用途待确认或连接未就绪均不会提交。

图片使用红色圆形测试图，语音合成“你好”，视觉识别内置红图。视频、转写、音乐及宿主视觉提供“前往功能验证”，打开实际任务表单，用户填写素材并选择模型后提交；打开表单本身不发起生成。实测结果依据现有接口返回，不额外证明媒体已经下载或可播放。

逐项显示验证中、通过、未通过或结果未确认；确认期间防止重复提交。网络中断、超时或响应无法确认时保留未知结果，不自动重试；再次检查配置只读状态，不能证明上一请求未计费。冷却或额度耗尽的模型可显式实测恢复，仍须满足当前功能范围及连接要求。

### TTS 的接口与音色限制

当前接入 Qwen-TTS 普通 HTTP 合成，例如 `qwen3-tts-flash`；模型在具体账号、地域是否可用仍须实测。Qwen 的 `realtime` 语音模型使用 WebSocket；Qwen-Audio-TTS、CosyVoice、Sambert、MiniMax 语音系列需要各自的接口或参数适配，不能共用现有请求。已知接口缺口会显示具体原因、排除自动池并在手选提交时本地拒绝；从旧模型入口触发检测也只会跳过，不发送请求、不写成供应商实测失败。发现或确认 TTS 用途本身不证明接口已经接入。见[官方模型与协议对照](https://help.aliyun.com/zh/model-studio/tts-model/)及[Qwen-Audio-TTS HTTP 接口](https://help.aliyun.com/zh/model-studio/qwen-audio-tts-http-api)。

复刻（`vc`）和声音设计（`vd`）模型需要与模型匹配的自建音色。固定“你好”探针没有音色素材，因而跳过；实际使用时先创建音色，再到语音功能填写对应音色 ID，不能自动沿用普通模型的 `Cherry`。

遇到 `Model not exist`，先核对错误中的模型 ID、请求域名所属地域及该模型的接口。不要把整个供应商判为不可用，也不要批量重测其他模型。可先确认一个与现有 HTTP 接口匹配的模型用途，再单独确认费用进行实测；发现的新模型仍需确认，旧模型不会被自动删除或替换。修正后的提示保留上游错误与 HTTP 状态，不自动换地域、模型或重试。普通版请求格式见[官方 Qwen-TTS HTTP 文档](https://help.aliyun.com/zh/model-studio/qwen-tts-api)。

Iris 用持久化证据描述“当前配置是否存在、最近是否实际成功、是否出现明确凭据失败”。它不是后台监控，也不等同于 Host Doctor。

## 四种状态

| 状态 | 颜色 | 含义 |
|---|---|---|
| `unconfigured` | 灰色 | 当前能力没有启用且带凭据的候选模型 |
| `configured` | 蓝色 | 已配置，但没有 7 天内的成功证据；旧证据过期后也回到此状态 |
| `verified` | 绿色 | 该 Provider × Model × Capability 在 7 天内通过显式实测或真实任务成功 |
| `failed` | 暗红色或红色 | 明确认证/权限失败，或已确认额度/预算耗尽；短时限流另以琥珀色显示 |

状态按 `Provider × Model × Capability` 记录，不因同名模型而合并。模型、Key、Base URL、协议或能力模型等关键配置变化会清空相关旧证据；移除模型或能力标签也会移除不再成立的记录。

0.2.6 单独保存“当前连接明确返回模型不存在”的可用性证据：健康详情显示隔离原因，自动请求跳过该模型，历史成功仍保留。核对目录后可单独实测恢复；目录中列出仅证明发现信息，不能覆盖失败或算作成功验证。目录快照按需缓存，工作台默认折叠；只读配置检查不会同步或实测。完整边界见 [目录更新与候选可用性](FUNCTION_MODEL_POOLS.md#目录更新与候选可用性)。

模型可单独设置 `imageProtocol`，未设置或 `auto` 时继承账号默认。改变有效图片协议只使该模型的生图验证失效；同模型的视觉验证、其他模型及冷却/额度停用均保留。再次选择同一有效协议不清空验证。设置入口见 [CLI 管理命令](CLI_MANAGEMENT.md)，DSH 模型池的生图模型行也可修改。

## 什么会改变状态

显式“模型实测”和正常用户任务都会产生证据。视觉、图片和 TTS 可从模型池逐项实测；视频与转写不会发送空样本探针，应使用真实的视频生成或音频转写任务验证。成功受理、同步完成或视觉成功会刷新绿色及其成功时间。

Iris 不做定时后台探测，也不会为了让图标变绿而产生隐形请求或费用。网络错误、5xx、内容安全、用户取消和受理未知不会覆盖近期成功证据。移除 API Key 后回到灰色。

## 限流与耗尽的区别

HTTP 状态、供应商错误码和明确错误说明一起决定路由规则，不凭 `quota` 或 `limit` 字样推断额度耗尽。百炼的 `Throttling.AllocationQuota` 也可能表示 TPS/TPM 限制。分类依据见[阿里云错误码说明](https://www.alibabacloud.com/help/zh/model-studio/error-code)。

| 响应 | 路由与显示 |
|---|---|
| 短时或无法进一步确定的 429，包括频率、并发、服务忙 | 琥珀色“429 冷却中”，暂时跳过；优先遵从 `Retry-After` 秒数或 HTTP 日期，缺失或无效时默认 60 秒 |
| 403 `AllocationQuota.FreeTierOnly`，或 403/429 明确表示免费额度耗尽 | 红色“额度耗尽已停用”，手动实测成功后才恢复 |
| 429 `BudgetLimitExceeded` | 红色“预算耗尽已停用”，手动实测成功后才恢复 |
| 普通 401/403 认证或权限失败 | 保留认证失败语义，不套用额度耗尽停用 |

冷却与停用按 Provider × Model 记录，对同账号该模型的所有能力生效；其他账号的同名模型不受影响。状态持久保存，重启后继续遵守。正常路由、显式生成和 OCR 后续切片都会跳过受阻模型；已受理 Task 仍可观察原远端任务，绝不因此自动重提。

模型池显示原因及冷却恢复时间，实测按钮保持可用。冷却到期只恢复候选资格，不触发验证请求；颜色按原有证据返回蓝色或绿色。发现、修改分配、改 Key/端点、移除再添加同名模型，以及旧任务成功，都不能解除明确耗尽的停用。显式实测只调用指定模型，失败不恢复，成功解除该账号该模型的冷却或停用。视频/转写实测须用 CLI `models test --input` 明确提供真实素材，未提供时跳过，见 [CLI 管理命令](CLI_MANAGEMENT.md)。

## failover 与泡泡汇总

每项能力按当前有序 failover 候选汇总：

1. 任一路候选为绿色，能力为绿色；
2. 否则任一路为蓝色，能力为蓝色；
3. 所有已配置候选均受阻时显示调用受阻；若全部只是冷却，显示琥珀色及最早恢复时间；
4. 没有候选时为灰色。

主泡泡再按六项能力使用同一保守规则汇总。汇总证据时间只从决定汇总颜色的候选中选择，例如绿色不会显示另一条较新蓝色临时观察的时间。界面同时显示文字和证据时间，不要求用户只凭颜色判断。

## 与诊断的区别

Host Doctor 只检查 DSH、Iris 注册、Host Port、客户端版本和 UI Slot 是否装载；它零网络、零计费，不能证明 API Key 或具体模型可用。Provider 健康来自模型实测和真实业务请求，才回答供应商侧是否近期成功。离线 `dsh-iris doctor` 则检查本地运行时、配置、存储与任务一致性，三者不能互相替代。

健康事实保存在 `$DSH_HOME/iris/v1/providers.json`；可选 `health.rateLimits` 保存模型、时间、来源、HTTP 状态、冷却截止时间或耗尽原因，沿用 v1 配置，不要求迁移。状态 API 仅返回脱敏标量。错误说明会移除 Authorization、Key、签名参数、私有路径和已配置的完整 API Key。