はじめに

一度はドキュメントの内容を通しで読んでみたかった。
完全に自分用なので、ほかの人の役には立たないと思います。
自分の解釈は * で示しています。たまにコンソールのスクショを載せています。
ドキュメントのすべてを記載しているわけではありません。

SageMaker ノートブックインスタンス

• Jupyter Notebook アプリを実行するMLコンピューティングインスタンス
• EC2でJupyterサーバを起動し、SageMaker Python SDK、AWS SDK for Python（Boto3）、AWS CLI、Conda、Pandas、ディープラーニングフレームワークライブラリなどのパッケージを含む事前構成済みのカーネルを提供
• 次のことができる
  • データの準備と処理
  • モデルをトレーニングするためのコードを書く
  • SageMakerホスティングにモデルをデプロイ
  • モデルをテスト・検証
• メンテナンス
  • ノートブックインスタンスの基盤となるソフトウェアを少なくとも90日に1回更新する
  • OSのアップグレードなど一部のメンテナンス更新では、アプリを短時間オフラインにする必要がある
  • 基盤となるソフトウェアが更新されている間は、この期間中に操作を実行することはできない
  • パッチを自動的に適用するには、少なくとも30日に1回ノートブックを再起動することを推奨
• SageMaker Python SDK を利用したML
  • MLモデルをトレーニング、検証、デプロイ、評価できる
  • AWS SDKfor Python（Boto3）とSageMaker API操作を抽象化

https://docs.aws.amazon.com/sagemaker/latest/dg/nbi.html

ノートブックインスタンスと使用してモデルを構築するためのチュートリアル

• ノートブックインスタンスを作成し、Conda環境で事前設定されたカーネルを含むJupyterノートブックを平木、SageMaker AIセッションを開始してエンドツーエンドのMLサイクルを実行する

https://docs.aws.amazon.com/sagemaker/latest/dg/gs-console.html

ノートブックインスタンスを作成する（チュートリアル）

• ノートブックインスタンスは、フルマネージドのML EC2 インスタンスで、Jupyter Notebook アプリケーションを実行する
• 作成時に選択する情報
  • ノートブックインスタンス名
  • ノートブックインスタンスタイプ
  • プラットフォーム識別子
    • OSとJupyterLabバージョンを定義
  • IAMロール
• ノートブックインスタンスを作成すると、5GBのEBSをインスタンスにアタッチする
• ノートブックインスタンスには、事前設定されたJupyterノートブックサーバ、SageMaker AI および AWS SDK ライブラリ、Anacondaライブラリのセットが含まれる
• ノートブックインスタンスの設定を変更する
  • ノートブックインスタンスを停止し、設定を更新する
  • ノートブックインスタンスタイプ、EBSボリュームサイズを変更できる
    • EBSボリュームは暗号化されているため、SageMaker AI は使用可能な空き容量を判断できない
    • そのため、ボリュームサイズを増やすことはできるが、減らすことはできない
    • ボリュームのサイズを小さくしたい場合は、必要なサイズの新しいノートブックインスタンスを作成する

https://docs.aws.amazon.com/sagemaker/latest/dg/gs-setup-working-env.html

ノートブックインスタンスにJupyterノートブックを作成（チュートリアル）

• ノートブックインスタンスページで、ノートブックインスタンスを開く
  • JupyterLabインターフェースのJupyterLabを開く
    • ファイルメニューで新規を選択し、ノートブックを選択
    • カーネルの選択で conda_python3 を選択
    • ファイルを選択し、ノートブックに名前をつけて保存する
  • Jupyterを開いてクラシックなJupyterビューを開く
    • ファイルタブで新規を選択し、conda_python3 を選択
    • ファイル、名前をつけて保存の順に選択して保存する

https://docs.aws.amazon.com/sagemaker/latest/dg/ex1-prepare.html

データセットを準備（チュートリアル）

• このステップでは成人国勢調査データセットをロードする
• SHAP( SHapley Additive exPlaneations）ライブラリを使用してデータセットを追加・確認・変換してS3にアップロードする
  • SHAP: MLモデルの出力を説明するゲーム理論的アプローチ
• SHAPを使用して、成人国勢調査データセットをインポート

import shap
X, y = shap.datasets.adult()
X_display, y_display = shap.datasets.adult(display=True)
feature_names = list(X.columns)
feature_names

• 現在のJupyterカーネルにSHAPライブラリがない場合、次のcondaコマンドを使用してインストールする

%conda install -c conda-forge shap

• JupyterLabを使用している場合は、インストールと更新が完了した後にカーネルを手動で更新する必要がある。次のIPythonスクリプトを実行してカーネルをシャットダウンする（カーネルは自動的に再起動する）

import IPython
IPython.Application.instance().kernel.do_shutdown(True)

• リスト feature_names オブジェクトは次の特徴のリストを返す必要がある

['Age',
 'Workclass',
 'Education-Num',
 'Marital Status',
 'Occupation',
 'Relationship',
 'Race',
 'Sex',
 'Capital Gain',
 'Capital Loss',
 'Hours per week',
 'Country']

• ラベル付けされていないデータから始める場合は、SageMaker Ground Truthを使用して数分でデータラベル付けワークフローを作成できる
• データセットの概要
  • 次のスクリプトを実行して、データセットの統計概要と数値特徴のヒストグラムを表示

display(X.describe())
hist = X.hist(bins=30, sharey=True, figsize=(20, 10))

• クリーンアップと変換に必要なデータセットを使用する場合は、SageMaker Data Wrangler を使用してデータの前処理と特徴量エンジニアリングを簡素化・合理化できる
• データセットをトレーニング、検証、テストデータセットに分割する
• Sklearnを用いて、データセットをトレーニングデータセットとテストセットに分割する
• トレーニングセットはモデルのトレーニングに使用され、テストセットは最終的なトレーニング済みモデルのパフォーマンスを評価するために利用される
• データセットは固定のランダムシードを使用してランダムに並べ替えられる
  • データセットの80%がトレーニングセットに、20%がテストセットに使用される

from sklearn.model_selection import train_test_split
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=1)
X_train_display = X_display.loc[X_train.index]

• トレーニングセットを分割して検証セットを分離する
• 検証セットはモデルのハイパーパラメータを調整しながら、トレーニング済みモデルのパフォーマンスを評価するために使用される
• トレーニングセットの75%が最終的なトレーニングセットになり、残りが検証セットになる

X_train, X_val, y_train, y_val = train_test_split(X_train, y_train, test_size=0.25, random_state=1)
X_train_display = X_display.loc[X_train.index]
X_val_display = X_display.loc[X_val.index]

• Pandas パッケージを使用して、数値特徴を実際のラベルと連結することにより、各データセットを明示的に整列させる

import pandas as pd
train = pd.concat([pd.Series(y_train, index=X_train.index,
                             name='Income>50K', dtype=int), X_train], axis=1)
validation = pd.concat([pd.Series(y_val, index=X_val.index,
                            name='Income>50K', dtype=int), X_val], axis=1)
test = pd.concat([pd.Series(y_test, index=X_test.index,
                            name='Income>50K', dtype=int), X_test], axis=1)

• データセットが期待通りに分割され、構造化されているかどうかを確認する

train
validation
test

• XGBoost アルゴリズムの入力ファイル形式に合わせて、トレーニングセットと検証データセットのデータフレームオブジェクトををCSVファイルに変換する

# Use 'csv' format to store the data
# The first column is expected to be the output column
train.to_csv('train.csv', index=False, header=False)
validation.to_csv('validation.csv', index=False, header=False)

• データセットをS3にアップロードする
• S3のデータセットは、EC2上のSageMakerインスタンスによってトレーニングに使用される

import sagemaker, boto3, os
bucket = sagemaker.Session().default_bucket()
prefix = "demo-sagemaker-xgboost-adult-income-prediction"

boto3.Session().resource('s3').Bucket(bucket).Object(
    os.path.join(prefix, 'data/train.csv')).upload_file('train.csv')
boto3.Session().resource('s3').Bucket(bucket).Object(
    os.path.join(prefix, 'data/validation.csv')).upload_file('validation.csv')

https://docs.aws.amazon.com/sagemaker/latest/dg/ex1-preprocess-data.html

モデルをトレーニングする（チュートリアル）

• トレーニングアルゴリズムを選択し、モデルのトレーニングジョブを実行する
• トレーニングアルゴリズムを選択
  • データセットに適したアルゴリズムを選択するには、通常、様々なモデルを評価して、データに最も適したモデルを見つける必要がある
  • このチュートリアルでは、簡単にするために事前評価を行わずにSageMaker AI XGBoostアルゴリズムを使用する
• トレーニングジョブを実行する
• SageMaker Python SDK をインポートし、現在のSageMaker AIセッションから基本情報を取得する

import sagemaker

region = sagemaker.Session().boto_region_name
print("AWS Region: {}".format(region))

role = sagemaker.get_execution_role()
print("RoleArn: {}".format(role))

• 次の情報が返される
  • region: ノートブックインスタンスが実行されているAWSリージョン
  • role:ノートブックインスタンスで実行されているIAMロール
• sagemaker.__version__を実行して、SageMaker Python SDK のバージョンを確認できる
  • このチュートリアルはsagemaker>=2.20に基づいているため、古い場合は次のコマンドを実行して最新バージョンをインストールする
    • インストール後は、カーネルを手動で更新してバージョン更新の適用を完了する必要がある

! pip install -qU sagemaker

• sagemaker.estimator.Estimatorクラスを使用して、XGBoost推定器を作成

from sagemaker.debugger import Rule, ProfilerRule, rule_configs
from sagemaker.session import TrainingInput

s3_output_location='s3://{}/{}/{}'.format(bucket, prefix, 'xgboost_model')

container=sagemaker.image_uris.retrieve("xgboost", region, "1.2-1")
print(container)

xgb_model=sagemaker.estimator.Estimator(
    image_uri=container,
    role=role,
    instance_count=1,
    instance_type='ml.m4.xlarge',
    volume_size=5,
    output_path=s3_output_location,
    sagemaker_session=sagemaker.Session(),
    rules=[
        Rule.sagemaker(rule_configs.create_xgboost_report()),
        ProfilerRule.sagemaker(rule_configs.ProfilerReport())
    ]
)

