配置 API

配置 API 把一个或多个独立调度模块、对外模型名称和 Virtual Key 限制组合成一个可调用单元。每个配置在产品界面中有一个当前 Access Key；底层允许轮换期间多个 Key 短暂并存。

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

概念关系

配置 API
  ├─ 基础信息：名称、启用状态
  ├─ 调度方式与模型模块 1
  │   ├─ 自定义名称：默认按调度方式编号
  │   ├─ 调度：固定 / 故障转移 / 自动路由 / 最少繁忙 / 最低延迟
  │   ├─ 候选模型资源
  ├─ 调度方式与模型模块 2 ...
  ├─ 推理入口与下游模型
  │   ├─ 已启用下游格式
  │   └─ 下游模型 ID -> 调度模块或具体候选模型
  └─ 当前 Access Key：频率、可用模型

创建配置

1. 基础信息

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

2. 调度方式与候选模型

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

一个配置可以添加多个“调度方式与模型”模块，每个模块独立命名并选择模式和候选。名称默认按调度方式编号，例如 固定模型1、固定模型2、故障转移1，也可以改成业务名称。只有可路由且健康状态明确的模型资源应进入候选池。

自动路由由 Lumoswitch Runtime 的 auto_router/complexity_router 执行，并显式启用会话亲和性；该设置在已审查的 LiteLLM 版本中自动包含 deployment pin。故障转移、最少繁忙和最低延迟分别编译为 Runtime 全局独立路由组，Access 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