路由与故障转移
XSI 的路由回答两个问题:请求发往哪个模型,以及由哪个上游 Key 承载。前者由模型映射决定,后者由 Level(Key 池分组)与调度策略决定。
核心对象
| 对象 | 说明 |
|---|---|
| Provider Key | 租户录入的上游 Key,带有 Provider(上游地址)、Level、启用状态等属性 |
| Level | Key 池分组编号。同一 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 会按服务商自动补全这类映射。
模型解析
请求模型按以下顺序解析,取第一个命中项:
- 当前生效的模型故障替换(
MODEL_FAILOVER,见下文) - 账号级
ModelMapper:先精确,再通配 - 租户级
MODEL_MAPPER:先精确,再通配 - 模糊匹配:模型已在价格表中则原样使用;否则在同家族、同模态的已定价模型中选择版本最接近者(例如
gpt-image-2.5-flare→gpt-image-2.6-flare),latest、preview、日期快照等后缀被忽略 - 原样使用
解析结果会真正改写发给上游的模型名(JSON 的 model、multipart 字段或 URL 中的模型),并缓存为账号级的精确映射,后续请求优先命中。因此通过 PUT /x-config 修改租户映射后,已解析过该模型的账号会继续使用缓存结果;需要立即生效时,用 POST /x-conf 的 ModelMapper 同步到后代。
通配规则:* 匹配任意字符,其余字符按字面匹配。多个通配同时命中时,优先选择字面后缀更靠近模型名末尾、后缀更长、前缀更长、字面总长更长、* 更少的模式。
MODEL_MAPPER = gpt-latest=gpt-6.2-sol, claude-*-latest=claude-sonnet-5-5Level 解析
| 账号 Gear | Level 来源 | 未命中时 |
|---|---|---|
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}/sleep | 32 小时 |
| 自动禁用 | 上游返回 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=3 | Gear > 0 | 该模型在租户内临时改用目标 Level | SWITCH_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。