配置 API

配置 API 把模型选择、Lumoswitch Runtime 路由策略、一个或多个对外模型名称和 Virtual Key 限制组合成一个可调用单元。每个配置有一个当前 Access Key；替代式轮换的宽限期内旧 Key 可以短暂并存。

平台模型和接入模型只在资源来源上不同。进入配置 API 后，两者使用相同的候选选择、路由、已启用下游格式和 Access Key 逻辑；平台模型不会获得绕过路由的直接 Key。

概念关系

配置 API
  ├─ 基础信息：名称、启用状态
  ├─ 调度：固定 / 故障转移 / 自动路由 / 最少繁忙 / 最低延迟
  ├─ 候选模型资源
  ├─ 下游输出：对外模型映射与已启用格式
  └─ 当前 Access Key：频率、可用模型

创建配置

1. 基础信息

填写唯一的配置名称，并决定创建后是否立即启用。配置停用时，对应 Access Key 无法调用。

2. 调度方式与候选模型

模式	选择要求	请求行为
固定模型	一个模型资源	始终调用同一模型
故障转移	一个以上，按优先级排列	当前模型失败时继续下一个候选
自动路由	两个以上，由轻量到推理排列	根据请求复杂度选择 `SIMPLE` 到 `REASONING` 层级
最少繁忙	两个以上	选择活动请求最少的候选
最低延迟	两个以上	选择已观测响应延迟最低的候选

只有可路由的模型资源应进入候选池。优先选择健康状态明确的资源。

自动路由由 Lumoswitch Runtime 的 auto_router/complexity_router 执行，并启用会话亲和性。最少繁忙和最低延迟通过当前 Access Key 的 router_settings.routing_strategy 执行；切回固定、故障转移或自动路由时会清空旧的 Key 级策略。

3. 下游输出

配置下游客户端使用的一个或多个对外模型名称，并选择开放 OpenAI-compatible、Anthropic Messages 和/或 Gemini generateContent。三种格式都直达Lumoswitch 推理服务。

对外模型名称：下游请求 model 字段使用的名称；一个配置最多可保存 20 个不重复名称。
当前配置：该名称使用当前调度模式和全部候选模型。
指定候选模型：该名称直接映射到一个候选资源，不经过配置级故障转移。

默认创建一个指向“当前配置”的对外模型。需要为不同客户端提供别名或显式开放单个候选时，可以继续添加映射。删除或修改现有名称前，应先更新所有下游客户端。

4. Access Key 限制

可选设置：

每分钟请求数。
允许的模型范围。

默认不额外限制请求频率。生产环境建议按应用容量设置明确上限。

5. 创建并保存 Key

提交后，Lumoswitch 创建配置并生成初始 Access Key。

完整 Access Key 仅在创建完成对话框中显示一次。丢失后无法从列表恢复明文，需要创建新 Key 或新配置。

编辑配置

编辑后，当前 Access Key 保留不变，新调度、输出和限制会立即影响后续调用。生产配置建议：

先确认新候选模型的健康状态。
保留至少一个已验证的回退资源。
最低延迟模式先用非生产流量预热观测数据，再在低流量时段切换。
低流量时段修改、删除或重定向现有对外模型名称。
保存后立即发起最小请求并查看仪表盘。

配置预设

配置编辑器中的“我的预设 / 官方预设 / 社区预设”读取真实的 Configuration Template 数据。应用前会按当前区域模型目录执行 preview；缺少必需模型时不会静默降级。个人预设支持保存不可变新版本、发布、收藏、fork、导入、脱敏导出和归档。

调用配置 API

curl "https://api.lumoswitch.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_LUMOSWITCH_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CLIENT_FACING_MODEL_NAME",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

停用与删除

停用：保留配置和历史关联，但对应 Key 无法继续调用。
删除：撤销配置和对应 Key。已部署客户端将立即失去访问能力。

删除前请确认所有客户端已切换到新配置和 Key。

On this page