Manuel utilisateur de l'environnement Vaniila / AI4industry

Sommaire

Introduction

Le CATIE fournit, au travers de sa plateforme Vaniila, un service Cloud permettant :

Le service proposé prend appui sur JupyterLab, une application web couramment utilisée dans le domaine de la data science et permettant l’exploration de jeux de données, la mise au point d’algorithmes de machine learning et leur documentation. Ainsi donc que sur la technologie Docker, qui permet la création de machines virtuelles légères et cloisonnées fournissant un environnement de travail basé sur Linux.

Modalités d’accès aux environnements

L’accès aux conteneurs d’environnement s’effectue à l’aide d’un navigateur web (de préference Firefox ou Google Chrome), au travers de serveurs d’authentification qui permettent ensuite de se connecter aux conteneurs proprement dits.

Le premier serveur d’authentification, destiné aux encadrants et aux participants aux use cases :

est accessible à l’adresse : https://ai4i1-jenv.vaniila.ai.

Le second, destiné aux participants aux uses cases:

est accessible sur https://ai4i2-jenv.vaniila.ai.

Aperçu du tableau de bord authentification / accès aux conteneurs

Chaque groupe de participants dispose d’un accès avec identifiant et mot de passe partagé entre tous les membres de ce groupe. Les identifiants associés aux différents groupes seront communiqués par les organisateurs.

Chaque groupe rattaché à un use case dispose de d'un conteneur d’environnement.

Les responsables de use cases et encadrants disposent également d’accès indépendants à des conteneurs leur permettant de tester et développer des algorithmes.

Pour toute question relative aux comptes et accès, merci de nous contacter à l'adresse : support@vaniila.ai.

L’interface JupyterLab

Chaque conteneur d’environnement est associé à une interface JupyterLab permettant la création et l’édition de notebooks, ainsi que des intéractions avec le système Linux sous-jacent au travers notamment d’un terminal en ligne de commande.

Aperçu général de l'interface JupyterlLab

Vue édition d'un notebook

Vue session de terminal

L’interface proposée fournit des fonctionnalités et outils permettant, essentiellement, d’intéragir avec un interpréteur de code Python.

L’utilisateur peut tout à la fois éditer des notebooks et scripts, les exécuter et en récupérer / exploiter les résultats.

Comme cela a déjà été évoqué elle permet en outre de lancer des sessions de terminal rendant possible les intéractions avec le système Linux exécuté en arrière plan.

Nous n’entrerons pas ici dans les détails relatifs aux caractéristiques et aux fonctionnalités de cet IDE et nous vous invitons plutôt à consulter sa documentation ainsi que les nombreux tutoriels accessibles en ligne à son sujet.

Accès simultanés au compte - avertissement

Il est tout à fait possible de se connecter simultanément, à plusieurs, au même compte et à un même conteneur d’environnement, depuis des ordinateurs / navigateurs web différents.

Toutefois, dans ce cas, vous devrez bien prendre garde à ne pas éditer les mêmes notebooks au même moment, sous peine de perdre une partie ou la totalité du travail récemment effectué sur ceux-ci.

Caractéristiques de l’environnement d’exécution

Les conteneurs d’environnement JupyterLab mis à disposition ici sont basés sur Ubuntu 20.04 en mode serveur. La version de Python installé est la 3.8.

Les ressources allouées à chaque conteneur sont, par défaut, limitées de la façon suivante :

Ces ressources maximales peuvent, ponctuellement, être ajustées. En cas de besoin veuillez nous contacter à l'adresse : support@vaniila.ai.

Il est rappelé que les environnements proposés n’intègrent pas d’accès à des GPUs.

Les environnements fournis peuvent, selon le contexte d’accès (encadrant, participant...) inclure, de base, plusieurs bibliothèques ou modules préinstallés tels que numpy, pandas, tensorflow...

Mise à jour de l'environnement / ajout de nouveaux modules

Chaque environnement peut être « tuné », en fonction des besoins, avec la possibilité de d’installer de nouveaux modules ou de désinstaller les modules fournis et de les réinstaller dans des versions plus anciennes si nécessaire.

Pour cela on utilise le gestionnaire de paquets pip pré-installé, en effectuant par exemple dans une session de terminal :

Il est également possible d'installer un module python directement depuis un notebook en effectuant :

!pip install tensorflow

Attention toutefois, dans ce cas, car le ou les nouveaux modules installés ne seront pas toujours immédiatement disponibles dans le notebook en question. Pour qu'ils le deviennent, il sera parfois nécessaire de redémarrer le kernel en se rendant pour cela dans le menu Kernel > Restart Kernel...

L'installation de certains packages spécifiques peut par ailleurs, dans certains cas, nécessiter l'installation de bibliothèques système supplémentaires.

Dans ce cas on effectuera, par exemple, dans une session de terminal :

sudo apt-get update

