Mettre votre étude Potato en ligne

Pour mettre une étude Potato en ligne, vous exécutez votre tâche sur un ordinateur que vos annotateurs peuvent joindre par une adresse web, vous protégez les annotations pendant l'étude et vous les téléchargez à la fin. Demander à l'équipe informatique de votre établissement et cliquer sur un bouton de déploiement préparé par un collègue sont les deux voies qui n'exigent aucun terminal de votre part.

Déployer une étude, c'est faire passer la tâche Potato que vous avez construite de votre propre ordinateur à un serveur, un ordinateur qui reste allumé et connecté à Internet. Les annotateurs ouvrent alors la tâche dans un navigateur web depuis n'importe où, et Potato enregistre chaque réponse sur le serveur au fil du travail. L'aperçu du Study Designer exécute Potato dans votre propre navigateur, et personne d'autre ne peut atteindre cette copie. Une étude construite dans le Designer a donc encore besoin de l'une des voies ci-dessous.

Toutes les voies partent du même dossier de projet. Dans le Study Designer, le bouton Télécharger le projet (.zip) enregistre config.yaml (le fichier qui décrit votre tâche), un fichier de données d'exemple et un README. Le fichier d'exemple contient trois items fictifs. Remplacez-le par vos propres items avant de déployer, dans le format que décrit Formats de données.

Choisir une voie

Les voies diffèrent par la personne qui fait le travail technique, par le coût du serveur et par la durée pendant laquelle l'étude peut rester en ligne. Les coûts ci-dessous viennent des grilles tarifaires des hébergeurs et des estimations de Potato au 2026-11-04, et les délais sont des ordres de grandeur et non des mesures :

Si vous hésitez, commencez par votre équipe informatique. Un serveur à l'intérieur de votre établissement garde les données sur un équipement que votre établissement gère déjà, et l'équipe informatique peut se charger des mises à jour de sécurité et des sauvegardes.

Demander à votre équipe informatique ou de calcul de recherche

Beaucoup d'universités et d'hôpitaux exploitent un service de calcul de recherche qui héberge des applications web pour les études. Pour une telle équipe, Potato est une application web ordinaire, et l'équipe peut partir d'un résumé d'une page de ce dont Potato a besoin.

1. Téléchargez le projet depuis le Study Designer et remplacez le fichier de données d'exemple par vos items.
2. Envoyez à votre équipe informatique le dossier du projet et un lien vers Exigences de Potato pour votre équipe informatique.
3. Dites à l'équipe qui sont vos annotateurs, combien participeront et combien de temps dure l'étude.
4. Précisez comment les annotateurs doivent se connecter. Les collègues qui ont un compte institutionnel peuvent utiliser l'authentification unique, la connexion que votre établissement exploite déjà, et les annotateurs extérieurs peuvent utiliser des noms d'utilisateur que vous listez.
5. Indiquez si les items ou les réponses contiennent des informations personnelles ou sensibles, et nommez l'approbation éthique sous laquelle l'étude se déroule.
6. Demandez à l'équipe l'adresse web de l'étude, la clé d'administration qui ouvre le tableau de bord d'administration de Potato, ainsi qu'un plan de sauvegarde et de remise des données à la fin de l'étude.

Quand l'adresse arrive, parcourez Avant d'inviter les annotateurs avant de l'envoyer à qui que ce soit.

Cliquer sur un bouton de déploiement préparé par un collègue

Un bouton de déploiement est un lien, sur la page d'un dépôt de code, qui met en place une copie d'une tâche Potato sur les serveurs d'un hébergeur, uniquement par des formulaires dans votre navigateur. Un collègue qui utilise git et un terminal crée le bouton une fois, à partir d'un dépôt qui contient votre dossier de projet, avec la commande potato deploy button. Exécuter Potato en local ou dans le cloud est la page à envoyer à ce collègue.

Le bouton fonctionne avec trois hébergeurs, qui facturent de façon différente :

• Render exécute l'étude sur une offre gratuite sans moyen de paiement. Un service Render gratuit se met en veille après 15 minutes sans visiteur et met environ une minute à se réveiller à l'arrivée de l'annotateur suivant.
• Heroku facture $7 par mois le serveur que crée le bouton. Heroku exige un compte vérifié, en général par une carte bancaire, avant que vous puissiez créer une application.
• AWS exécute un serveur Lightsail pour $12 par mois. Le bouton AWS lit la tâche depuis un dépôt public, et il ne convient donc qu'à des items qui peuvent être publics.

Render et Heroku effacent le disque du serveur à chaque redémarrage du serveur. Le bouton copie donc les annotations toutes les cinq minutes vers un dataset privé sur Hugging Face, un site de partage de données et de modèles, et recopie les annotations à chaque démarrage du serveur. Vous nommez ce dataset au moment du clic, et le dataset appartient à votre compte.

