Dify réunit l'orchestration des prompts, la base de connaissances, les workflows et les agents dans une même interface visuelle. La plateforme ne produit pas de modèles : ses capacités viennent des fournisseurs que vous connectez. Une pratique courante consiste à héberger Dify soi-même, puis à le raccorder à une passerelle API unifiée via une interface compatible OpenAI, afin de regrouper côté passerelle la gestion des clés, des modèles et de la consommation.

Cet article suit l'ordre du déploiement, de l'ajout d'un fournisseur, de la saisie des paramètres, de la création d'un workflow minimal, de l'usage en équipe et du durcissement de la sécurité. Les noms d'interface, de plugins et de variables dépendent de la version : référez-vous à la documentation officielle actuelle. Les modèles et les prix figurent sur la page Tarifs des modèles et peuvent évoluer.

Remarque : Dify est une marque de son détenteur. Cet article est une présentation technique et n'implique aucune affiliation avec les éditeurs concernés.

1. Cloud ou auto-hébergement

Dify propose un service cloud et une édition communautaire auto-hébergée. Le cloud évite l'exploitation et convient à une validation rapide ; l'auto-hébergement garde les données sur votre propre serveur et convient aux équipes ayant des exigences de réseau, de données et de permissions.

  • Simple essai : le cloud est plus rapide, mais vérifiez l'emplacement des données et l'accessibilité réseau.
  • Modèles internes ou plugins personnalisés : l'auto-hébergement est plus souple, mais vous assumez les mises à jour, les sauvegardes et HTTPS.
  • Usage durable en équipe : dans les deux cas, planifiez les rôles des membres, la gestion des clés et le budget.

2. Déploiement avec Docker Compose

L'édition communautaire se lance de préférence avec Docker Compose. La documentation actuelle indique au minimum 2 cœurs de CPU et 4 GiB de mémoire ; sur macOS, la machine virtuelle de Docker Desktop devrait disposer d'au moins 8 GiB. Sous Linux, il faut Docker 19.03 ou ultérieur et Compose 2.24 ou ultérieur.

  1. Clonez le dépôt sur le dernier tag de release ; git, curl et jq sont nécessaires.
  2. Entrez dans le répertoire dify/docker et copiez .env.example vers .env.
  3. Lancez les services avec docker compose up -d.
  4. Vérifiez l'état avec docker compose ps et attendez que les services soient prêts.
  5. Ouvrez http://adresse-du-serveur/install pour créer l'administrateur, puis connectez-vous depuis la racine.
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

L'accès se fait par défaut sur le port 80 et l'entrée d'initialisation est /install. Le nombre de conteneurs varie selon les versions : ne vous fiez pas au comptage d'anciens tutoriels. Un conteneur init_permissions à l'état Exited est généralement une tâche ponctuelle terminée, ce qui est normal.

La configuration se trouve dans .env et écrase les variables de même nom sous envs/. Après modification, exécutez docker compose down puis up -d. Avant une mise à jour, lisez les notes de la version concernée et comparez les nouvelles variables de .env.example ; ne réutilisez pas tel quel un ancien fichier compose.

3. Ajouter un fournisseur de modèles compatible OpenAI

Seuls le propriétaire et les administrateurs de l'espace de travail peuvent gérer les fournisseurs de modèles. L'entrée se trouve généralement dans Integrations ou dans les paramètres Model Provider : installez d'abord le plugin OpenAI-API-compatible, puis cliquez sur Setup pour saisir les identifiants. Les libellés changent selon les versions ; en cas de doute, suivez la documentation actuelle.

L'ordre typique d'ajout d'un modèle est le suivant :

  1. Installer ou activer le plugin compatible OpenAI.
  2. Renseigner la clé API et la Base URL personnalisée.
  3. Enregistrer et attendre la validation des identifiants.
  4. Ajouter un modèle et choisir son type.
  5. Renseigner le nom du modèle, la longueur de contexte et les capacités.
  6. Vérifier avec l'entrée de test ou une application minimale.
Champ Comment le remplir Erreur fréquente
Base URL Généralement jusqu'à /v1, par exemple https://ai.zhongshangqihang.com/v1 Ajouter /chat/completions, ce qui renvoie une 404
Clé API Coller la chaîne complète, sans ajouter Bearer à la main Espaces, retours à la ligne ou guillemets parasites, ce qui renvoie une 401
Nom du modèle Identique à /v1/models ou à la page Tarifs des modèles Casse ou suffixe de date erroné, ce qui donne model not found
Type de modèle LLM, Embedding, Rerank, voix, etc. selon l'usage Type incorrect : le modèle n'apparaît pas dans l'application
Longueur de contexte Valeur réellement prise en charge, avec une marge Indiquer le maximum théorique : les longues requêtes sont refusées en amont
Capacités Streaming, appels de fonctions, vision selon le support réel Échec des outils de l'agent, rejet des images

