在 AIRI 中接入 LM Studio 本地模型：从零配置到源码级原理-育师

在 AIRI 中接入 LM Studio 本地模型：从零配置到源码级原理

【免费下载链接】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（自托管、用户自主掌控的 AI 伴侣项目）的「意识（Consciousness）」模块，讲解如何将 LM Studio 作为本地聊天模型提供者接入 AIRI。读完本文，你将掌握 LM Studio 本地服务的启动与 CORS 配置、在 AIRI 设置界面中的完整配置步骤、配置自动校验与模型选择的实际用法，以及从源码层面理解 LM Studio 提供者的默认 Base URL、校验器与故障排查机制。

为什么选择 LM Studio：不依赖云 API Key 的本地模型方案

LM Studio 是一款能在本机原生运行模型的桌面应用，并为第三方程序提供原生 HTTP API。对于希望自己运行模型、自己管理模型文件的用户，它是不依赖云端 API Key 的选择——这是它与 OpenAI、Anthropic 等云服务提供者的本质区别。

在 AIRI 中，LM Studio 提供者的源码定义（packages/stage-ui/src/libs/providers/providers/lm-studio/index.ts）也印证了这一点：

提供者 id 为lm-studio，注册顺序order: 3，名称「LM Studio」；
其能力标签tasks: ['chat']，即主要服务于聊天/意识对话场景；
配置 schema 中apiKey为可选字段（.optional()），而baseUrl默认值被直接写死为http://localhost:1234/v1/。

从源码结构可以推断，AIRI 将 LM Studio 视为一个「本地优先、无需鉴权」的 OpenAI 兼容提供者——你在多数情况下只需保证服务可达，连 API Key 都可以留空。

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

从 LM Studio 下载页面安装并打开 LM Studio，然后下载并加载一个聊天模型（chat model）；
打开Local Server选项卡，点击启动本地服务器（Start Server）；
如果 AIRI 无法访问本地服务，需要在 LM Studio 的服务器设置（Server Settings）中勾选Enable CORS。

关于第 3 点的 CORS 问题，源码给出了非常明确的原因与指引。在 LM Studio 提供者的连接性校验失败提示中（lm-studio/index.ts）明确写着：

Failed to reach LM Studio server… Make sure LM Studio is running and the local server is started… If the LM Studio instance is already running, this is likely a CORS issue. You need to enable CORS in LM Studio: go to 'Local Server' tab and check 'Enable CORS' option in the Server Settings.

也就是说，当 AIRI（尤其是 Web 端，浏览器环境存在跨域限制）连不上 LM Studio 时，服务未启动与 CORS 未开启是两大首要嫌疑，源码已经把这些排查步骤固化进了校验错误信息里。

第二步：在 AIRI 中配置 LM Studio 提供者

打开设置 → 提供者 → 聊天 → LM Studio；
保持默认 Base URL：http://localhost:1234/v1/；
如果 LM Studio 服务需要鉴权则填入 API Key，否则留空。

对应的设置页面源码位于 packages/stage-pages/src/pages/settings/providers/chat/lm-studio.vue，其中：

页面通过ProviderBaseUrlInput组件提供 Base URL 输入框，占位符即为http://localhost:1234/v1/（见 lm-studio.vue）；
Base URL 的值被双向绑定到提供者配置存储（useProviderConfigStore）中providers['lm-studio'].baseUrl字段；
页面还引入了useProviderValidation组合式函数，负责驱动整个自动校验流程。

配置参数一览

参数	默认值	说明
`baseUrl`	`http://localhost:1234/v1/`	LM Studio Local Server 的 OpenAI 兼容 API 地址，末尾需包含`/v1/`路径
`apiKey`	空（可选）	LM Studio 本地服务默认不需要鉴权，留空即可；若你为服务配置了鉴权，则填入对应密钥

参数 schema 定义于 lm-studio/index.ts：apiKey为可选字符串，baseUrl可选但带有.default('http://localhost:1234/v1/')，即用户不填时也会回落到该默认地址。字段在设置界面中被渲染为type: 'password'的密钥输入与普通文本输入（见 lm-studio/index.ts）。

提供者实例的构造

源码中createProvider(config)将 LM Studio 配置合并构造为三类提供者能力（lm-studio/index.ts）：

createChatProvider：负责聊天补全（chat completions），即意识对话的核心通道；
createEmbedProvider：负责向量嵌入（embedding），供检索/记忆相关模块使用；
createModelProvider：负责模型列表（models）查询，供后续模型选择使用。

