Dify réunit orchestration de prompts, recherche dans une base de connaissances, workflows et agents dans une même interface visuelle, mais la liste de modèles préconfigurée ne couvre pas forcément les modèles dont vous disposez. Dès lors que le service cible expose une interface compatible OpenAI, il peut être ajouté comme « modèle personnalisé », avec votre clé et votre facturation.

En pratique, les blocages viennent rarement du bouton à cliquer : il manque /v1 dans l'URL de base, le nom du modèle diffère de celui publié sur la passerelle, l'appel de fonctions n'est pas activé, ou le réseau de Dify n'atteint pas votre adresse interne. Cet article suit l'ordre « préparer — ajouter — lier — dépanner » ; les noms d'interface dépendent de la version actuelle.

Remarque : Dify est une marque de son détenteur ; cet article n'a aucun lien d'affiliation avec les fournisseurs cités. Noms de modèles, longueurs de contexte et prix sont ceux de la page Tarifs des modèles ; les versions courantes d'octobre 2026 servent de référence.

1. Vérifier quatre points avant l'intégration

N'ouvrez pas Dify tout de suite : validez d'abord l'amont avec une requête minimale. Il faut confirmer :

  1. Protocole : l'interface est-elle compatible OpenAI, avec au minimum /v1/chat/completions ?
  2. URL de base : la plupart des services attendent une URL jusqu'à /v1, pas le chemin complet /v1/chat/completions.
  3. Nom du modèle : il doit correspondre exactement à ce que renvoie /v1/models de la passerelle, en tenant compte de la casse, des suffixes de date et des alias.
  4. Capacités : streaming, appel de fonctions, entrée visuelle ; pour une base de connaissances, vérifiez aussi la dimension d'embedding.

Précontrôle avec curl :

curl https://votre-adresse-passerelle/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "votre-modele",
    "messages": [{"role": "user", "content": "Réponds seulement OK"}]
  }'

Si la réponse contient choices, l'adresse, la clé et le nom du modèle sont corrects. Valider cette étape avant d'ajouter Dify évite la moitié des détours.

2. Ajouter un fournisseur de modèles dans Dify

Dify gère l'accès aux modèles sous forme de plugins ; l'entrée et les noms de champs varient selon la version. Le parcours typique :

  1. Ouvrez la page de réglages des fournisseurs de modèles.
  2. Trouvez le plugin OpenAI-API-compatible et installez-le ou activez-le ; le nom dépend de la version.
  3. Cliquez sur ajouter un modèle et choisissez le type.
  4. Renseignez le nom du modèle, la clé API et l'URL de base.
  5. Renseignez la longueur de contexte, la sortie maximale et les autres paramètres selon les capacités réelles.
  6. Enregistrez puis testez pour confirmer que le modèle renvoie du contenu.

Points de saisie :

Champ Bonne pratique Erreur fréquente
URL de base Généralement jusqu'à /v1, par exemple https://api.example.com/v1 Ajouter /chat/completions, ce qui provoque un 404
Nom du modèle Identique à la réponse de /v1/models Casse ou suffixe de version erroné, modèle introuvable
Clé API Coller la chaîne complète, sans ajouter Bearer Espace ou guillemet en trop, réponse 401
Type de modèle LLM, Embedding, Rerank, transcription, TTS selon l'usage Mauvais type, modèle invisible dans l'application
Longueur de contexte Valeur réellement prise en charge, plutôt sous-estimée Valeur théorique maximale, requêtes longues refusées
Capacités Streaming, fonctions, vision selon le support réel Échec des outils de l'agent ou du téléversement d'images

3. Ne pas recopier les paramètres des pages marketing

La « longueur de contexte maximale » affichée est souvent une limite théorique ; la valeur utilisable dépend aussi de la longueur de sortie, de la facturation et des limites de la passerelle. Prévoyez une marge :

  • Indiquez la longueur de contexte explicitement prise en charge, sans viser le maximum pour « paraître plus puissant ».
  • Réglez séparément la sortie maximale, pour éviter troncature ou dérive des coûts.
  • En cas de doute sur l'appel de fonctions, désactivez-le, validez en dialogue simple, puis activez les capacités une par une.
  • Pour les modèles visuels, vérifiez si l'image passe par URL ou Base64 ; certaines interfaces compatibles n'acceptent qu'un seul format.
  • Une fois un modèle d'embedding utilisé pour une base de connaissances, sa dimension est fixée ; changer de modèle impose généralement de reconstruire l'index.

Pour plusieurs modèles chez un même fournisseur, ajoutez-les un par un. Le nom exposé peut différer de l'amont, mais il doit rester lisible et traçable, par exemple avec l'usage ou la version dans le nom.

4. Lier le modèle aux applications

