Lumoswitch 快速开始

Lumoswitch 是面向 AI 应用、Agent 和开发工具的模型接入平台与控制台。它使用 Lumoswitch Access Key 调用已配置的接入渠道，并把固定、故障转移、自动选模和负载均衡策略同步到 Lumoswitch Runtime。

完成后你将获得

• 可选的渠道 API Key（用于接入上游）
• 平台模型和/或接入模型资源
• 一套模型选择与故障转移规则
• 一个与你选择的下游协议对应的 Base URL
• 一个仅展示一次完整内容的 Lumoswitch Access Key

前置准备

1. 已拥有 Lumoswitch 账号并登录控制台。
2. 如果只使用平台模型，不需要准备渠道 API Key。
3. 如需接入上游，再准备具有模型列表和调用权限的渠道 API Key。

Lumoswitch 不会在控制台列表中返回上游密钥明文。不要在文档、截图、代码仓库或聊天记录中粘贴真实密钥。

五步完成首次接入

1. 选择模型来源

进入 快速开始。平台模型会直接列出；如需使用接入模型，再选择渠道并填写接入名称和 API Key。平台模型和接入模型在后续配置中的定位相同，都会进入候选资源和调度。

没有已接入上游也可以继续。详见 上游接入。

2. 拉取模型

此步骤会同时展示平台模型，并从已启用的上游拉取接入模型。接入模型检测成功后会持久化为可调度资源。

即使暂时没有模型也可以继续浏览后续步骤并保存草稿；但配置 API 要真正完成调用，仍必须至少有一个健康且可路由的候选模型。详见 模型资源。

3. 选择调度方式与模型

选择一种调度方式：

自动路由的候选顺序会映射到 SIMPLE、MEDIUM、COMPLEX、REASONING 四个层级；候选不足四个时相邻层级会复用模型。最少繁忙和最低延迟不把列表顺序当作优先级。

4. 配置下游输出

设置默认对外模型名称，并选择要开放的客户端格式。OpenAI 使用 /v1 Base URL，Anthropic 与 Gemini 使用推理服务域名根地址。创建后可在配置编辑器中添加更多对外模型映射，分别指向完整调度或指定候选资源。

平台模型不会绕过调度，也不会直接生成一把只绑定平台模型的 Key。它与接入模型一样，必须先加入候选资源并配置调度。

提交后，Lumoswitch 会同时创建一条 配置 API 和初始 Access Key。

5. 保存接入凭证

复制页面上的 Base URL 和 Access Key。

Access Key 的完整内容只显示一次。关闭对话框前请先存入密钥管理工具或环境变量。

发起首次请求

将控制台显示的值写入环境变量：

export LUMOSWITCH_BASE_URL="https://api.lumoswitch.com/v1"
export LUMOSWITCH_API_KEY="your-lumoswitch-access-key"

先查询当前可用模型：

curl "$LUMOSWITCH_BASE_URL/models" \
  -H "Authorization: Bearer $LUMOSWITCH_API_KEY"

再发起一次聊天补全请求：

curl "$LUMOSWITCH_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $LUMOSWITCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lumos-chat",
    "messages": [
      {"role": "user", "content": "Say hello in one sentence."}
    ]
  }'

lumos-chat 是示例名称，请替换为你在配置 API 中设置的对外模型名称。

支持的下游端点

GET  /v1/models
POST /v1/chat/completions
POST /v1/responses
POST /v1/embeddings
POST /v1/messages
POST /v1/messages/count_tokens
POST /v1beta/models/{model}:generateContent
POST /v1beta/models/{model}:streamGenerateContent
POST /v1beta/models/{model}:countTokens

Gemini 同时支持 /models/{model}:... 别名。公开路径白名单与鉴权边界见 协议与兼容性。

快速排查

下一步

• 在 仪表盘 确认整条调用链路状态。
• 在 配置 API 继续调整路由模式和 Key 限制。
• 用 项目 隔离不同应用或环境。