Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

# Comment utiliser SageMaker AI XGBoost
<a name="xgboost-how-to-use"></a>

Avec SageMaker l'IA, vous pouvez utiliser XGBoost comme algorithme ou framework intégré. Quand vous utilisez XGBoost en tant que cadre, vous bénéficiez d’une plus grande flexibilité et d’un accès à des scénarios plus avancés, car vous pouvez personnaliser vos propres scripts d’entraînement. Les sections suivantes décrivent comment utiliser XGBoost avec le SDK SageMaker Python et l' input/output interface de l'algorithme XGBoost. Pour plus d'informations sur l'utilisation de XGBoost depuis l'interface utilisateur Amazon SageMaker Studio Classic, consultez. [SageMaker JumpStart modèles préentraînés](studio-jumpstart.md)

**Topics**
+ [Utilisation de XGBoost en tant que cadre](#xgboost-how-to-framework)
+ [Utilisation de XGBoost en tant qu'algorithme intégré](#xgboost-how-to-built-in)
+ [Input/Output interface pour l'algorithme XGBoost](#InputOutput-XGBoost)

## Utilisation de XGBoost en tant que cadre
<a name="xgboost-how-to-framework"></a>

Utilisez XGBoost en tant que framework pour exécuter des scripts d'entraînement qui peuvent intégrer un traitement de données supplémentaire dans vos tâches d'entraînement. Dans l'exemple de code suivant, le SDK SageMaker Python fournit l'API XGBoost en tant que framework. Cela fonctionne de la même manière que l' SageMaker IA fournit d'autres API de framework TensorFlow, telles que MXnet et. PyTorch

```
import boto3
import sagemaker
from sagemaker.xgboost.estimator import XGBoost
from sagemaker.session import Session
from sagemaker.inputs import TrainingInput

# initialize hyperparameters
hyperparameters = {
        "max_depth":"5",
        "eta":"0.2",
        "gamma":"4",
        "min_child_weight":"6",
        "subsample":"0.7",
        "verbosity":"1",
        "objective":"reg:squarederror",
        "num_round":"50"}

# set an output path where the trained model will be saved
bucket = sagemaker.Session().default_bucket()
prefix = 'DEMO-xgboost-as-a-framework'
output_path = 's3://{}/{}/{}/output'.format(bucket, prefix, 'abalone-xgb-framework')

# construct a SageMaker AI XGBoost estimator
# specify the entry_point to your xgboost training script
estimator = XGBoost(entry_point = "{{your_xgboost_abalone_script.py}}", 
                    framework_version='{{1.7-1}}',
                    hyperparameters=hyperparameters,
                    role=sagemaker.get_execution_role(),
                    instance_count=1,
                    instance_type='ml.m5.2xlarge',
                    output_path=output_path)

# define the data type and paths to the training and validation datasets
content_type = "libsvm"
train_input = TrainingInput("s3://{}/{}/{}/".format(bucket, prefix, 'train'), content_type=content_type)
validation_input = TrainingInput("s3://{}/{}/{}/".format(bucket, prefix, 'validation'), content_type=content_type)

# execute the XGBoost training job
estimator.fit({'train': train_input, 'validation': validation_input})
```

Pour un exemple complet d'utilisation d' SageMaker AI XGBoost comme framework, consultez Régression [avec Amazon](https://sagemaker-examples.readthedocs.io/en/latest/introduction_to_amazon_algorithms/xgboost_abalone/xgboost_abalone_dist_script_mode.html) AI XGBoost. SageMaker 

## Utilisation de XGBoost en tant qu'algorithme intégré
<a name="xgboost-how-to-built-in"></a>

Utilisez l'algorithme intégré XGBoost pour créer un conteneur d'entraînement XGBoost comme indiqué dans l'exemple de code suivant. Vous pouvez détecter automatiquement l'URI de l'image de l'algorithme intégré à XGBoost à l'aide de l'API SageMaker AI`image_uris.retrieve`. Si vous utilisez le [SDK Amazon SageMaker Python](https://sagemaker.readthedocs.io/en/stable) version 1, utilisez l'`get_image_uri`API. Pour vous assurer que l’API `image_uris.retrieve` trouve le bon URI, consultez [Paramètres communs pour les algorithmes intégrés](https://docs.aws.amazon.com/sagemaker/latest/dg/sagemaker-algo-docker-registry-paths.html). Recherchez ensuite `xgboost` dans la liste complète des URI d’images d’algorithmes intégrés et des régions disponibles.

Après avoir spécifié l'URI de l'image XGBoost, utilisez le conteneur XGBoost pour créer un estimateur à l'aide de l'API SageMaker AI Estimator et lancer une tâche de formation. Ce mode d'algorithme intégré XGBoost n'intègre pas votre propre script d'entraînement XGBoost et s'exécute directement sur les jeux de données en entrée.

**Important**  
Lorsque vous récupérez l'URI de l'image SageMaker AI XGBoost, n'utilisez pas `:latest` ou `:1` pour la balise URI de l'image. Vous devez spécifier l'un des [Versions prises en charge](xgboost.md#xgboost-supported-versions) pour choisir le conteneur SageMaker AI-managed XGBoost avec la version native du package XGBoost que vous souhaitez utiliser. Pour trouver la version du package migrée vers les conteneurs SageMaker AI XGBoost, consultez les [chemins de registre Docker](https://docs.aws.amazon.com/sagemaker/latest/dg-ecr-paths/sagemaker-algo-docker-registry-paths.html) et les exemples de code. Choisissez ensuite votre Région AWS et accédez à la section **XGBoost (algorithme)**.

```
import sagemaker
import boto3
from sagemaker import image_uris
from sagemaker.session import Session
from sagemaker.inputs import TrainingInput

# initialize hyperparameters
hyperparameters = {
        "max_depth":"5",
        "eta":"0.2",
        "gamma":"4",
        "min_child_weight":"6",
        "subsample":"0.7",
        "objective":"reg:squarederror",
        "num_round":"50"}

# set an output path where the trained model will be saved
bucket = sagemaker.Session().default_bucket()
prefix = 'DEMO-xgboost-as-a-built-in-algo'
output_path = 's3://{}/{}/{}/output'.format(bucket, prefix, 'abalone-xgb-built-in-algo')

# this line automatically looks for the XGBoost image URI and builds an XGBoost container.
# specify the repo_version depending on your preference.
xgboost_container = sagemaker.image_uris.retrieve("xgboost", region, "{{1.7-1}}")

# construct a SageMaker AI estimator that calls the xgboost-container
estimator = sagemaker.estimator.Estimator(image_uri=xgboost_container, 
                                          hyperparameters=hyperparameters,
                                          role=sagemaker.get_execution_role(),
                                          instance_count=1, 
                                          instance_type='ml.m5.2xlarge', 
                                          volume_size=5, # 5 GB 
                                          output_path=output_path)

# define the data type and paths to the training and validation datasets
content_type = "libsvm"
train_input = TrainingInput("s3://{}/{}/{}/".format(bucket, prefix, 'train'), content_type=content_type)
validation_input = TrainingInput("s3://{}/{}/{}/".format(bucket, prefix, 'validation'), content_type=content_type)

# execute the XGBoost training job
estimator.fit({'train': train_input, 'validation': validation_input})
```

Pour plus d'informations sur la configuration de XGBoost en tant qu'algorithme intégré, consultez les exemples de bloc-notes suivants.
+ [Managed Spot Training for XGBoost](https://sagemaker-examples.readthedocs.io/en/latest/introduction_to_amazon_algorithms/xgboost_abalone/xgboost_managed_spot_training.html)
+ [Régression avec Amazon SageMaker AI XGBoost (entrée Parquet)](https://sagemaker-examples.readthedocs.io/en/latest/introduction_to_amazon_algorithms/xgboost_abalone/xgboost_parquet_input_training.html)

## Input/Output interface pour l'algorithme XGBoost
<a name="InputOutput-XGBoost"></a>

Le boosting de gradient fonctionne sur les données tabulaires, avec les lignes représentant les observations, une colonne représentant la variable ou l’étiquette cible, et les autres colonnes représentant les fonctions. 

L'implémentation SageMaker IA de XGBoost prend en charge les formats de données suivants pour l'entraînement et l'inférence :
+  *text/libsvm* (par défaut) 
+  *text/csv*
+  *application/x-parquet*
+  *application/x-recordio-protobuf*

**Note**  
Il y a quelques points à prendre en compte concernant l'entrée d'entraînement et d'inférence :  
Pour des performances accrues, nous vous recommandons d’utiliser XGBoost avec le *mode Fichier*, dans lequel vos données Amazon S3 sont stockées sur les volumes d’instances d’entraînement.
Pour l'entraînement avec une entrée sous forme de colonnes, l'algorithme suppose que la variable cible (étiquette) correspond à la première colonne. Pour l'inférence, l'algorithme suppose que l'entrée n'a pas de colonne d'étiquettes.
Pour des données CSV, l'entrée ne doit pas comporter d'enregistrement d'en-tête.
Pour l'entraînement LIBSVM, l'algorithme suppose que les colonnes suivantes, après la colonne d'étiquettes, contiennent les paires de valeurs d'index basé sur zéro pour les fonctionnalités. Par conséquent, chaque ligne a le format suivant : <label> <index0>:<value0> <index1>:<value1>.
Pour en savoir plus sur les types d'instance et l'entraînement distribué, consultez [Recommandation sur les instances EC2 pour l’algorithme XGBoost](xgboost.md#Instance-XGBoost).

Pour le mode d’entrée de l’entraînement CSV, la mémoire totale disponible pour l’algorithme doit être en mesure de contenir le jeu de données d’entraînement. La mémoire totale disponible est calculée comme suit : `Instance Count * the memory available in the InstanceType`. Pour le mode d'entrée de l'entraînement libsvm, ce n'est pas obligatoire, mais nous le recommandons.

Pour la version v1.3-1 et les versions ultérieures, SageMaker AI XGBoost enregistre le modèle dans le format binaire interne XGBoost, en utilisant. `Booster.save_model` Les versions précédentes utilisaient le module Python pickle pour serialize/deserialize le modèle.

**Note**  
Faites attention aux versions lorsque vous utilisez un modèle SageMaker AI XGBoost dans un XGBoost open source. Les versions 1.3-1 et ultérieures utilisent le format binaire interne XGBoost tandis que les versions précédentes utilisent le module pickle Python.

**Pour utiliser un modèle entraîné avec SageMaker AI XGBoost v1.3-1 ou version ultérieure dans le logiciel libre XGBoost**
+ Utilisez le code Python suivant :

  ```
  import xgboost as xgb
  
  xgb_model = xgb.Booster()
  xgb_model.load_model({{model_file_path}})
  xgb_model.predict({{dtest}})
  ```

**Pour utiliser un modèle entraîné avec les versions précédentes d' SageMaker AI XGBoost dans l'open source XGBoost**
+ Utilisez le code Python suivant :

  ```
  import pickle as pkl 
  import tarfile
  
  t = tarfile.open('model.tar.gz', 'r:gz')
  t.extractall()
  
  model = pkl.load(open({{model_file_path}}, 'rb'))
  
  # prediction with test data
  pred = model.predict({{dtest}})
  ```

**Pour différencier l'importance des points de données étiquetés, utilisez Instance Weight Supports**
+ SageMaker AI XGBoost permet aux clients de différencier l'importance des points de données étiquetés en attribuant à chaque instance une valeur de pondération. Pour la *text/libsvm*saisie, les clients peuvent attribuer des valeurs de poids aux instances de données en les attachant après les étiquettes. Par exemple, `label:weight idx_0:val_0 idx_1:val_1...`. Pour la *text/csv*saisie, les clients doivent activer le `csv_weights` drapeau dans les paramètres et associer les valeurs de poids dans la colonne après les étiquettes. Par exemple : `label,weight,val_0,val_1,...`).