n8n est une plateforme d'automatisation visuelle qui relie déclencheurs, nœuds de traitement et nœuds de sortie dans un workflow. Elle ne fournit pas de modèle : celui-ci vient du service API que vous configurez. Pour les équipes en Chine, la pratique courante consiste à préparer une passerelle compatible OpenAI, puis à configurer une URL de base personnalisée dans n8n pour intégrer dialogue, résumé, classification et autres étapes dans les processus métier.

Cet article suit l'ordre réel de mise en place : installation, préparation des paramètres, configuration des identifiants, exécution d'un workflow, gestion des erreurs, puis déploiement d'équipe. Les noms d'interface évoluent selon les versions ; la version que vous utilisez fait foi.

Remarque : n8n est une marque de n8n GmbH et OpenAI une marque d'OpenAI, Inc. Cet article est purement technique, sans affiliation ni coopération avec ces sociétés. Le périmètre des modèles et les prix sont indiqués sur la page tarifs des modèles.

1. Cloud ou auto-hébergement

n8n propose un service cloud et un déploiement auto-hébergé. Le cloud évite l'administration serveur et convient aux validations rapides ; l'auto-hébergement contrôle le chemin des données, la sortie réseau et le rythme des mises à jour, adapté aux équipes avec exigences de conformité ou besoin d'accès intranet. Cet article privilégie l'auto-hébergement, car URL de base personnalisée, variables d'environnement et permissions d'équipe y sont plus fréquentes.

L'auto-hébergement a aussi un coût : serveur, base de données, sauvegardes, HTTPS, mises à jour et configuration de sécurité sont à votre charge. Identifiez d'abord qui exploite, puis décidez.

2. Installation et initialisation

La méthode de production recommandée est Docker Compose ; un essai mono-machine peut démarrer avec une commande docker run. L'image est n8nio/n8n, le port par défaut 5678, le volume de données /home/node/.n8n. Ce répertoire contient non seulement la base SQLite mais aussi les clés de chiffrement : il doit être persistant.

docker volume create n8n_data

docker run -it --rm --name n8n \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="Asia/Shanghai" \
  -e TZ="Asia/Shanghai" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -v n8n_data:/home/node/.n8n \
  n8nio/n8n

Après le démarrage, ouvrez http://localhost:5678 et créez le compte propriétaire. En production, n'utilisez pas durablement SQLite sur une seule machine : configurez DB_TYPE=postgresdb et DB_POSTGRESDB_* pour PostgreSQL, et intégrez la base au plan de sauvegarde. L'installation npm (npx n8n ou installation globale) convient aux tests locaux ; la documentation indique que l'installation npm est abandonnée depuis n8n 3.0 et que la production doit utiliser Docker. Les versions de Node.js requises figurent dans la documentation d'installation ; la plage actuellement indiquée va de 20.19 à 24.x.

3. Préparer la clé, l'URL de base et l'identifiant de modèle

Pour intégrer un service compatible OpenAI, trois paramètres suffisent :

Paramètre Valeur à saisir Erreur fréquente
Clé API Créée dans la console de la passerelle, nommée par projet Espace ou saut de ligne au copier-coller
URL de base https://ai.zhongshangqihang.com/v1 Saisir le chemin complet /chat/completions
Identifiant de modèle Identifiant API de la page des tarifs Utiliser le nom affiché ou un ancien suffixe de version

La clé se crée après l'inscription à ZSQH AI Gateway. Prévoyez une clé par environnement, test et production séparés, pour pouvoir révoquer individuellement en cas de fuite. Copiez l'identifiant de modèle depuis la page tarifs des modèles en respectant casse et suffixe de version. Les modèles disponibles et la facturation évoluent ; la console et la page des tarifs font foi.

4. Configurer les identifiants OpenAI

Dans n8n, ouvrez Credentials à gauche et créez un identifiant de type OpenAI. Les champs de la version actuelle incluent API Key, Organization ID (facultatif) et Base URL. Avec une passerelle, remplacez l'URL de base par l'adresse de la passerelle, généralement jusqu'à /v1, sans /chat/completions. Organization ID ne sert que pour l'API OpenAI d'origine avec un compte multi-organisations ; via une passerelle compatible, laissez vide.