Avant de cliquer, rassemblez trois choses :

• un compte chez l'hébergeur, Render ou Heroku ;
• un compte Hugging Face gratuit, avec un jeton d'accès qui a la permission d'écriture, créé sur huggingface.co/settings/tokens ; et
• l'accès au dépôt, si le dépôt est privé. Heroku vous demande de lier votre compte GitHub pour un dépôt privé.

Déployez ensuite :

1. Cliquez sur le bouton dans le README du dépôt et connectez-vous chez l'hébergeur.
2. Donnez un nom à l'application. Ce nom fait partie de l'adresse web de l'étude.
3. Dans POTATO_BACKUP_HF_REPO, saisissez un nom de dataset composé de votre nom d'utilisateur Hugging Face et d'un nom pour l'étude, comme your-username/my-study-annotations. Quand le nom est nouveau, Potato crée le dataset et le rend privé.
4. Collez votre jeton Hugging Face dans HF_TOKEN. Laissez tous les autres champs à la valeur que le bouton a remplie.
5. Lancez le déploiement et attendez que l'hébergeur indique que l'application s'exécute. Ouvrez l'adresse web que l'hébergeur affiche.
6. Trouvez la clé d'administration, un mot de passe que l'hébergeur a généré pendant le déploiement. Sur Heroku, la clé est l'entrée POTATO_ADMIN_API_KEY dans l'onglet Settings de l'application, et sur Render la même entrée se trouve dans la page Environment du service.
7. Ouvrez l'adresse de l'étude avec /admin ajouté à la fin, et collez la clé d'administration pour ouvrir le tableau de bord d'administration.

Le dépôt fixe la tâche, les items et la liste des annotateurs. Terminez la tâche avant de cliquer, car toute modification ultérieure passe par le collègue qui a créé le bouton. Gardez le dépôt privé, sauf si les items peuvent être publics.

Partager un lien depuis votre propre ordinateur

Votre propre ordinateur peut servir un pilote pendant un après-midi. Les annotateurs ouvrent un lien web temporaire, les annotations arrivent dans votre dossier de projet, et le lien cesse de fonctionner quand vous fermez la commande. Cette voie demande un terminal, un programme pour saisir des commandes, qui s'appelle Terminal sur un Mac (dans Applications, puis Utilitaires) et PowerShell sous Windows (cherchez « PowerShell » dans le menu Démarrer).

1. Installez Python 3.9 ou une version plus récente depuis python.org/downloads. Sous Windows, le téléchargement est le gestionnaire d'installation de Python. Sur un Mac, le téléchargement est l'installateur macOS.

2. Ouvrez le terminal et installez Potato. Sur un Mac, saisissez :

   bashCopier

   python3 -m pip install potato-annotation

   Sous Windows, saisissez :

   powershellCopier

   py -m pip install potato-annotation

3. Décompressez le projet que vous avez téléchargé depuis le Study Designer. Sur un Mac, double-cliquez sur le fichier .zip. Sous Windows, faites un clic droit sur le fichier et choisissez Extraire tout. Remplacez le fichier de données d'exemple par vos items.

4. Placez le terminal dans le dossier du projet et démarrez Potato. Le nom de dossier ci-dessous est un exemple, utilisez donc le nom de votre propre dossier. Sur un Mac :

   bashCopier

   cd ~/Downloads/my-task
   python3 -m potato start config.yaml

   Sous Windows :

   powershellCopier

   cd $HOME\Downloads\my-task
   py -m potato start config.yaml

5. Ouvrez http://localhost:8000 dans votre navigateur. Seul votre ordinateur peut atteindre cette adresse. Appuyez sur Ctrl-C dans le terminal pour arrêter Potato.

6. Pour laisser entrer d'autres personnes, installez cloudflared, un programme gratuit de Cloudflare qui n'exige aucun compte. Sur un Mac avec Homebrew, exécutez brew install cloudflared. Sous Windows, téléchargez l'installateur Windows depuis la page de téléchargement de Cloudflare.

7. Exécutez potato share à la place de potato start :

   bashCopier

   python3 -m potato share config.yaml

   Sous Windows, saisissez py -m potato share config.yaml. Potato affiche qui pourra se connecter et demande confirmation avant de publier quoi que ce soit. Saisissez y, et Potato affiche un lien https:// à envoyer à vos annotateurs.

Le lien ne fonctionne que pendant que la commande s'exécute. Fermer le terminal, mettre l'ordinateur en veille ou changer de réseau met fin au lien, et une nouvelle exécution affiche un nouveau lien. Certains réseaux universitaires bloquent les liens trycloudflare.com que crée cloudflared. Si un annotateur signale un lien bloqué, potato share config.yaml --backend tailscale utilise Tailscale à la place. Tailscale demande un compte gratuit. Si potato share signale No tunnel backend found, Potato n'a pas trouvé cloudflared sur votre ordinateur, et le message liste les commandes d'installation.