• 次のパラメータを指定している
  • image_url: トレーニングコンテナイメージのURL
  • role: SageMaker AIがユーザーに代わってタスクを実行するIAMロール
  • instance_count,instance_type: モデルのトレーニングに使用するEC2 MLインスタンスのタイプと数
  • volume_size: インスタンスにアタッチするEBSのサイズ
    • Fileモードを使用する場合、トレーニングデータを保存するのに十分な大きさである必要がある
    • このパラメータを指定しない場合、デフォルトで30になる
  • output_path: モデル成果物とトレーニング結果を保存するS3のパス
  • sagemaker_session: トレーニングジョブが使用するSageMaker API操作やその他のAWSサービスとのやり取りを管理するセッションオブジェクト
  • rules: SageMaker Debuggerの組み込みルールのリストを指定
    • create_xgboost_report()ルールがトレーニングの進捗と結果に関する洞察を提供するレポートを作成
    • ProfilerReport()ルールがEC2の計算リソース使用率に関するレポートを作成
• 大規模なディープラーニングモデルの分散トレーニングを実行する場合は、データ並列処理またはモデル並列処理にSageMaker AI Distributed を使用
• 推定器のメソッドを呼び出して、XGBoost アルゴリズムのハイパーパラメータを設定

xgb_model.set_hyperparameters(
    max_depth = 5,
    eta = 0.2,
    gamma = 4,
    min_child_weight = 6,
    subsample = 0.7,
    objective = "binary:logistic",
    num_round = 1000
)

• TrainingInputクラスを使用して、トレーニング用のデータ入力フローを設定

from sagemaker.session import TrainingInput

train_input = TrainingInput(
    "s3://{}/{}/{}".format(bucket, prefix, "data/train.csv"), content_type="csv"
)
validation_input = TrainingInput(
    "s3://{}/{}/{}".format(bucket, prefix, "data/validation.csv"), content_type="csv"
)

• モデルのトレーニングを開始する
  • fitメソッドにwait=Trueを設定すると、進行状況ログを表示し、トレーニングが完了するまで待機する

xgb_model.fit({"train": train_input, "validation": validation_input}, wait=True)

• このチュートリアルのトレーニングジョブには最大10分かかる場合がある
• トレーニングジョブが完了したら、SageMaker Debugger によって生成されたXGBoostトレーニングレポートとプロファイリングレポートをダウンロードできる
• トレーニングレポートでは、損失関数、特徴の重要度、混同行列、精度曲線など、トレーニングの進行状況と結果に関する洞察が得られる
• 次のコードで、デバッガートレーニングレポートが生成される S3 URI を指定し、レポートが存在するか確認できる

rule_output_path = xgb_model.output_path + "/" + xgb_model.latest_training_job.job_name + "/rule-output"
! aws s3 ls {rule_output_path} --recursive

• レポートを現在のワークスペースにダウンロードする

! aws s3 cp {rule_output_path} ./ --recursive

• 次のスクリプトを実行して、レポートのファイルリンクを取得する

from IPython.display import FileLink, FileLinks
display("Click link below to view the XGBoost Training report", FileLink("CreateXgboostReport/xgboost_report.html"))

• 次のスクリプトは、EC2インスタンスのリソース使用率、システムボトルネック検出結果、Python操作のプロファイリング結果の概要と詳細を示すデバッガープロファイリングレポートのファイルリンクを返す

profiler_report_name = [rule["RuleConfigurationName"] 
                        for rule in xgb_model.latest_training_job.rule_job_summary() 
                        if "Profiler" in rule["RuleConfigurationName"]][0]
profiler_report_name
display("Click link below to view the profiler report", FileLink(profiler_report_name+"/profiler-output/profiler-report.html"))

• トレーニング済みの XGBoost モデルができた。SageMaker AI は、モデル成果物をS3に保存する。場所を見つけるには、次のコードを実行する

xgb_model.model_data

• バイアスを測定するには、SageMaker Clarify を使用する

https://docs.aws.amazon.com/sagemaker/latest/dg/ex1-train-model.html

モデルをEC2にデプロイする（チュートリアル）

import sagemaker
from sagemaker.serializers import CSVSerializer
xgb_predictor=xgb_model.deploy(
    initial_instance_count=1,
    instance_type='ml.t2.medium',
    serializer=CSVSerializer()
)

• パラメータの説明
  • initial_instance_count: モデルをデプロイするインスタンスの数
  • instance_type: デプロイされたモデルを操作するインスタンスのタイプ
  • serializer: 様々な形式の入力データをCSV形式の文字列にシリアル化する。XGBoostアルゴリズムはCSV形式の入力ファイルを受け入れるため、これを使用する
• deployメソッドはデプロイ可能なモデルを作成し、SageMaker AIホスティングサービスのエンドポイントを設定し、モデルをホストするエンドポイントを起動する
• デプロイされたエンドポイントの名前を取得するには、次のコードを実行する
  • エンドポイントの形式はsagemaker-xgboost-YYYY-MM-DD-HH-MM-SS-SSS

xgb_predictor.endpoint_name

• エンドポイントはインスタンス内でアクティブなままなので、後でシャットダウンしない限りいつでも予測を行うことができる
• SageMaker AI Predictor を使用してホストされたエンドポイントを再利用する
• モデルをエンドポイントにデプロイした後、エンドポイントをペアリングして新しいSageMaker AI予測子を設定し、他のノートブックで継続的にリアルタイム予測を行える