Quelques pratiques :

  1. La clé reste dans l'identifiant, jamais dans un nœud Code, un nœud Set ou le JSON du workflow.
  2. Nommez l'identifiant par son usage, par exemple « passerelle-production-resume-contenu », pas « test1 ».
  3. Après enregistrement, lancez le test ; en cas d'échec, vérifiez d'abord l'URL de base et la sortie réseau.
  4. Sur une instance d'équipe, créez un identifiant par projet, sans clé partagée entre plusieurs personnes.
  5. En auto-hébergement, conservez précieusement N8N_ENCRYPTION_KEY : après un changement, les identifiants existants peuvent devenir illisibles.

5. Faire tourner un premier workflow

Exemple : « générer un brouillon de réponse après soumission d'un formulaire ».

  1. Créez un workflow et ajoutez un Form Trigger ou un Manual Trigger.
  2. Ajoutez un nœud OpenAI, avec Resource sur Text.
  3. Choisissez Operation « Generate a Chat Completion » ; dans les anciennes versions, l'opération s'appelle « Message a Model ».
  4. Sélectionnez l'identifiant et le modèle créés, puis passez les champs du formulaire par expression, par exemple {{ $json.message }}.
  5. Dans le prompt, fixez le rôle, le format de sortie et la longueur pour réduire le bruit.
  6. Ajoutez un nœud Set pour ne conserver que les champs utiles ensuite.
  7. Ajoutez un nœud Gmail, Slack ou tableur pour écrire le résultat à destination.
  8. Exécutez manuellement, vérifiez entrée et sortie nœud par nœud, puis activez.

Si la passerelle ne prend pas en charge l'API Responses, ne choisissez pas « Generate a Model Response » : utilisez l'opération correspondant à Chat Completions. Les paramètres pris en charge dépendent de votre version de n8n et de la documentation de la passerelle.

6. Appeler l'interface compatible avec le nœud HTTP Request

Pour les paramètres non exposés, les lots de requêtes ou les champs spéciaux, utilisez un nœud HTTP Request vers /v1/chat/completions. Méthode POST, URL complète, Authentication sur Predefined Credential Type avec l'identifiant OpenAI, ou Generic Credential Type avec Bearer Auth. Body en JSON, avec modèle, messages et paramètres.

Le corps de requête ne doit pas contenir la clé ; l'authentification est injectée par l'identifiant. Analysez la réponse au format Chat Completions d'OpenAI, généralement choices[0].message.content. Si la réponse est en streaming, désactivez le streaming côté n8n ou utilisez un mode capable de traiter les SSE, sinon l'analyse échoue souvent.

7. Tests et gestion des erreurs

Validez d'abord l'adresse, la clé et le modèle avec curl en dehors de n8n, puis revenez au workflow : cela évite bien des détours. Pour un workflow non supervisé, considérez l'échec comme normal :

  1. Activez Retry On Fail dans les paramètres du nœud, avec 2 à 3 tentatives sur 429, 5xx et timeout.
  2. Réglez l'intervalle de retry pour ne pas accentuer la limitation.
  3. Choisissez On Error selon le métier : arrêter, continuer, ou brancher l'erreur vers une branche d'exception.
  4. Fixez un timeout sur les requêtes HTTP ; la génération longue peut être assouplie, mais jamais sans limite.
  5. Configurez un workflow d'erreur qui envoie l'ID d'exécution, le nom du nœud et un résumé d'entrée vers Slack ou e-mail.
  6. Avant de réessayer, vérifiez l'idempotence pour éviter messages ou écritures en double.
