Cómo utilizar la interfaz compatible con LM Studio OpenAI: tutorial de acceso a la API local

LM Studio puede convertir modelos cargados localmente en interfaces compatibles con OpenAI. Para proyectos existentes, generalmente no es necesario reescribir la lógica de llamada: cambie base_url del cliente OpenAI a la dirección local de LM Studio y luego cambie model al identificador del modelo en LM Studio.

Las direcciones más utilizadas son:

1

http://localhost:1234/v1

Es adecuado para conectarse a Python, JavaScript, C# u otro código de cliente OpenAI existente. Las siguientes instrucciones están en el orden “ejecutar primero y luego acceder al proyecto”.

Hablemos primero de la conclusión.

Para utilizar la interfaz compatible con OpenAI de LM Studio, solo necesita completar cuatro pasos:

Inicie el servidor local en la página Desarrollador de LM Studio.
Cargue un modelo de chat.
Solicite http://localhost:1234/v1/models, confirme la identificación del modelo.
Cambie el cliente base_url a http://localhost:1234/v1.

Escritura mínima en 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" es solo un valor de marcador de posición para OpenAI SDK cuando la autenticación no está habilitada; Si habilita el token API en la configuración del servicio LM Studio, debe cambiarse al token real.

Paso 1: inicie el servidor local de LM Studio

Abra LM Studio, ingrese a la página Desarrollador y active el interruptor Iniciar servidor. El servicio predeterminado escuchará:

1

http://localhost:1234

También puede utilizar la herramienta de línea de comandos de LM Studio para iniciar:

1

lms server start

Si lms no está disponible en su computadora, puede instalar la CLI de acuerdo con la documentación oficial de LM Studio:

1

npx lmstudio install-cli

El inicio del servicio solo significa que el puerto API está escuchando, pero no significa que exista un modelo sobre el cual se pueda razonar. Continúe cargando un modelo en la página de Chat o Desarrollador, o cárguelo con lms load.

Paso 2: obtenga primero la identificación del modelo

No adivine el parámetro model según el nombre del archivo. La forma más estable es solicitar una lista de modelos:

1

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

Se puede utilizar Windows PowerShell:

1

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

La lista data devuelta tendrá el identificador del modelo. Luego complete model con el ID real devuelto en la solicitud.

Este paso puede evitar dos problemas comunes: el modelo se descargó pero no se cargó, o el nombre escrito en el código no coincide con la ID del modelo expuesta actualmente por LM Studio.

Paso 3: Probar la finalización del chat con curl

Primera prueba con el endpoint compatible con OpenAI más intuitivo:

 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
  }'

Cuando tiene éxito, la respuesta suele ser:

1

choices[0].message.content

Las finalizaciones de chat aplican automáticamente la plantilla de mensajes del modelo de chat. Siempre que el modelo en sí sea del tipo chat/instrucciones, normalmente no hay necesidad de empalmar manualmente tokens de control especiales en el lado del cliente.

Cómo reemplazar OpenAI con el proyecto Python

Si el proyecto utiliza originalmente el SDK de OpenAI Python, generalmente solo hay dos enfoques: base_url y 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)

La ventaja de esto es que la capa de aplicación todavía usa los objetos y formatos de retorno del SDK de OpenAI, y el backend puede cambiar entre la API de OpenAI en la nube y el LM Studio local.

Pero “compatibilidad” no significa que todas las características del modelo de nube se puedan copiar tal cual. La disponibilidad de llamadas a herramientas, resultados estructurados, entradas visuales, contenido de inferencia y la API de Responses aún depende de la versión de LM Studio, las capacidades del modelo actual y la compatibilidad con los terminales correspondientes.

Salida de transmisión

Establezca stream=True en Finalizaciones de chat:

 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)

La salida de streaming es adecuada para interfaces de chat, herramientas de terminal y respuestas largas. Mejora la experiencia de espera del usuario y no hace que el modelo local se genere más rápido.

Cómo elegir entre incrustaciones, respuestas y API REST nativa

