Dify reúne la orquestación de prompts, la base de conocimiento, los flujos de trabajo y los agentes en una misma interfaz visual. No produce modelos: su capacidad proviene de los proveedores que conectas. Una práctica habitual en los equipos es autoalojar Dify y conectar una pasarela de API unificada mediante una interfaz compatible con OpenAI, de modo que las claves, los modelos y el consumo se gestionen del lado de la pasarela.

Este artículo sigue el orden de despliegue, alta del proveedor, configuración de parámetros, flujo mínimo, uso en equipo y refuerzo de seguridad. Los nombres de la interfaz, los plugins y las variables corresponden a la documentación oficial de la versión actual; los modelos y los precios se rigen por la página de precios de modelos y pueden cambiar.

Nota: Dify es una marca de su titular. Este artículo es una explicación técnica independiente y no implica afiliación con los fabricantes mencionados.

1. ¿Nube o autoalojado?

Dify ofrece un servicio en la nube y una edición comunitaria para autoalojamiento. La nube ahorra operación y sirve para validar rápido; el autoalojamiento mantiene los datos en tu propio servidor y encaja en equipos con requisitos de red, datos y permisos.

  • Solo para pruebas: la nube es más rápida, pero conviene confirmar la ubicación de los datos y la accesibilidad de la red.
  • Modelos internos o plugins personalizados: el autoalojamiento es más flexible, aunque tú asumes actualizaciones, copias de seguridad y HTTPS.
  • Uso prolongado en equipo: en ambos casos hay que planificar permisos de miembros, gestión de claves y presupuesto.

2. Despliegue con Docker Compose

Para la edición comunitaria se recomienda Docker Compose. La configuración mínima de la documentación actual es de 2 núcleos de CPU y 4 GiB de memoria; en macOS, la máquina virtual de Docker Desktop debería tener al menos 8 GiB. En Linux se requiere Docker 19.03 o superior y Compose 2.24 o superior.

  1. Clona el repositorio en la etiqueta del release más reciente; necesitas git, curl y jq.
  2. Entra en el directorio dify/docker y copia .env.example como .env.
  3. Ejecuta docker compose up -d para iniciar los servicios.
  4. Comprueba el estado con docker compose ps y espera a que los servicios estén listos.
  5. Abre http://dirección-del-servidor/install para crear el administrador y después inicia sesión desde la raíz.
git clone --branch "$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r .tag_name)" https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env
docker compose up -d
docker compose ps

El acceso predeterminado es por el puerto 80 y la entrada de instalación es /install. La cantidad de contenedores cambia según la versión, así que no la cuentes con tutoriales antiguos; que init_permissions aparezca como Exited suele ser normal, porque es una tarea de una sola ejecución.

La configuración vive en .env y sobrescribe las variables con el mismo nombre que estén en envs/. Después de cambiar algo, ejecuta docker compose down y luego up -d. Antes de actualizar, lee las notas de la versión correspondiente, compara las variables nuevas de .env.example y no reutilices sin revisar el archivo compose anterior.

3. Añadir un proveedor de modelos compatible con OpenAI

Solo el propietario y los administradores del espacio de trabajo pueden gestionar proveedores de modelos. La entrada suele estar en Integrations o en Model Provider dentro de los ajustes; instala primero el plugin OpenAI-API-compatible y pulsa Setup para introducir las credenciales. Los nombres cambian entre versiones; si no los encuentras, consulta la documentación actual.

El orden típico para añadir un modelo es:

  1. Instala o activa el plugin compatible con OpenAI.
  2. Introduce la API Key y la Base URL personalizada.
  3. Guarda y espera a que pase la validación de credenciales.
  4. Añade el modelo y elige su tipo.
  5. Completa el nombre del modelo, la longitud de contexto y los interruptores de capacidad.
  6. Verifica con la prueba de la interfaz o con una aplicación mínima.
Campo Cómo rellenarlo Error habitual
Base URL Normalmente hasta /v1, por ejemplo https://ai.zhongshangqihang.com/v1 Añadir /chat/completions y recibir un 404
API Key Pegar la cadena completa, sin añadir Bearer a mano Espacios, saltos de línea o comillas: respuesta 401
Nombre del modelo Igual que en /v1/models o en la página de precios de modelos Mayúsculas o sufijo de fecha incorrectos: model not found
Tipo de modelo LLM, Embedding, Rerank, voz, etc., según el uso Tipo equivocado: el modelo no aparece en la aplicación
Longitud de contexto El valor que el proveedor admite realmente, con margen 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

