Dify : Architecture, Workflows Agentiques et Production LLM

Construire des architectures agentiques et des pipelines RAG exige un espace de travail unifié. Dify rassemble la gestion des modèles, l’ingénierie des invites, les flux visuels, l’observabilité et le déploiement. Le projet est accessible sur le dépôt Dify sur GitHub. Je guide ici chaque étape, de la découverte initiale jusqu’aux configurations avancées de production.

Architecture et fonctionnalités maîtresses

Dify répond à la fragmentation des outils d’intelligence artificielle. La plateforme convertit un prototype expérimental en application prête pour l’échelle industrielle sans réécrire la pile logicielle.

• Workflow visuel : Conception et test de flux d’intelligence artificielle complexes sur un canevas graphique interactif.
• Support étendu de modèles : Intégration de centaines de LLM propriétaires et open source (GPT, Mistral, Llama 3) via des dizaines de fournisseurs d’inférence ou d’instances auto-hébergées compatibles avec l’API OpenAI.
• Prompt IDE : Espace d’élaboration de consignes, comparaison de performances entre modèles et ajout de modules complémentaires comme la synthèse vocale (Text-to-Speech).
• Pipeline RAG : Traitement complet du document, de l’ingestion à l’extraction vectorielle, avec prise en charge native des formats PDF, PPT et fichiers textuels courants.
• Capacités agentiques : Définition d’agents autonomes basés sur le Function Calling ou le paradigme ReAct, assistés par plus de 50 outils intégrés (Google Search, DALL-E, Stable Diffusion, WolframAlpha) ou des outils personnalisés.
• LLMOps et Observabilité : Suivi des journaux d’exécution, intégration d’outils tiers (Opik, Langfuse, Arize Phoenix) et annotation continue pour affiner prompts et jeux de données.
• Backend-as-a-Service (BaaS) : Exposition d’interfaces de programmation applicative (API) pour chaque ressource créée, facilitant l’intégration directe dans vos systèmes métiers.

Modes de déploiement et écosystème d’infrastructure

Dify propose trois voies d’accès :

Dify Cloud : Version hébergée sans installation préalable, comprenant 200 crédits d’appels GPT-4 pour le bac à sable.
Édition Communautaire auto-hébergée : Maîtrise totale sur votre propre infrastructure.
Édition Entreprise : Fonctionnalités avancées dédiées aux organisations avec support ciblé.

Pour le déploiement d’infrastructure automatisé, la communauté maintient des modèles pour divers environnements :

• Kubernetes : Déploiements via Helm Charts et manifestes YAML pour architectures haute disponibilité.
• Terraform : Déploiement en un clic sur Azure Global et Google Cloud Platform.
• AWS CDK : Déploiements pilotés par le code sur clusters Amazon EKS ou conteneurs Amazon ECS.
• Alibaba Cloud : Automatisation via Alibaba Cloud Computing Nest et Alibaba Cloud Data Management.
• Azure DevOps : Déploiements automatisés vers AKS par pipelines dédiés.
• Supervision Grafana : Tableaux de bord connectés à la base PostgreSQL de Dify pour scruter locataires, applications et messages.

Démarrage rapide avec Docker Compose

Les prérequis matériels minimaux exigent 2 cœurs CPU et 4 Gio de mémoire vive. Docker ainsi que Docker Compose (version 2.24.0 ou supérieure) doivent être opérationnels sur votre machine hôte.

cd dify
cd docker
cp .env.example .env
docker compose up -d

Une fois les conteneurs initialisés, le tableau de bord de configuration devient accessible sur votre navigateur à l’adresse http://localhost/install.

Installation locale depuis le code source

Le développement local réclame une séparation claire entre intergiciels, services backend et interface utilisateur.

Système d’exploitation	Logiciel requis	Instructions spécifiques
macOS 10.14+	Docker Desktop	Allouez 2 vCPU et 8 Go de RAM minimum à la machine virtuelle Docker.
Linux	Docker 19.03+ / Compose 1.25.1+	Suivez les guides officiels du moteur Docker.
Windows avec WSL 2	Docker Desktop	Stockez impérativement le code source sur le système de fichiers Linux WSL.

Installez FFmpeg sur votre machine hôte si vous prévoyez d’utiliser le module OpenAI TTS. Téléchargez Node.js version 22 LTS sur le portail de téléchargement Node.js ainsi que l’outil PNPM version 10.

1. Cloner le dépôt et lancer les intergiciels

