CLI - Lancer une app sur AI Deploy

Objectif

Ce guide couvre la soumission d'apps via la CLI ovhai. Pour déployer une app, certains paramètres sont obligatoires. D'autres sont optionnels, selon vos besoins. Nous vous montrerons comment fonctionne chaque paramètre à l'aide d'exemples.

Prérequis

• Une CLI ovhai fonctionnelle. Voir comment installer la CLI ovhai

En pratique

Cette documentation est divisée en plusieurs parties :

• Déployer une app
• Définir des variables d'environnement
• Attribuer un nom à l'app
• Attacher des données
• Attacher des ressources de calcul
• Stratégie de scaling
• Définir des tokens et des labels
• Rendre votre app publique et la partager
• Modifier le port d'accès par défaut
• Configurer un health check
• Modifier le format de sortie

Déployer une app

Si vous avez besoin d'aide pour soumettre une nouvelle app, exécutez ovhai app run --help.

Sortie :

Usage: 
    ovhai app run [OPTIONS] [IMAGE] [COMMAND]...

Arguments:
  [IMAGE]       Docker image
  [COMMAND]...  List of command arguments to pass to app. If some app arguments start with '-' or '--' don't forget to add '--' as first argument to avoid interpreting following ones as ovhai parameter. Example: `ovhai app create ubuntu -- bash -c 'echo $(date)'`

Options:
  -e, --env <name=value>                                                                                        Environment variable to be set inside app
      --token `<TOKEN>`                                                                                           Authentication using Token rather than OAuth
  -p, --default-http-port `<DEFAULT_HTTP_PORT>`                                                                   Port used as the default one to access HTTP service inside app
      --unsecure-http                                                                                           HTTP services inside app will not require authentication to be accessed from the outside
  -g, --gpu `<GPU>`                                                                                               Number of GPUs
  -f, --flavor `<FLAVOR>`                                                                                         the flavor to use, `ovhai capabilities flavor list` to get the whole list
  -c, --cpu `<CPU>`                                                                                               Number of CPUs (ignored if GPUs is specified)
  -v, --volume <container@alias/prefix:mount_path(:permission)(:cache) or url:mount_path(:permission)(:cache)>  Volumes mounted on the image. `alias` is the data store alias of your data. You can get a list of all available data stores for the object storage by typing `ovhai data store list`. `/prefix` is optional [default: ""]. `:permission` is optional [default: ro] [possible values: ro, rw, rwd]. `:cache` is optional [default: "no-cache"] [possible values: cache, no-cache]
  -n, --name `<NAME>`                                                                                             Optional name, only informative
  -l, --label <name=value>                                                                                      Optional labels, only informative
  -o, --output `<OUTPUT>`                                                                                         Command output format [possible values: json, yaml]
      --replicas `<REPLICAS>`                                                                                     Fixed scaling strategy: Number of replicas (defaults to 1)
      --auto-min-replicas <MIN REPLICAS>                                                                        Automatic scaling strategy: Minimum number of replicas [aliases: min-replicas]
      --auto-max-replicas <MAX REPLICAS>                                                                        Automatic scaling strategy: Maximum number of replicas [aliases: max-replicas]
      --auto-resource-type `<TYPE>`                                                                               Automatic scaling strategy: Resource type to base the automatic scaling on [aliases: resource-type] [possible values: CPU, RAM]
      --auto-resource-usage-threshold `<THRESHOLD>`                                                               Automatic scaling strategy: Average resource usage threshold (in percents) at which the number of replicas will be automatically increased [aliases: resource-threshold]
      --probe-path `<PATH>`                                                                                       Path to access (defaults to /)
      --probe-port `<PORT>`                                                                                       Number of the port to access (defaults to --default-http-port)
      --no-color                                                                                                Remove colors from output
  -h, --help                                                                                                    Print help (see more with '--help')

L'argument IMAGE est obligatoire. En effet, vous devez spécifier une image Docker que vous avez construite vous-même ou trouvée librement disponible sur un dépôt public tel que DockerHub.

Pour lancer une app basique, utilisez la commande suivante :

ovhai app run <registry-address>/<image-identifier>:<tag-name>

Comme indiqué dans la commande d'aide, de nombreuses options peuvent être passées à cette commande. Voyons leur utilité et comment les utiliser.

Définir des variables d'environnement