Plusieurs modèles peuvent être ajoutés sous un même fournisseur et configurés un par un. Il est conseillé d'inclure l'usage ou la version dans le nom. Une fois un modèle Embedding utilisé pour la base de connaissances, sa dimension est fixée : changer de modèle impose généralement de reconstruire l'index.

4. Vérifier d'abord avec curl, puis tester dans Dify

Tester directement après la saisie rend le diagnostic difficile en cas d'échec : passerelle, réseau ou champ mal rempli ? Validez d'abord l'amont avec curl :

export ZSQH_API_KEY="sk-votre-cle"

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

Une réponse contenant choices confirme que la clé, l'adresse et le nom du modèle sont valides. Une 401 indique la clé, une 404 le chemin, et model not found le nom du modèle. La Base URL s'arrête à /v1 et ne doit pas contenir le chemin complet de l'interface ; n'ajoutez pas Bearer à la clé, Dify le fait lui-même.

Dify valide les identifiants à l'enregistrement du fournisseur, mais cette validation ne suffit pas à confirmer que chaque modèle fonctionne : vérifiez aussi le type, la longueur de contexte et les capacités. Sans bouton de test, créez une application de chat minimale ou appelez l'API de l'application.

5. Construire un workflow minimal

Faites d'abord fonctionner le chemin le plus court, puis ajoutez des nœuds progressivement. Exemple avec un workflow :

  1. Dans Studio, créez un Workflow ou un Chatflow : Chatflow pour le dialogue, Workflow pour le traitement par lots ou l'automatisation.
  2. Définissez une variable d'entrée dans le nœud de départ, par exemple query.
  3. Ajoutez un nœud LLM, sélectionnez le fournisseur et le modèle qui viennent d'être connectés, puis référencez la variable de départ dans le prompt.
  4. Ajoutez un nœud de fin et reliez la sortie du LLM à la variable de sortie.
  5. Lancez un test avec une vraie question et inspectez entrée, sortie et consommation de tokens nœud par nœud.
  6. Après validation, publiez, puis appelez l'application via la page embarquée ou l'API.

Pour la recherche documentaire, ajoutez un nœud de récupération de connaissances avant le LLM et configurez d'abord les modèles Embedding et Rerank dans les paramètres de l'espace de travail. Pour les branchements, ajoutez une classification de question ou une condition. Le nœud Agent convient aux scénarios avec outils, mais il faut choisir un modèle compatible avec les appels de fonctions, valider séparément ces appels, puis l'intégrer au flux principal.

Chaque nœud LLM et Agent peut choisir son propre modèle ; les nœuds non spécifiés retombent sur le modèle par défaut de l'espace de travail. Utilisez un petit modèle pour la classification et la réécriture, un modèle plus puissant pour la génération finale. Liez explicitement les nœuds critiques afin d'éviter une dérive si le modèle par défaut change.

6. Usage en équipe : membres, clés et environnements

Les membres d'un espace de travail sont généralement répartis entre propriétaire, administrateur, éditeur et membre standard ; les permissions dépendent de la version et de l'offre. Les identifiants fournisseur appartiennent à tout l'espace de travail, pas à une personne : limitez le nombre d'administrateurs.

  • Utilisez des identifiants ou des clés distincts en développement et en production, pour faciliter les quotas et la révocation.
  • Générez une clé API par application ; elle ne vaut que pour cette application, mais couvre tous ses utilisateurs finaux.
  • Les appelants distinguent les utilisateurs finaux avec le paramètre user ; ne placez jamais la clé d'application dans un front-end ou un client.
  • La racine de l'API de service de Dify Cloud est https://api.dify.ai/v1 ; en auto-hébergement, utilisez votre domaine suivi de /v1.
  • L'en-tête est Authorization: Bearer <cle> et l'appel doit rester côté serveur.

En édition à plusieurs, convenez au préalable des noms, des variables et du processus de publication, sinon les workflows deviennent vite difficiles à maintenir. Pour les applications exposées, définissez aussi la publication et le retour arrière des versions ; ne modifiez pas les prompts directement en production.