Symptôme Cause fréquente Traitement
401 Clé erronée, expirée ou identifiant non sélectionné Resélectionner l'identifiant, vérifier espaces et état
403 Modèle non activé ou permissions insuffisantes Vérifier les droits du modèle et le quota du projet
404 URL de base ou chemin incorrect Saisir seulement /v1, sans chemin complet
429 Concurrence ou quota dépassé Réduire la concurrence, activer le backoff
400 Paramètre non pris en charge par la passerelle Retirer les champs incompatibles, vérifier l'ID de modèle
Timeout Sortie réseau ou réponse amont lente Vérifier proxy, DNS et timeouts

8. Points clés du déploiement d'équipe

Pour une équipe, l'essentiel n'est pas de multiplier les comptes, mais de délimiter identifiants, projets et exploitation :

  • Isolez les lignes métier avec Projects ; workflows et identifiants appartiennent au projet.
  • Émettez une clé par personne et par projet, révocable individuellement en cas de départ ou de fuite.
  • En production, imposez HTTPS et configurez N8N_WEBHOOK_URL vers une adresse accessible de l'extérieur ; l'ancien nom de variable est WEBHOOK_URL.
  • En mode queue, tous les workers doivent partager le même N8N_ENCRYPTION_KEY, sinon les identifiants ne peuvent pas être déchiffrés.
  • En production, utilisez un task runner externe ; n'exécutez pas les nœuds Code dans le processus principal.
  • Sauvegardez la base et la clé de chiffrement séparément, avec des accès contrôlés.
  • Fixez une durée de conservation des données d'exécution pour limiter la croissance de l'historique et l'exposition de données sensibles.

L'auto-hébergement ne suffit pas à assurer la conformité. Vérifiez séparément si le modèle amont conserve les requêtes ou les utilise pour l'entraînement ; pour les flux contenant des données clients, ajoutez anonymisation et validation humaine.

Questions fréquentes

Le nœud OpenAI de n8n accepte-t-il une URL de base personnalisée ?

Oui. L'identifiant OpenAI actuel comporte un champ Base URL, par défaut https://api.openai.com/v1, à remplacer par l'adresse de la passerelle. Si votre version n'a pas ce champ, un nœud HTTP Request avec Bearer Auth permet aussi l'appel.

Jusqu'où faut-il saisir l'URL de base ?

Généralement jusqu'à /v1, par exemple https://ai.zhongshangqihang.com/v1. Ne saisissez pas /v1/chat/completions : le nœud ajoute lui-même le chemin. Un mauvais niveau se manifeste le plus souvent par un 404.

Pourquoi le test d'identifiant passe-t-il alors que l'exécution dit que le modèle n'existe pas ?

Le test d'identifiant valide généralement seulement la clé et l'adresse, pas l'accès à chaque modèle. Vérifiez que l'ID de modèle correspond à la page des tarifs, que le projet a bien accès à ce modèle et que la requête n'est pas routée vers une autre URL de base.

Faut-il obligatoirement PostgreSQL pour n8n auto-hébergé ?

Non. SQLite convient aux tests et aux petits volumes. En production, PostgreSQL est généralement préféré pour les sauvegardes, la concurrence et la montée en charge ; la documentation Docker Compose fait foi. Quel que soit le moteur, le répertoire /home/node/.n8n doit être persistant.

Que surveiller avec plusieurs utilisateurs ?

Séparez les identifiants par projet et par personne, sans clé longue durée partagée ; utilisez les rôles de projet pour contrôler l'accès aux workflows et identifiants ; activez HTTPS, MFA et un task runner externe en production ; sauvegardez la clé de chiffrement avec accès restreint. Pour un point d'entrée et une gestion d'usage unifiés, les clés virtuelles et quotas d'une passerelle sont utiles.

Pour aller plus loin

La difficulté de l'intégration d'une API personnalisée à n8n n'est pas de glisser des nœuds, mais d'aligner trois éléments : URL de base, clé et identifiant de modèle. Validez d'abord avec curl, configurez l'identifiant OpenAI, puis ajoutez retries, branches d'erreur et permissions d'équipe. Pour un point d'entrée unifié, inscrivez-vous à ZSQH AI Gateway ; modèles et prix sont sur la page tarifs des modèles.

Lectures associées :