import sagemaker
xgb_predictor_reuse=sagemaker.predictor.Predictor(
    endpoint_name="sagemaker-xgboost-YYYY-MM-DD-HH-MM-SS-SSS",
    sagemaker_session=sagemaker.Session(),
    serializer=sagemaker.serializers.CSVSerializer()
)

• 予測子 xgb_predictor_reuse はオリジナルと全く同じように動作する
• バッチ変換で予測を行う
  • 本番環境でエンドポイントをホストする代わりに、バッチ変換を使用してテストデータセットで予測を行うための1回限りのバッチ推論ジョブを実行できる
• 次のコードを実行して、テストデータセットの特徴列をCSVに変換し、S3にアップロードする

X_test.to_csv('test.csv', index=False, header=False)

boto3.Session().resource('s3').Bucket(bucket).Object(
os.path.join(prefix, 'test/test.csv')).upload_file('test.csv')

• バッチ変換ジョブの入力と出力のS3URIを指定する

# The location of the test dataset
batch_input = 's3://{}/{}/test'.format(bucket, prefix)

# The location to store the results of the batch transform job
batch_output = 's3://{}/{}/batch-prediction'.format(bucket, prefix)

• 最小限のパラメータを指定して、トランスフォーマーオブジェクトを作成

transformer = xgb_model.transformer(
    instance_count=1, 
    instance_type='ml.m4.xlarge', 
    output_path=batch_output
)

• バッチ変換ジョブを実行

transformer.transform(
    data=batch_input, 
    data_type='S3Prefix',
    content_type='text/csv', 
    split_type='Line'
)
transformer.wait()

• バッチ変換ジョブが完了すると、batch_output に予測データを保存
  • 次のコマンドで、バッチ変換ジョブの出力データをダウンロードする

! aws s3 cp {batch_output} ./ --recursive

• XGBoost トレーニング ジョブのロジスティック回帰に基づいて予測された float 値を確認できる

https://docs.aws.amazon.com/sagemaker/latest/dg/ex1-model-deployment.html

モデルを評価する（チュートリアル）

• モデルをトレーニング・デプロイしたのでモデルを評価して、新しいデータに対して正確な予測が生成されることを確認する
• モデルの評価にはテストデータセットを使用する
• テストセットの各行を予測するには、次の関数を設定する
  • rows引数は一度に予測する行数を指定する
  • その値を変更して、インスタンスのハードウェアリソースを最大限に活用するバッチ推論を実行できる

import numpy as np
def predict(data, rows=1000):
    split_array = np.array_split(data, int(data.shape[0] / float(rows) + 1))
    predictions = ''
    for array in split_array:
        predictions = ','.join([predictions, xgb_predictor.predict(array).decode('utf-8')])
    return np.fromstring(predictions[1:], sep=',')

• 次のコードを実行して、テストデータセットの予測を行い、ヒストグラムをプロットする
  • 実際の値の0番目の列を除いた、テストデータセットの特徴列のみを取得する必要がある

import matplotlib.pyplot as plt

predictions=predict(test.to_numpy()[:,1:])
plt.hist(predictions)
plt.show()

• 予測値はfloat型。浮動小数点値に基づいて真偽を判定するには、カットオフ値を設定する必要がある
  • 以下のコード例に示すように、Scikit-learnライブラリを使用して、カットオフ値を0.5とした混同メトリクスと分類レポートの出力を返す
  • これにより、混同行列が返される

import sklearn

cutoff=0.5
print(sklearn.metrics.confusion_matrix(test.iloc[:, 0], np.where(predictions > cutoff, 1, 0)))
print(sklearn.metrics.classification_report(test.iloc[:, 0], np.where(predictions > cutoff, 1, 0)))

