核心概念

在配置 Lumoswitch 前，先理解调用链上的几个对象。最常见的配置错误，都来自将上游 Key、Lumoswitch Access Key 和模型名称混在一起。

调用链

下游应用 / Agent / 开发工具
  -> Lumoswitch Base URL + Access Key
  -> 配置 API（对外模型 + 调度规则）
  -> 模型资源
  -> 上游 + 凭证池
  -> 接入渠道

下游与上游

• 下游：调用 Lumoswitch 的应用，例如 OpenAI SDK、Codex、OpenWebUI 或你的服务。
• 上游：由 Lumoswitch 推理服务实际请求的模型服务，例如 OpenAI、DeepSeek、Qwen 或本地 Ollama。
• 模型厂商：实际创建模型的组织，例如 Anthropic、DeepSeek 或月之暗面。
• 接入渠道：提供模型 API 的服务，例如 OpenAI API、OpenRouter 或 Together AI；它可能分发多个厂商的模型。

下游只应持有 Lumoswitch Access Key，不应接触上游渠道 Key。

上游与凭证池

一个上游是某个接入渠道的已配置账号和端点，定义 Base URL、协议和凭证池。模型列表从上游拉取；上游可包含多个加密凭证。不同凭证优先级会编译为有序回退层级，同优先级部署由 Lumoswitch Runtime 按当前运行策略选择，Lumoswitch 不承诺固定轮询。

模型资源

模型资源是“某个上游通过某个凭证提供的某个模型”。同一 providerModelId 来自不同上游时，是不同的可调度资源。

配置 API

配置 API 是对下游的产品化边界，它决定：

• 客户端看到的一个或多个对外模型名称，以及每个名称的调度目标。
• 可使用的候选模型资源。
• 固定或故障转移方式；未验证的高级模式会被后端拒绝。
• 输出协议与流式输出。
• Access Key 的速率和模型限制。

对外模型与真实模型

对外模型名称是稳定的业务接口，可以不暴露真实渠道模型。

下游 model = support-prod
  -> 主资源 = Qwen / qwen-plus
  -> 回退资源 = DeepSeek / deepseek-chat

更换真实模型时，下游可以继续使用 support-prod。

Access Key

Lumoswitch Access Key 使用所选格式的标准 Header 鉴权：OpenAI 使用 Bearer Auth，Anthropic 使用 x-api-key，Gemini 使用 x-goog-api-key。它只在创建或轮换时显示一次完整内容，数据库仅保存运行时令牌标识、前缀和业务状态。每个配置有一个当前 Key；轮换宽限期内旧 Key 与 replacement Key 可以短暂并存。

项目范围

项目用于隔离和归类配置与 Access Key，适合区分产品、环境或客户。

调度与故障转移

调度结果可同时受配置模式、模型别名、项目范围、上游健康、凭证优先级和限流影响。