Dify reúne la orquestación de prompts, la recuperación en bases de conocimiento, los flujos de trabajo y los agentes en una misma interfaz visual, pero la lista de modelos preconfigurada no siempre cubre los que tienes a mano. Siempre que el servicio de destino ofrezca una interfaz compatible con OpenAI, puedes conectarlo como «modelo personalizado» y ejecutar tus aplicaciones con tu propia clave y tu propia facturación.

A la hora de configurar, lo que bloquea a la mayoría no es qué botón pulsar, sino varios detalles: falta /v1 en la Base URL, el nombre del modelo no coincide con el que figura en la pasarela, el interruptor de llamadas a funciones está apagado o la red donde está Dify no llega a tu dirección interna. Este artículo sigue el orden «preparar—añadir—vincular—diagnosticar»; los nombres de la interfaz corresponden a la versión actual.

Nota: Dify es una marca de su titular y este artículo no guarda relación de afiliación con los fabricantes mencionados. Los nombres de modelo, la longitud de contexto y los precios figuran en la página de precios de modelos; aquí se toman como referencia las versiones habituales de octubre de 2026.

1. Confirma cuatro cosas antes de conectar

No te apresures a abrir Dify: primero verifica con una petición mínima que el servicio upstream responde. Hay que confirmar:

  1. Protocolo: si la interfaz es compatible con OpenAI y ofrece al menos /v1/chat/completions.
  2. Base URL: la mayoría de los servicios piden escribirla hasta /v1, no la ruta completa /v1/chat/completions.
  3. Nombre del modelo: debe coincidir exactamente con lo que devuelve /v1/models de la pasarela; cuidado con mayúsculas, sufijos de fecha y alias.
  4. Capacidades: si admite salida en streaming, llamadas a funciones y entrada de imágenes; para una base de conocimiento, confirma también la dimensión de Embedding.

Haz una comprobación previa con curl:

curl https://tu-direccion-de-pasarela/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tu-nombre-de-modelo",
    "messages": [{"role": "user", "content": "Responde solo OK"}]
  }'

Si la respuesta incluye choices, la dirección, la clave y el nombre del modelo son correctos. Supera esta prueba antes de conectar Dify y te ahorrarás la mitad del camino.

2. Añade un proveedor de modelos en Dify

En Dify, la conexión de modelos se gestiona mediante plugins, y tanto la entrada como los nombres de los campos pueden cambiar según la versión. El flujo típico es:

  1. Entra en la página de configuración de proveedores de modelos.
  2. Busca el plugin OpenAI-API-compatible (compatible con OpenAI) e instálalo o actívalo; el nombre exacto depende de la versión.
  3. Haz clic en añadir modelo y elige el tipo.
  4. Rellena el nombre del modelo, la API Key y la Base URL.
  5. Introduce la longitud de contexto, la salida máxima y los demás parámetros según las capacidades reales del modelo.
  6. Guarda y pulsa probar para confirmar que devuelve contenido.

Puntos clave al rellenar los campos:

Campo Forma correcta Error habitual
Base URL Normalmente hasta /v1, por ejemplo https://api.example.com/v1 Añadir /chat/completions y provocar un 404
Nombre del modelo Idéntico a lo que devuelve /v1/models Mayúsculas o sufijo de versión incorrectos: «modelo no encontrado»
API Key Pegar la cadena completa, sin añadir Bearer a mano Espacios o comillas de más: respuesta 401
Tipo de modelo LLM, Embedding, Rerank, transcripción de voz o TTS según el uso Tipo equivocado: el modelo no aparece en la aplicación
Longitud de contexto El valor que el proveedor admite realmente; mejor quedarse corto Poner el máximo teórico y que el upstream rechace peticiones largas
Interruptores de capacidad Activar streaming, funciones y visión según el soporte real El agente falla al usar herramientas o se rechazan las imágenes

3. No copies los parámetros de la página promocional

El «contexto máximo» de la página del modelo suele ser el límite teórico; el valor utilizable depende también de la longitud de salida, del modo de facturación y de los límites de la pasarela. Al configurar conviene dejar margen:

  • Introduce una longitud de contexto que el proveedor admita explícitamente; no pongas el límite máximo solo para que «parezca más potente».
  • Configura la salida máxima por separado para evitar que las respuestas largas se trunquen o que el coste se descontrole.
  • Si no estás seguro de que admita llamadas a funciones, desactívalas, valida con una conversación normal y actívalas una por una.
  • En los modelos de visión, confirma si la imagen va por URL o en Base64; algunas interfaces compatibles solo aceptan una de las dos formas.
  • Cuando un modelo de Embedding se usa en una base de conocimiento, su dimensión queda fijada; cambiar de modelo normalmente obliga a reconstruir el índice.

Si necesitas varios modelos bajo el mismo proveedor, añádelos uno a uno. El nombre expuesto puede ser distinto del que usa el upstream, pero conviene mantenerlo legible y trazable, por ejemplo incluyendo el uso o la versión en el nombre.

4. Vincula el modelo a la aplicación