• 与えられたテストセットで最適なカットオフを見つけるには、ロジスティック回帰の対数損失関数を計算する
  • 対数損失関数は、グラウンドトゥルースラベルの予測確率を返すロジスティックモデルの負の対数尤度として定義される
  • 次のサンプルコードでは、数値的に反復的に対数損失値( -(y*log(p)+(1-y)log(1-p))を計算する

import matplotlib.pyplot as plt

cutoffs = np.arange(0.01, 1, 0.01)
log_loss = []
for c in cutoffs:
    log_loss.append(
        sklearn.metrics.log_loss(test.iloc[:, 0], np.where(predictions > c, 1, 0))
    )

plt.figure(figsize=(15,10))
plt.plot(cutoffs, log_loss)
plt.xlabel("Cutoff")
plt.ylabel("Log loss")
plt.show()

• これにより、ログ損失曲線が返される
• Numpy argmin と min 関数を使用して、エラー曲線の最小点を見つける

print(
    'Log loss is minimized at a cutoff of ', cutoffs[np.argmin(log_loss)], 
    ', and the log loss value at the minimum is ', np.min(log_loss)
)

• 対数損失関数を計算して最小化する代わりに、代替手段としてコスト関数を推定することができる
  • たとえば、顧客離脱予測問題などのビジネス問題に対してバイナリ分類を実行するモデルをトレーニングする場合、混同行列の要素に重みを設定し、それに応じてコスト関数を計算できる

https://docs.aws.amazon.com/sagemaker/latest/dg/ex1-test-model.html

ノートブックインスタンスのリソースをクリーンアップ（チュートリアル）

• トレーニングジョブとログは削除できず、無期限に保持される
• エンドポイントを削除
  • それをサポートするMLコンピューティングインスタンスも削除される
• エンドポイント設定を削除
• モデルを削除
• ノートブックインスタンスを停止し、削除
• S3 でモデル成果物とトレーニングデータセットを保存するためのS3を削除
• /aws/sagemaker/ で始まるすべてのロググループを削除

https://docs.aws.amazon.com/sagemaker/latest/dg/ex1-cleanup.html

Amazon Linux2ノートブックインスタンス

• JupyterLab1、JupyterLab3で実行されているノートブックインスタンスは、2025.6.30にサポートが終了するので、この日までにJupyterLab4に移行することを推奨する
• ノートブックインスタンスは、AL2オペレーティングシステムをサポート
• notebook-al2-v1
  • JupyterLabバージョン1
• notebook-al2-v2
  • JupyterLabバージョン3
• notebook-al2-v3
  • JupyterLabバージョン4
• 利用可能なカーネル
  • R
  • PySpark
  • Spark
  • SparkR
  • conda_python3
  • conda_pytorch_p310
  • conda_tensorflow2_p310
• AL1メンテナンスフェーズ計画
  • 2021.8.18
    • AL2に基づくノートブックインスタンスが起動される
    • 新しく起動されたノートブックインスタンスはデフォルトでAL1
    • AL1はセキュリティパッチと更新でサポートされるが、新しい機能はない
  • 2022.10.31
    • デフォルトのプラットフォーム識別子が al1-v1 から al2-v2 になる
  • 2022.12.1
    • AL1は重要でないセキュリティパッチとアップデートのサポートが終了
    • 重要なセキュリティパッチとアップデートの修正は引き続き受ける
    • AL1でインスタンスを起動できるが、サポートされていないOSを利用することに伴うリスクを負う
  • 2023.2.1
    • AL1は、新しいノートブックの作成に利用できなくなる
    • AL1の継続的な可用性は保証できないため、ステータスが「INSERVICE」のノートブックは新しいプラットフォームに移行する必要がある
  • 2024.3.31
    • AL1は2024.3.31にノートブックインスタンスでのサポートを終了
    • AL1はセキュリティ更新やバグ修正は受けられず、新しいノートブックの作成もできない
    • ステータスが「STOPPED」のノートブックインスタンスは再起動できない
    • ステータスが「INSERVICE」のノートブックは最新のプラットフォームに移行する必要がある
• Amazon Linux2への移行
  • AL1からAL2へ自動的に移行されない
  • アップグレードするには、新しいノートブックインスタンスを作成し、コードと環境を複製し、古いノートブックインスタンスを削除する必要がある

https://docs.aws.amazon.com/sagemaker/latest/dg/nbi-al2.html

JupyterLab のバージョン管理

• ノートブックインスタンスのインターフェースは、ノートブック、コード、データ用のWebベースインタラクティブ開発環境であるJupyterLabに基づく
• 1つのノートブックインスタンスで実行できるJupyterLabインスタンスは1つだけ
• プラットフォーム識別子を明示的に設定しない場合、ノートブックインスタンスはデフォルトでJupyterLab1を実行する
• JupyterLabバージョンメンテナンス
  • JupyterLab1、3のノートブックインスタンスは、2025.6.30に標準サポートが終了する
    • JupyterLab1、3ノートブックインスタンスを新規作成したり、停止したものを再起動できない
    • 稼働中のJupyterLab1、3ノートブックインスタンスは引き続き機能するが、セキュリティ更新や重大なバグ修正は受信できない
    • JupyterLab1、3上のインスタンスのセキュリティを管理する責任がある
    • 既存のJupyterLab1、3ノートブックインスタンスで問題が発生した場合、新しいJupyterLab4ノートブックインスタンスに移行しない限り、継続的な可用性を保証できない
• JupyterLab4
  • AL2でのみ利用できる
  • Jupyter3になかった次の機能が含まれる
    • より高速な体験のために最適化されたレンダリング
    • タブの切り替えを高速化し、長いノートブックでのパフォーマンスを向上させるためのオプトイン設定
    • テキストエディタのアップグレード
    • pypiからインストールする新しい拡張機能マネージャー
    • UI改善
  • JupyterLab3から4に移行しようとすると、JupyterLab3、4の間でパッケージバージョンが変更され、既存のライフサイクル設定やJupyter/JupyterLab拡張機能が破損する可能性がある

https://docs.aws.amazon.com/sagemaker/latest/dg/nbi-jl.html

ノートブックインスタンスを作成する

• リクエストを受け取ると、SageMaker AI は以下を実行する
  • ネットワークインターフェースを作成
    • オプションのVPC設定を選択すると、VPCにネットワークインターフェースを作成する
    • リクエストで指定したサブネットとセキュリティグループを利用する
  • MLコンピューティングインスタンスを起動
    • SageMaker AI VPC でインスタンスを起動
    • VPCを指定した場合、VPCとインスタンス間のトラフィックを有効にする
  • 一般的なディープラーニングプラットフォーム用のAnacondaパッケージとライブラリをインストール
  • ML ストレージボリュームをアタッチ
    • ボリュームは、トレーニングデータセットをクリーンアップしたり、データを一時的に保存するための作業領域として利用できる
    • サイズは5GB-16384GB
    • 暗号化されているため、ボリューム上の使用可能な空き容量を判断できない
    • ボリュームを増やすことはできるが、減らすことはできない
    • /home/ec2-user/SageMakerに保存されたファイルとデータのみがノートブックインスタンスセッション間で保持される
    • このディレクトリの外に保存されたデータは、インスタンスが停止したり再起動したりすると上書きされる
    • 各インスタンスの/tmpディレクトリは、インスタンスストアに最低10GBのストレージを提供
    • インスタンスタイプがNVMeをサポートしている場合、NVMeインスタンスストアボリュームを使用できる
      • NVMeインスタンスストアボリュームは永続的ではなく、インスタンスが起動されるたびに再構成する必要がある
  • サンプルのJupyterノートブックをコピーする
• ノートブックインスタンスの作成手順
  • ノートブックインスタンス名
  • ノートブックインスタンスタイプ
  • プラットフォーム識別子
    • OSとJupyterLabのバージョンが決まる
  • インスタンス作成時・起動時に実行できるシェルスクリプトを指定（ライフサイクル設定スクリプト）
  • ボリュームのサイズ
  • 最小IMDSバージョン
    • 2023.2.1以降、IMDSv1は新規ノートブックインスタンス作成時に使用できない
  • IAMロール
    • 新しくロールを作成するを選択すると、AmazonSageMaker-ExecutionRole-YYYYMMDDTHHmmSSという名称で作成する
      • 管理ポリシーAmazonSageMakerFullAccessがアタッチされる
      • ノートブックインスタンスがSageMaker AIとS3を呼び出すことを許可する
  • ルートアクセスの有効・無効
    • ルートアクセスを付与すると、すべてのノートブックインスタンスユーザーに管理者権限が付与され、インスタンス上のすべてのファイルにアクセスして編集できるようになる
  • 暗号化キー
    • KMSを使用して、ボリューム上のデータを暗号化できる
  • ネットワーク
    • インスタンスをVPC内に配置できる
    • インターネットアクセスが必要な場合は、直接インターネットアクセスを有効にする
  • Gitリポジトリをノートブックインスタンスに関連づける
• ノートブックインスタンスのセキュリティを強化するため、地域の notebook.region.sagemaker.aws ドメインはすべてインターネット公開サフィックスリストに登録されている
  • さらなるセキュリティのために、__Host-接頭辞を持つクッキーを使用して、ノートブックインスタンスのドメインに機密クッキーを設定することを推奨する
  • これにより、CSRFからドメインを保護することができる

https://docs.aws.amazon.com/sagemaker/latest/dg/howitworks-create-ws.html

ノートブックインスタンスにアクセスする

• コンソールから
• CreatePresignedNotebookInstanceUrl API 利用
  • 発行されるURLは5分のみ有効で、経過後にURLを利用するとAWSコンソールのサインインページに遷移する

https://docs.aws.amazon.com/sagemaker/latest/dg/howitworks-access-ws.html

ノートブックインスタンスを更新する

• InService状態の時は、インスタンスのタグを更新できる
• その他の属性を更新するには、Stoppedである必要がある

https://docs.aws.amazon.com/sagemaker/latest/dg/nbi-update.html

LCCスクリプトを使用したノートブックインスタンスのカスタマイズ

• LCC（ライフサイクル設定）は、インスタンス作成・起動時に実行されるスクリプト
• スクリプトの文字制限は16384文字
• スクリプトで使用可能な＄PATH環境変数の値は /usr/local/sbin:/usr/local/bin:/usr/bin:/usr/sbin:/sbin:/bin
• 環境変数 $PWDの値である作業ディレクトリは/
• /aws/sagemaker/NotebookInstances ロググループのログストリーム[notebook-instance-name]/[LifecycleConfigHook]からログを確認できる
• スクリプトは5分以上実行すると失敗する
• 時間短縮方法
  • 必要な手順を削減する
  • タスクを並列プロセスで実行する
  • コマンドでnohupを利用
• ベストプラクティス
  • rootユーザーとして実行される。スクリプトが/home/ec2-user/SageMakerディレクトリ内で変更を行う場合、ec2-userユーザーとして実行するにはsudo -u ec2-user コマンドを使用する。これは SageMaker AI が実行するユーザーと同じ
  • ノートブックインスタンスはconda環境を利用して様々なカーネルを実装する。1つ以上のカーネルで使用できるパッケージをインストールする場合は、パッケージをインストールするコマンドを、パッケージをインストールするカーネルを含むconda環境をアクティブにするconda環境コマンドで囲む

#!/bin/bash
sudo -u ec2-user -i <<EOF

# This will affect only the Jupyter kernel called "conda_python3".
source activate python3

# Replace myPackage with the name of the package you want to install.
pip install myPackage
# You can also perform "conda install" here as well.

source deactivate

EOF

• スクリプトを作成する際は、ノートブックを作成するときにコンソールで使用できるテキストエディターなど、Unixスタイルの改行機能を備えたテキストエディターを使用することを推奨する
  • Linux以外のOSからテキストをコピーすると、互換性のない改行が発生し、予期しないエラーが発生する可能性がある

https://docs.aws.amazon.com/sagemaker/latest/dg/notebook-lifecycle-config.html

外部ライブラリとカーネルのインストール

• ノートブックインスタンスのすべてのパッケージはSageMaker AIで利用するためにライセンスされており、追加の商用ライセンスは必要ない
  • 将来変更される可能性はあるため、更新についてはライセンス条件を定期的に見直すことを推奨する
• ノートブックインスタンスにはscikit,Pandas,NumPy,TensorFlow,MXNetなどのJupyterカーネルとPythonパッケージが含まれており、インスタンスを停止・起動すると更新される
• インスタンス内の異なるJupyterカーネルは、別々のconda環境
• カスタム環境とカーネルとEBSにインストールすることで、インスタンスを停止・起動したときにそれらが維持し、インストールした外部ライブラリがSageMaker AIによって更新されないようにする
  • これを行うには、インスタンス作成時に実行されるスクリプト（on-create）と、インスタンスを再起動するときに実行されるスクリプト（on-start）の両方を含むライフサイクル設定を使用する
• パッケージインストールツール
  • conda install
  • pip install
• パッケージのインストール方法
  • ライフサイクル設定スクリプト
  • ノートブック（次のコマンドがサポート）
    • %conda install
    • %pip install
  • Jupyterターミナル
• ノートブック内ではシステムコマンド構文（!で始まる）を使って !pip install のようにパッケージをインストールできる
• %pip、%conda のコマンドでは、使用中の環境やインタプリタを正しく考慮するため、ノートブックからパッケージをインストールする推奨の方法
• Conda
  • SageMaker AI ではデフォルトチャネルとconda-forgeチャネルのいずれかの使用をサポート
  • Condaが依存関係グラフを解決する方法により、conda-forgeからのパッケージのインストールにかなり長い時間がかかる場合がある（10分以上）
  • Deep Learning AMI には多数のconda環境やパッケージがプリインストールされており、「環境に一貫性がありません。パッケージプランを慎重に確認してください」という警告が表示される場合があるが、この警告にかかわらずSageMaker AI は、SageMaker AIが提供するすべての環境が正しいことを保証する
    • ユーザーがインストールしたパッケージが正しく機能することを保証できない
  • SageMaker AI、AWS Deep Learning AMI、EMRのユーザーは、Anacondaを使用する場合、2024.2.1まで商用ライセンスを取得せずに商用Anacondaリポジトリにアクセスできる
    • 2024.2.1以降、商用Anacondaリポジトリを使用する場合は、お客様が独自のAnacondaラインセンス要件を決定する責任がある
  • 環境をアクティブ化する2つの方法
    • conda activate/deactivate
    • source activate/deactivate
  • SageMaker AI は、インスタンスが停止しても保持されるConda環境をEBSに移動することをサポート
    • 環境がルートボリュームにインストールされている場合、環境は保持されない
  • サポートされているconda操作
    • 単一環境でのパッケージインストール
    • すべての環境でのパッケージインストール
    • R環境でのRパッケージインストール
    • メインのcondaリポジトリからパッケージインストール
    • conda-forgeからパッケージインストール
    • EBSを使用するためにCondaのインストール場所を変更
    • conda activateとsource activateの両方をサポート
• Pip
  • Pythonパッケージをインストール・管理するためのデファクトツール
  • デフォルトでPythonパッケージインデックス（PyPI）でパッケージを検索
  • PyPIの代わりに代替パッケージリポジトリを利用できる
  • サポートされているPip操作
    • アクティブなconda環境なしでpipを使用してパッケージをインストールする
      • システム全体にパッケージをインストールする
    • pipを使用してconda環境にパッケージをインストールする
    • pipを使用してすべてのconda環境にパッケージをインストールする
    • EBSを使用するためにpipのインストール場所を変更する
    • 代替リポジトリを使用してpipでパッケージをインストールする
• サポートされいないこと
  • パッケージがSageMaker AIまたはDLAMIによってインストールされ、これらのパッケージに対して次の操作を行うと、ノートブックインスタンスが不安定になる可能性がある
    • アンインストール
    • ダウングレード
    • アップグレード
  • ネットワークの構成やcondaやPyPIの可用性に関する潜在的な問題により、パッケージが一定または確率的な時間内にインストールされていることは保証できない

https://docs.aws.amazon.com/sagemaker/latest/dg/nbi-add-external.html

ノートブックインスタンスのソフトウェア更新

• SageMaker AIはノートブックインスタンスにインストールされているソフトウェアを定期的にテストしてリリースする
  • カーネルアップデート
  • セキュリティパッチ
  • AWS SDK アップデート
  • Amazon SageMaker Python SDK アップデート
  • オープンソースソフトウェアのアップデート
• 最新のソフトウェアアップデートがあることを確認するには、StopNotebookInstance を呼び出して、ノートブックインスタンスを停止して再起動する
• カーネルと一部のパッケージの更新は、ノートブックインスタンスのルートアクセスが有効になっているかどうかで異なる場合がある

https://docs.aws.amazon.com/sagemaker/latest/dg/nbi-software-updates.html

ノートブックを使用して EMR Spark インスタンスを制御する

• カスタムライフサイクル設定スクリプトで作成されたノートブックインスタンスを使用して、ノートブックからAWSサービスにアクセスできる
• 例えば、Sparkmagic でノートブックを使用してEMRインスタンスなどの他のAWSリソースを制御できるようにするスクリプトを作成できる
• その後、ノートブックでデータ分析する代わりに、EMRインスタンスを利用してデータを処理できる
• これにより、インスタンスを使用してデータを処理しないため、より小さなノートブックインスタンスを作成できる
• 3つの手順が必要
  • EMR Sparkインスタンスを作成
  • Jupyterノートブック作成
  • ノートブックからEMRへの接続をテスト
• Sparkmagic を使用してノートブックから制御できるEMR Sparkインスタンスを作成する
  • EMRコンソールを開き、EMRクラスターを作成する
  • マスターパブリックDNS、EMRマスターのセキュリティグループ、VPC、サブネットIDをメモする
• Sparkmagicを使用してEMR Sparkインスタンスを制御するノートブックを作成する
  • SageMaker AIからノートブックインスタンスを作成
  • ライフサイクル設定に次のコードを追加

# OVERVIEW
# This script connects an Amazon EMR cluster to an Amazon SageMaker notebook instance that uses Sparkmagic.
#
# Note that this script will fail if the Amazon EMR cluster's master node IP address is not reachable.
#   1. Ensure that the EMR master node IP is resolvable from the notebook instance.
#      One way to accomplish this is to have the notebook instance and the Amazon EMR cluster in the same subnet.
#   2. Ensure the EMR master node security group provides inbound access from the notebook instance security group.
#       Type        - Protocol - Port - Source
#       Custom TCP  - TCP      - 8998 - $NOTEBOOK_SECURITY_GROUP
#   3. Ensure the notebook instance has internet connectivity to fetch the SparkMagic example config.
#
# https://aws.amazon.com/blogs/machine-learning/build-amazon-sagemaker-notebooks-backed-by-spark-in-amazon-emr/

# PARAMETERS
EMR_MASTER_IP=your.emr.master.ip

cd /home/ec2-user/.sparkmagic

echo "Fetching Sparkmagic example config from GitHub..."
wget https://raw.githubusercontent.com/jupyter-incubator/sparkmagic/master/sparkmagic/example_config.json

echo "Replacing EMR master node IP in Sparkmagic config..."
sed -i -- "s/localhost/$EMR_MASTER_IP/g" example_config.json
mv example_config.json config.json

echo "Sending a sample request to Livy.."
curl "$EMR_MASTER_IP:8998/sessions"

• 上記スクリプトで、your.emr.master.ipをEMRインスタンスのマスターパブリックDNS名に置き換える
• ノートブックのネットワーク設定で、EMRインスタンスが配置されるVPC、サブネットを選択し、EMRマスターノードで利用されるセキュリティグループを選択する
• EMR インスタンスとノートブック間の接続をテストする
  • ノートブックインスタンスでJupyterを開き、Sparkmagic(PySpark)を選択する
  • セルで%%infoを実行すると、次のような結果となることが想定される

Current session configs: {'driverMemory': '1000M', 'executorCores': 2, 'kind': 'pyspark'}
                    No active sessions.

https://docs.aws.amazon.com/sagemaker/latest/dg/nbi-lifecycle-config-emr.html

SageMaker AI ノートブックインスタンスにGitリポジトリを関連づける

• Gitリポジトリをノートブックインスタンスに関連づけて、ノートブックインスタンスを停止・削除しても保持されるソース管理環境にノートブックを保存できる
• 1つのデフォルトリポジトリと、3つの追加リポジトリを関連づけられる
• SageMaker AIアカウントにGitリポジトリを追加する
  • CodeCommit以外のGitリポジトリは、プライベートの場合Git資格情報を利用する
    • Git資格情報はSecretManagerシークレットを利用する
    • Gitリポジトリで2要素認証が有効になっている場合は、個人アクセストークンをpasswordフィールドに入力する
• ノートブックインスタンス作成時、関連づけるGitリポジトリを選択する
• 別のAWSアカウントのCodeCommitリポジトリを関連づけられる
  • CodeCommit アカウントに、リポジトリへのアクセスを許可するIAMロール作成
  • ノートブックインスタンスにおいて、上記IAMロールを利用するプロファイルを作成して利用する

[profile CrossAccountAccessProfile]
region = us-west-2
role_arn = arn:aws:iam::CodeCommitAccount:role/CrossAccountRepositoryContributorRole
credential_source=Ec2InstanceMetadata
output = json

[credential]
        helper = !aws codecommit credential-helper --profile CrossAccountAccessProfile $@
        UseHttpPath = true

https://docs.aws.amazon.com/sagemaker/latest/dg/nbi-git-repo.html

ノートブックインスタンスのメタデータ

• /opt/ml/metadata/resource-metadata.jsonに保存される

{
    "ResourceArn": "NotebookInstanceArn",
    "ResourceName": "NotebookInstanceName"
}

• 上記ファイルにアクセスして、ノートブックインスタンスに関するその他の情報を取得できる

NOTEBOOK_ARN=$(jq '.ResourceArn'
            /opt/ml/metadata/resource-metadata.json --raw-output)
aws sagemaker list-tags --resource-arn $NOTEBOOK_ARN

https://docs.aws.amazon.com/sagemaker/latest/dg/nbi-metadata.html

JupyterログをCloudWatch ログから確認

• ノートブックインスタンスの詳細ページのモニターから、ログを表示
• ログストリームは NotebookInstanceName/jupyter.log

https://docs.aws.amazon.com/sagemaker/latest/dg/jupyter-logs.html