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 通常最省事。

參考：