Bajo un mismo proveedor puedes añadir varios modelos y configurarlos uno a uno. Conviene que el nombre incluya el uso o la versión. 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.

4. Primero curl, después la prueba en Dify

Si pruebas directamente después de rellenar los campos, un fallo no distingue entre la pasarela, la red o un campo mal escrito. Valida primero el upstream con curl:

export ZSQH_API_KEY="sk-tu-clave"

curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tu-id-de-modelo","messages":[{"role":"user","content":"Responde solo OK"}]}' \
  -w "\nHTTP %{http_code}\n"

Si la respuesta incluye choices, la clave, la dirección y el nombre del modelo son válidos. Un 401 apunta a la clave; un 404, a la ruta; un «model not found», al nombre del modelo. La Base URL se escribe hasta /v1, no la ruta completa del endpoint; no agregues Bearer a mano a la clave, porque Dify lo añade.

Dify valida las credenciales al guardar el proveedor, pero pasar la validación no significa que todos los modelos funcionen: confirma también el tipo, la longitud de contexto y los interruptores de capacidad. Si no hay botón de prueba, crea la aplicación de chat más simple o llama a la API de la aplicación.

5. Montar un flujo mínimo

Haz funcionar primero la cadena mínima y añade nodos poco a poco. Tomemos un flujo de trabajo como ejemplo:

  1. En Studio, crea un Workflow o un Chatflow: para conversación elige Chatflow; para lotes o automatización, Workflow.
  2. Define una variable de entrada en el nodo de inicio, por ejemplo query.
  3. Añade un nodo LLM, selecciona el proveedor y el modelo recién conectados y referencia la variable del nodo de inicio en el prompt.
  4. Añade un nodo final y conecta la salida del LLM a la variable de salida.
  5. Ejecuta una prueba con una pregunta real y revisa entrada, salida y consumo de tokens nodo por nodo.
  6. Cuando esté correcto, publica y llama desde la página embebida o la API de la aplicación.

Cuando necesites recuperación, añade un nodo de recuperación de conocimiento antes del LLM y configura antes los modelos de Embedding y Rerank en los ajustes del espacio de trabajo. Para ramas, usa clasificación de preguntas o condiciones. El nodo Agent sirve para escenarios con herramientas, pero exige un modelo que admita llamadas a funciones; valida la herramienta por separado y luego intégrala en el flujo principal.

Cada nodo LLM y Agent puede elegir modelo; los nodos sin modelo usan el predeterminado del espacio. Usa modelos pequeños para clasificar, reescribir o extraer y uno potente para la generación final. En los nodos críticos conviene fijar el modelo de forma explícita para evitar que un cambio del predeterminado altere el comportamiento.

6. Uso en equipo: miembros, claves y entornos

Los miembros del espacio de trabajo suelen dividirse en propietario, administrador, editor y miembro normal; los permisos dependen de la versión y del plan. Las credenciales de proveedor pertenecen a todo el espacio de trabajo, no a una persona, así que limita el número de administradores.

  • Usa credenciales o claves distintas en desarrollo y producción para poder limitar y revocar por separado.
  • Genera una clave de API por aplicación; la clave de aplicación solo actúa sobre esa aplicación, pero cubre a todos sus usuarios finales.
  • Distingue a los usuarios finales con el parámetro user y no incrustes la clave de aplicación en el frontend ni en el cliente.
  • La raíz de la API de servicio de Dify Cloud es https://api.dify.ai/v1; en autoalojado, usa tu propio dominio más /v1.
  • La cabecera es Authorization: Bearer <key> y la llamada debe realizarse solo desde el backend.

Cuando varias personas editan, conviene acordar nombres, variables y flujo de publicación; de lo contrario, el flujo se vuelve difícil de mantener. Para aplicaciones externas, define también cómo se publican y revierten las versiones, y no modifiques prompts directamente en producción.

