Conecta un LLM local o una IA personalizada a tu navegador con SurfMind

Con SurfMind puedes elegir los modelos que quieras usar. Puedes conectarlo a un modelo que se ejecuta en tu propia máquina (Ollama, LM Studio, Jan, llama.cpp, vLLM) o a casi cualquier proveedor de IA externo que admita la API de completado de OpenAI: Poe, z.ai, Together, Groq, DeepSeek, AWS Bedrock y muchos más.

La mayoría de los proveedores populares y ejecutores locales ya vienen configurados en los ajustes de SurfMind: haces clic en Connect y pegas tu API key. Para todo lo demás, el formulario Custom Providers / API te permite añadir el endpoint tú mismo.

El problema: cuando no funciona a la primera, puede deberse a un pequeño error de configuración. El error que recibes ("connection failed", "401", "404", "model not found") puede ser complicado de interpretar.

Esta entrada es una guía rápida para comprobar y resolver el problema por tu cuenta. Repasa la lista de comprobación y confirma tu configuración. Si aun así no funciona, escríbenos a wave@surfmind.ai.

¿Buscas un proveedor concreto? Consulta nuestra lista: modelos locales (Ollama, LM Studio, OpenWebUI, Jan…) o proveedores de IA (Poe, z.ai, Together, Groq, AWS…).

La lista de comprobación de 60 segundos

Antes que nada, repasa estos puntos. La mayoría de los problemas de configuración se reducen a uno de ellos:

1. ¿Está realmente en marcha el servidor? Para los modelos locales, el ejecutor (Ollama, LM Studio, etc.) tiene que estar iniciado y tener un modelo cargado.
2. ¿Es correcto el puerto? El de Ollama es 11434. El de LM Studio es 1234. No son intercambiables, y este es el error más común de todos.
3. ¿Es correcta la ruta? La ruta nativa de Ollama es /api/chat. Casi todo lo demás usa /v1/chat/completions. Confundirlas te da un error.
4. ¿Es correcto el protocolo — http o https? Los modelos locales en localhost usan http:// (sin s). Los proveedores en la nube usan https://. Si los confundes, parecerá que no hay conexión.
5. ¿Pegaste el endpoint completo, no solo la base? El campo API URL de SurfMind espera la URL completa terminada en /chat/completions (o /api/chat para Ollama), no solo https://api.provider.com/v1.
6. ¿Es correcta la API key (y su formato)? Los ejecutores locales normalmente no necesitan clave. Los proveedores externos necesitan Authentication configurado como API Key, el formato Authorization: Bearer y tu clave real.
7. Para modelos locales en el navegador: ¿está permitido CORS? Este es el paso adicional que requieren las configuraciones locales (OLLAMA_ORIGINS, o "Enable CORS" en LM Studio).

Si después de esto sigues atascado, continúa leyendo: cada uno de estos puntos tiene detalles que es fácil pasar por alto.

Cómo conectar un proveedor

Son solo unos clics desde el selector de modelos:

Paso 1. Haz clic en el nombre del modelo en la parte inferior del panel de SurfMind para abrir tus Favoritos y luego haz clic en Show all.

Paso 2. En la parte superior de la lista de modelos, haz clic en Add model provider. Se abre la página Models en los ajustes de SurfMind.

Paso 3. Busca tu proveedor. Los ejecutores locales (Ollama, LM Studio, vLLM, llama.cpp, Open WebUI) están en Self-hosted. Los proveedores en la nube (OpenAI, Anthropic, Google, OpenRouter, Groq, DeepSeek, Mistral, Poe, z.ai, Together, AWS Bedrock y más) están en Providers. Si la lista es larga, usa el cuadro de búsqueda, y luego haz clic en Connect.

Paso 4. Para un proveedor en la nube, pega tu API key y haz clic en Connect. El diálogo enlaza a la página donde puedes obtener una clave. Para un ejecutor autoalojado, el formulario se abre con las URLs locales ya rellenadas, así que solo tienes que guardarlo (Open WebUI también necesita tu clave).

Una vez conectado, los modelos del proveedor aparecen en el selector de modelos. Despliega la fila del proveedor para elegir cuáles se muestran.

¿No ves tu proveedor? Añádelo como proveedor personalizado

Si tu proveedor o ejecutor no está en la lista (Jan, LocalAI, la pasarela de tu empresa o un proveedor que aún no hemos añadido), haz clic en Custom Providers / API en la parte superior de la página Models.

Se abre el formulario "Custom Model API", donde introduces el endpoint tú mismo.

El resto de esta guía trata sobre todo de este formulario, porque es ahí donde se producen los errores de configuración.

Qué va en cada campo

Cuando haces clic en Custom Providers / API, aparece el formulario "Custom Model API". Esto es exactamente lo que debes poner en cada campo:

Las dos cosas en las que más se equivoca la gente son API URL (base frente a endpoint completo) y API Key Format (qué cabecera). El resto de esta guía profundiza en ellos.

Error n.º 1: la ruta de la API URL (la trampa de /api/chat frente a /v1/chat/completions)

Este es el error más importante, y vale la pena entender por qué ocurre.

Aquí se usan dos formatos de API distintos:

• La API nativa de Ollama, que usa http://localhost:11434/api/chat.
• La API de completado de OpenAI, que usa .../v1/chat/completions. Es la que utilizan LM Studio, vLLM, Jan, Poe, z.ai, Together, Groq, básicamente todos los demás.

Así que si copias una guía de configuración escrita para LM Studio e intentas usar esa ruta con Ollama (o viceversa), obtendrás un 404 aunque el servidor esté funcionando perfectamente. El servidor está activo; simplemente estás llamando a la puerta equivocada.

Un apunte útil: Ollama admite ambos formatos de API. La entrada Ollama de Self-hosted en SurfMind usa la ruta nativa /api/chat, que es la opción más sencilla y te da descubrimiento automático de modelos. Solo necesitas la ruta /v1/chat/completions de Ollama si una herramienta exige específicamente el formato de OpenAI. Para SurfMind, simplemente haz clic en Connect en la fila de Ollama.

Error n.º 2: el número de puerto

Cada ejecutor local elige su propio puerto por defecto, y se parecen lo suficiente como para equivocarse al teclear:

11434 frente a 1234 es la confusión clásica: a primera vista son fáciles de confundir, pero con un dígito de diferencia no conecta nada. Si cambiaste tú mismo el puerto (p. ej. ejecutaste vLLM con --port 9000), usa tu puerto, no el predeterminado.

Para comprobarlo, abre en el navegador la dirección del servidor con su puerto. Visitar http://localhost:11434 debería mostrar el mensaje "Ollama is running" de Ollama. Si la página no carga en absoluto, el servidor no está activo o tienes el puerto equivocado.

Error n.º 3: pegar la URL base en lugar del endpoint

La documentación de los proveedores casi siempre te da una URL base, algo como https://api.poe.com/v1. Eso es porque sus ejemplos de código usan el SDK de OpenAI, que añade /chat/completions automáticamente.

El campo API URL de SurfMind no hace eso por ti. Espera el endpoint completo. Así que tienes que añadir la ruta tú mismo:

• URL base de la documentación: https://api.poe.com/v1
• Lo que pegas en SurfMind: https://api.poe.com/v1/chat/completions

La misma idea para el campo Models URL (usado para listar automáticamente los modelos disponibles): toma la base y añade /models → https://api.poe.com/v1/models.

Dos descuidos relacionados:

• /v1 duplicado. Si la base ya termina en /v1, no añadas otro. .../v1/v1/chat/completions es un 404.
• Barras finales. .../chat/completions/ con una barra al final puede fallar en algunos servidores. Quítala.

Error n.º 4: discrepancia entre http y https

El esquema al principio de la URL importa, y confundirlo produce un "connection failed" que parece que el servidor está caído cuando no lo está.

• Los modelos locales son http. Ollama, LM Studio, Jan, llama.cpp — cualquier cosa en localhost — sirve http:// sin más. Escribir https://localhost:11434 falla, porque no hay certificado TLS en un servidor local. Si copiaste un fragmento con https delante de localhost, quita la s.
• Los proveedores en la nube son https. Poe, z.ai, Together, Groq y el resto solo aceptan https://. Enviarles http:// hace que la petición se rechace o se redirija en silencio.

También hay que tener en cuenta la seguridad del navegador: las páginas servidas por https bloquean las peticiones a endpoints http sin cifrar ("mixed content"). SurfMind trata http://localhost como una excepción de confianza, así que los modelos locales funcionan — pero una IP de LAN sin más como http://192.168.1.50:11434 puede seguir estando bloqueada. Si estás apuntando a otra máquina de tu red, es preferible usar https, o servir el modelo detrás de un proxy https local.

Regla general: http para localhost, https para todo lo que esté en internet.

Error n.º 5: la Models URL no coincide con la API URL

La Models URL es opcional. Es el endpoint que SurfMind llama para obtener la lista de modelos que ofrece un proveedor, de modo que pueda mostrarlos en un desplegable en lugar de obligarte a escribir nombres. Si tus modelos no aparecen en el selector después de guardar, este campo suele ser el culpable. Debe usar el mismo formato de API que el endpoint de chat:

Un error común es mezclarlos: usar /api/tags con un proveedor compatible con OpenAI, o /v1/models con la ruta nativa /api/chat de Ollama. Si te conectaste a través de la fila Ollama de Self-hosted, esto se rellena correctamente por ti; déjalo como está.

Cuándo dejarlo en blanco: algunos proveedores no exponen un endpoint público de listado de modelos, o lo bloquean. No pasa nada: deja la Models URL vacía y escribe tú mismo el id exacto del modelo en el campo de modelo (consulta el Error n.º 8). El chat seguirá funcionando; simplemente no obtendrás el desplegable autocompletado.

Error n.º 6: el formato de la API key (Bearer frente a x-api-key)

En el formulario personalizado, Authentication y API Key Format deciden cómo se adjunta tu clave a la petición. Elige la opción incorrecta y obtendrás un 401 Unauthorized incluso con una clave perfectamente válida. Las opciones:

Después, el campo API Key toma solo la clave en sí:

• No escribas la palabra Bearer: SurfMind la añade cuando eliges Authorization: Bearer.
• No dejes un espacio al final (una causa sorprendentemente común de 401).
• Para modelos locales, elige No authentication. (LM Studio es la excepción: quiere algún valor no vacío; su propia documentación usa lm-studio.)

Si no estás seguro de qué formato usa un proveedor: el 99 % de los proveedores compatibles con OpenAI usan Authorization: Bearer. Recurre a x-api-key solo si la documentación del proveedor muestra explícitamente una cabecera x-api-key. ¿Sigues recibiendo un 401? Regenera la clave, vuelve a comprobar el formato elegido y confirma que no se haya colado ningún espacio.

Error n.º 7: CORS, el escollo exclusivo de lo local

Los navegadores se niegan a llamar a un servidor local a menos que ese servidor permita explícitamente las peticiones desde la extensión. Esto afecta específicamente a las configuraciones locales (los proveedores externos ya lo permiten).

• Ollama: inícialo con el acceso desde el navegador habilitado:

  # Mac/Linux
  OLLAMA_ORIGINS="*" ollama serve
  
  # Windows (PowerShell)
  $env:OLLAMA_ORIGINS="*"; ollama serve

  ¿"port 11434 already in use"? La aplicación en segundo plano de Ollama ya está en marcha. Ciérrala primero (barra de menús en Mac, bandeja del sistema en Windows) y luego ejecuta el comando anterior.

• LM Studio: en la pestaña Developer / servidor local, activa Enable CORS antes de iniciar el servidor.

Otra sutileza: si localhost no conecta, prueba con 127.0.0.1 en su lugar (o al revés). En algunos sistemas no se resuelven de la misma manera.

Error n.º 8: el nombre del modelo tiene que coincidir exactamente

Una vez conectado, el nombre del modelo que selecciones tiene que coincidir con lo que el proveedor espera, exactamente, incluidas las mayúsculas y minúsculas. Es fácil equivocarse con proveedores que no muestran una lista de modelos o que usan nombres poco habituales:

• Poe usa los nombres de los bots que aparecen en pantalla como Claude-Sonnet-4.6 y GPT-5.4: cópialos exactamente como aparecen en Poe.
• z.ai usa ids como glm-4.6 y glm-5.
• Together AI usa ids con espacio de nombres: meta-llama/Llama-3.3-70B-Instruct-Turbo, deepseek-ai/DeepSeek-V3.
• Fireworks usa un id de ruta completa: accounts/fireworks/models/llama-v3p3-70b-instruct.

Si la conexión funciona pero obtienes "model not found", casi siempre es un error tipográfico en el nombre o un uso incorrecto de mayúsculas. Cuando SurfMind puede listar modelos automáticamente mediante la Models URL, elige de la lista en lugar de escribir.

Referencia rápida: modelos locales

Todos estos se ejecutan en tu propia máquina. Ollama, LM Studio, vLLM, llama.cpp y Open WebUI ya aparecen en Self-hosted en la página Models: haz clic en Connect y las URLs de abajo se rellenan por ti. Para Jan y LocalAI, haz clic en Custom Providers / API, pega las URLs y configura Authentication como No authentication. Si cambiaste el puerto de un ejecutor, edita la URL para que coincida. Los nombres de los proveedores enlazan a la documentación de configuración de cada herramienta.

Ollama

• API URL: http://localhost:11434/api/chat
• Models URL: http://localhost:11434/api/tags
• API key: ninguna

LM Studio

• API URL: http://localhost:1234/v1/chat/completions
• Models URL: http://localhost:1234/v1/models
• API key: cualquier valor no vacío (p. ej. lm-studio)

Jan

• API URL: http://localhost:1337/v1/chat/completions
• Models URL: http://localhost:1337/v1/models
• API key: ninguna (o tu clave de Jan)

llama.cpp

• API URL: http://localhost:8080/v1/chat/completions
• Models URL: http://localhost:8080/v1/models
• API key: ninguna (a menos que lo iniciaras con --api-key)

vLLM

• API URL: http://localhost:8000/v1/chat/completions
• Models URL: http://localhost:8000/v1/models
• API key: tu --api-key si lo configuraste

LocalAI

• API URL: http://localhost:8080/v1/chat/completions
• Models URL: http://localhost:8080/v1/models
• API key: ninguna

OpenWebUI: la excepción a la regla de "sin clave". OpenWebUI sí necesita una API key, y sus rutas son /api/..., no /v1/.... Conéctalo desde la lista Self-hosted y pega tu clave sk-…, que encontrarás en Settings → Account → API keys. Usa http://localhost:3000 si lo tienes instalado con Docker de la forma habitual, o la dirección de tu servidor si se ejecuta en otra máquina.

• API URL: http://localhost:3000/api/chat/completions
• Models URL: http://localhost:3000/api/models
• API key: tu clave de OpenWebUI (sk-…)

La configuración completa y la resolución de problemas están en nuestra guía de la OpenWebUI API.

No olvides el paso de CORS (Error n.º 7) para cualquiera de estos. Para Ollama en concreto, el recorrido completo con capturas de pantalla está en nuestra guía de Ollama, y si estás decidiendo entre los dos primeros, consulta Ollama frente a LM Studio.

Referencia rápida: proveedores de IA populares

Todos los proveedores de abajo ya aparecen en Providers en la página Models: haz clic en Connect y pega tu clave; las URLs se rellenan por ti. Los incluimos aquí como referencia, o por si prefieres añadir alguno a mano con Custom Providers / API (configura Authentication como API Key con el formato Authorization: Bearer). Los nombres de los proveedores enlazan a la documentación de la API de cada proveedor.

Poe — una sola clave para cientos de modelos (Claude, GPT, Gemini, Llama…), cuyo uso se descuenta de los puntos de tu suscripción de Poe. Los nombres de los modelos son los nombres de los bots que aparecen en pantalla: cópialos exactamente como se muestran en Poe (p. ej. Claude-Sonnet-4.6, GPT-5.4). Clave desde poe.com → Settings → API key.

• API URL: https://api.poe.com/v1/chat/completions
• Models URL: https://api.poe.com/v1/models

CanopyWave — proveedor de GPU en la nube que sirve modelos abiertos (Kimi, DeepSeek, Llama, Qwen). Clave desde el panel de CanopyWave.

• API URL: https://inference.canopywave.io/v1/chat/completions
• Models URL: https://inference.canopywave.io/v1/models

z.ai (GLM) — los modelos GLM de Zhipu (glm-4.6, glm-5). Cuidado: z.ai también publica un endpoint independiente de Coding Plan (https://api.z.ai/api/coding/paas/v4) y un endpoint PaaS (https://api.z.ai/api/paas/v4); usa el compatible con OpenAI de abajo y no añadas un /v1 adicional.

• API URL: https://api.z.ai/api/openai/v1/chat/completions
• Models URL: https://api.z.ai/api/openai/v1/models

Together AI — amplio catálogo de modelos abiertos. Los ids de los modelos son largos (meta-llama/Llama-3.3-70B-Instruct-Turbo): cópialos exactamente de la página de modelos de Together.

• API URL: https://api.together.xyz/v1/chat/completions
• Models URL: https://api.together.xyz/v1/models

Groq — inferencia extremadamente rápida. Escollo: la ruta es /openai/v1, no solo /v1.

• API URL: https://api.groq.com/openai/v1/chat/completions
• Models URL: https://api.groq.com/openai/v1/models

DeepSeek — los modelos actuales son deepseek-v4-flash y deepseek-v4-pro (los alias más antiguos deepseek-chat / deepseek-reasoner están siendo retirados; consulta la documentación de DeepSeek para lo más reciente). El /v1 es opcional; DeepSeek acepta la URL con o sin él.

• API URL: https://api.deepseek.com/v1/chat/completions
• Models URL: https://api.deepseek.com/v1/models

Mistral — mistral-large-latest, mistral-small-latest, etc. Compatible estándar con OpenAI.

• API URL: https://api.mistral.ai/v1/chat/completions
• Models URL: https://api.mistral.ai/v1/models

Fireworks AI — escollo: la ruta es /inference/v1, no /v1. Los ids de los modelos tienen esta forma: accounts/fireworks/models/llama-v3p3-70b-instruct.

• API URL: https://api.fireworks.ai/inference/v1/chat/completions
• Models URL: https://api.fireworks.ai/inference/v1/models

xAI (Grok) — los modelos Grok (grok-4, etc.). Compatible estándar con OpenAI.

• API URL: https://api.x.ai/v1/chat/completions
• Models URL: https://api.x.ai/v1/models

AWS Bedrock — Bedrock ahora tiene un endpoint compatible con OpenAI, pero con dos escollos: el host es específico de la región (p. ej. us-west-2) y la ruta es /openai/v1. Debes usar una Bedrock API key (un token bearer que generas en la consola), no tus claves de acceso de AWS / SigV4 habituales. Los ids de los modelos tienen esta forma: openai.gpt-oss-120b-1:0. Cuando conectas Bedrock desde la lista Providers, elige tu región en el desplegable y SurfMind construye la URL por ti.

• API URL: https://bedrock-runtime.<region>.amazonaws.com/openai/v1/chat/completions
• Models URL: déjala en blanco; introduce el id del modelo más tarde

¿Sigue sin conectar? Diagnóstico final

Repasa esta lista:

1. Revisa primero la página Models. Si tu proveedor aparece ahí, conéctalo desde allí en lugar de crear una entrada personalizada.
2. Abre el host de la API URL en tu navegador. Si el servidor local no carga → no está en marcha, o el puerto es incorrecto.
3. Vuelve a leer la ruta. Ollama → /api/chat. Todos los demás → /v1/chat/completions (o la ruta especial del proveedor de la tabla).
4. Confirma que pegaste el endpoint completo, no la base, y que no hay un /v1 duplicado ni una barra al final.
5. ¿401? Es la clave o su formato. Formato = Authorization: Bearer, clave sin espacios, sin el prefijo Bearer.
6. ¿404 "model not found"? La conexión está bien: corrige el nombre del modelo (mayúsculas y minúsculas exactas).
7. ¿Modelo local, bloqueado en el navegador? Habilita CORS (OLLAMA_ORIGINS="*" o el interruptor de LM Studio), y prueba 127.0.0.1 frente a localhost.

Estos pasos resuelven la inmensa mayoría de los problemas de configuración.

¿Todavía necesitas ayuda?

Si has repasado la lista de comprobación y tu proveedor sigue sin conectar, escríbenos a wave@surfmind.ai indicando el proveedor que intentas usar y el error que ves. Te ayudaremos a conectarlo.

---

¿Lo conectaste? Abre SurfMind en la próxima página que ibas a leer y pon tu modelo a trabajar.

Consigue SurfMind →