LM Studio OpenAI 兼容接口怎么用：本地 API 接入教程

LM Studio 可以把本地加载的模型变成 OpenAI 兼容接口。对现有项目来说，通常不需要重写调用逻辑：把 OpenAI 客户端的 base_url 改成 LM Studio 本地地址，再把 model 换成 LM Studio 里的模型标识即可。

最常用的地址是：

1

http://localhost:1234/v1

它适合接入已有的 Python、JavaScript、C# 或其他 OpenAI 客户端代码。下面按“先跑通，再接进项目”的顺序说明。

先说结论

要使用 LM Studio 的 OpenAI 兼容接口，只需要完成四步：

在 LM Studio 的 Developer 页面启动本地服务器。
加载一个聊天模型。
请求 http://localhost:1234/v1/models，确认模型 ID。
将客户端 base_url 改为 http://localhost:1234/v1。

最小 Python 写法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:1234/v1",
    api_key="lm-studio",
)

response = client.chat.completions.create(
    model="你的 LM Studio 模型 ID",
    messages=[
        {"role": "user", "content": "用一句话解释什么是 KV cache。"}
    ],
)

print(response.choices[0].message.content)

api_key="lm-studio" 在未开启鉴权时只是给 OpenAI SDK 的占位值；如果你在 LM Studio 服务设置中启用了 API token，则应改成真正的 token。

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

打开 LM Studio，进入 Developer 页面，打开 Start server 开关。默认服务会监听：

1

http://localhost:1234

也可以使用 LM Studio 的命令行工具启动：

1

lms server start

如果电脑上还没有 lms，可以按 LM Studio 官方文档安装 CLI：

1

npx lmstudio install-cli

服务启动只代表 API 端口已监听，不代表已经有可推理的模型。继续在 Chat 或 Developer 页面加载一个模型，或者用 lms load 载入。

第二步：先获取模型 ID

不要凭文件名猜 model 参数。最稳的办法是请求模型列表：

1

curl http://localhost:1234/v1/models

Windows PowerShell 可以用：

1

Invoke-RestMethod http://localhost:1234/v1/models

返回的 data 列表里会有模型标识。之后在请求中把 model 填为实际返回的 ID。

这一步能避免两个常见问题：模型虽然下载了但还没加载，或者代码里写的名称与 LM Studio 当前暴露的模型 ID 不一致。

第三步：用 curl 测试 Chat Completions

先用最直观的 OpenAI 兼容端点测试：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


curl http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的 LM Studio 模型 ID",
    "messages": [
      {"role": "system", "content": "你是一个简洁的中文助手。"},
      {"role": "user", "content": "解释什么是向量数据库。"}
    ],
    "temperature": 0.7
  }'

成功后，回答通常在：

1

choices[0].message.content

Chat Completions 会自动应用聊天模型的 prompt template。只要模型本身是 chat/instruct 类型，通常不需要在客户端手动拼接特殊控制 token。

Python 项目怎么替换 OpenAI

如果项目原本就使用 OpenAI Python SDK，重点通常只有两处：base_url 和 model。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:1234/v1",
    api_key="lm-studio",
)

completion = client.chat.completions.create(
    model="你的 LM Studio 模型 ID",
    messages=[
        {"role": "system", "content": "你是一名 Python 助手。"},
        {"role": "user", "content": "写一个读取 JSON 文件的最小示例。"},
    ],
    temperature=0.2,
    max_tokens=500,
)

print(completion.choices[0].message.content)

这样做的好处是：应用层仍然使用 OpenAI SDK 的对象和返回格式，后端可在云端 OpenAI API 与本地 LM Studio 之间切换。

但“兼容”不等于每个云端模型特性都能原样复制。工具调用、结构化输出、视觉输入、推理内容和 Responses API 是否可用，仍取决于 LM Studio 版本、当前模型能力和对应端点支持情况。

流式输出

在 Chat Completions 中设置 stream=True：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


stream = client.chat.completions.create(
    model="你的 LM Studio 模型 ID",
    messages=[{"role": "user", "content": "写一首四行小诗。"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

流式输出适合聊天界面、终端工具和长回答。它改善的是用户等待体验，不会让本地模型本身生成得更快。

Embeddings、Responses 与原生 REST API 怎么选

LM Studio 的 OpenAI 兼容层包含常用端点：

端点	适合什么
`/v1/models`	查询当前可用模型
`/v1/chat/completions`	兼容大多数旧式聊天代码
`/v1/responses`	需要较新的 OpenAI Responses 风格时使用
`/v1/embeddings`	向量化文本、RAG 检索
`/v1/completions`	旧式文本补全兼容

LM Studio 也有自己的原生接口，当前推荐路径是 /api/v1/*，例如 /api/v1/chat 和 /api/v1/models。原生 API 更适合需要模型加载/卸载、状态化聊天、MCP 或 LM Studio 专属能力的项目。

简单判断：已有 OpenAI SDK 项目，优先用 /v1；新项目要深度管理本地模型或使用 LM Studio 专属能力，再考虑 /api/v1。

结构化输出和工具调用

LM Studio 的 OpenAI 兼容层支持在相应端点中使用工具调用与结构化输出，但先确认两件事：

你加载的模型本身要有较可靠的工具调用或 JSON 输出能力。
LM Studio 和客户端 SDK 的版本要足够新。

不要只因为请求没有报错，就假设模型能稳定生成符合 schema 的结果。上线前应使用真实参数、异常分支和多轮请求做测试。

常见报错排查

1. 连接被拒绝或 `Connection refused`

先确认 Developer 页面里的服务器已启动，再测试：

1

curl http://localhost:1234/v1/models

如果这里都连不上，优先检查端口、LM Studio 是否仍在运行，或本机安全软件是否拦截本地端口。

2. `404 Not Found`

最常见原因是路径写错。OpenAI 兼容聊天端点是：

1

/v1/chat/completions

不是 /api/v1/chat/completions。后者属于另一套原生 API 路径。

3. 模型不存在或返回空列表

先在 LM Studio 中加载模型，再检查 /v1/models 的返回。代码里的 model 必须使用实际返回的标识，不要照抄别人的模型名。

4. 能回答但格式很奇怪

检查是否加载了 base 模型而不是 instruct/chat 模型；同时检查聊天模板是否由 LM Studio 自动应用。对于工具调用和 JSON 输出，还要确认模型是否真正支持该能力。

5. 局域网设备访问不到

LM Studio 可以在 Developer 页面配置服务到本地网络。开启网络访问后，还需要确认防火墙、监听地址和 API token 设置。不要把无鉴权的本地模型服务直接暴露到公网。

一套最小接入清单

1
2
3
4
5
6
7


1. LM Studio Developer -> Start server
2. 加载一个 instruct/chat 模型
3. curl http://localhost:1234/v1/models
4. 客户端 base_url 改为 http://localhost:1234/v1
5. model 填实际返回的 ID
6. 用 chat/completions 跑通单轮请求
7. 再测试流式、工具调用、Embeddings 或结构化输出

先跑通最小请求，再接 RAG、Agent 或编辑器插件，排障会简单很多。

总结

LM Studio 的 OpenAI 兼容接口适合把本地模型接进已有 OpenAI SDK 项目。最关键的不是复制一段代码，而是确认服务已启动、模型已加载、base_url 指向 /v1、model 使用实际模型 ID。

如果你需要的是更深的本地模型管理、状态化聊天或 MCP，LM Studio 的 /api/v1/* 原生接口会更合适；如果目标是快速兼容旧项目，继续使用 /v1/chat/completions 通常最省事。

参考：