sudo apt-get install build-essential

En cas de problèmes d'installation ou de configuration merci de nous contacter à l'adresse : support@vaniila.ai.

Veuillez noter le fait que ces opérations n'affectent pas les environnements des membres des autres groupes, chaque environnement étant compartimenté à l'intérieur d'un conteneur Docker dédié.

Répertoire 'work' et sauvegarde des données

L'utilisateur standard Linux des conteneurs d'environnement est l'utilisateur jovyan. Celui-ci dispose d'un répertoire personnel ~/(alias de /home/jovyan/) dans lequel a été créé un répertoire work/ destiné à recueillir tous les fichiers de travail des utilisateurs : notebooks, scripts et résultats en particulier.

Sachez que seule la persistance du contenu du répertoire ~/work/ est garantie en cas de problème nécessitant, par exemple, la régénération de votre conteneur. Toute fichier enregistré en dehors de ce répertoire ~/work/, par exemple directement dans le répertoire ~/, sera donc perdu si un problème nécessite la réinitialisation du ou des conteneurs associés au compte.

Nous vous encourageons naturellement à sauvegarder, en parallèle, votre code ou vos données à l'intérieur de dépôts GitHub / GitLab par exemple.

Données relatives aux use cases AI4industry

Le répertoire ~/work/data/ est destiné à recueillir les données associées au use case à traiter.

Ce répertoire est vide à la première connexion à l'environnement et il est nécessaire d'y rapatrier les données.

Pour ce faire vous devez ouvrir une session de terminal (clic sur le bouton + en haut à gauche puis clic sur le bouton "Terminal"), puis rapatrier les données par FTP en exécutant la commande :

lftp -e "set ftp:ssl-allow no; mirror --verbose -c --verbose /data /home/jovyan/work/data; quit" -u USERNAME,'PASSWORD' ai4i-data.vaniila.ai

où :

1/ USERNAME et PASSWORD sont les mêmes identifiants que ceux utilisés pour se connecter au conteneur d'environnement Vaniila (informations reçue par mail) dans le cas des équipes de participants.

Exemple d'USERNAME dans ce cas : ai4i-aio-team1

2/ USERNAME et PASSWORD sont des identifiants distincts et spécifiques, également reçus par mail, dans le cas des encadrants.

Note importante :

Il se peut (encadrants en particulier) que le répertoire vide /home/jovyan/work/data/ n'existe pas à votre première connexion et que l'utilitare lftp ne soit pas pré-installé.

Dans ce cas veuillez effectuer :


mkdir /home/jovyan/work/data/

sudo apt-get update

sudo apt-get install lftp

avant de lancer la commande de rapatriement spécifiée plus haut.

Pour l'utilisation du copier-coller dans JupyterLab, voir la section consacrée aux trucs et astuces.

En cas de problèmes d'accès ou de rapatriement des données, merci de nous contacter à l'adresse support@vaniila.ai.

Notes :

Partage de fichiers avec les encadrants et membres des autres équipes du use case

Participants et encadrants ont la possibilité d'échanger des fichiers au travers d'un répertoire partagé, accessible en lecture / écriture par tous, au travers des protocoles FTP / SFTP ou SSHFS.