7. Lista de seguridad y operación

  1. Activa HTTPS y no expongas directamente el puerto 80; el proxy inverso se encarga del certificado y del control de acceso.
  2. Después de la instalación, restringe /install, usa contraseñas fuertes y activa la verificación en dos pasos disponible.
  3. Guarda las claves solo en .env o en un gestor de secretos; no las subas al repositorio y rótalas cuando cambie el personal.
  4. Abre en el firewall solo los puertos necesarios; no expongas la base de datos ni la base vectorial a internet.
  5. Configura el proxy SSRF y la salida de red del autoalojado según la documentación actual; lee las notas de .env antes de cambiar la red.
  6. Haz copias periódicas de PostgreSQL, los archivos subidos y .env, y realiza simulacros de restauración.
  7. Copia antes de actualizar, fija la etiqueta del release y sigue las notas de esa versión.
  8. Define presupuesto, concurrencia y alertas en la pasarela para evitar que los bucles agoten la cuota.
  9. Ejecuta en los nodos de código solo código que hayas revisado; no los trates como una frontera de seguridad universal.

La seguridad no es una configuración única: es un proceso que se revisa en cada actualización, cambio de personal y rotación de claves.

8. Errores frecuentes

  • 401: la clave es incorrecta o lleva caracteres de más; vuelve a pegarla y confirma que es la del proveedor correspondiente.
  • 404 o model_not_found: la ruta de la Base URL no es correcta o el nombre del modelo no coincide; revisa /v1 y el identificador del modelo.
  • Tiempo de espera agotado: Dify no alcanza el upstream o este responde despacio; revisa DNS, firewall, proxy y configuración SSRF.
  • No se puede instalar el proveedor: el mercado de plugins no es accesible o la versión es incompatible; revisa la red y la documentación actual.
  • El modelo no aparece en la aplicación: el tipo está mal elegido o el nodo no está vinculado; revisa la lista de modelos del proveedor y la configuración del nodo.
  • Recuperación anómala en la base de conocimiento: la dimensión de Embedding no coincide o el índice no está terminado; cambia de modelo o reconstruye el índice.

Preguntas frecuentes

¿Cuál es la configuración mínima para autoalojar Dify?

La documentación actual indica 2 núcleos de CPU y 4 GiB de memoria; en macOS, la máquina virtual de Docker Desktop debería tener al menos 8 GiB. En la práctica también influyen la concurrencia y el tamaño de la base de conocimiento, así que deja margen en producción.

¿Cómo elegir entre Dify Cloud y el autoalojamiento?

Si quieres validar rápido y no ocuparte de la operación, elige la nube; si necesitas que los datos queden en tu servidor, conectar servicios internos o usar plugins propios, elige el autoalojamiento. Ambos admiten modelos compatibles con OpenAI; la diferencia está en la responsabilidad operativa y en la frontera de red.

El proveedor se añadió bien, pero el modelo no aparece en la aplicación. ¿Qué reviso?

Primero confirma el tipo de modelo, por ejemplo si registraste un Embedding como LLM; después revisa si el modelo está añadido bajo ese proveedor y si la aplicación o el nodo lo tiene vinculado. Algunos nodos solo aceptan modelos con capacidades específicas.

¿Cada nodo del flujo necesita su propio modelo?

Puedes elegirlo por nodo o usar el modelo predeterminado del espacio. En flujos con varios nodos conviene repartir por tarea: modelos pequeños para clasificar y extraer, uno potente para la generación final; fija el modelo en los nodos críticos para evitar cambios cuando se modifique el predeterminado.

¿Se puede compartir una sola API Key en todo el equipo?

Se puede, pero no es recomendable. Una clave compartida no distingue a los llamadores, un incidente afecta a todos y no permite limitar el consumo por separado. Emite claves por aplicación o entorno, distingue a los usuarios finales con el parámetro user y rótalas con regularidad.

Siguiente paso

Conectar Dify puede dividirse en cuatro pasos: poner en marcha la instancia, validar el upstream con curl, rellenar los parámetros del modelo según sus capacidades reales y comprobar la vinculación de nodos con un flujo mínimo. Si necesitas una entrada unificada compatible con OpenAI y gestión de consumo, puedes registrarte en ZSQH AI Gateway; los modelos y la facturación se rigen por la página de precios de modelos.

Lecturas relacionadas: