LM Studio no permite adjuntar imágenes: causas y soluciones

Si LM Studio no te deja adjuntar imágenes o el modelo responde como si no las hubiera recibido, empieza por comprobar qué modelo tienes cargado. La aplicación puede trabajar con modelos de visión, pero un modelo que solo admite texto no adquiere esa capacidad al añadir un archivo.

También conviene separar el fallo del chat de los problemas al enviar imágenes desde un script. La prueba más útil consiste en usar una imagen sencilla y comprobar cada vía por separado, antes de modificar configuraciones o reinstalar el programa.

Comprueba que el modelo cargado admite imágenes

Para interpretar fotografías, capturas o documentos escaneados necesitas un modelo de visión y lenguaje, también llamado VLM. No basta con que el nombre pertenezca a una familia conocida: revisa la variante y sus capacidades antes de descargarla.

1. Comprueba el nombre exacto del modelo seleccionado en el chat.
2. Consulta su ficha para confirmar que admite entrada de imágenes.
3. Si necesitas otro modelo, búscalo en Discover y elige una distribución compatible con LM Studio.
4. Cárgalo y prueba con una sola imagen y una petición sencilla, como describir los objetos que aparecen.

El buscador integrado permite localizar modelos por nombre o mediante la dirección de su repositorio en Hugging Face. Para abrir Discover puedes utilizar Ctrl + 2 en Windows y Linux, o Cmd + 2 en Mac.

Si una descarga importada manualmente falla, compara primero el resultado con una distribución obtenida desde el buscador de la aplicación. Esto ayuda a separar un problema del paquete del modelo de un fallo en tu código.

Prueba el archivo y revisa los ajustes de entrada de imágenes

Como prueba de diagnóstico, utiliza una imagen pequeña que puedas abrir correctamente con el visor del sistema. Los formatos documentados para la entrada de imágenes del servidor son JPEG, PNG y WebP.

Si el archivo original utiliza otro formato, expórtalo realmente a PNG o JPEG. Cambiar únicamente la extensión no convierte su contenido.

Comprueba también qué significa exactamente el fallo:

• No puedes seleccionar o adjuntar la imagen: revisa el modelo cargado y reproduce el problema en un chat nuevo.
• El envío produce un error: conserva el mensaje completo y prueba con otro archivo sencillo.
• La imagen se procesa, pero el texto pequeño se interpreta mal: revisa la resolución de entrada y prueba con un recorte de la zona importante.

LM Studio dispone de ajustes de imágenes en Settings > Chat > Image Inputs. La aplicación ha incorporado cambios tanto en el redimensionado como en el procesamiento visual, por lo que conviene comprobar las notas de versión si utilizas una instalación antigua.

Reducir dimensiones puede servir como prueba si falla una imagen grande, pero también puede perjudicar la lectura de letras pequeñas. Compara ambos resultados antes de establecer un límite permanente.

Cómo enviar una imagen desde Python sin editar los chats internos

Para automatizar el análisis, utiliza el SDK oficial de Python. Puedes instalarlo o actualizarlo en el entorno de tu proyecto:

python -m pip install --upgrade lmstudio

Con LM Studio en ejecución y un modelo de visión descargado, este ejemplo prepara el archivo y lo incorpora al mensaje:

from pathlib import Path
import lmstudio as lms

ruta = Path("imagen.png").resolve()

if not ruta.is_file():
    raise FileNotFoundError(f"No existe la imagen: {ruta}")

modelo = lms.llm("IDENTIFICADOR_DEL_MODELO_CON_VISION")
imagen = lms.prepare_image(str(ruta))

chat = lms.Chat()
chat.add_user_message(
    "Describe los elementos principales de esta imagen.",
    images=[imagen],
)

respuesta = modelo.respond(chat)
print(respuesta)

Sustituye el identificador por el de tu modelo y coloca una imagen válida en la ruta indicada. El ejemplo comprueba primero que el archivo existe para evitar confundir un error de ubicación con un fallo de visión.

Escribir la ruta en el texto del mensaje no adjunta el archivo. En este flujo, la imagen se prepara con prepare_image() y se incorpora mediante el argumento images.

Si aparece un error de conexión, revisa el host, el puerto y la autenticación de tu instalación antes de cambiar el archivo. La configuración del cliente debe corresponder al servidor al que quieres conectarte.

Si utilizas HTTP, comprueba el endpoint y su esquema

La API nativa de LM Studio y la interfaz compatible con OpenAI utilizan estructuras distintas. No mezcles sus campos dentro de una misma petición.

En POST /api/v1/chat, la entrada puede incluir un bloque de texto y otro de imagen con esta estructura:

{
  "model": "IDENTIFICADOR_DEL_MODELO_CON_VISION",
  "input": [
    {
      "type": "text",
      "content": "Describe esta imagen."
    },
    {
      "type": "image",
      "data_url": "data:image/png;base64,BASE64_REAL_DEL_ARCHIVO"
    }
  ]
}

Este JSON es una plantilla: debes sustituir el identificador y el contenido base64. El tipo MIME del prefijo debe corresponder al archivo real. En este endpoint, data_url contiene la URI de datos completa.

Para utilizar HTTP, activa el servidor desde la sección de desarrollo o con lms server start. Su dirección predeterminada es http://localhost:1234; añade la autenticación correspondiente si la tienes habilitada.

Si tu aplicación utiliza /v1/chat/completions, consulta el esquema de esa interfaz. El bloque anterior pertenece a la API nativa y no debe copiarse sin adaptar a otro endpoint.

Evita modificar los archivos internos como solución general

LM Studio guarda las conversaciones en JSON y permite localizar sus archivos desde el menú contextual del chat. Sin embargo, su documentación desaconseja editarlos manualmente o depender de su estructura.

Por eso, crear archivos en las carpetas internas o reconstruir sus metadatos no es una solución recomendable para un problema normal de adjuntos. Un procedimiento descubierto para una versión concreta puede dejar de funcionar con una actualización.

Para preparar una incidencia reproducible, anota la versión de LM Studio, el modelo exacto, el formato y dimensiones de la imagen, la vía utilizada y el error completo. Prueba con un archivo sin datos personales que puedas compartir. Esa comparación permite investigar el fallo sin alterar tus conversaciones guardadas.