> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-docs-weave-byob-note.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.
Ce tutoriel explique aux ingénieurs ML et aux administrateurs de plateforme comment configurer W\&B Launch pour soumettre des tâches d'entraînement à Amazon SageMaker. À la fin, vous disposerez des ressources AWS, des rôles IAM, de la configuration de la file d’attente et de l’agent Launch nécessaires pour exécuter des tâches d'entraînement SageMaker depuis W\&B.
Vous pouvez utiliser W\&B Launch pour soumettre des jobs Launch à 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 gère le provisionnement et la libération des ressources de calcul, ce qui peut en faire un bon choix pour les équipes qui ne disposent pas d'un cluster EKS.
Une file d’attente Launch W\&B connectée à Amazon SageMaker exécute les jobs Launch sous forme de SageMaker Training Jobs avec 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). Vous devez stocker dans Amazon Elastic Container Registry (ECR) les images extraites par SageMaker. Cela signifie que vous devez stocker sur ECR l'image que vous utilisez pour l'entraînement.
Ce guide montre 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 job Launch](https://github.com/wandb/launch-jobs/tree/main/jobs/deploy_to_sagemaker_endpoints).
## Prérequis
Avant de commencer, vous devez 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-image).
* [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-the-launch-agent).
Les sections suivantes expliquent comment remplir chaque prérequis.
### Décidez si vous voulez que l’agent Launch crée une image Docker
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, à téléverser l’image vers 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.
* Utilisez 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 devez téléverser manuellement votre image Docker dans votre registre de conteneurs Amazon ECR.
### Configurer les ressources AWS
Vous devez avoir configuré les ressources AWS suivantes 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.
Consignez 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).
### Créer une stratégie IAM pour l'agent Launch
L'agent Launch nécessite une stratégie IAM qui accorde les autorisations requises pour soumettre des tâches d'entraînement SageMaker et, éventuellement, téléverser des images vers ECR. Suivez les étapes ci-dessous pour créer la stratégie :
1. Depuis la page IAM dans AWS, créez une stratégie.
2. Basculez vers l'éditeur de stratégie JSON, puis collez la stratégie suivante selon votre cas d'utilisation. Remplacez les espaces réservés entre `[CROCHETS]` par vos propres valeurs :
```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/[ROLE-ARN-FROM-QUEUE-CONFIG]"
},
{
"Effect": "Allow",
"Action": "kms:CreateGrant",
"Resource": "[ARN-OF-KMS-KEY]",
"Condition": {
"StringEquals": {
"kms:ViaService": "SageMaker.[REGION].amazonaws.com",
"kms:GrantIsForAWSResource": "true"
}
}
}
]
}
```
```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/[ROLE-ARN-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"
}
}
}
]
}
```
3. Cliquez sur **Next**.
4. Donnez un nom et une description à la stratégie.
5. Cliquez sur **Create policy**.
Vous disposez maintenant d'une stratégie IAM que vous pouvez associer au rôle de l'agent Launch dans la section suivante.
### Créer un rôle IAM pour l'agent Launch
L'agent Launch doit disposer des autorisations nécessaires pour créer des tâches d'entraînement Amazon SageMaker. En attachant la stratégie que vous avez créée dans la section précédente à un rôle dédié, vous permettez à l'agent d'utiliser ces autorisations au moment de l'exécution. 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 avez créée dans la section précédente.
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).
* 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.
## Configurer la file d’attente Launch pour SageMaker
Une fois les prérequis AWS en place, vous pouvez créer la file d’attente Launch de W\&B qui achemine les tâches vers SageMaker. Créez une file d’attente dans W\&B App qui utilise SageMaker comme ressource de calcul :
1. Accédez à la [Launch App](https://wandb.ai/launch).
2. Cliquez sur **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**, fournissez des informations sur votre tâche 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 les [prérequis](#prerequisites)). Ne le confondez pas avec le rôle IAM de l’**agent** Launch.
* `OutputDataConfig.S3OutputPath` : un URI Amazon S3 qui indique où SageMaker stocke les données de sortie.
* `ResourceConfig` : spécification requise d’une configuration de ressource. Pour connaître les options de configuration de ressource, voir la [documentation AWS `ResourceConfig`](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. Pour connaître les options, voir la [documentation AWS `StoppingCondition`](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_StoppingCondition.html).
7. Cliquez sur **Create Queue**.
Votre file d’attente est créée et prête à recevoir des tâches une fois que vous avez configuré un agent Launch pour l’interroger.
## Configurer l’agent Launch
Les sections suivantes décrivent où vous pouvez déployer votre agent et comment le configurer en fonction de l’endroit où vous le déployez.
Vous disposez de [plusieurs options pour déployer 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](#configure-a-launch-agent) en fonction de l’endroit où vous le déployez.
### Décidez où exécuter l’agent Launch
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 fonctionne en permanence, l’agent n’a pas besoin de plus d’une instance EC2 de type `t2.micro`, ce qui reste abordable.
Pour des cas d’usage expérimentaux ou une utilisation individuelle, vous pouvez exécuter l’agent Launch sur votre machine locale pour démarrer rapidement.
En fonction de votre cas d’usage, suivez les instructions dans les onglets suivants pour configurer votre agent Launch :
W\&B recommande d’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.
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**. Vous pouvez éventuellement ajouter une balise.
3. Dans **Instance type**, sélectionnez un type d’instance pour votre instance 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é 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éé dans la section précédente.
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**). Après avoir confirmé que votre instance EC2 est en cours d’exécution, ouvrez le terminal de votre machine locale et procédez comme suit :
1. Sélectionnez **Connect**.
2. Sélectionnez l’onglet **SSH client** et suivez les instructions 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 configurer le fichier de configuration de l’agent Launch.
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]
```
Les jetons de session ont une [durée maximale](https://docs.aws.amazon.com/cli/latest/reference/sts/get-session-token.html#description) de 1 heure ou 3 jours, selon le principal associé.
### Configurer un agent Launch
Après avoir choisi où exécuter l’agent, configurez-le afin qu’il puisse interroger votre file d’attente SageMaker et s’authentifier auprès d’AWS. 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`.
Votre agent Launch est maintenant en cours d’exécution et interroge la file d’attente SageMaker à la recherche de jobs.
## Facultatif : Téléversez l’image Docker de votre job Launch vers Amazon ECR
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. [Votre agent Launch prend en charge deux options de comportement.](#decide-if-you-want-the-launch-agent-to-build-a-docker-image)
Envoyez vers votre dépôt Amazon ECR l’image Docker qui contient votre job Launch. 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 jobs Launch.
{/* ## Lancer des jobs depuis W&B
Si vous vous rendez dans l’interface W&B, votre file d’attente Launch SageMaker sera désormais active. Vous pouvez y soumettre des jobs depuis l’UI ou le CLI. */}