Installation couvre les environnements virtuels et les fonctionnalités optionnelles, et Exécuter Potato en local ou dans le cloud couvre potato share plus en détail.

Louer un serveur avec une commande

potato deploy up loue un serveur chez une entreprise de cloud, obtient un certificat HTTPS (le cadenas dans la barre d'adresse du navigateur), téléverse votre dossier de projet, démarre l'étude et affiche l'adresse web. La commande demande la préparation du terminal des étapes 1 à 3 ci-dessus, un compte chez l'entreprise de cloud et un jeton d'API, une clé semblable à un mot de passe qui permet à un programme d'agir sur votre compte. Le guide de chaque hébergeur couvre le compte et le jeton depuis le début :

Chaque hébergeur utilise les deux mêmes commandes, et le guide de chaque hébergeur donne le nom du fournisseur et la commande d'installation correspondante. La première commande affiche le plan et le coût mensuel et ne crée rien, et la seconde crée le serveur après votre confirmation :

potato deploy up config.yaml --provider aws --dry-run
potato deploy up config.yaml --provider aws

Le bouton Duplicate this Space de Hugging Face copie un Space dans le navigateur, mais la copie d'un Space Potato conserve les réglages de sauvegarde du propriétaire d'origine et perd les secrets de l'original. Déployez plutôt un Space Potato avec potato deploy up --provider huggingface.

Avant d'inviter les annotateurs

Parcourez cette liste dès que l'étude a une adresse web, quelle que soit la voie choisie :

• Décidez qui peut se connecter. La configuration fermée la plus simple est une liste de noms d'utilisateur. Dans le Study Designer, désactivez Autoriser tous les utilisateurs et ajoutez chaque annotateur sous Utilisateurs autorisés. Chaque annotateur listé choisit un mot de passe en s'inscrivant à la première visite, et Potato refuse toute personne qui ne figure pas sur la liste. Envoyez directement à chaque annotateur son nom d'utilisateur, car la première personne qui s'inscrit avec un nom d'utilisateur listé devient propriétaire de ce compte. Pour les comptes institutionnels, consultez SSO et OAuth, et pour les crowdworkers, consultez Intégration du crowdsourcing. Avec Autoriser tous les utilisateurs activé, toute personne qui trouve l'adresse peut créer un compte. Gardez ce réglage pour les démonstrations publiques.
• Sachez où se trouvent les annotations. Potato enregistre les réponses de chaque annotateur au fil du travail, dans un fichier nommé user_state.json à l'intérieur d'un dossier par annotateur. Les dossiers se trouvent dans le dossier de sortie que nomme la configuration, que le Study Designer appelle output. Sur votre propre ordinateur, ce dossier est à l'intérieur de votre dossier de projet. Avec un bouton de déploiement, le dataset Hugging Face contient la copie qui survit à un redémarrage. Sur un serveur loué, potato deploy pull télécharge le dossier. Sur un serveur institutionnel, demandez à l'équipe informatique comment le serveur est sauvegardé.
• Testez avec un second navigateur. Ouvrez l'adresse de l'étude dans une fenêtre privée, qui s'appelle Navigation privée dans Chrome, Fenêtre privée dans Safari et Firefox, et InPrivate dans Edge. Ajoutez à la liste un nom d'utilisateur comme pilot-test, inscrivez-vous avec ce nom et répondez à trois items. Fermez la fenêtre, reconnectez-vous et vérifiez que les réponses sont toujours là. Ouvrez ensuite le tableau de bord d'administration et vérifiez que l'annotateur de test y apparaît. Essayez l'adresse sur un téléphone si des annotateurs risquent de travailler sur téléphone.
• Gardez la clé d'administration privée. La clé d'administration ouvre le tableau de bord d'administration à /admin. Le tableau de bord montre les réponses de chaque annotateur. Sur votre propre ordinateur, Potato enregistre la clé dans admin_api_key.txt dans le dossier du projet la première fois que vous ouvrez /admin.
• Rédigez l'invitation. Envoyez à chaque annotateur l'adresse, le nom d'utilisateur, la durée de la tâche et la personne à contacter en cas de problème.

Récupérer vos résultats

Le tableau de bord d'administration télécharge les résultats sur votre ordinateur sans aucun terminal. Ouvrez /admin, saisissez la clé d'administration et choisissez Publish Dataset. Sous Target, choisissez Local archive, réglez Data format sur CSV pour un tableur et cliquez sur Publish. Quand l'archive est prête, cliquez sur Download archive.

L'archive contient les réponses de chaque annotateur, les items et les étiquettes combinées par vote majoritaire. Un README dans l'archive indique le nombre d'étiquettes et l'accord entre annotateurs. Les noms des annotateurs sont remplacés par A1, A2 et ainsi de suite, sauf si vous décochez Anonymize annotators. Les réponses aux enquêtes restent hors de l'archive, sauf si vous cochez Include survey / phase responses, car ces réponses peuvent contenir des informations personnelles.

Depuis un terminal, python -m potato.export écrit les mêmes annotations dans un dossier, dans n'importe lequel des formats d'export de Potato :

python -m potato.export --config config.yaml --format csv --output results

Sur un serveur créé avec potato deploy up, potato deploy pull config.yaml télécharge tout ce que le serveur a recueilli, bases de données comprises.

Terminer l'étude pour que le serveur cesse de coûter de l'argent

Téléchargez les résultats avant de supprimer quoi que ce soit, et ouvrez le téléchargement pour vérifier que les réponses du dernier annotateur y sont. Arrêtez ensuite le serveur comme l'exige la voie choisie :

• Votre propre ordinateur. Appuyez sur Ctrl-C dans le terminal. Rien n'a été facturé.
• Votre équipe informatique. Dites à l'équipe que l'étude est terminée, demandez une copie du dossier de sortie et demandez combien de temps la copie du serveur sera conservée.
• Un bouton de déploiement. Supprimez l'application depuis l'onglet Settings de l'application sur Heroku, ou supprimez le service depuis sa page Settings sur Render. Le dataset Hugging Face contient une copie complète des annotations. Quand vous n'avez plus besoin de la sauvegarde, supprimez le dataset depuis la page de réglages du dataset.
• Un serveur loué. Exécutez potato deploy pull config.yaml, vérifiez le dossier récupéré, puis exécutez potato deploy destroy config.yaml. Potato refuse de détruire un serveur dont les données n'ont jamais été récupérées.

Questions fréquentes

Comment créer un serveur Potato pour mon étude ?

Vous créez un serveur Potato en exécutant votre tâche sur un ordinateur que vos annotateurs peuvent joindre par une adresse web. L'équipe informatique de votre établissement peut exécuter la tâche pour vous, un collègue peut préparer un bouton de déploiement sur lequel vous cliquez, potato share peut servir un pilote depuis votre portable, et potato deploy up peut louer un serveur pour vous. Le tableau sous Choisir une voie compare les voies selon le coût et selon le travail de terminal que chacune exige.

Comment installer Potato sur mon PC ?

Installez Python 3.9 ou une version plus récente depuis python.org, puis saisissez py -m pip install potato-annotation dans PowerShell sous Windows, ou python3 -m pip install potato-annotation dans Terminal sur un Mac. Après l'installation, py -m potato start config.yaml sous Windows ou python3 -m potato start config.yaml sur un Mac démarre une tâche. Installation couvre les fonctionnalités optionnelles.

Mots utilisés sur cette page

• Serveur. Un serveur est un ordinateur qui reste allumé et connecté à Internet pour que d'autres personnes puissent utiliser un programme de cet ordinateur dans un navigateur web.
• URL, ou adresse web. Une URL est l'adresse que les annotateurs saisissent ou sur laquelle ils cliquent, comme https://my-study.example.edu. Un domaine est la partie nom de l'adresse, ici my-study.example.edu.
• HTTPS. HTTPS chiffre tout ce qui circule entre le navigateur de l'annotateur et le serveur, mots de passe et réponses compris. Les navigateurs affichent un cadenas pour une adresse HTTPS.
• Port. Un port est un point d'entrée numéroté d'un ordinateur. Potato écoute sur le port 8000, sauf si la configuration nomme un autre port, et l'adresse locale http://localhost:8000 se termine par ce numéro.
• Terminal. Un terminal est un programme pour saisir des commandes, appelé Terminal sur un Mac et PowerShell sous Windows.
• Clé d'administration. La clé d'administration est un long mot de passe qui ouvre le tableau de bord d'administration de Potato.
• Jeton d'API. Un jeton d'API est une clé semblable à un mot de passe qui permet à un programme, comme la commande de déploiement de Potato, d'agir sur votre compte chez un hébergeur.

Pour aller plus loin

• Exigences de Potato pour votre équipe informatique, la page à envoyer à votre équipe informatique
• Exécuter Potato en local ou dans le cloud, pour tous les hébergeurs, les boutons de déploiement et les sauvegardes
• Déployer un serveur d'annotation, pour choisir un hébergeur pour une longue étude
• Exécuter Potato dans Docker, pour les serveurs qui exécutent des conteneurs
• Tableau de bord d'administration, pour suivre l'avancement pendant l'étude