Vous pouvez ajuster le comportement de votre image Docker sans avoir à la reconstruire à chaque fois (par exemple pour mettre à jour la source d'entrée de votre modèle (caméra, image, vidéo, fichier, etc.)) en utilisant le flag --env. Cela vous permet de définir simplement des variables d'environnement directement dans votre app.

Les valeurs de ces flags --env prendront le pas sur celles spécifiées dans votre Dockerfile et dans vos scripts Python, à condition que la variable Python ne soit initialisée que si elle n'existe pas, comme suit :

if not os.environ["ENV_VAR"]:
    os.environ['ENV_VAR'] = 'value'

Comme expliqué, cette variable peut être modifiée au lancement de l'app en utilisant le flag --env :

ovhai app run <registry-address>/<image-identifier>:<tag-name> \
    --env ENV_VAR=new_val

Attribuer un nom à l'app

Afin de gérer vos apps plus facilement, et d'éviter de vous retrouver avec des noms aléatoires, nous vous recommandons de donner un nom à votre app. Pour cela, utilisez le paramètre --name de la manière suivante :

ovhai app run `<registry-address>`/<image-identifier>:`<tag-name>` \
    --name my_first_app

Attacher des données

Cette étape suppose que vous disposez de données dans votre OVHcloud Object Storage que vous souhaitez utiliser au sein de votre app déployée, ou que vous devez sauvegarder les données générées par votre app dans l'Object Storage. Pour en savoir plus sur les données, les volumes et les permissions, consultez la page données.

Vous pouvez attacher autant de volumes que vous le souhaitez à votre app avec diverses options. Passons en revue ces options et présentons quelques bonnes pratiques concernant les montages de volumes.

Le flag --volume permet d'attacher un conteneur en tant que volume à l'app. La description du volume définit l'option pour le volume et le processus de synchronisation <container@alias/prefix:mount_path(:permission)(:cache)> :

• container le nom du conteneur, dans OVHcloud Object Storage, à synchroniser
• alias est l'alias du data store de vos données. Une liste de tous les alias disponibles peut être obtenue en exécutant ovhai data store list
• prefix (optionnel) les objets du conteneur sont filtrés sur la base de ce préfixe, seuls les objets correspondants sont synchronisés
• mount_path l'emplacement dans l'app où les données synchronisées sont montées
• permission les droits d'accès sur les données montées. Les droits disponibles sont lecture seule (ro), lecture-écriture (rw) ou lecture-écriture-suppression (rwd). Ce paramètre est optionnel.
• cache indique si les données synchronisées doivent être ajoutées au cache du projet. Les options disponibles sont cache ou no-cache. Les données présentes dans le cache peuvent être utilisées par d'autres apps sans synchronisation supplémentaire. Pour bénéficier du cache, les nouvelles apps doivent également monter les données avec l'option cache. Ce paramètre est également optionnel.

Exemple :

Supposons que vous ayez une équipe de data scientists travaillant sur le même jeu de données d'entrée mais exécutant chacun leur propre expérimentation. Dans ce cas, une bonne pratique consiste à monter le jeu de données d'entrée avec la permission ro et le cache activé pour chaque expérimentation : les données d'entrée sont synchronisées une seule fois et ne sont jamais resynchronisées. De plus, chaque expérimentation produira des résultats spécifiques qui devront être stockés dans un conteneur dédié. Pour chaque app, nous monterions alors un conteneur de sortie avec la permission rw et sans cache. Si un conteneur n'existe pas encore dans l'object storage, il est créé lors de la synchronisation des données.

En supposant que nos données se trouvent dans l'Object Storage de Gravelines (GRA), dans un conteneur nommé dataset, la commande serait désormais :

ovhai app run <registry-address>/<image-identifier>:<tag-name> \
    --volume dataset@GRA:/workspace/dataset:ro:cache \
    --volume output@GRA:/workspace/output:rw \

Attacher des ressources de calcul

Vous devez d'abord ajuster les ressources nécessaires à votre app en fonction de la tâche de votre modèle et de la charge de travail attendue. Pour cela, vous pouvez utiliser les flags --cpu ou --gpu.

Les flags --cpu et --gpu sont exclusifs. Si des ressources GPU sont spécifiées, le flag CPU est ignoré, et inversement.

Vous pouvez également utiliser le flag --flavor pour spécifier le type de ressources que vous souhaitez utiliser. Vous pouvez consulter la liste complète en exécutant ovhai capabilities flavor list. Si ce flag n'est pas spécifié, le modèle de CPU/GPU par défaut du cluster sur lequel vous soumettez votre app sera utilisé.

Par exemple, voici comment lancer une app s'exécutant sur 10 CPU dont l'id est ai1-1-cpu :

ovhai app run `<registry-address>`/<image-identifier>:`<tag-name>` \
    --cpu 10 \
    --flavor ai1-1-cpu

Stratégie de scaling

Pour votre app, vous pouvez choisir un scaling statique ou automatique.

Pour plus d'informations sur les stratégies de scaling statique et automatique, veuillez consulter cette documentation.

Quand choisir le scaling statique ?

La stratégie de scaling statique vous permet de choisir le nombre de réplicas sur lesquels l'app sera déployée. Pour cette méthode, le nombre minimum de réplicas est 1 et le maximum est 10.

• Le scaling statique peut être utilisé si vous souhaitez avoir des coûts fixes.
• Cette stratégie de scaling est également utile lorsque votre consommation ou votre charge d'inférence sont fixes.

Voici un exemple pour lancer votre app avec une stratégie de scaling statique, avec 2 réplicas :

ovhai app run <registry-address>/<image-identifier>:<tag-name> \
    --replicas 2

Quand choisir l'autoscaling ?

Avec la stratégie d'autoscaling, il est possible de choisir à la fois le nombre minimum de réplicas (1 par défaut) et le nombre maximum de réplicas. La haute disponibilité mesurera l'utilisation moyenne des ressources sur ses réplicas et ajoutera des instances si cette moyenne dépasse le seuil de pourcentage d'utilisation moyenne spécifié. À l'inverse, elle supprimera des instances lorsque cette utilisation moyenne des ressources passera en dessous du seuil. La métrique surveillée peut être CPU ou RAM, et le seuil est un pourcentage (entier compris entre 1 et 100).

• Vous pouvez utiliser l'autoscaling si vous avez des charges d'inférence irrégulières ou en dents de scie.

Voici un exemple pour lancer votre app avec une stratégie d'autoscaling, utilisant entre 2 et 12 réplicas selon un monitoring à 60 % de la RAM :

ovhai app run `<registry-address>`/<image-identifier>:`<tag-name>` \
    --auto-min-replicas 1 \
    --auto-max-replicas 12 \
    --auto-resource-type RAM \
    --auto-resource-usage-threshold 60

Définir des tokens et des labels

L'utilisation de tokens peut vous aider à partager votre app de façon sécurisée. Plus d'informations sur la création, la gestion et l'utilisation des tokens sont disponibles ici.

Pour ajouter un token à votre app, vous pouvez exécuter :

ovhai app run `<registry-address>`/<image-identifier>:`<tag-name>` \
    --token `<TOKEN>` 

Si votre token a été créé avec un sélecteur de label, il peut être intéressant d'assigner un label à votre app. Pour cela, ajoutez le paramètre :

ovhai app run `<registry-address>`/<image-identifier>:`<tag-name>` \
    --label <name=value>

Rendre votre app publique et la partager

Si vous souhaitez que votre app soit accessible sans authentification, ajoutez le paramètre --unsecure-http :

ovhai app run <registry-address>/<image-identifier>:<tag-name> \
    --unsecure-http 

Vous pouvez ensuite partager l'URL d'accès de votre app avec n'importe qui. Aucune authentification supplémentaire ne sera nécessaire pour y accéder.

Modifier le port d'accès par défaut

Lorsqu'une app est en cours d'exécution, une app_url lui est associée, vous permettant d'accéder à tout service exposé dans votre app. Par défaut, le port exposé pour cette URL est le 8080.

Cependant, si vous utilisez un framework qui utilise un autre port, il sera intéressant de surcharger celui utilisé par défaut. Par exemple, le port 8501 est le port par défaut utilisé par l'app streamlit. Nous utiliserons donc :

ovhai app run `<registry-address>`/<image-identifier>:`<tag-name>` \
    --name streamlit_app \
    --default-http-port 8501

Cela indiquera que le port à atteindre sur l'URL de l'app est le 8501.

Configurer un health check

Pour garantir la santé et la disponibilité de l'image Docker qui exécute votre app Python, il peut être intéressant de configurer un chemin de sonde (probe path) et un port de sonde (probe port). En effet, ces paramètres permettent d'effectuer efficacement des health checks, qui jouent un rôle crucial pour déterminer la disponibilité et l'état de votre app. Pour effectuer ces health checks, nous utiliserons des sondes (probes).

--probe-path : en définissant un chemin de sonde, vous définissez un endpoint URL spécifique au sein de votre app qui peut être accédé pour déterminer son état de santé. Cet endpoint doit être conçu pour répondre avec un code de statut HTTP approprié, indiquant si le container est en bonne santé ou non. Par exemple, une réponse réussie avec un code de statut HTTP 200 signifie un état sain, tandis que tout autre code de statut indique un problème.

--probe-port : le port de sonde spécifie le port réseau sur lequel l'app écoute les requêtes entrantes. Il permet d'établir une connexion avec le container et d'effectuer le health check.

Pour configurer votre health check, vous pouvez utiliser la commande suivante :

ovhai app run <registry-address>/<image-identifier>:<tag-name> \
    --probe-path <PATH> \
    --probe-port <PORT> 

Modifier le format de sortie

Lorsque vous utilisez la commande ovhai app run, de nombreuses informations vous sont fournies (id de l'app, lien de l'app, ressources de l'app, etc.). Vous pouvez afficher toutes ces informations dans un format spécifique, comme .json ou .yaml, en utilisant le paramètre --output. Voici un exemple avec un format json :

ovhai app run `<registry-address>`/<image-identifier>:`<tag-name>` \
    --output json

Aller plus loin

Pour en savoir plus sur la CLI et les commandes disponibles pour interagir avec votre app, consultez la présentation de ovhai.

Pour une formation ou une assistance technique sur la mise en œuvre de nos solutions, contactez votre commercial ou consultez la page Professional Services pour obtenir un devis et faire analyser votre projet par nos experts.

Votre avis nous intéresse !

N’hésitez pas à nous faire part de vos questions, retours et suggestions pour améliorer le service :

• Sur le serveur Discord OVHcloud