7. Liste de contrôle sécurité et exploitation

  1. Activez HTTPS et n'exposez pas directement le port 80 ; le reverse proxy gère aussi les certificats et le contrôle d'accès.
  2. Après l'initialisation, restreignez /install, utilisez un mot de passe fort et activez la double authentification disponible.
  3. Gardez les clés uniquement dans .env ou un service de gestion de secrets, jamais dans le dépôt ; changez-les lors des départs.
  4. N'ouvrez que les ports nécessaires au pare-feu ; n'exposez pas la base de données ni la base vectorielle sur Internet.
  5. Configurez le proxy SSRF et la sortie réseau de l'auto-hébergement selon la documentation ; lisez les commentaires de .env avant de modifier le réseau.
  6. Sauvegardez régulièrement PostgreSQL, les fichiers téléversés et .env, et testez la restauration.
  7. Sauvegardez avant chaque mise à jour, fixez le tag de release et suivez les notes de la version correspondante.
  8. Définissez côté passerelle des budgets, des limites de concurrence et des alertes pour éviter les boucles coûteuses.
  9. N'exécutez dans les nœuds de code que du code que vous avez relu ; ne les considérez pas comme une frontière de sécurité.

La sécurité n'est pas une configuration unique : c'est un processus à revoir lors des mises à jour, des changements d'équipe et des rotations de clés.

8. Erreurs courantes

  • 401 Unauthorized : clé erronée ou caractères parasites ; recollez-la et vérifiez qu'elle appartient bien à ce fournisseur.
  • 404 ou model_not_found : chemin de Base URL incorrect ou nom de modèle différent ; vérifiez /v1 et l'identifiant du modèle.
  • Délai d'attente : Dify n'atteint pas l'amont ou celui-ci répond lentement ; contrôlez DNS, pare-feu, proxy et configuration SSRF.
  • Fournisseur impossible à installer : place de marché inaccessible ou version incompatible ; vérifiez le réseau et la documentation.
  • Modèle absent dans l'application : type incorrect ou nœud non lié ; vérifiez la liste du fournisseur et la configuration du nœud.
  • Recherche dans la base de connaissances anormale : dimensions d'Embedding incohérentes ou index incomplet ; changez de modèle ou reconstruisez l'index.

FAQ

Quelle est la configuration minimale pour auto-héberger Dify ?

La documentation actuelle indique 2 cœurs de CPU et 4 GiB de mémoire ; sur macOS, la machine virtuelle de Docker Desktop devrait avoir au moins 8 GiB. La charge réelle dépend aussi de la concurrence et de la taille de la base de connaissances : gardez une marge en production.

Dify Cloud ou auto-hébergement : que choisir ?

Pour valider rapidement sans exploitation, choisissez le cloud ; pour garder les données sur votre serveur, connecter des services internes ou des plugins personnalisés, choisissez l'auto-hébergement. Les deux acceptent des modèles compatibles OpenAI ; la différence porte sur la responsabilité d'exploitation et la frontière réseau.

Le fournisseur est ajouté, mais le modèle n'apparaît pas dans l'application.

Vérifiez d'abord le type du modèle, par exemple un Embedding déclaré comme LLM, puis si le modèle a bien été ajouté à ce fournisseur et si l'application ou le nœud le référence. Certains nœuds n'acceptent que des modèles dotés de capacités précises.

Faut-il choisir un modèle pour chaque nœud d'un workflow ?

Les deux sont possibles : modèle propre au nœud ou modèle par défaut de l'espace de travail. Pour un flux à plusieurs nœuds, répartissez les tâches : petit modèle pour classifier et extraire, modèle plus puissant pour la génération finale ; liez explicitement les nœuds critiques pour éviter les dérives.

Une clé API partagée par toute l'équipe, est-ce acceptable ?

C'est possible mais déconseillé. Une clé partagée ne permet pas d'identifier les appelants, amplifie l'impact d'une fuite et complique les quotas. Émettez une clé par application ou par environnement, distinguez les utilisateurs finaux avec user et faites tourner les clés régulièrement.

Pour aller plus loin

L'intégration de Dify se résume en quatre étapes : démarrer une instance, valider l'amont avec curl, renseigner les paramètres des modèles selon leurs capacités réelles, puis vérifier les liaisons de nœuds avec un workflow minimal. Pour une entrée compatible OpenAI unifiée et une gestion de la consommation, vous pouvez créer un compte sur la passerelle AI de ZSQH ; les modèles et la facturation sont détaillés sur la page Tarifs des modèles.

Lectures associées :