Que el modelo se haya añadido correctamente no significa que la aplicación ya lo esté usando. En Dify hay al menos tres lugares que revisar:

  • Asistente de chat / aplicación de generación de texto: elige el modelo en la página de orquestación y comprueba que las variables del prompt no tengan el nombre del modelo codificado.
  • Flujos de trabajo / Agentes: cada nodo LLM o nodo de agente elige su modelo por separado; distintos nodos pueden mezclar modelos.
  • Base de conocimiento: en la configuración de modelos del sistema, indica el modelo de Embedding y el de Rerank; la indexación y la consulta deben usar el mismo conjunto.

Un reparto práctico: usa modelos pequeños para tareas simples como clasificar, reescribir o extraer, y un modelo potente para la generación final. Así controlas el coste y evitas que el modelo grande se sature con muchas peticiones cortas.

5. Errores habituales y orden de diagnóstico

Síntoma Causa posible Solución
401 Unauthorized Clave incorrecta, caducada o con caracteres de más Repite la prueba con curl y vuelve a pegar la clave
404 Not Found Ruta de la Base URL incorrecta Confirma que es /v1 y no la ruta completa del endpoint
model not found El nombre no coincide con el registrado en la pasarela Consulta /v1/models y revisa mayúsculas
Tiempo de espera agotado Dify no alcanza el upstream o este responde despacio Revisa red, DNS, firewall y proxy
400 context length Límite de contexto o de salida mayor que el real Reduce los parámetros y divide antes los textos largos
429 Too Many Requests Límite de tasa del upstream Baja la concurrencia y configura reintentos con retroceso
Fallo de llamada a herramientas El modelo no admite funciones o el formato de parámetros no encaja Desactiva las herramientas y valida primero la conversación simple
Recuperación anómala en la base de conocimiento Dimensión de Embedding inconsistente Vuelve al modelo anterior o reconstruye el índice

Otro punto que se pasa por alto: si Dify está desplegado en la nube o en un contenedor, localhost, 127.0.0.1 y las direcciones de red privada normalmente no son accesibles; algunas versiones además activan protección SSRF y bloquean directamente las peticiones a la red interna. Expón el servicio de modelos en una dirección HTTPS pública o, en un entorno autoalojado, configura proxy y listas de permitidos según la documentación.

6. Estabilidad y coste

Una vez completada la conexión, conviene añadir tres cosas:

  1. Configura tiempos de espera y reintentos: ajusta el timeout a la ruta más lenta del negocio y limita los reintentos a 429 y 5xx para evitar cobros duplicados.
  2. Registra las llamadas: conserva al menos el nombre del modelo, la latencia, el consumo de tokens y el código de error; así podrás localizar el nodo exacto cuando algo falle.
  3. Controla el contexto: recuperar más fragmentos de la base de conocimiento no siempre es mejor; los fragmentos irrelevantes encarecen la llamada y enturbian la respuesta.

En cuanto al coste, Dify solo orquesta; el gasto viene de las llamadas al modelo upstream. Sustituir nodos simples por modelos pequeños, comprimir prompts y reducir reintentos inútiles suele ser más eficaz que cambiar de proveedor. El precio unitario exacto figura en precios de modelos; no uses una cifra fija para presupuestos a largo plazo.

Preguntas frecuentes

¿Hay que instalar un plugin para conectar modelos personalizados en Dify?

Las versiones más recientes gestionan la conexión mediante plugins de proveedor de modelos; el nombre y la entrada dependen de la versión. Si la tuya no incluye ese plugin, busca uno relacionado con la compatibilidad con OpenAI en el mercado de plugins o actualiza a una versión que lo admita.

¿Por qué funciona curl pero Dify devuelve error?

Revisa primero tres puntos: si la red donde está Dify puede acceder a esa dirección; si la interfaz añade automáticamente una ruta a la Base URL; y si la clave tiene espacios o saltos de línea. La causa más frecuente es que Dify Cloud no puede llegar a tu dirección de red interna.

¿Se puede conectar directamente una interfaz no compatible con OpenAI?

No directamente. Primero hay que convertirla al formato OpenAI mediante una pasarela o una capa de adaptación y después conectarla a Dify. Esa capa debe gestionar la estructura de mensajes, las llamadas a herramientas y los eventos de streaming; no basta con redirigir la URL.

¿Puedo añadir varios modelos con un mismo proveedor?

Sí. Configura cada modelo con su nombre, contexto e interruptores de capacidad, y selecciona el que necesites en cada aplicación. Conviene distinguir el uso en el nombre para que el equipo no elija mal.

¿Sigue funcionando la base de conocimiento si cambio el modelo de Embedding?

Normalmente no se pueden mezclar directamente. Si cambia la dimensión del vector o el espacio semántico, el índice antiguo deja de encajar con las nuevas consultas; hay que reconstruir la base de conocimiento y volver a indexar. Antes de cambiar, valida la recuperación con un conjunto de datos pequeño.

Siguiente paso

La clave para conectar Dify se resume en tres frases: valida primero el upstream con curl, rellena los parámetros según las capacidades reales y confirma la vinculación nodo por nodo. Si necesitas una entrada compatible con OpenAI unificada y gestión de consumo, puedes registrarte en la pasarela de IA de ZSQH; los modelos y precios figuran en precios de modelos.

Lecturas relacionadas: