Provider 故障排查

Provider 连通性测试、常见错误、fallback 行为、Vision 检测、rate-limit 处理和密钥恢复。

连通性测试

Chat 模式

POST /cells/{cellID}/providers/test
Content-Type: application/json

{
  "provider_name": "azure-legal",
  "mode": ""
}

Embedding 模式

POST /cells/{cellID}/providers/test
Content-Type: application/json

{
  "provider_name": "azure-legal",
  "mode": "embedding"
}

Vision 模式

POST /cells/{cellID}/providers/test
Content-Type: application/json

{
  "provider_name": "azure-legal",
  "mode": "vision"
}

常见错误及处理

错误	含义	处理方式
`ErrVisionNotSupported`	模型不支持 Vision	切换到 `SupportsVision=true` 的模型
`ErrProviderStrategyUnset`	两侧池非空但未声明策略	显式设置 ProviderStrategy
`ErrModelRequired`	未指定模型	应用层显式传入 Model
`context_length_exceeded`	超出上下文窗口	配置 `Models[].ContextWindow`
401 Unauthorized	凭证过期	检查 SecretRef 配置
429 Too Many Requests	rate-limit	自动 fallback 到下一个 Provider

Fallback 行为

SequentialFallbackResolver

当主 Provider 返回 401/429/5xx 时，resolver 按顺序尝试下一个可用 Provider。

Provider A (wes:) → 401 (JWT 过期)
  ↓ fallback
Provider B (byok:openai) → 200 ✓

INV-BILLING-04：BillingRequired=true 的 provider 凭证过期后，上游返回 401，正常 fallback 到 BYOK provider。

四种 ProviderStrategy

策略	尝试顺序
`own_only`	Cell 私有 → 无 fallback
`shared_only`	Hypervisor 共享 → 无 fallback
`own_first`	Cell 私有 → Hypervisor 共享
`shared_first`	Hypervisor 共享 → Cell 私有

Vision 能力检测

Vision 能力声明在 Models[].SupportsVision（不是 Provider 级别）。

providers:
  - name: openai
    models:
      - id: gpt-4o
        supports_vision: true
      - id: gpt-4o-mini
        supports_vision: false

请求含 image ContentBlock 但模型未声明 SupportsVision=true 时：

硬错误 ErrVisionNotSupported（不再静默剥离图片）

Rate-Limit 处理

per-Cell health tracking 在连续失败后触发 rate-limit：

引擎记录每次调用的成功/失败状态
连续失败达到阈值 → 标记该 Provider 为 unhealthy
后续请求自动 fallback 到下一个 Provider
周期性 re-probe 检查恢复

密钥失效恢复

场景：spec.key 丢失

spec.key 丢失后，引擎降级挂载 Cell（degradedSecrets 台账记录）。

恢复步骤：

恢复 spec.key 文件到 {DataDir}/secrets/spec.key
重启引擎（或通过 API 重新配置 Provider）
引擎自动 decode 密文

INV-PERSIST-07：降级态下的写入被拒绝（ErrDegradedSecretOverwrite），防止空密文覆盖原密文。

SecretRef 三源

Source	说明	换机代价
`inline`	AES-256-GCM 封套落盘	需随 spec.key 一起迁移
`env`	环境变量，不落盘	重放注入方
`live`	运行时动态获取	重放注入方

诊断命令

# 查看 Hypervisor 快照（含 Provider 状态）
curl http://localhost:9091/admin/observe/snapshot | jq

# 查看 Provider 延迟统计
curl http://localhost:9091/admin/observe/provider-latency | jq

# 查看 Cell 内 Provider 列表
curl http://localhost:9091/cells/{cellID}/providers | jq