Un modèle ajouté n'est pas encore utilisé par l'application. Dans Dify, vérifiez au moins trois endroits :

  • Assistant de chat / application de génération de texte : choisissez le modèle dans la page d'orchestration et vérifiez que le nom n'est pas figé dans une variable du prompt.
  • Workflow / Agent : chaque nœud LLM ou Agent choisit son modèle ; des nœuds différents peuvent en utiliser plusieurs.
  • Base de connaissances : définissez le modèle d'embedding et le modèle de rerank dans les réglages système ; l'indexation et la requête doivent utiliser le même couple.

Une répartition utile : petit modèle pour classifier, reformuler ou extraire, modèle puissant pour la génération finale. Cela maîtrise les coûts et évite de saturer le modèle puissant avec de nombreuses requêtes courtes.

5. Erreurs courantes et ordre de diagnostic

Symptôme Cause possible Traitement
401 Unauthorized Clé erronée, expirée ou caractères en trop Retester avec curl, recoller la clé
404 Not Found Chemin d'URL de base incorrect Vérifier /v1, sans chemin complet
model not found Nom différent de celui publié sur la passerelle Consulter /v1/models, respecter la casse
Délai dépassé Dify n'atteint pas l'amont, ou réponse lente Vérifier réseau, DNS, pare-feu et proxy
400 context length Contexte ou sortie réglés au-delà du réel Baisser les paramètres, segmenter les longs textes
429 Too Many Requests Limitation de débit amont Réduire la concurrence, prévoir backoff
Échec d'appel d'outil Modèle sans appel de fonctions ou format incorrect Désactiver l'outil, valider le dialogue simple
Recherche anormale dans la base Dimensions d'embedding incohérentes Revenir au modèle d'origine ou reconstruire l'index

Un point souvent oublié : si Dify est déployé dans le cloud ou un conteneur, localhost, 127.0.0.1 et les adresses privées sont généralement inaccessibles ; certaines versions activent aussi une protection SSRF qui bloque les requêtes internes. Exposez le service de modèles en HTTPS public, ou configurez proxy et liste blanche conformément à la documentation en auto-hébergement.

6. Stabilité et coûts

Après l'intégration, ajoutez trois éléments :

  1. Délais et tentatives : réglez le timeout sur le chemin métier le plus lent, et ne réessayez que sur 429 et 5xx pour éviter la double facturation.
  2. Journal des appels : conservez au minimum nom du modèle, durée, consommation de tokens et code d'erreur, pour localiser le nœud en cause.
  3. Maîtrise du contexte : plus de fragments récupérés n'est pas toujours mieux ; les passages hors sujet augmentent le coût et perturbent la réponse.

Côté coût, Dify ne fait qu'orchestrer ; la dépense vient des appels aux modèles. Remplacer les nœuds simples par un petit modèle, compresser les prompts et réduire les tentatives inutiles est souvent plus efficace que changer de fournisseur. Les prix exacts sont sur la page Tarifs des modèles ; n'utilisez pas de chiffres figés pour un budget de long terme.

Questions fréquentes

Dify exige-t-il un plugin pour les modèles personnalisés ?

Les versions récentes passent par des plugins de fournisseurs de modèles ; nom et emplacement dépendent de la version. Si le plugin manque, cherchez un plugin compatible OpenAI dans la place de marché ou mettez à niveau vers une version qui prend en charge cette capacité.

Pourquoi curl fonctionne-t-il mais Dify renvoie une erreur ?

Vérifiez trois points en priorité : le réseau de Dify atteint-il l'adresse ; l'URL de base est-elle complétée automatiquement dans l'interface ; la clé contient-elle espace ou retour à la ligne. Un Dify cloud ne peut pas joindre une adresse interne, ce qui est la cause la plus fréquente.

Peut-on connecter directement une interface non compatible OpenAI ?

Pas directement. Il faut d'abord la convertir au format OpenAI via une passerelle ou une couche d'adaptation, puis l'ajouter à Dify. Cette couche doit gérer la structure des messages, les appels d'outils et les événements de streaming, pas seulement réécrire l'URL.

Peut-on ajouter plusieurs modèles chez un même fournisseur ?

Oui. Configurez nom, contexte et capacités pour chacun, puis choisissez dans l'application. Nommez-les selon leur usage pour éviter les erreurs d'équipe.

La base de connaissances reste-t-elle utilisable après un changement de modèle d'embedding ?

En général non, pas en mélange direct. Si la dimension ou l'espace sémantique change, l'ancien index ne correspond plus aux nouvelles requêtes ; il faut reconstruire la base et réindexer. Validez d'abord la recherche sur un petit jeu de données.

Pour aller plus loin

L'intégration Dify tient en trois phrases : valider l'amont avec curl, renseigner les paramètres selon les capacités réelles, puis vérifier la liaison nœud par nœud. Pour une entrée compatible OpenAI et une gestion d'usage unifiées, vous pouvez créer un compte ZSQH AI Gateway ; modèles et prix sont sur la page Tarifs des modèles.

Lectures associées :