git clone https://github.com/langgenius/dify.git
cd dify/docker
cp envs/middleware.env.example middleware.env
docker compose --env-file middleware.env -f docker-compose.middleware.yaml -p dify up -d

2. Configurer et lancer l’API Backend

Le gestionnaire de paquets uv orchestre les dépendances Python du backend. Sur macOS, installez la bibliothèque requise avec la commande brew install libmagic.

cd ../api
cp .env.example .env
awk -v key="$(openssl rand -base64 42)" '/^SECRET_KEY=/ {sub(/=.*/, "=" key)} 1' .env > temp_env && mv temp_env .env
uv sync --dev
uv run flask db upgrade
uv run flask run --host 0.0.0.0 --port=5001 --debug

3. Démarrer les Workers asynchrones et Beat

Le traitement des jeux de données et le nettoyage des fichiers reposent sur Celery. Lancez le processus selon votre environnement :

# Sur macOS ou Linux
uv run celery -A app.celery worker -P gevent -c 1 --loglevel INFO -Q dataset,dataset_summary,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_executor,retention,workflow_based_app_execution

# Sur Windows
uv run celery -A app.celery worker -P solo --without-gossip --without-mingle --loglevel INFO -Q dataset,dataset_summary,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_executor,retention,workflow_based_app_execution

Pour planifier les tâches de fond périodiques et les déclencheurs programmés, démarrez le planificateur Beat dans un terminal dédié :

uv run celery -A app.celery beat

4. Configurer et démarrer le frontend Web

cd ../web
npm i -g pnpm
pnpm install --frozen-lockfile
cp .env.example .env.local

Configurez le fichier .env.local avec les paramètres de développement :

NEXT_PUBLIC_DEPLOY_ENV=DEVELOPMENT
NEXT_PUBLIC_EDITION=SELF_HOSTED
NEXT_PUBLIC_API_PREFIX=http://localhost:5001/console/api
NEXT_PUBLIC_PUBLIC_API_PREFIX=http://localhost:5001/api
NEXT_PUBLIC_COOKIE_DOMAIN=
NEXT_PUBLIC_SENTRY_DSN=
NEXT_PUBLIC_SENTRY_ORG=
NEXT_PUBLIC_SENTRY_PROJECT=

Générez les artefacts de production puis lancez le serveur frontend :

pnpm build
pnpm start

L’interface graphique est désormais accessible sur votre navigateur local http://localhost:3000.

Guide exhaustif des variables d’environnement

Le fichier docker/.env regroupe les paramètres fondamentaux. Les modèles spécialisés logent dans docker/envs/. Pour surcharger un paramètre, copiez le fichier cible sans son suffixe .example (ex: cp envs/vectorstores/milvus.env.example envs/vectorstores/milvus.env). Le fichier racine docker/.env prévaut sur tous les sous-fichiers.

Réseau et URLs de routage

