AIRI 接入 LM Studio 本地模型：零 API Key 的聊天模型配置完整指南

AIRI 接入 LM Studio 本地模型：零 API Key 的聊天模型配置完整指南

【免费下载链接】airi💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi

本篇技术指南讲解如何在 AIRI 中接入LM Studio本地模型服务，让聊天模型运行在自有的设备上、默认无需云端 API Key。文章覆盖从 LM Studio 本地服务器的启动、AIRI 服务商配置到自动校验与模型选择的完整流程，并深入结合仓库中服务商注册与校验器的源码实现，帮助读者理解每一步背后的真实调用关系与排障原理，最终掌握一套完全本地化、可离线运行的模型接入方案。

为什么选择 LM Studio

LM Studio 是一款可以在本机运行模型并提供本地 API 的桌面应用。对 AIRI 而言，选择 LM Studio 的核心价值在于：

• 不依赖云端 API Key：模型文件由自己下载与管理，请求全部落在本地，隐私与成本可控；
• 本地化运行：适合希望在自己设备上运行模型、自行管理模型文件的用户；
• OpenAI 兼容接口：AIRI 将其作为标准的 OpenAI 兼容服务接入，配置与验证链路与云端服务商保持一致的抽象。

这一设计在仓库中得到印证：LM Studio 服务商定义 中，apiKey字段被声明为可选（.optional()），并且校验器显式启用了skipApiKeyCheck: true——意味着 AIRI 校验该服务时根本不要求填写 API Key，这与其他云端服务商默认必须提供 Key 的行为形成鲜明对比。

第一步：启动 LM Studio 本地服务

1. 从 LM Studio 官网下载并安装桌面应用，打开后在界面中下载并加载一个聊天模型；
2. 打开Local Server标签页，点击Start Server启动本地服务器；
3. 如果 AIRI 无法访问本地服务，请在 LM Studio 的服务器设置中启用 CORS（Cross-Origin Resource Sharing）。

这里需要区分两个容易混淆的网络问题（仓库源码的排障文案对此有明确提示）：

• CORS 只解决浏览器跨域拦截，不提供网络可达性，也不提供鉴权。AIRI 若运行在浏览器/WebView 环境中，请求被浏览器拦截时会提示 CORS 错误，此时需在 LM Studio 的 Local Server → Server Settings 中勾选 Enable CORS；
• 如果 AIRI 与 LM Studio 不在同一台设备，需要在 LM Studio 中启用Serve on Local Network（或让服务器绑定到非回环地址），并在 AIRI 端使用 LM Studio 所在设备的局域网地址（如http://192.168.x.x:1234/v1/）而非localhost。

⚠️ 安全警告：不要把 LM Studio 本地服务器暴露到公网，仅在可信的局域网内使用。源码中的连接失败提示也反复强调 "Make sure LM Studio is running and the local server is started"，即排查第一步永远是确认服务进程本身存活。

第二步：在 AIRI 中配置 LM Studio 服务商

1. 打开设置 → 服务商 → 聊天 → LM Studio；
2. 保留默认 Base URL：http://localhost:1234/v1/；
3. 若你的 LM Studio 服务需要鉴权（例如配置了自定义密钥），再填写 API Key；否则留空即可。

源码中的默认值与字段设计

从 LM Studio 服务商定义 可以确认配置项的精确行为：

const lmStudioConfigSchema = z.object({ apiKey: z.string('API Key').optional(), baseUrl: z.string('Base URL').optional().default('http://localhost:1234/v1/'), })

• baseUrl的默认值正是文档中展示的http://localhost:1234/v1/（LM Studio 本地服务器的默认监听地址与 OpenAI 兼容路径前缀）；
• apiKey为可选，默认缺省为空——对应"本地服务默认不需要 API Key"的说明；
• 服务商tasks仅声明['chat']，注册顺序order: 3，在 服务商注册表 中与 Ollama、vLLM 等并列位于本地模型阵营。

对应的设置页面由 chat/lm-studio.vue 提供，其 Base URL 输入框的占位符同样写死为http://localhost:1234/v1/，与 schema 默认值保持一致。

底层 Provider 的组装方式

当配置保存后，createProvider会通过merge()将三个子 Provider 合并为一个实例：

