FastGPT avec Docker : éviter 3 erreurs d’installation
Installez FastGPT avec Docker sans bloquer sur MinIO, l’import CSV ou les embeddings. Vérifiez aussi la mémoire, les sauvegardes et l’exposition réseau.
Installer FastGPT avec Docker : les pièges à vérifier avant de commencer
Suivre l'installation de FastGPT « à la lettre » ne suffit pas toujours. Il suffit d'une image MinIO introuvable, d'un CSV d'import refusé ou d'un modèle d'embedding manquant pour bloquer le déploiement avant même la première base de connaissances. Et quand ça coince, ce n'est pas forcément la faute d'une mauvaise configuration globale : il y a souvent quelques détails précis, faciles à rater.
Lors d'un essai de FastGPT v4.15 sur un serveur Linux récent, trois points ont demandé une correction rapide : la source de l'image MinIO, le format des fichiers d'import FAQ et la configuration des modèles d'embedding. Deux autres sujets méritent d'être anticipés avant toute mise en ligne : l'exposition des ports Docker et la mémoire disponible.
L'idée ci-dessous est simple : comprendre ces blocages, les corriger sans bricoler dans tous les sens, puis garder un déploiement stable. Les vérifications mentionnées sont calées sur une version donnée : vérifiez toujours vos fichiers Compose et les instructions pour la version que vous déployez.
Vérifier les prérequis avant le déploiement
FastGPT est un chatbot relié à une base de connaissances. Donc, même si Docker démarre « tout », ça ne veut pas dire que le parcours complet est prêt. En pratique, il faut regarder au moins trois couches : les conteneurs (et leurs dépendances), la configuration des modèles, puis les données que vous importez.
Ça aide à diagnostiquer vite. Si un conteneur ne démarre pas, le problème est généralement dans Docker Compose (image, paramètre système, etc.). Si vous voyez un message du type « aucun modèle d'embedding disponible », vous êtes plutôt côté configuration des modèles. Et si l'import est refusé, c'est presque toujours un souci de format de données. Chercher la cause au mauvais niveau fait perdre du temps - et peut vous pousser à modifier des choses inutiles.
Commencer par la version et les ressources
Notez la version exacte de FastGPT et les versions des images référencées dans votre fichier Compose. Évitez les balises « flottantes » et les changements que vous ne pouvez pas retrouver ensuite : si vous devez reproduire, comparer deux environnements ou revenir en arrière, vous serez content d'avoir ces détails sous la main.
Côté serveur, prévoyez aussi une marge mémoire. Sur l'essai mentionné ici, la consommation au repos était d'environ 2,1 Go. Ce chiffre n'est pas universel : la charge, les services activés, les données et les versions peuvent changer la donne. Mais si votre VPS est annoncé à 2 Go de RAM, vous risquez d'être à l'étroit dès le démarrage ou lors d'une opération plus lourde.
Pour un premier déploiement, 4 Go de RAM est un point de départ plus raisonnable que 2 Go, sans garantir que ce sera « suffisant pour la production ». Mesurez l'usage réel après démarrage et pendant les opérations qui sollicitent le système. En production, n'oubliez pas d'ajouter la mémoire du système, du reverse proxy, de la base de données et des autres services déjà présents sur la machine.
Identifier ce que vous cherchez à faire
Avant de lancer l'installation, préparez une mini check-list :
- Quelle version de FastGPT déployez-vous ?
- Quelles images Docker sont référencées et depuis quels registres ?
- Quel service fournit les réponses du chatbot ?
- Quel service ou fournisseur fournit les embeddings ?
- Quel est le format exact des données à importer ?
- Quels ports doivent être accessibles depuis Internet ?
- Où seront stockées les données à sauvegarder ?
Ça peut sembler « administratif » pour un simple test, mais ça devient utile quand vous devez refaire l'installation, l'expliquer à quelqu'un, ou diagnostiquer un échec à distance. Et pour une équipe en France/Europe, ça aide aussi à cadrer tôt les sujets de résidence et de traitement des données avant de brancher des documents internes à un service d'IA.
Corriger les trois blocages fréquents
Ces trois problèmes sont indépendants. Traitez-les un par un : vous verrez vite quelle correction règle quel blocage, et votre configuration restera lisible.
1. L'image MinIO ne se télécharge plus depuis Docker Hub
Le message pull access denied for minio/minio indique que Docker n'arrive pas à récupérer l'image depuis le registre attendu.
Dans le cas de l'installation testée (FastGPT v4.15), l'image MinIO référencée n'était plus récupérable depuis Docker Hub. Relancer la commande plusieurs fois ne change rien : si l'image n'est pas accessible, elle ne le devient pas « par magie ».
La correction qui a fonctionné consistait à utiliser l'image depuis le miroir publié par FastGPT : registry.cn-hangzhou.aliyuncs.com/fastgpt/minio. Selon où vous êtes, l'accès à ce registre peut être lent. Et vérifiez quand même que la version/tag récupéré correspond bien à ce que votre configuration attend.
Dans votre fichier Compose, cherchez le service MinIO et la valeur de image. Le changement porte sur le registre et le chemin, pas sur une mise à jour improvisée de tous les services. Gardez le même tag (ou la même version) que celui prévu dans les fichiers de la version installée, si le miroir le propose. Évitez de copier un tag trouvé dans un vieux tutoriel : sans compatibilité, vous ne gagnez rien.
Après la modification, relancez le téléchargement et vérifiez l'état des conteneurs puis leurs journaux. Si le registre reste inaccessible, distinguez trois cas : souci réseau, nom d'image, ou tag incompatible. Remplacer « par autre chose » peut faire démarrer, mais introduire un comportement différent ou des données interprétées autrement.
Bref : le miroir est un contournement utile, pas une garantie éternelle. Pour un déploiement important, notez clairement la source choisie et envisagez un cache ou un miroir interne - à condition de bien vérifier les règles de distribution et de mise à jour applicables à votre contexte.
2. Le fichier CSV d'import FAQ exige une troisième colonne
Un CSV « qui ressemble » à un fichier avec question et réponse peut quand même être rejeté. Dans l'essai, l'en-tête attendu était q,a,indexes, pas simplement q,a.
Le point clé : respectez le schéma attendu par l'outil, même si indexes vous paraît secondaire. Un exemple minimal :
q,a,indexes
"Comment réinitialiser mon mot de passe ?","Utilisez le lien de réinitialisation sur la page de connexion.","compte,connexion"
La colonne indexes sert à fournir les valeurs attendues pour l'indexation dans ce format.
Avant d'importer un gros fichier, testez avec un échantillon : gardez le même en-tête et mettez une ou deux lignes, puis lancez l'import. C'est nettement plus rapide que de corriger des centaines d'entrées après un rejet global.
Et au passage, vérifiez les « classiques » qui cassent souvent les imports : séparateur, encodage, guillemets quand les réponses contiennent des virgules, retours à la ligne dans les champs, et présence d'un en-tête cohérent. La doc (ou les exemples) de la version que vous déployez reste la référence pour ce qui est accepté dans indexes.
Dernier point : « import valide » ne veut pas dire « base de connaissances correcte ». Un CSV peut importer malgré tout, avec des réponses contradictoires, des formulations trop vagues, ou des infos périmées. Après import, nettoyez, retirez les doublons, puis testez le chatbot avec des questions représentatives. La qualité dépend autant du contenu que du découpage.
3. Un modèle de conversation ne remplace pas un modèle d'embedding
FastGPT a besoin d'un modèle de conversation pour répondre. Mais la base de connaissances repose aussi sur des embeddings : des représentations numériques utilisées pour retrouver les passages pertinents.
Ces fonctions ne sont pas interchangeables. Le modèle de conversation génère du texte. Le modèle d'embedding transforme du texte en vecteurs pour permettre une recherche sémantique. Donc configurer uniquement un modèle de chat (par exemple DeepSeek) ne suffit pas forcément à créer et interroger une base de connaissances.
Dans l'installation observée, l'interface indiquait l'absence de modèle d'embedding avec le message System not embedding model.
La correction : ajouter un modèle d'embedding compatible avec FastGPT, en plus du modèle de conversation. Le modèle peut être hébergé chez vous ou via un fournisseur externe, selon ce que vous avez choisi et vos contraintes. Avant de valider, vérifiez la compatibilité, les identifiants, les paramètres requis et les coûts éventuels.
Choisissez aussi en conscience : un service externe simplifie l'exploitation, mais implique d'envoyer les textes au prestataire et peut entraîner une facturation à l'usage. Un modèle hébergé chez vous donne plus de contrôle, mais demande des ressources, de la supervision et des compétences supplémentaires. Pour des documents personnels ou sensibles, évaluez le traitement des données au regard de vos obligations, notamment RGPD, avant de choisir un fournisseur.
Une fois le modèle ajouté, confirmez que FastGPT le reconnaît vraiment et qu'il sert bien à créer la base. Ne vous arrêtez pas à une simple configuration visible : faites un test complet (création de base + interrogation sur quelques documents).
Sécuriser l'accès réseau et dimensionner le serveur
Un service qui démarre n'est pas automatiquement prêt à être exposé sur Internet. Docker peut publier des ports même si vous pensiez que les règles UFW suffiraient. Le comportement dépend de la configuration réseau de la machine : UFW n'est donc pas une preuve suffisante que les conteneurs ne sont pas accessibles.
Lier les ports à l'interface locale
Si FastGPT doit être accessible uniquement via un reverse proxy, évitez d'exposer ses ports sur toutes les interfaces réseau. Dans un fichier Compose, vous pouvez publier le port comme ceci :
ports:
- "127.0.0.1:3000:3000"
Les valeurs ci-dessus sont un exemple : adaptez-les à vos ports réels et à votre version.
L'objectif : rendre le port joignable localement (par le reverse proxy), sans l'ouvrir directement côté Internet. Ensuite, placez un reverse proxy devant l'application pour gérer HTTPS et le routage.
Après déploiement, vérifiez aussi concrètement les ports publiés : depuis la machine et depuis l'extérieur. Ne présumez pas qu'une règle UFW bloquera « comme il faut » une publication Docker. Un contrôle pratique est indispensable avant de connecter des comptes réels ou des documents sensibles.
Et ne publiez pas par défaut les ports des services internes qui n'ont aucune raison d'être joignables depuis Internet. Une interface d'administration, une base de données, ou un stockage objet ne doivent pas être publics sans raison claire, ni protections adaptées.
4 Go de RAM : un repère, pas une promesse
Sur la machine testée, l'usage mémoire au repos était proche de 2,1 Go. Ça explique pourquoi un serveur à 2 Go peut vite manquer de marge, même si « rien ne semble tourner fort ». Gardez de la place pour le système, les pics d'activité et les autres conteneurs.
Pour un essai isolé, vous pouvez démarrer petit, puis surveiller. Pour un usage en équipe, prévoyez une capacité supérieure aux besoins mesurés au repos. Surveillez la mémoire pendant l'import, l'indexation et les périodes d'utilisation.
Le dimensionnement dépend aussi du nombre d'utilisateurs, du volume de documents, du modèle retenu, et de l'endroit où le modèle s'exécute. Un modèle via API externe ne consomme pas la même chose côté machine qu'un modèle hébergé sur votre serveur. La recommandation de 4 Go reste donc un point de départ basé sur un test, pas une garantie pour la production.
Préparer l'exploitation et les mises à jour
Les erreurs d'installation se voient parce qu'elles arrêtent le déploiement. Les problèmes d'exploitation sont plus discrets : sauvegarde inutilisable, mise à jour qui change une dépendance, ou perte de données après une panne. Avant de brancher le chatbot à un site ou à un processus métier, vérifiez que vous pouvez le maintenir.
Tester la sauvegarde et la restauration
Identifiez les volumes Docker et les répertoires qui contiennent les données persistantes. Sauvegarder seulement le fichier Compose ne suffit pas forcément : vous ne sauvegardez peut-être pas la base, les fichiers, ni les données associées à la configuration. À l'inverse, copier des fichiers « à chaud » sans comprendre comment c'est stocké ne garantit pas une restauration cohérente.
Mettez en place une procédure adaptée à vos services, puis faites un test de restauration sur un autre environnement. Une sauvegarde ne sert que si vous savez la restaurer dans un délai acceptable.
Gardez aussi les versions des images et les paramètres nécessaires à une remise en service. Et évidemment, ne mettez pas les secrets en clair dans un dépôt de code.
Pour un petit test, une procédure manuelle peut suffire. Dès que le service compte, automatisez les sauvegardes, vérifiez les résultats, et testez la restauration régulièrement. C'est rarement le sujet « le plus excitant » - mais c'est souvent lui qui évite la catastrophe après un incident.
Mettre à jour sans casser le déploiement
Évitez de mettre à jour FastGPT, MinIO, les dépendances et le fichier Compose en même temps. Quand tout bouge, diagnostiquer devient compliqué : si un service ne redémarre plus, vous ne saurez pas ce qui a réellement changé.
Le bon rythme : sauvegarde vérifiée → lecture des changements de version → mise à jour contrôlée → vérification des journaux → test des fonctions importantes.
Notez aussi ce que vous avez adapté localement, surtout si vous utilisez un miroir différent de celui indiqué au départ. Sans trace, une mise à jour peut réintroduire l'ancienne référence et faire réapparaître le problème de téléchargement.
Une note d'exploitation courte - versions, ports, volumes, modèles configurés et méthode de restauration - suffit souvent à éviter les oublis pénibles.
Le retour décrit ici renvoie aussi à des modèles Compose, à des scripts de sauvegarde/restauration, et à un exemple de widget pour site. Vous pouvez consulter le guide d'installation et ses modèles. Pour le contexte initial du retour d'expérience, la publication source décrit l'installation de FastGPT v4.15.
Tester le parcours utilisateur, pas seulement les conteneurs
Le test final doit couvrir tout le trajet : l'application démarre, le modèle de conversation répond, une base est créée, les documents s'indexent, et une question retrouve une réponse pertinente. Ajoutez à ça un contrôle d'accès depuis l'extérieur, un test de sauvegarde, et un redémarrage des conteneurs.
Si votre chatbot doit répondre aux visiteurs d'un site, testez aussi le widget dans son contexte réel : affichage sur mobile, comportement en cas d'indisponibilité, et ce qu'il est autorisé (ou non) à divulguer. Un chatbot peut être techniquement « ok » et pourtant répondre mal, ou exposer des contenus qui n'auraient jamais dû être indexés.
Conclusion
FastGPT peut tourner avec Docker sans une installation trop compliquée, mais trois détails peuvent vraiment tout bloquer : une image MinIO indisponible depuis la source prévue, un CSV sans la colonne indexes, et l'absence d'un modèle d'embedding. En les traitant séparément, vous diagnostiquez plus vite et vous évitez les corrections approximatives.
Avant de mettre en ligne, ajoutez deux contrôles à votre routine : l'exposition réelle des ports Docker et la consommation mémoire. Puis passez par un déploiement reproductible : testez l'import et la recherche, vérifiez ensuite la sauvegarde et la restauration. Pour votre prochain essai, servez-vous de cette liste comme « contrôle pré-prod », et piochez dans le guide avec fichiers Compose et scripts si vous voulez des bases prêtes à adapter.