配置 API
配置 API 把模型选择、调度规则、下游输出和 Access Key 限制组合成一个可调用单元。每个配置与一个唯一的下游 Access Key 一对一绑定。
概念关系
配置 API
├─ 基础信息：名称、说明、启用状态
├─ 调度：固定 / 故障转移 / AI 智能调度
├─ 候选模型资源
├─ 下游输出：协议、对外模型名称、流式输出
└─ 唯一 Access Key：频率、可用模型创建配置
1. 基础信息
填写唯一的配置名称。可选填写说明，并决定创建后是否立即启用。配置停用时，对应 Access Key 无法调用。
2. 调度方式与候选模型
| 模式 | 标签 | 选择要求 | 失败行为 | | --- | --- | --- | | 固定模型 | 可用 | 选择一个模型资源 | 失败后直接返回错误 | | 故障转移 | 可用 | 按优先级排列多个模型 | 当前模型失败时继续下一个 | | AI 智能调度 | 可用 | 选择至少两个候选，并指定路由判断模型 | 路由模型失败时按候选顺序尝试 | | 自动调度 | 弃用、停用 | 不再接受新建或编辑 | 旧配置会被 Gateway 视为无可用候选 |
自动调度（按简单/普通/复杂请求分配模型）已弃用并停用。请改用故障转移或 AI 智能调度。
只有可路由的模型资源应进入候选池。优先选择健康状态明确的资源。
3. 下游输出
配置下游客户端看到的接口形式。默认为 OpenAI-compatible，并默认暴露一个下游模型。
- 对外模型名称：下游请求
model字段使用的名称。 - 调度目标：对外模型对应的当前调度和候选模型。
- 流式输出：允许下游请求使用
stream时返回流式响应。 - OpenAI Key 格式兼容：为强制校验
sk-前缀的客户端生成兼容格式。Base URL 仍必须指向 Lumoswitch。
4. Access Key 限制
可选设置：
- 每分钟请求数。
- 允许的模型范围。
默认不额外限制请求频率。生产环境建议按应用容量设置明确上限。
5. 创建并保存 Key
提交后，Lumoswitch 创建配置并生成唯一 Access Key。
完整 Access Key 仅在创建完成对话框中显示一次。丢失后无法从列表恢复明文，需要创建新 Key 或新配置。
编辑配置
编辑后，当前 Access Key 保留不变，新调度、输出和限制会立即影响后续调用。生产配置建议：
- 先确认新候选模型的健康状态。
- 保留至少一个已验证的回退资源。
- 低流量时段修改对外模型名称。
- 保存后立即发起最小请求并查看仪表盘。
调用配置 API
curl "https://your-gateway.example.com/v1/chat/completions" \
-H "Authorization: Bearer YOUR_LUMOSWITCH_ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_PUBLIC_MODEL_NAME",
"messages": [
{"role": "user", "content": "Hello"}
]
}'停用与删除
- 停用：保留配置和历史关联，但对应 Key 无法继续调用。
- 删除：撤销配置和对应 Key。已部署客户端将立即失去访问能力。
删除前请确认所有客户端已切换到新配置和 Key。