三者在同一个baseURL与apiKey之上复用，这也意味着 LM Studio 提供者不只服务于聊天——只要 LM Studio 加载了支持嵌入的模型，相关能力即可一并生效。

第三步：配置校验与模型选择

自动校验机制

AIRI 在编辑配置的过程中会对提供者自动进行有效性校验。校验是否触发的判定条件是validationRequiredWhen——LM Studio 提供者在baseUrl非空（!!config.baseUrl?.trim()）时才要求校验（见 lm-studio/index.ts）。

LM Studio 提供者启用了三组 OpenAI 兼容校验器（lm-studio/index.ts）：

校验项	含义	校验器枚举（定义于 types.ts）
Connectivity	轻量 GET`/models`检查服务可达性	`ProviderValidationCheck.Connectivity`
ModelList	拉取模型列表并确认非空	`ProviderValidationCheck.ModelList`
ChatCompletions	发送一次 generateText 探测，带细粒度错误处理与缓存	`ProviderValidationCheck.ChatCompletions`

关键细节：

skipApiKeyCheck: true——跳过 API Key 检查，再次印证本地服务默认无需鉴权；
schedule: { mode: 'interval', intervalMs: 15_000 }——校验以每 15 秒一次的间隔轮询执行，保证配置保存后仍能持续感知服务状态变化。

这些校验器的底层实现在 packages/stage-ui/src/libs/providers/validators/openai-compatible.ts：连接性校验基于isNetworkError判断网络错误、模型列表通过@xsai/model的listModels拉取、聊天探测通过@xsai/generate-text的generateText发出真实请求。校验结果通过设置页的ProviderValidationAlerts组件呈现（is-valid / is-validating / validation-message 等状态）。

选择已加载的模型

校验通过后，点击Select Model →（选择模型）按钮即可跳转到设置 → 模块 → 意识（Consciousness）页面选择已加载的模型。对应源码见 lm-studio.vue：按钮触发router.push('/settings/modules/consciousness')，进入意识模块的模型选择流程。

值得一提的是，设置页也提供Ping API手动测试按钮（runManualTest）与「强制有效」（force valid）能力，用于自动校验不便或需要即时人工确认的场景。

进阶：视觉模型也走 LM Studio

除了聊天，AIRI 还为视觉（vision）模块提供了独立的 LM Studio 提供者，页面源码位于 packages/stage-pages/src/pages/settings/providers/vision/lm-studio.vue。它使用提供者 idvision-lm-studio，同样维护一个 Base URL 输入（占位符同为http://localhost:1234/v1/），校验通过后跳转到router.push('/settings/modules/vision')选择视觉模型。也就是说，同一台 LM Studio 服务可以同时支撑 AIRI 的聊天（意识）与视觉两条能力线，只要你在 LM Studio 中加载了对应类型的模型。

故障排查

连接失败时，按以下顺序排查：

Local Server 是否在运行：打开 LM Studio 的 Local Server 选项卡确认服务器已启动；
端口是否与 Base URL 一致：默认端口为 1234，若你在 LM Studio 中修改过端口，务必同步修改 AIRI 的 Base URL；
CORS 是否开启：AIRI 与 LM Studio 非同源（尤其 Web 端）时，需在 LM Studio Server Settings 中勾选 Enable CORS；
跨设备场景：如果 AIRI 与 LM Studio 不在同一台设备上，将 Base URL 改为从 AIRI 设备可访问的 LAN 地址（如http://192.168.x.x:1234/v1/），并且只在可信网络环境中开放该服务——这是本地服务的通用安全前提。

以上判断依据均可从文档 docs/content/ko/docs/manual/config/providers/consciousness/lm-studio.md 的「问题解决」一节，以及 LM Studio 提供者源码中内置的连通性失败提示文案（lm-studio/index.ts）得到交叉印证。

小结

接入 LM Studio 的本质是：在本机启动一个 OpenAI 兼容的本地 API 服务，然后在 AIRI 的设置界面中填入默认 Base URL（http://localhost:1234/v1/），无需 API Key，交由 AIRI 内置的三重校验器自动确认连通性、模型列表与聊天能力，最后在意识模块中选择已加载的模型即可开始对话。整个过程完全由用户掌控模型文件与推理数据，不依赖任何云端 API Key——这正是「自托管、自主掌控」理念在模型层的最佳落地点。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考