路由与故障转移

XSI 的路由回答两个问题:请求发往哪个模型,以及由哪个上游 Key 承载。前者由模型映射决定,后者由 Level(Key 池分组)与调度策略决定。

核心对象

对象说明
Provider Key租户录入的上游 Key,带有 Provider(上游地址)、Level、启用状态等属性
LevelKey 池分组编号。同一 Level 内的 Key 组成一个轮询池
MODEL_MAPPER模型改写规则:请求模型 → 上游模型
LEVEL_MAPPER分组规则:上游模型 → Level
Gear账号的路由模式,决定使用租户映射还是账号自身映射,以及能否跨组重试

典型配置:OpenAI Key 放在 Level 1,Anthropic Key 放在 Level 2,DeepSeek Key 放在 Level 3,再设置 LEVEL_MAPPER = gpt*=1, claude*=2, deepseek*=3。录入 Key 时 XSI 会按服务商自动补全这类映射。

模型解析

请求模型按以下顺序解析,取第一个命中项:

  1. 当前生效的模型故障替换(MODEL_FAILOVER,见下文)
  2. 账号级 ModelMapper:先精确,再通配
  3. 租户级 MODEL_MAPPER:先精确,再通配
  4. 模糊匹配:模型已在价格表中则原样使用;否则在同家族、同模态的已定价模型中选择版本最接近者(例如 gpt-image-2.5-flare → gpt-image-2.6-flare),latest、preview、日期快照等后缀被忽略
  5. 原样使用

解析结果会真正改写发给上游的模型名(JSON 的 model、multipart 字段或 URL 中的模型),并缓存为账号级的精确映射,后续请求优先命中。因此通过 PUT /x-config 修改租户映射后,已解析过该模型的账号会继续使用缓存结果;需要立即生效时,用 POST /x-conf 的 ModelMapper 同步到后代。

通配规则:* 匹配任意字符,其余字符按字面匹配。多个通配同时命中时,优先选择字面后缀更靠近模型名末尾、后缀更长、前缀更长、字面总长更长、* 更少的模式。

MODEL_MAPPER = gpt-latest=gpt-6.2-sol, claude-*-latest=claude-sonnet-5-5

Level 解析

账号 GearLevel 来源未命中时
Gear > 0(跟随租户)租户 LEVEL_MAPPER:先精确,再通配(最长模式优先)账号自身的 Level
Gear ≤ 0(独立)账号自身的 LevelMapper账号自身的 Level

新账号的 Gear 继承自父账号;root 与注册账号默认 Gear = 1,即跟随租户配置。

Key 选择

  • 每个租户的每个 Level 维护一个轮询环,跳过禁用与休眠中的 Key。
  • Responses、Chat Completions 与 Messages 请求使用粘性会话:同一会话固定到同一个 Key,以提高提示缓存命中率,并让 GET /v1/responses/{id} 读到同一上游账号上的结果。会话标识依次取请求头 session_id、conversation_id,请求体 prompt_cache_key,请求头 session-id、thread-id;都没有时按“租户 + 账号 + Level”固定。绑定默认保留 24 小时(STICKY_BINDING_TTL)。
  • 粘性调度默认对所有 Level 开启(STICKY_SCHEDULER=true);设为 false 后只对租户 STICKY_LEVELS 中的 Level 开启。
  • 视频轮询固定使用创建任务的 Key;DeepSeek 文件请求固定使用上传文件的 Key。
  • Level 中没有可用 Key 时返回 500 No available key。

自动重试

重试发生在向客户端写出任何字节之前,对流式请求同样有效:

项目规则
适用请求POST
触发状态400 < status < 600 且不在 NO_RETRY_STATUS(默认 200,400,403,404,405,413,421,422,499,500)
同组重试当前 Level 内最多 7 次,避开最近一次失败的 Key(池中只有一个 Key 时可能重试同一个 Key)
跨组重试Gear ≤ 0 的账号:在账号 AllowLevels 中的其他 Level 上各最多 3 次;Gear > 0 的账号不跨 AllowLevels,但可能在映射得到的 Level 与账号自身 Level 之间重试
例外Responses 创建返回 400 且提示 not supported 时,只在同组换 Key;视频创建永不重试

全部失败时,客户端收到首次失败的上游响应。

Key 休眠与生命周期

机制条件效果
自动休眠上游返回 STATUS_CODES 中的状态(默认 429,401,402,503,408,524);同组多于 1 个 Key;Key 的 Level > 0;未设置 NoSleep退出轮询 KEY_BACK 分钟(默认 60)
唤醒同伴同组仅剩的 Key 也失败唤醒同组中自动休眠的 Key,避免整组不可用
手动休眠POST /x-keys/{id}/sleep32 小时
自动禁用上游返回 AUTO_DISABLE_KEY_STATUS 中的状态Status=false,直到手动启用
自动删除上游返回 AUTO_DELETE_KEY_STATUS 中的状态删除 Key

自动禁用与自动删除默认关闭,且不会作用于同组中最后一个启用的 Key。例如 AUTO_DISABLE_KEY_STATUS=401 可让被上游吊销的 Key 自动退出。

分组切换与模型故障替换

当同一租户下同一模型的失败次数累计达到 MODEL_FAILOVER_THRESHOLD(代码默认 3,Compose 模板为 2)时触发;只要相邻两次失败的间隔不超过 1 分钟就持续累计,中间的成功请求不会清零:

机制配置适用账号效果持续时间
分组切换SWITCH_OVER = 1=3Gear > 0该模型在租户内临时改用目标 LevelSWITCH_OVER_TTL(默认 1 小时)
模型故障替换MODEL_FAILOVER = gpt-6.2-sol=gpt-6.1-sol未发生分组切换时对该账号临时把模型替换为备用模型(必须已定价),并通知运营者MODEL_FAILOVER_TTL(默认 1 小时)

状态码在 NO_RETRY_STATUS 中的失败不计入。切换与替换状态保存在各实例内存中。

配置示例

curl -X PUT "$XSI_BASE_URL/x-config" \
  -H "Authorization: Bearer $XSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "LEVEL_MAPPER": "gpt*=1, claude*=2, deepseek*=3",
    "SWITCH_OVER": "1=4",
    "MODEL_FAILOVER": "claude-opus-5-5=claude-sonnet-5-5"
  }'
  • Level 1 放主力 OpenAI Key,Level 4 放备用(例如 Azure OpenAI),持续失败时自动切换。
  • Opus 持续失败时,受影响账号临时改用 Sonnet。

相关文档