Manuel utilisateur de l'environnement Vaniila / AI4industry

(version en ligne et mise à jour de ce document disponible sur : https://ai4industry-doc.vaniila.ai/vaniila-ai4industry/).

Sommaire

Introduction

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

  • l’édition et l’exécution de notebooks Jupyter, documents électroniques pouvant rassembler, dans un même document, textes, images et code informatique exécutable
  • et plus largement la création, la manipulation de fichiers et l’exécution de scripts, au travers d’environnements virtuels Linux basés sur la mise en œuvre de conteneurs Docker dédiés

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 1 et 2, est accessible à l’adresse : https://ai4industry-as1.vaniila.ai.

Le second, destiné aux participants aux uses cases 3 à 11, est accessible sur https://ai4industry-as2.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 deux conteneurs d’environnement, respectivement nommés c1 et c2, identiques au départ mais qui peuvent évoluer de manière séparée selon les modifications apportées de part et d’autre. Ces deux environnements partagent un répertoire de travail commun facilitant ainsi la communication entre conteneurs et membres du groupe.

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.

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.

Plusieurs utilisateurs peuvent se connecter simultanément au même compte et à un même conteneur d’environnement JupyterLab, depuis des navigateurs différents. Toutefois cela leur impose de bien prendre garde à ne pas éditer les mêmes fichiers en même temps, sous peine de perdre une partie ou la totalité du travail 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 :

  • 1 vCore max
  • 4 Go de RAM max (tout programme lancé et consommant plus de 4 Go de RAM sera automatiquement interrompu par le système)

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 :

  • pip install tensorflow pour installer la dernière version du package tensorflow
  • pip install tensorflow==2.2.0 pour installer une version antérieure de ce package

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 libglib2.0-0

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', communication inter-conteneurs 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.

Veuillez noter le fait que ce répertoire ~/work/ est partagé entre tous les conteneurs associés à un même compte (exemple : conteneurs d'environnement c1 et c2 d'un groupe de participants à un use case). Ce qui facilite naturellement la communication inter-conteneurs et le travail entre les membres d'un groupe mais impose à ceux-ci de bien organiser le stockage des fichiers de manière à ne pas "se marcher sur les pieds".

Sachez que seule la persistance du contenu de ce répertoire 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

Les données relatives aux use cases sont stockées dans le répertoire /resources/use-cases-data/ accessible, en lecture seule, depuis le conteneur.

Un lien symbolique vers ce répertoire est également disponible dans le répertoire ~/work/, de manière à faciliter le parcours des jeux de données à l'aide de l'explorateur JupyterLab.

Ces données peuvent être uploadées et gérées directement par les responsables de use cases via un accès FTP, dont les identifiants leur ont été communiqués par les organisateurs.

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 :

  • copier : Cmd+C sous Mac, Ctrl+Insert sous Windows ou Linux
  • coller : Cmd+V sous Mac, shift+Insert sous Windows ou Linux ou, selon le contexte, clic sur le bouton central de la souris

Troubleshooting

1/ 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 lecture / écriture). Cette erreur se produit typiquement lorsque vous êtes positionné(e) en dehors du réportoire ~/work/. Veuillez alors vous repositionner dans ~/work/ en cliquant sur le bouton situé en haut à gauche dans le volet d'exploration JupyterLab.

2/ 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 lecture / écriture.

3/ 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.

4/ 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.

Contacts / Assistance technique

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

  • via le canal de visionconférence mis en place dans Teams, salle "Aide / Assistance technique > Assistance technique Vaniilia"
  • et / ou par mail à l'adresse : support@vaniila.ai