> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-docs-1917.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tutoriel : Configurer W&B Launch sur SageMaker

> Configurez W&B Launch pour soumettre des tâches d'entraînement à Amazon SageMaker, avec des instructions de configuration pour ECR, S3 et IAM.

Vous pouvez utiliser W\&B Launch pour soumettre des launch jobs à Amazon SageMaker afin d’entraîner des modèles de machine learning à l’aide d’algorithmes fournis ou personnalisés sur la plateforme SageMaker. SageMaker se charge de provisionner et de libérer les ressources de calcul, ce qui peut en faire un bon choix pour les équipes qui ne disposent pas de cluster EKS.

Les launch jobs envoyés à une file d’attente W\&B Launch connectée à Amazon SageMaker sont exécutés comme des SageMaker Training Jobs via l’API [CreateTrainingJob](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html). Utilisez la configuration de la file d’attente Launch pour contrôler les arguments envoyés à l’API `CreateTrainingJob`.

Amazon SageMaker [utilise des images Docker pour exécuter des tâches d’entraînement](https://docs.aws.amazon.com/sagemaker/latest/dg/your-algorithms-training-algo-dockerfile.html). Les images récupérées par SageMaker doivent être stockées dans Amazon Elastic Container Registry (ECR). Cela signifie que l’image utilisée pour l’entraînement doit être stockée dans ECR.

<Note>
  Ce guide explique comment exécuter des SageMaker Training Jobs. Pour savoir comment déployer des modèles pour l’inférence sur Amazon SageMaker, voir [cet exemple de launch job](https://github.com/wandb/launch-jobs/tree/main/jobs/deploy_to_sagemaker_endpoints).
</Note>

<div id="prerequisites">
  ## Prérequis
</div>

Avant de commencer, assurez-vous de remplir les prérequis suivants :

* [Déterminez si vous souhaitez que l’agent Launch crée une image Docker pour vous.](#decide-if-you-want-the-launch-agent-to-build-a-docker-images)
* [Configurez les ressources AWS et rassemblez des informations sur les rôles IAM de S3, ECR et SageMaker.](#set-up-aws-resources)
* [Créez un rôle IAM pour l’agent Launch](#create-an-iam-role-for-launch-agent).

<div id="decide-if-you-want-the-launch-agent-to-build-a-docker-images">
  ### Décidez si vous voulez que l’agent Launch crée une image Docker
</div>

Décidez si vous voulez que l’agent Launch de W\&B crée une image Docker pour vous. Vous avez le choix entre deux options :

* Autoriser l’agent Launch à créer une image Docker, à publier l’image sur Amazon ECR et à soumettre des jobs [SageMaker Training](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html) pour vous. Cette option peut simplifier le travail des ingénieurs ML qui itèrent rapidement sur leur code d’entraînement.
* L’agent Launch utilise une image Docker existante qui contient vos scripts d’entraînement ou d’inférence. Cette option s’intègre bien aux systèmes CI existants. Si vous choisissez cette option, vous devrez téléverser manuellement votre image Docker dans votre registre de conteneurs Amazon ECR.

<div id="set-up-aws-resources">
  ### Configurer les ressources AWS
</div>

Assurez-vous que les ressources AWS suivantes sont configurées dans la région AWS de votre choix :

1. Un [dépôt Amazon ECR](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-create.html) pour stocker les images de conteneur.
2. Un ou plusieurs [buckets S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) pour stocker les données d’entrée et de sortie de vos tâches d’entraînement SageMaker.
3. Un rôle IAM pour Amazon SageMaker qui permet à SageMaker d’exécuter des tâches d’entraînement et d’interagir avec Amazon ECR et Amazon S3.

Notez les ARN de ces ressources. Vous en aurez besoin lorsque vous définirez la [configuration de la file d’attente Launch](#configure-launch-queue-for-sagemaker).

<div id="create-a-iam-policy-for-launch-agent">
  ### Créer une stratégie IAM pour l'agent Launch
</div>

1. Dans l'écran IAM d'AWS, créez une nouvelle stratégie.
2. Basculez vers l'éditeur de stratégie JSON, puis collez la stratégie suivante selon votre cas d'usage. Remplacez les valeurs entre `<>` par vos propres valeurs :

<Tabs>
  <Tab title="L'agent soumet une image Docker déjà construite">
    ```json theme={null}
      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Effect": "Allow",
            "Action": [
              "logs:DescribeLogStreams",
              "SageMaker:AddTags",
              "SageMaker:CreateTrainingJob",
              "SageMaker:DescribeTrainingJob"
            ],
            "Resource": "arn:aws:sagemaker:<region>:<account-id>:*"
          },
          {
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": "arn:aws:iam::<account-id>:role/<RoleArn-from-queue-config>"
          },
        {
            "Effect": "Allow",
            "Action": "kms:CreateGrant",
            "Resource": "<ARN-OF-KMS-KEY>",
            "Condition": {
              "StringEquals": {
                "kms:ViaService": "SageMaker.<region>.amazonaws.com",
                "kms:GrantIsForAWSResource": "true"
              }
            }
          }
        ]
      }
    ```
  </Tab>

  <Tab title="L'agent construit et soumet une image Docker">
    ```json theme={null}
      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Effect": "Allow",
            "Action": [
              "logs:DescribeLogStreams",
              "SageMaker:AddTags",
              "SageMaker:CreateTrainingJob",
              "SageMaker:DescribeTrainingJob"
            ],
            "Resource": "arn:aws:sagemaker:<region>:<account-id>:*"
          },
          {
            "Effect": "Allow",
            "Action": "iam:PassRole",
            "Resource": "arn:aws:iam::<account-id>:role/<RoleArn-from-queue-config>"
          },
           {
          "Effect": "Allow",
          "Action": [
            "ecr:CreateRepository",
            "ecr:UploadLayerPart",
            "ecr:PutImage",
            "ecr:CompleteLayerUpload",
            "ecr:InitiateLayerUpload",
            "ecr:DescribeRepositories",
            "ecr:DescribeImages",
            "ecr:BatchCheckLayerAvailability",
            "ecr:BatchDeleteImage"
          ],
          "Resource": "arn:aws:ecr:<region>:<account-id>:repository/<repository>"
        },
        {
          "Effect": "Allow",
          "Action": "ecr:GetAuthorizationToken",
          "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": "kms:CreateGrant",
            "Resource": "<ARN-OF-KMS-KEY>",
            "Condition": {
              "StringEquals": {
                "kms:ViaService": "SageMaker.<region>.amazonaws.com",
                "kms:GrantIsForAWSResource": "true"
              }
            }
          }
        ]
      }
    ```
  </Tab>
</Tabs>

3. Cliquez sur **Suivant**.
4. Donnez un nom et une description à la stratégie.
5. Cliquez sur **Créer une stratégie**.

<div id="create-an-iam-role-for-launch-agent">
  ### Créer un rôle IAM pour l'agent Launch
</div>

L'agent Launch doit disposer des autorisations nécessaires pour créer des tâches d'entraînement Amazon SageMaker. Suivez la procédure ci-dessous pour créer un rôle IAM :

1. Dans l'écran IAM d'AWS, créez un rôle.
2. Pour **Trusted Entity**, sélectionnez **AWS Account** (ou une autre option conforme aux politiques de votre organisation).
3. Faites défiler l'écran des autorisations et sélectionnez le nom de la stratégie que vous venez de créer.
4. Donnez un nom et une description au rôle.
5. Sélectionnez **Create role**.
6. Notez l'ARN du rôle. Vous indiquerez cet ARN lorsque vous configurerez l'agent Launch.

Pour créer des rôles IAM, consultez la [documentation AWS Identity and Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html).

<Note>
  * Si vous voulez que l'agent Launch crée des images, consultez [Configuration avancée de l'agent](./setup-agent-advanced) pour connaître les autorisations supplémentaires requises.
  * L'autorisation `kms:CreateGrant` pour les files d'attente SageMaker n'est requise que si le ResourceConfig associé a un VolumeKmsKeyId spécifié et que le rôle associé n'a pas de stratégie autorisant cette action.
</Note>

<div id="configure-launch-queue-for-sagemaker">
  ## Configurer une file d’attente Launch pour SageMaker
</div>

Ensuite, créez une file d'attente dans la W\&B App qui utilise SageMaker comme ressource de calcul :

1. Accédez à la [Launch App](https://wandb.ai/launch).
2. Cliquez sur le bouton **Create Queue**.
3. Sélectionnez l'**Entity** dans laquelle vous souhaitez créer la file d'attente.
4. Saisissez un nom pour votre file d'attente dans le champ **Name**.
5. Sélectionnez **SageMaker** comme **Resource**.
6. Dans le champ **Configuration**, indiquez les informations concernant votre job SageMaker. Par défaut, W\&B préremplit un corps de requête `CreateTrainingJob` en YAML et en JSON :
   ```json theme={null}
   {
     "RoleArn": "<REQUIRED>", 
     "ResourceConfig": {
         "InstanceType": "ml.m4.xlarge",
         "InstanceCount": 1,
         "VolumeSizeInGB": 2
     },
     "OutputDataConfig": {
         "S3OutputPath": "<REQUIRED>"
     },
     "StoppingCondition": {
         "MaxRuntimeInSeconds": 3600
     }
   }
   ```

Vous devez au minimum spécifier :

* `RoleArn` : l'ARN du rôle IAM d'exécution SageMaker (voir [prérequis](#prerequisites)). À ne pas confondre avec le rôle IAM de l'**agent** Launch.
* `OutputDataConfig.S3OutputPath` : un URI Amazon S3 indiquant l'emplacement où les sorties SageMaker seront stockées.
* `ResourceConfig` : spécification requise d'une configuration de ressources. Les options de configuration des ressources sont décrites [ici](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ResourceConfig.html).
* `StoppingCondition` : spécification requise des conditions d'arrêt de la tâche d'entraînement. Les options sont décrites [ici](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_StoppingCondition.html).

7. Cliquez sur le bouton **Create Queue**.

<div id="set-up-the-launch-agent">
  ## Configurer l’agent Launch
</div>

La section suivante décrit où vous pouvez déployer votre agent et comment le configurer en fonction de son emplacement de déploiement.

Il existe [plusieurs options pour le déploiement de l’agent Launch pour une file d’attente Amazon SageMaker](#decide-where-to-run-the-launch-agent) : sur une machine locale, sur une instance EC2 ou dans un cluster EKS. [Configurez votre agent Launch en conséquence](#configure-a-launch-agent) selon l’endroit où vous le déployez.

<div id="decide-where-to-run-the-launch-agent">
  ### Choisissez où exécuter l'agent Launch
</div>

Pour les charges de travail de production et pour les clients qui disposent déjà d'un cluster EKS, W\&B recommande de déployer l'agent Launch sur le cluster EKS à l'aide de ce chart Helm.

Pour les charges de travail de production sans cluster EKS existant, une instance EC2 est une bonne option. Bien que l'instance de l'agent Launch reste en fonctionnement en permanence, l'agent n'a pas besoin de plus qu'une instance EC2 de type `t2.micro`, ce qui reste relativement abordable.

Pour des cas d'utilisation expérimentaux ou individuels, exécuter l'agent Launch sur votre machine locale peut être un moyen rapide de démarrer.

En fonction de votre cas d'utilisation, suivez les instructions fournies dans les onglets suivants pour configurer correctement votre agent Launch :

<Tabs>
  <Tab title="EKS">
    W\&B vous encourage vivement à utiliser le [chart Helm géré par W\&B](https://github.com/wandb/helm-charts/tree/main/charts/launch-agent) pour installer l'agent dans un cluster EKS.
  </Tab>

  <Tab title="EC2">
    Accédez au tableau de bord Amazon EC2 et effectuez les étapes suivantes :

    1. Cliquez sur **Launch instance**.
    2. Saisissez un nom dans le champ **Name**. Ajoutez éventuellement un tag.
    3. Dans **Instance type**, sélectionnez un type d'instance pour votre conteneur EC2. Vous n'avez pas besoin de plus de 1 vCPU et 1 GiB de mémoire (par exemple, une t2.micro).
    4. Créez une paire de clés pour votre organisation dans le champ **Key pair (login)**. Vous utiliserez cette paire de clés pour [vous connecter à votre instance EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect.html) avec un client SSH à une étape ultérieure.
    5. Dans **Network settings**, sélectionnez un groupe de sécurité approprié pour votre organisation.
    6. Développez **Advanced details**. Pour **IAM instance profile**, sélectionnez le rôle IAM de l'agent Launch que vous avez créé ci-dessus.
    7. Vérifiez le champ **Summary**. Si tout est correct, sélectionnez **Launch instance**.

    Accédez à **Instances** dans le panneau de gauche du tableau de bord EC2 sur AWS. Assurez-vous que l'instance EC2 que vous avez créée est en cours d'exécution (voir la colonne **Instance state**). Une fois que vous avez confirmé que votre instance EC2 est en cours d'exécution, ouvrez le terminal de votre machine locale et effectuez les opérations suivantes :

    1. Sélectionnez **Connect**.
    2. Sélectionnez l'onglet **SSH client** et suivez les instructions indiquées pour vous connecter à votre instance EC2.
    3. Dans votre instance EC2, installez les packages suivants :
       ```bash theme={null}
       sudo yum install python311 -y && python3 -m ensurepip --upgrade && pip3 install wandb && pip3 install wandb[launch]
       ```
    4. Ensuite, installez et démarrez Docker dans votre instance EC2 :
       ```bash theme={null}
       sudo yum update -y && \
       sudo yum install -y docker python3 && \
       sudo systemctl start docker && \
       sudo systemctl enable docker && \
       sudo usermod -a -G docker ec2-user

       newgrp docker
       ```

    Vous pouvez maintenant passer à la configuration de l'agent Launch.
  </Tab>

  <Tab title="Machine locale">
    Utilisez les fichiers de configuration AWS situés dans `~/.aws/config` et `~/.aws/credentials` pour associer un rôle à un agent exécuté sur une machine locale. Fournissez l'ARN du rôle IAM que vous avez créé pour l'agent Launch à l'étape précédente.

    ```yaml title="~/.aws/config" theme={null}
    [profile SageMaker-agent]
    role_arn = arn:aws:iam::<account-id>:role/<agent-role-name>
    source_profile = default                                                                   
    ```

    ```yaml title="~/.aws/credentials" theme={null}
    [default]
    aws_access_key_id=<access-key-id>
    aws_secret_access_key=<secret-access-key>
    aws_session_token=<session-token>
    ```

    Notez que les jetons de session ont une [durée maximale](https://docs.aws.amazon.com/cli/latest/reference/sts/get-session-token.html#description) d'1 heure ou de 3 jours selon le principal auquel ils sont associés.
  </Tab>
</Tabs>

<div id="configure-a-launch-agent">
  ### Configurer un agent Launch
</div>

Configurez l’agent Launch à l’aide d’un fichier de configuration YAML nommé `launch-config.yaml`.

Par défaut, W\&B recherche le fichier de configuration dans `~/.config/wandb/launch-config.yaml`. Vous pouvez également indiquer un autre répertoire lorsque vous activez l’agent Launch avec l’option `-c`.

L’extrait YAML suivant montre comment spécifier les options de configuration de base de l’agent :

```yaml title="launch-config.yaml" theme={null}
max_jobs: -1
queues:
  - <queue-name>
environment:
  type: aws
  region: <your-region>
registry:
  type: ecr
  uri: <ecr-repo-arn>
builder: 
  type: docker

```

Démarrez maintenant l’agent avec `wandb launch-agent`

<div id="optional-push-your-launch-job-docker-image-to-amazon-ecr">
  ## (Facultatif) Envoyez l'image Docker de votre launch job vers Amazon ECR
</div>

<Note>
  Cette section s'applique uniquement si votre agent Launch utilise des images Docker existantes qui contiennent votre logique d'entraînement ou d'inférence. [Deux options sont possibles pour le comportement de votre agent Launch.](#decide-if-you-want-the-launch-agent-to-build-a-docker-images)
</Note>

Envoyez vers votre dépôt Amazon ECR l'image Docker qui contient votre launch job. Si vous utilisez des jobs basés sur des images, votre image Docker doit déjà se trouver dans votre registre ECR avant que vous ne soumettiez de nouveaux launch jobs.

{/* ## Lancer des jobs depuis W&B

Si vous vous rendez dans l’interface W&B, votre file d’attente SageMaker de Launch sera désormais active. Vous pouvez y soumettre des jobs depuis l’UI ou le CLI. */}