La capa de compatibilidad OpenAI de LM Studio incluye puntos finales comunes:

punto final	adecuado para qué
`/v1/models`	Consultar modelos disponibles actualmente
`/v1/chat/completions`	Compatible con la mayoría de los códigos de chat antiguos
`/v1/responses`	Úselo cuando se requieran estilos de respuestas OpenAI más nuevos
`/v1/embeddings`	Texto vectorizado, recuperación RAG
`/v1/completions`	Compatibilidad con finalización de texto heredado

LM Studio también tiene su propia interfaz nativa. La ruta recomendada actualmente es /api/v1/*, como /api/v1/chat y /api/v1/models. La API nativa es más adecuada para proyectos que requieren carga/descarga de modelos, chat con estado, MCP o capacidades específicas de LM Studio.

Juicio simple: si ya tiene un proyecto OpenAI SDK, use /v1 primero; Si un nuevo proyecto requiere una gestión en profundidad de los modelos locales o utiliza las capacidades exclusivas de LM Studio, considere /api/v1.

Salida estructurada y llamadas a herramientas

La capa de compatibilidad OpenAI de LM Studio admite llamadas a herramientas y salida estructurada en los puntos finales correspondientes, pero primero confirme dos cosas:

El modelo que cargue debe tener capacidades confiables de llamada de herramientas o salida JSON.
Las versiones de LM Studio y el SDK del cliente deben ser lo suficientemente nuevas.

No asuma que el modelo puede generar de manera estable resultados que se ajusten al esquema solo porque no hay errores en la solicitud. Las pruebas deben realizarse utilizando parámetros reales, ramas anormales y múltiples rondas de solicitudes antes de conectarse.

Solución de problemas de errores comunes

1. Conexión rechazada o `Connection refused`

Primero confirme que el servidor en la página del desarrollador se haya iniciado y luego pruebe:

1

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

Si no puede conectarse aquí, primero verifique el puerto, si LM Studio aún se está ejecutando o si el software de seguridad local bloquea el puerto local.

2. `404 Not Found`

La razón más común es que la ruta está escrita incorrectamente. Los puntos finales de chat compatibles con OpenAI son:

1

/v1/chat/completions

No /api/v1/chat/completions. Este último pertenece a otro conjunto de rutas API nativas.

3. El modelo no existe o se devuelve una lista vacía.

Primero cargue el modelo en LM Studio y luego verifique el retorno de /v1/models. model en el código debe utilizar el identificador devuelto real y no copiar los nombres de modelo de otras personas.

4. Puedo responder pero el formato es extraño.

Compruebe que esté cargado el modelo base en lugar del modelo de instrucción/chat; También verifique que LM Studio aplique automáticamente la plantilla de chat. Para llamadas a herramientas y resultados JSON, confirme también que el modelo realmente admita la capacidad.

5. No se puede acceder al dispositivo LAN

LM Studio puede configurar servicios para la red local en la página del desarrollador. Después de habilitar el acceso a la red, también debe confirmar la configuración del firewall, la dirección de escucha y el token API. No exponga servicios de modelos locales no autenticados directamente a la red pública.

Una lista de verificación de acceso mínimo

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 或结构化输出

Primero ejecute la solicitud mínima y luego conecte RAG, Agent o el complemento del editor; la solución de problemas será mucho más fácil.

Resumir

La interfaz compatible con OpenAI de LM Studio es adecuada para conectar modelos locales a proyectos OpenAI SDK existentes. Lo más importante no es copiar un fragmento de código, sino confirmar que se inicia el servicio, se carga el modelo, base_url apunta a /v1 y model usa la ID del modelo real.

Si lo que necesita es una gestión de modelos local más profunda, chat con estado o MCP, la interfaz nativa /api/v1/* de LM Studio será más adecuada; Si el objetivo es una rápida compatibilidad con proyectos antiguos, continuar usando /v1/chat/completions suele ser lo más fácil de hacer.

referirse a: