Lumoswitch 快速开始
Lumoswitch 是面向 AI 应用、Agent 和开发工具的多协议 LLM 网关与控制台。它使用一个 Lumoswitch Access Key 统一调用不同模型厂商，并负责模型调度和故障转移。
完成后你将获得
- 一个或多个已安全托管的上游模型 API Key
- 至少一个可调度的模型资源
- 一套模型选择与故障转移规则
- 一个与你选择的下游协议对应的 Base URL
- 一个仅展示一次完整内容的 Lumoswitch Access Key
前置准备
- 已拥有 Lumoswitch 账号并登录控制台。
- 至少准备一个模型厂商的 API Key。
- 确认该 API Key 具有模型列表和模型调用权限。
Lumoswitch 不会在控制台列表中返回上游密钥明文。不要在文档、截图、代码仓库或聊天记录中粘贴真实密钥。
五步完成首次接入
1. 配置上游 Key
进入 快速开始，选择模型厂商，填写接入名称和厂商 API Key，然后保存。如果使用自定义 OpenAI-compatible 服务，还需要核对 Base URL。保存后系统会自动拉取模型列表。
完成后，页面会显示已接入的上游数量。详见 上游接入。
2. 拉取模型
从已启用的上游拉取模型列表。检测成功后，模型会持久化为可调度的模型资源。
至少需要一个可用模型才能继续。如未检测到模型，请返回检查上游 Base URL、Key 权限和账户状态。详见 模型资源。
3. 选择调度方式与模型
选择一种调度方式：
| 调度方式 | 适用场景 | 行为 |
|---|---|---|
| 固定模型 | 结果稳定、只允许一个模型 | 所有请求使用同一模型，失败时直接返回错误 |
| 故障转移 | 追求高可用性 | 按候选模型顺序调用，当前模型失败时切换到下一个 |
| AI 智能调度 | 希望由模型选择执行候选 | 使用路由模型在候选模型中选择 |
| 自动调度 | 已弃用、已停用 | 不再接受新建或编辑 |
4. 配置下游输出
默认使用 OpenAI-compatible 输出。设置对外暴露的模型名称；下游应用调用时，model 字段应使用这个名称。
提交后，Lumoswitch 会同时创建一条 配置 API 和与之一对一绑定的 Access Key。
5. 保存接入凭证
复制页面上的 Base URL 和 Access Key。
Access Key 的完整内容只显示一次。关闭对话框前请先存入密钥管理工具或环境变量。
发起首次请求
将控制台显示的值写入环境变量：
export LUMOSWITCH_BASE_URL="https://your-gateway.example.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 中设置的对外模型名称。
支持的 OpenAI-compatible 端点
GET /v1/models
POST /v1/chat/completions
POST /v1/responses
POST /v1/embeddings快速排查
| 现象 | 检查项 |
|---|---|
| 返回 401 | 检查是否使用了 Lumoswitch Access Key，以及 Key 是否已启用 |
| 模型不存在 | 确认 model 与配置 API 中的对外模型名称一致 |
| 无可用上游 | 检查上游和模型资源的健康状态 |
| 请求被限制 | 检查配置 API 的每分钟请求数限制 |