本地模型接入
Lumoswitch 可把 Ollama 或 LM Studio 的 OpenAI-compatible 接口注册为上游。同步推理由 Lumoswitch 推理服务发起，因此控制面和 Lumoswitch Runtime 所在网络都必须能够访问模型服务地址：前者用于连接测试和模型发现，后者用于真实模型调用。
Ollama
- 在 Ollama 中拉取并启动模型。
- 确认 OpenAI-compatible 接口可访问。
- 在 Lumoswitch 新增 Ollama 上游。
- 填写控制面和 Lumoswitch Runtime 都能访问的 Base URL，例如
http://ollama:11434/v1。 - 保存后执行连接测试和模型检测。
默认示例模型为 llama3.2，实际应使用 ollama list 中存在的模型。
LM Studio
- 在 LM Studio 下载并加载模型。
- 启动 Local Server。
- 在 Lumoswitch 新增 LM Studio 上游。
- Lumoswitch Runtime 与 LM Studio 在同一台主机时，Base URL 可使用
http://127.0.0.1:1234/v1；跨容器或跨主机时应改用实际可路由地址。 - 执行连接测试、模型检测和聊天测试。
localhost 的含义
localhost 分别指向正在执行连接测试的 Lumoswitch 控制面或发起推理的 Lumoswitch Runtime 自己所在的机器或容器，不一定是你的电脑。一个地址必须同时在这两个执行环境中可达。
| 场景 | 应使用的地址 |
|---|---|
| Runtime 与模型服务在同一网络 | 服务名或可路由的本机地址 |
| Runtime 与模型服务在不同容器 | 容器服务名或容器网络地址 |
| Runtime 在远程服务器 | 远程服务器可访问的内网地址 |
| 使用托管版 Lumoswitch | 托管服务通常无法访问你的本机 localhost |
不要为了方便把本地模型端口直接暴露到公网。优先使用受控内网、VPN 或安全隧道。
私有地址限制
部分 Lumoswitch 实例会拒绝访问私有 IP，以降低 SSRF 风险。如果连接测试提示私有地址被禁止，需要联系实例管理员确认是否允许本地上游；普通用户无法通过更换 Key 绕过此限制。
常见问题
- 模型列表为空：确认模型已下载并由服务加载。
- Runtime 连接失败：分别从 Lumoswitch 控制面和 Lumoswitch Runtime 所在网络测试 Base URL，而不是只在浏览器中测试。
- Docker 中
127.0.0.1无效：改用模型服务容器名或宿主机可达地址。 - 请求很慢：检查本机推理资源、上下文长度和并发请求数。
协议与兼容性
查阅 Lumoswitch 已开放的推理协议、路径与鉴权方式，确认 OpenAI、Anthropic Messages 和 Gemini 请求所需的 Base URL 与 Header。了解模型能力如何影响接口开放、故障转移候选的兼容性要求，以及文件、管理接口和原生透传等保持私有的安全边界。
API 参考
查阅 Lumoswitch 公开推理 API 的调用示例，使用 Access Key 完成鉴权，查询模型列表并发送模型请求。了解 OpenAI、Anthropic 与 Gemini 格式的入口关系、流式响应和错误处理，确认配置开放的路径、模型白名单与限额，并在故障转移前验证候选模型能力。