• CONSOLE_API_URL (défaut : vide) : URL publique de l’API backend. Indispensable pour les redirections OAuth et Notion.
• SERVER_CONSOLE_API_URL (défaut : http://api:5001) : Adresse interne utilisée par le frontend Next.js pour interroger le backend via le réseau Docker.
• CONSOLE_WEB_URL (défaut : vide) : URL publique de la console. Utilisée pour forger les liens dans les courriels système.
• SERVICE_API_URL (défaut : vide) : URL de base montrée aux développeurs pour consommer l’API publique.
• APP_API_URL (défaut : vide) : Point d’accès API utilisé par le conteneur web pour les applications publiées.
• APP_WEB_URL (défaut : vide) : URL publique d’accès aux applications web publiées. Requis pour le nœud Human Input.
• TRIGGER_URL (défaut : http://localhost) : Adresse publique des points d’entrée de webhooks et déclencheurs externes.
• FILES_URL (défaut : repli sur CONSOLE_API_URL) : URL de base pour la distribution des fichiers signés et temporaires.
• INTERNAL_FILES_URL (défaut : repli sur FILES_URL) : Point d’accès direct aux fichiers pour les conteneurs internes.
• FILES_ACCESS_TIMEOUT (défaut : 300) : Durée de validité en secondes des URLs de fichiers signées.
• ENABLE_COLLABORATION_MODE (défaut : true) : Active l’édition collaborative en temps réel sur le canevas.

Configuration du serveur, journalisation et limites

• LOG_LEVEL (défaut : INFO) : Sévérité minimale (DEBUG, INFO, WARNING, ERROR, CRITICAL).
• LOG_OUTPUT_FORMAT (défaut : text) : Format des sorties (text ou json).
• LOG_FILE (défaut : /app/logs/server.log) : Emplacement du fichier journal.
• LOG_FILE_MAX_SIZE (défaut : 20) : Taille maximale en Mo avant rotation du fichier.
• LOG_FILE_BACKUP_COUNT (défaut : 5) : Quantité de fichiers d’archive conservés.
• LOG_DATEFORMAT (défaut : %Y-%m-%d %H:%M:%S) : Format d’horodatage textuel.
• LOG_TZ (défaut : UTC) : Fuseau horaire pour les journaux et tâches planifiées.
• DEBUG (défaut : false) : Journalisation verbeuse des nœuds, outils et invites LLM.
• ENABLE_REQUEST_LOGGING (défaut : false) : Trace chaque requête HTTP.
• DEPLOY_ENV (défaut : PRODUCTION) : Étiquette d’environnement transmise aux traceurs.
• EDITION (défaut : SELF_HOSTED) : Identité du déploiement. Ne pas modifier en CLOUD.
• MIGRATION_ENABLED (défaut : true) : Exécute les migrations de base de données au démarrage.
• CHECK_UPDATE_URL (défaut : https://updates.dify.ai) : Vérification de nouvelles versions.
• SECRET_KEY : Clé cryptographique centrale pour cookies, jetons JWT et chiffrement AES-256.
• INIT_PASSWORD (défaut : vide) : Mot de passe de verrouillage pour l’écran /install.
• ACCESS_TOKEN_EXPIRE_MINUTES (défaut : 60) : Durée de validité du jeton de session.
• REFRESH_TOKEN_EXPIRE_DAYS (défaut : 30) : Durée de persistance de la connexion.
• APP_MAX_EXECUTION_TIME (défaut : 1200) : Temps limite d’exécution d’une application en secondes.
• APP_DEFAULT_ACTIVE_REQUESTS (défaut : 0) : Limite de requêtes concurrentes par application (0 = illimité).
• APP_MAX_ACTIVE_REQUESTS (défaut : 0) : Plafond global de requêtes concurrentes par application.
• MODE (défaut : worker) : Détermine le rôle du conteneur dify-api (api, worker, beat, job, migration).

Paramétrage d’exécution des conteneurs Gunicorn et Celery

• DIFY_BIND_ADDRESS (défaut : 0.0.0.0) : Interface réseau d’écoute de l’API.
• DIFY_PORT (défaut : 5001) : Port d’écoute de l’API.
• SERVER_WORKER_AMOUNT (défaut : 1) : Nombre de processus workers Gunicorn.
• SERVER_WORKER_CLASS (défaut : gevent) : Type de worker Gunicorn.
• SERVER_WORKER_CONNECTIONS (défaut : 10) : Connexions simultanées par worker gevent.
• GUNICORN_TIMEOUT (défaut : 360) : Délai d’inactivité avant redémarrage du worker (adapté au streaming SSE).
• API_WEBSOCKET_WORKER_AMOUNT (défaut : 1) : Workers alloués aux WebSockets.
• API_WEBSOCKET_WORKER_CLASS (défaut : geventwebsocket.gunicorn.workers.GeventWebSocketWorker) : Classe WebSocket.
• API_WEBSOCKET_WORKER_CONNECTIONS (défaut : 1000) : Connexions WebSocket maximales par worker.
• API_WEBSOCKET_GUNICORN_TIMEOUT (défaut : 360) : Timeout Gunicorn WebSocket.
• CELERY_WORKER_CLASS (défaut : gevent) : Type de worker pour la file Celery.
• CELERY_WORKER_AMOUNT (défaut : 4) : Processus workers Celery statiques.
• CELERY_AUTO_SCALE (défaut : false) : Activation du dimensionnement automatique Celery.
• CELERY_MAX_WORKERS / CELERY_MIN_WORKERS : Bornes d’autoscaling Celery.
• COMPOSE_WORKER_HEALTHCHECK_DISABLED (défaut : true) : Désactive le test de santé de Compose pour Celery.

Bases de données relationnelles et pools

• DB_TYPE (défaut : postgresql) : Type de base (postgresql, mysql, oceanbase, seekdb).
• DB_USERNAME / DB_PASSWORD / DB_HOST / DB_PORT / DB_DATABASE : Paramètres de connexion.
• SQLALCHEMY_POOL_SIZE (défaut : 30) : Connexions persistantes dans le pool.
• SQLALCHEMY_MAX_OVERFLOW (défaut : 10) : Connexions temporaires excédentaires autorisées.
• SQLALCHEMY_POOL_RECYCLE (défaut : 3600) : Recyclage des connexions en secondes.
• SQLALCHEMY_POOL_TIMEOUT (défaut : 30) : Délai d’attente d’une connexion disponible.
• SQLALCHEMY_POOL_PRE_PING (défaut : false) : Test de validité de connexion avant exécution de requête.
• POSTGRES_MAX_CONNECTIONS (défaut : 200) : Plafond de connexions côté serveur PostgreSQL.
• POSTGRES_SHARED_BUFFERS (défaut : 128MB) : Mémoire partagée PostgreSQL.

Cache et courtier Redis

• REDIS_HOST / REDIS_PORT / REDIS_USERNAME / REDIS_PASSWORD / REDIS_DB : Connexion autonome (standalone).
• REDIS_KEY_PREFIX (défaut : vide) : Préfixe appliqué aux clés, canaux et files d’attente.
• REDIS_USE_SSL (défaut : false) : Chiffrement SSL/TLS des échanges.
• REDIS_USE_SENTINEL (défaut : false) : Mode haute disponibilité Sentinel avec REDIS_SENTINELS et REDIS_SENTINEL_SERVICE_NAME.
• REDIS_USE_CLUSTERS (défaut : false) : Mode partitionné avec REDIS_CLUSTERS et REDIS_CLUSTERS_PASSWORD.
• CELERY_BROKER_URL (défaut : redis://:difyai123456@redis:6379/1) : File d’attente de messages.
• CELERY_BACKEND (défaut : redis) : Stockage des résultats de tâches (redis ou database).

Stockage de fichiers et archives

• STORAGE_TYPE (défaut : opendal) : Moteur de stockage (opendal, s3, azure-blob, aliyun-oss, google-storage, huawei-obs, volcengine-tos, tencent-cos, baidu-obs, oci-storage, supabase, clickzetta-volume, local).
• ARCHIVE_STORAGE_ENABLED (défaut : false) : Stockage S3 d’archivage des journaux d’exécutions de flux.
• ARCHIVE_STORAGE_ENDPOINT / ARCHIVE_STORAGE_ARCHIVE_BUCKET / ARCHIVE_STORAGE_EXPORT_BUCKET : Paramètres de compartiments d’archivage.

Bases de données vectorielles et extraction de documents (RAG)

• VECTOR_STORE (défaut : weaviate) : Moteur vectoriel (weaviate, qdrant, milvus, myscale, pgvector, pgvecto-rs, chroma, opensearch, elasticsearch, tidb, upstash, etc.).
• VECTOR_INDEX_NAME_PREFIX (défaut : Vector_index) : Préfixe des index vectoriels.
• UPLOAD_FILE_SIZE_LIMIT (défaut : 15) : Limite en Mo des documents importés.
• UPLOAD_FILE_BATCH_LIMIT (défaut : 5) : Quantité de fichiers par lot.
• UPLOAD_FILE_EXTENSION_BLACKLIST (défaut : vide) : Extensions de fichiers interdites séparées par des virgules.
• ETL_TYPE (défaut : dify) : Bibliothèque d’extraction textuelle (dify ou Unstructured via UNSTRUCTURED_API_URL).
• INDEXING_MAX_SEGMENTATION_TOKENS_LENGTH (défaut : 4000) : Taille maximale en jetons par segment découpé.

Sécurité, Sandbox de code et proxy SSRF

• CODE_EXECUTION_ENDPOINT (défaut : http://sandbox:8194) : Service isolé d’exécution de code Python et JavaScript.
• CODE_EXECUTION_API_KEY (défaut : dify-sandbox) : Jeton d’authentification du bac à sable.
• CODE_MAX_STRING_LENGTH (défaut : 400000) : Taille maximale des chaînes produites par un nœud de code.
• SSRF_PROXY_HTTP_URL / SSRF_PROXY_HTTPS_URL (défaut : http://ssrf_proxy:3128) : Proxy protégeant le réseau local contre les attaques par falsification de requête côté serveur.
• RESPECT_XFORWARD_HEADERS_ENABLED (défaut : false) : Prise en compte des en-têtes de proxy amont.

Interface programmatique, CLI et Agent V2 (Bêta)

• OPENAPI_ENABLED (défaut : false) : Active la surface d’API /openapi/v1/* requise par le client CLI difyctl.
• ENABLE_OAUTH_BEARER (défaut : false) : Authentification Bearer OAuth pour le CLI.
• OPENAPI_KNOWN_CLIENT_IDS (défaut : difyctl) : Identifiants autorisés pour le flux d’authentification machine.
• DIFY_AGENT_SERVER_SECRET_KEY : Clé secrète racine en base64url de 32 octets générée via python3 -c "import secrets; print(secrets.token_urlsafe(32))" pour sécuriser l’Agent V2.
• DIFY_AGENT_API_TOKEN : Jeton porteur entre l’API Dify et le backend agentique.
• NEXT_PUBLIC_ENABLE_AGENT_V2 (défaut : true) : Affichage des fonctionnalités Agent V2 sur l’interface.

Gestion des comptes et intégrations tierces

• ENABLE_EMAIL_PASSWORD_LOGIN (défaut : true) : Connexion classique par mot de passe.
• ENABLE_EMAIL_CODE_LOGIN (défaut : false) : Connexion par code à usage unique expédié par courriel.
• ENABLE_SOCIAL_OAUTH_LOGIN (défaut : false) : Connexion par compte GitHub ou Google.
• ALLOW_REGISTER (défaut : false) : Autorise l’auto-inscription publique.
• ALLOW_CREATE_WORKSPACE (défaut : false) : Crée automatiquement un espace de travail pour chaque nouvel inscrit.
• MAIL_TYPE (défaut : resend) : Fournisseur d’expédition de courriels (resend, smtp, sendgrid).
• NOTION_INTEGRATION_TYPE (défaut : public) : Intégration Notion (public ou direct internal via Notion Integrations).

Guide de dépannage et résolution des incidents

Voici les manœuvres de maintenance opérationnelle pour résoudre les anomalies récurrentes :

1. Réinitialisation du mot de passe administrateur

Sur un déploiement Docker Compose :

docker exec -it docker-api-1 flask reset-password

Saisissez l’adresse électronique du compte et définissez le nouveau mot de passe lors de l’invite interactive.

2. Erreurs 401 après un changement de domaine

Ce problème découle de règles CORS obsolètes. Ajustez les variables suivantes dans votre fichier d’environnement puis redémarrez les conteneurs :

CONSOLE_CORS_ALLOW_ORIGINS=https://console.mondomaine.com
WEB_API_CORS_ALLOW_ORIGINS=https://app.mondomaine.com
CONSOLE_API_URL=https://api.mondomaine.com
CONSOLE_WEB_URL=https://console.mondomaine.com
SERVICE_API_URL=https://api.mondomaine.com
APP_API_URL=https://api-app.mondomaine.com
APP_WEB_URL=https://app.mondomaine.com

3. Ajustement de la taille des fichiers téléversés

Augmentez simultanément la limite de l’application et la directive du serveur mandataire Nginx dans .env sous peine de subir une erreur HTTP 413 :

UPLOAD_FILE_SIZE_LIMIT=50
NGINX_CLIENT_MAX_BODY_SIZE=50M

4. Erreur de connexion PostgreSQL (pg_hba.conf)

Si le journal affiche FATAL: no pg_hba.conf entry for host "172.19.0.7", autorisez le sous-réseau Docker :

docker exec -it docker-db-1 sh -c "echo 'host all all 172.19.0.0/16 trust' >> /var/lib/postgresql/data/pgdata/pg_hba.conf"
docker compose restart

5. Perte des clés de chiffrement RSA

Si une exception FileNotFoundError survient dans libs/rsa.py suite à la suppression de api/storage/privkeys, régénérez la paire de clés :

docker exec -it docker-api-1 flask reset-encrypt-key-pair

Attention : Cette opération est irréversible. Toutes les clés API de modèles et d’outils enregistrées dans chaque espace de travail sont purgées et requièrent une nouvelle saisie manuelle.

Limites, contraintes et facteurs de risque

Le déploiement d’architectures agentiques impose une vigilance stricte sur plusieurs aspects structurels :

• Remplacement de SECRET_KEY : Toute modification de cette clé en cours de vie déconnecte l’ensemble des utilisateurs, invalide les URLs de fichiers signées et corrompt définitivement les identifiants OAuth tiers chiffrés.
• Exposition de l’Agent V2 : Conserver les valeurs de jetons et clés secrètes fournies par défaut dans .env.example permet à des tiers de forger des jetons d’accès internes et d’exécuter du code arbitraire au sein du bac à sable.
• Profondeur d’arborescence : La constante MAX_TREE_DEPTH limite par défaut à 50 le nombre de nœuds sur une branche d’exécution unique afin de préserver les performances du moteur de graphe.
• Consommation mémoire des Workers : Le découpage de documents massifs via Celery requiert un calibrage méticuleux des processus gevent sous peine de saturer la mémoire disponible de la machine hôte.