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

SurfMind no te encierra en un único conjunto de modelos. A través de la Custom Model API, puedes apuntarlo 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 hable la API de completado de OpenAI: Poe, z.ai, Together, Groq, DeepSeek, AWS Bedrock y muchos más.

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, 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. ¿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.
5. ¿Es correcta la API key (y su cabecera)? Los ejecutores locales normalmente no necesitan clave. Los proveedores externos necesitan Authorization como cabecera y tu clave real como valor.
6. 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 una versión sutil que pilla a la gente.

Qué va en cada campo

Cuando abres la pestaña Custom → Add Custom Models, aparece el formulario "Custom Model API". Esto es exactamente lo que debes poner en cada campo:

Los dos campos en los que más se equivoca la gente son API URL (base frente a endpoint completo) y API Key Header (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.

En este mundo hay dos "dialectos" 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 hablan 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 en realidad habla ambos dialectos. El Ollama preset de 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, usa simplemente el preset.

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.

Comprobación rápida: abre el puerto en tu navegador. 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 por ti entre bastidores.

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: 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. Tiene que seguir el mismo dialecto que el endpoint de chat:

Un error común es mezclarlos: usar /api/tags con un proveedor compatible con OpenAI, o /v1/models con el preset nativo de Ollama. Si usaste el Ollama preset, 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.º 7). El chat seguirá funcionando; simplemente no obtendrás el desplegable autocompletado.

Error n.º 5: la API Key Header (Bearer frente a x-api-key)

El desplegable API Key Header decide cómo se adjunta tu clave a la petición. Elige la incorrecta y obtendrás un 401 Unauthorized incluso con una clave perfectamente válida. Hay tres 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.
• No dejes un espacio al final (una causa sorprendentemente común de 401).
• Para modelos locales, déjalo vacío. (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é cabecera usa un proveedor: el 99 % de los proveedores compatibles con OpenAI usan Authorization. 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 la cabecera elegida y confirma que no se haya colado ningún espacio.

Error n.º 6: 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.º 7: 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. Esto pilla a la gente en proveedores que no listan modelos automáticamente, o que usan una nomenclatura inusual:

• Poe usa nombres de bot con formato de visualización 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. Abre la pestaña Custom de SurfMind → Add Custom Models, elige el preset correspondiente (Ollama tiene el suyo propio; el resto usa el preset genérico OpenAI-compatible) y configura API Key Header como None. 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

No olvides el paso de CORS (Error n.º 6) 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 estos proveedores en la nube hablan la API compatible con OpenAI. Usa el preset genérico OpenAI-compatible, configura la API Key Header como Authorization (todos usan tokens Bearer) y pega tu clave. 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…), facturados contra los puntos de tu suscripción de Poe. Los nombres de los modelos son nombres de bot con formato de visualización: 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.

• 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. 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.
2. Vuelve a leer la ruta. Ollama → /api/chat. Todos los demás → /v1/chat/completions (o la ruta especial del proveedor de la tabla).
3. Confirma que pegaste el endpoint completo, no la base, y que no hay un /v1 duplicado ni una barra al final.
4. ¿401? Es la clave o la cabecera. Cabecera = Authorization, clave sin espacios, sin el prefijo Bearer.
5. ¿404 "model not found"? La conexión está bien: corrige el nombre del modelo (mayúsculas y minúsculas exactas).
6. ¿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.

Esa secuencia resuelve la inmensa mayoría de las configuraciones.

¿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 →