(localisation et nom du répertoire : /shared sur l'espace partagé accessible avec les identifiants de connexion communiqués)

Pour afficher la liste des répertoires créés sur le serveur FTP, dans cet espace partagé, effectuer :

lftp -e "set ftp:ssl-allow no; cd /shared; ls; quit" -u USERNAME,PASSWORD -u USERNAME,'PASSWORD' ai4i-data.vaniila.ai

Pour y créer un nouveau répertoire, effectuer par exemple :

lftp -e "set ftp:ssl-allow no; mkdir /shared/MON_NOUVEAU_REPERTOIRE; quit" -u USERNAME,'PASSWORD' ai4i-data.vaniila.ai

puis, pour y copier un fichier, effectuer :

lftp -e "set ftp:ssl-allow no; cd /shared/MON_NOUVEAU_REPERTOIRE/ ; put MON_FICHIER.txt; quit" -u USERNAME,'PASSWORD' ai4i-data.vaniila.ai

Note :

1/ L'utilitaire lftp offre de nombreuses autres possibilités pour l'upload / download de fichiers, que celles illustrées au travers des commandes précédentes. Pour plus d'informations sur celle-ci, nous vous invitons à consulter des tutoriels tels que :

2/ l'espace partagé /shared est également accessible, par FTP, au travers d'autres clients que l'utilitaire lftp. Notamment, en dehors du contexte Vaniila, à l'aide du client graphique FileZilla. N'hésitez pas à utiliser celui-ci en cas de doute sur le nom et la liste des fichiers partgés / déposés.

3/ Le répertoire /shared partagé est en lecture / écriture et accessible par l'ensemble des participants au use case donc soyez attentifs lorsque y déposez / supprimez des fichiers !

En cas de problèmes ou de questions, n'hésitez pas à nous contacter à l'adresse support@vaniila.ai.

Accès à des ressources extérieures

L'environnement proposé permet d'exécuter, en ligne de commande via un terminal, des utilitaires tels que wget et git.

L'interface graphique de JupyterLab permet également d'uploader des fichiers dans le conteneur via le bouton prévu à cet effet "Upload files".

Il est également possible, depuis celle-ci, de rapatrier (download) des fichier stockés dans votre instance. Pour cela on n'hésitera pas, si un grand nombre de fichiers devaient être rapatriés, à générer des archives à l'aide des utilitaires tar ou zip en ligne de commande (ne pas oublier d'ajuster les options de sortie pour que l'archive soit bien générée dans un répertoire sur lequel vous possédez des droits en écriture).

Trucs et astuces divers

Nous vous rappelons que la documentation de JupyterLab est disponible ici :

https://jupyterlab.readthedocs.io

Références utiles relatives à l'utilisation de Jupyter, à ses magic commands, etc.

Voici par ailleurs les raccourcis clavier permettant de copier / coller du contenu dans un terminal :

Troubleshooting

1/ Je ne vois pas de répertoire ~/work/data/ et/ou je ne trouve pas l'utilitaire lftp

Il se peut que le répertoire vide /home/jovyan/work/data/ n'existe pas à votre première connexion et que l'utilitare lftp ne soit pas pré-installé.

Dans ce cas veuillez effectuer :


mkdir /home/jovyan/work/data/

sudo apt-get update

sudo apt-get install lftp

2/ Erreur : impossible de créer un nouveau notebook (erreur : "Unexpected error while saving file...")

Assurez-vous, lorsque vous tentez de créer un nouveau fichier en cliquant par exemple sur le bouton "Nouveau Notebook Python 3", que vous vous êtes bien positionné(e) à l'intérieur d'un répertoire sur lesquels vous possédez des droits en écriture. Cette erreur se produit typiquement lorsque vous êtes positionné(e) en dehors du répertoire ~/work/. Veuillez alors vous repositionner dans ~/work/ en cliquant sur le bouton situé en haut à gauche dans le volet d'exploration JupyterLab.

3/ Erreur : impossible d'uploader un fichier dans mon conteneur (erreur : "Upload Error : Unexpected error while saving file...")

Même origine que l'erreur décrite précédemment : assurez vous que vous êtes positionné(e) dans un un répertoire sur lesquels vous possédez des droits en écriture.

4/ Je viens d'installer, à partir d'un notebook, un nouveau module python (via !pip install) mais il m'est impossible de l'importer (ModuleNotFoundError)

Rendez-vous dans le menu Kernel puis cliquez sur Restart Kernel.... Le module en question devrait pouvoir ensuite être importé depuis vos notebooks.

5/ Je viens d'installer un nouveau module python mais une erreur s'affiche au moment où je tente de l'importer

Il se peut que le module en question prenne appui sur une bibliothèque système ne figurant pas parmi celles déjà installée dans votre conteneur. Dans ce cas veuillez identifier la ou les bibliothèques manquantes puis les installer via sudo apt-get update et sudo apt-get install comme indiqué plus haut. En cas de problème persistant merci de nous contacter à l'adresse : support@vaniila.ai en nous communiquant le message d'erreur retourné par l'interpréteur Python, de manière à ce que nous installions les composants manquants ou ajustions la configuration.

6/ Je suis encadrant et tente d'accéder au conteneur d'un groupe d'apprenants mais je n'y parviens pas bien que je dispose de ses identifiants de connexion

Pour switcher d'un compte à un autre vous devez :

1/ Tout d'abord vous déconnecter de votre instance JupyterLab en cliquant sur File / Logout ou bien en activant directement l'URL https://ai4industry-nbs1.vaniila.ai/hub/logout ou https://ai4industry-nbs2.vaniila.ai/hub/logout selon le serveur auquel vous avez été affecté(e).

2/ Vous déconnecter du serveur d'authentification via le menu "Déconnexion"

3/ Vous rendre sur https://ai4industry-as1.vaniila.ai ou https://ai4industry-as2.vaniila.ai et saisir les identifiants du nouveau compte auquel vous souhaitez vous connecter.

7/ Affichage intempestif d'un popup "Your server at /user/..../ is not running. Would you like to restart it?"

Problème temporaire apparaissant lorsque de gros volumes de données sont téléchargés simultanément par plusieurs groupes, ce qui réduit la bande passante disponible au niveau du serveur et entrave la communication entre les instances JupyterLab et celui-ci. Veuillez dans ce cas simplement cliquer sur "Dismiss".

Contacts / Assistance technique

En cas de problèmes lié à l'utilisation de la plateforme merci de nous contacter :