LM Studio 本地服务模式和 OpenAI 兼容接口教程

程序已经按 OpenAI 客户端的写法发出请求，却一直连不上 LM Studio，先别急着改代码。最容易被忽略的不是 JSON 字段，而是三个可见状态：LM Studio 的本地服务是否运行、客户端使用的端口是否与界面一致、请求里的模型 ID 是否来自当前服务返回的列表。把这三处对齐后，现有的 OpenAI Python、JavaScript 或 cURL 调用通常只需更换基础地址。

这套流程适用于 Windows、macOS 和 Linux 上的 LM Studio 桌面应用。目标是让同一台电脑上的程序访问本地模型；如果要让局域网其他设备接入，还需要额外评估监听范围、认证和防火墙，不能直接照搬本机地址。

先确认模型和开发者入口都可用

入口位置：打开 LM Studio，先在模型下载页准备一个与机器内存匹配的模型，再切换到左侧的 Developer 服务页。主要动作：在顶部模型选择器载入模型，或者准备让 Just-in-Time Model Loading 在收到请求时按模型 ID 动态加载。成功标志：服务页能看到模型条目、状态区域和本地地址。失败处理：如果模型选择器为空，先回到 Discover 下载模型；载入时报内存不足时，换体积更小的量化版本或降低上下文长度。

启动服务器，以界面显示的端口为准

1. 入口位置：Developer 服务页顶部的 Status 开关。主要动作：把开关切到运行状态；也可以在终端执行 lms server start。成功标志：界面显示 Status: Running，右侧出现 Reachable at 地址。失败处理：开关立即退回时，打开 Server Settings 换一个未被占用的端口；终端执行 lms server status 可以直接查看实际监听端口。

官方示例通常使用 http://localhost:1234。端口可以改动，所以不要把 1234 当成不可变常量。比如 lms server status 报告端口为 8000，客户端基础地址就应写成 http://localhost:8000/v1。同一台电脑调用时优先使用 127.0.0.1 或 localhost，避免无意间把服务暴露到局域网。

先用模型列表验证地址，再发聊天请求

1. 入口位置：系统终端或应用自己的 HTTP 调试工具。主要动作：请求 GET /v1/models，把端口替换为 Developer 页显示的值。

   curl http://127.0.0.1:1234/v1/models

   成功标志：返回 JSON，顶层 object 为 list，data 数组中的每个模型至少包含 id、object 和 owned_by。复制准备调用的 id，不要凭下载页名称猜。失败处理：Connection refused 表示服务器没运行或端口写错；返回空数组时，先载入模型，或者检查 Just-in-Time Model Loading 是否允许服务看到已下载模型；返回 401 则说明认证开关已经开启。

2. 入口位置：仍在终端中调用 OpenAI 兼容的聊天补全端点。主要动作：把上一步返回的模型 ID 放进 model 字段，再发送消息数组。

   curl http://127.0.0.1:1234/v1/chat/completions 
     -H "Content-Type: application/json" 
     -d '{
       "model": "MODEL_ID_FROM_V1_MODELS",
       "messages": [
         {"role": "user", "content": "请用一句话说明本地推理的含义"}
       ],
       "temperature": 0.7
     }'

   成功标志：响应中出现 choices，回答文字位于 choices[0].message.content。失败处理：模型不存在通常是 ID 拼写或加载状态不一致；400 多半来自 JSON 引号、逗号或字段类型错误；请求一直等待时，查看 Developer Logs，区分模型仍在加载、正在推理还是请求根本没有到达。

LM Studio 当前公开的 OpenAI 兼容端点还包括 POST /v1/responses、POST /v1/embeddings 和旧式的 POST /v1/completions。新聊天程序可优先使用 Chat Completions；需要 Responses API 语义的客户端则使用 /v1/responses，不要把两种响应结构混在同一段解析代码里。

把现有 OpenAI Python 客户端指向本机

1. 入口位置：项目的 OpenAI 客户端初始化代码。主要动作：将 base_url 改为 LM Studio 地址，并提供一个非空的 api_key。默认未启用认证时，这个值只是满足客户端参数要求；启用认证后必须改为真实令牌，且应从环境变量读取。

   import os
   from openai import OpenAI
   
   client = OpenAI(
       base_url="http://127.0.0.1:1234/v1",
       api_key=os.environ.get("LM_STUDIO_API_KEY", "lm-studio"),
   )
   
   result = client.chat.completions.create(
       model="MODEL_ID_FROM_V1_MODELS",
       messages=[{"role": "user", "content": "你好，请确认本地服务已接通"}],
   )
   print(result.choices[0].message.content)

   成功标志：终端打印本地模型回答，同时 LM Studio 的 Developer Logs 出现对应请求。失败处理：如果客户端仍访问云端地址，检查是否还有旧的环境变量或第二处客户端初始化；若报 401，确认认证开关和令牌是否匹配；若程序运行在容器或另一台设备，127.0.0.1 指向的是程序自身，必须改用可达的主机地址并先做好认证。

认证默认关闭，需要时再创建令牌

入口位置：Developer 页的 Server Settings。主要动作：仅在需要限制调用方时开启 Require Authentication。成功标志：开关开启后，无令牌请求返回 401，带有效 Authorization: Bearer TOKEN 的请求正常响应。失败处理：开启后所有 REST API、Python SDK 和 TypeScript SDK 请求都需要有效令牌；如果旧程序突然全部 401，先检查请求头，不要为了图省事长期关闭认证。

入口位置：认证开关附近的 Manage Tokens。主要动作：按调用方分别创建令牌，复制后保存在系统密钥库或环境变量中。成功标志：令牌列表能区分名称和创建时间，请求日志也能对应调用方。失败处理：完整令牌只在创建时显示一次；丢失后应撤销旧令牌并新建，不能把令牌写进文章、截图、Git 仓库或前端代码。

最后核对本地客户端是否真的接通

• lms server status 报告的端口与代码中的 base_url 一致。
• GET /v1/models 返回 object: list，并能找到准备调用的模型 ID。
• POST /v1/chat/completions 返回 choices[0].message.content。
• Developer Logs 能看到请求进入、模型处理和响应结束，而不是只有客户端单方面等待。
• Require Authentication 的开关状态与请求头一致，真实令牌没有出现在源码或日志截图中。
• 只在确有跨设备需求时开启局域网访问；浏览器前端需要跨域时再单独评估 CORS。

官方资料入口：

• LM Studio 本地服务器
• OpenAI 兼容端点概览
• 模型列表端点
• Chat Completions 端点
• API 令牌认证