return merge( createChatProvider({ apiKey: config.apiKey, baseURL: config.baseUrl! }), createEmbedProvider({ apiKey: config.apiKey, baseURL: config.baseUrl! }), createModelProvider({ apiKey: config.apiKey, baseURL: config.baseUrl! }), )

这意味着 LM Studio 接入后不仅提供聊天补全（chat），还同时具备嵌入（embed）与模型列表（model）能力——这为后续"选择已加载模型"的功能提供了接口基础。由于同一baseUrl被三处复用，Base URL 填写错误会同时影响连接测试、模型列表拉取与聊天请求，这是排障时值得留意的关联性。

第三步：验证配置

1. Ping API：点击该按钮，AIRI 会向本地服务发起实时请求，测试能否连通；
2. 选择模型：测试成功后，点击对应按钮进入设置 → 模块 → 意识（Consciousness），选择 LM Studio 中已加载的模型。

校验器如何工作

AIRI 对 LM Studio 的验证并非一次性点击，而是由一套可调度、带缓存的校验机制驱动。从 服务商定义 可以看到：

validators: { ...createOpenAICompatibleValidators({ checks: [ ProviderValidationCheck.Connectivity, ProviderValidationCheck.ModelList, ProviderValidationCheck.ChatCompletions, ], skipApiKeyCheck: true, schedule: { mode: 'interval', intervalMs: 15_000 }, connectivityFailureReason: ..., modelListFailureReason: ..., }), }

结合 校验枚举定义 与 OpenAI 兼容校验器实现，三个检查项的语义如下：

三个要点值得注意：

• skipApiKeyCheck: true：校验时跳过 API Key 检查，是"本地服务无需 Key"这一设计在验证链路的直接落地；
• 15 秒间隔调度：校验并非只执行一次，而是每 15 秒按 interval 模式自动复检，因此 LM Studio 服务中途停止后，AIRI 能在较短时间内感知到连接失效；
• 错误文案内置排障指引：connectivityFailureReason会在失败信息中直接给出三步建议——确认 LM Studio 正在运行并启动 Local Server、通过 Local Server 标签页的 Start Server 启动服务、以及若已运行则检查 CORS 是否已启用。

此外，聊天补全探测对错误的分类很讲究：网络层错误（isNetworkError）判为连通性失败；而 HTTP 400 或 2xx 状态被视为服务已连通（chatOk）——这避免了因模型对探测请求的拒绝而误报"连接失败"。

排查：无法连接时怎么办

按仓库源码排障文案与文档说明，建议按下述顺序排查：

1. 确认 Local Server 正在运行：在 LM Studio 的 Local Server 标签页点击 Start Server，观察端口是否已监听；
2. 核对端口与 Base URL 一致：默认端口是1234，路径为/v1/；若修改过端口，务必同步修改 AIRI 中的 Base URL；
3. 区分设备场景：AIRI 与 LM Studio 同机时用http://localhost:1234/v1/；跨设备时改用 LAN 地址（如http://192.168.x.x:1234/v1/），并确认 LM Studio 已启用 Serve on Local Network；
4. 浏览器环境先查 CORS：若错误信息提示 CORS，在 LM Studio 服务器设置中勾选 Enable CORS。注意 CORS 不解决网络可达性问题，仅解除浏览器的跨域限制；
5. 安全边界：本地服务仅在可信局域网开放，切勿暴露到公网。

小结

LM Studio 接入方案让 AIRI 在完全脱离云端 API Key 的前提下获得可用的聊天模型能力。其接入链路高度"标准化"：默认http://localhost:1234/v1/的 OpenAI 兼容端点、可选的 API Key、以及覆盖连通性/模型列表/聊天补全的三级自动校验，配合 15 秒间隔的自动复检与内置 CORS 排障文案，让本地模型配置与云端服务商的体验保持一致。

如果想进一步研究，可继续阅读 LM Studio 服务商源码、OpenAI 兼容校验器 与 设置页实现，或查看其他语言版本的本篇文档（英文版、韩文版）。此外，仓库还支持 vLLM 等本地/自托管服务商，可作为本地模型方案的横向参考。

【免费下载链接】airi💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi