核心概念

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

调用链

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

下游与上游

• 下游：调用 Lumoswitch 的应用，例如 OpenAI SDK、Codex、OpenWebUI 或你的服务。
• 上游：Lumoswitch 实际请求的模型服务，例如 OpenAI、DeepSeek、Qwen 或本地 Ollama。

下游只应持有 Lumoswitch Access Key，不应接触上游厂商 Key。

上游与凭证池

一个上游定义厂商、Base URL 和协议。模型列表从上游实时拉取；上游可包含多个加密凭证，并按优先级和可用性参与轮询与回退。

模型资源

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

配置 API

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

• 下游看到的模型名称。
• 可使用的候选模型资源。
• 固定、故障转移或 AI 智能调度方式。
• 输出协议与流式输出。
• Access Key 的速率和模型限制。

对外模型与真实模型

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

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

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

Access Key

Lumoswitch Access Key 用于 Gateway Bearer 鉴权。它只在创建时显示一次完整内容，数据库中仅保存哈希。配置 API 和 Access Key 一对一绑定。

项目范围

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

调度与故障转移

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