翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# Amazon SageMaker ML 系統追跡
<a name="lineage-tracking"></a>

**重要**  
2023 年 11 月 30 日以降、従来の Amazon SageMaker Studio のエクスペリエンスは Amazon SageMaker Studio Classic と名前が変更されました。以下のセクションは、Studio Classic アプリケーションの使用を前提とした内容です。更新後の Studio エクスペリエンスを使用する場合は、「[Amazon SageMaker Studio](studio-updated.md)」を参照してください。  
Studio Classic は既存のワークロードでも維持されますが、オンボーディングに利用できなくなります。既存の Studio Classic アプリケーションのみを停止または削除でき、新しいアプリケーションを作成することはできません。[ワークロードを新しい Studio エクスペリエンスに移行](studio-updated-migrate.md)することをお勧めします。

Amazon SageMaker ML 系統追跡は、データ準備からモデルのデプロイまで、機械学習 (ML) ワークフローのステップに関する情報を作成して保存します。追跡情報を使用すると、ワークフローステップの再現、モデルおよびデータセットの系統の追跡、モデルのガバナンスと監査基準の確立を行うことができます。

SageMaker AI のリネージ追跡機能は、バックエンドで動作し、モデルトレーニングワークフローとデプロイワークフローに関連するすべてのメタデータを追跡します。これには、トレーニングジョブ、使用したデータセット、パイプライン、エンドポイント、実際のモデルが含まれます。系統サービスに対していつでもクエリを実行し、モデルのトレーニングに使用された正確なアーティファクトを確認できます。これらのアーティファクトを使用すると、使用した正確なデータセットにアクセスできる限り、同じ機械学習ワークフローを再作成してモデルを再現できます。トライアルコンポーネントは、トレーニングジョブを追跡します。このトライアルコンポーネントには、トレーニングジョブの一部として使用されたすべてのパラメータがあります。ワークフロー全体を再実行する必要がない場合は、トレーニングジョブを再現して同じモデルを派生させることができます。

SageMaker AI リネージ追跡を使用すると、データサイエンティストとモデルビルダーは以下を実行できます。
+ モデル検出実験の実行履歴を保持する。
+ モデル系統のアーティファクトを追跡してモデルガバナンスを確立し、監査とコンプライアンスの検証を行う。

以下の図は、エンドツーエンドのモデルトレーニングおよびデプロイの ML ワークフローで、Amazon SageMaker AI が自動的に作成するリネージグラフの例を示しています。

![\[\]](http://docs.aws.amazon.com/ja_jp/sagemaker/latest/dg/images/pipelines/PipelineLineageWorkflow.png)


**Topics**
+ [系統追跡エンティティ](lineage-tracking-entities.md)
+ [Amazon SageMaker AI 作成の追跡エンティティ](lineage-tracking-auto-creation.md)
+ [追跡エンティティを手動で作成する](lineage-tracking-manual-creation.md)
+ [系統エンティティをクエリする](querying-lineage-entities.md)
+ [クロスアカウントのリネージを追跡する](xaccount-lineage-tracking.md)

# 系統追跡エンティティ
<a name="lineage-tracking-entities"></a>

追跡エンティティは、エンドツーエンドの機械学習ワークフローのすべての要素の表現を保持します。この表現を使用すると、モデルガバナンスの確立、ワークフローの再現、作業履歴の記録の保持を行うことができます。

Amazon SageMaker AI では、処理ジョブ、トレーニングジョブ、バッチ変換ジョブなどの SageMaker AI ジョブを作成する際に、トライアルコンポーネントとそれに関連するトライアルおよび実験の追跡エンティティが自動的に作成されます。自動追跡以外にも、「[追跡エンティティを手動で作成する](lineage-tracking-manual-creation.md)」でワークフローのカスタムステップをモデル化できます。詳細については、「[Studio Classic の Amazon SageMaker Experiments](experiments.md)」を参照してください。

SageMaker AI は、ワークフロー内の他のステップの追跡エンティティも自動的に作成するため、ワークフローを最初から最後まで追跡できます。詳細については、「[Amazon SageMaker AI 作成の追跡エンティティ](lineage-tracking-auto-creation.md)」を参照してください。

SageMaker AI が作成したエンティティを補足する追加のエンティティを作成することもできます。詳細については、「[追跡エンティティを手動で作成する](lineage-tracking-manual-creation.md)」を参照してください。

SageMaker AI は、新しいエンティティを作成するのではなく、既存のエンティティを再利用します。例えば、固有の `SourceUri` を持つアーティファクトは 1 つしか存在しません。

**系統クエリの主要な概念**
+ **系統** - ML ワークフロー内のさまざまなエンティティ間の関係を追跡するメタデータ。
+ **QueryLineage** - 系統を検査し、エンティティ間の関係を検出するアクション。
+ **系統エンティティ** - 系統を構成するメタデータ要素。
+ **クロスアカウントの系統** - ML ワークフローは、複数のアカウントにまたがることがあります。クロスアカウントの系統を使用すると、共有エンティティリソース間の系統の関連付けを自動的に作成するように複数のアカウントを設定できます。そうすると、QueryLineage で、これらの共有アカウントからもエンティティを返すことができるようになります。

以下の追跡エンティティが定義されます。

**実験エンティティ**
+ [トライアルコンポーネント](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrialComponent.html) - 機械学習トライアルのステージ。処理ジョブ、トレーニングジョブ、バッチ変換ジョブが含まれます。
+ [トライアル](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrial.html) - 一般的にモデルを作成するトライアルコンポーネントの組み合わせ。
+ [実験](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateExperiment.html) - 一般的に特定のユースケースの解決に焦点を当てた一連のトライアル。

**系統エンティティ**
+ [トライアルコンポーネント](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrialComponent.html) - 系統内の処理、トレーニング、変換のジョブを表します。実験管理の一部にもなります。
+ [コンテキスト](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateContext.html) - 他の追跡エンティティや実験エンティティの論理グループ化を提供します。概念的に、実験とトライアルはコンテキストになります。エンドポイントやモデルパッケージなどが例として挙げられます。
+ [アクション](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateAction.html) - アクションまたはアクティビティを表します。一般に、アクションには、少なくとも 1 つの入力アーティファクトか出力アーティファクトが含まれます。ワークフローステップやモデルのデプロイなどが例として挙げられます。
+ [アーティファクト](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateArtifact.html) - URI アドレス可能なオブジェクトやデータを表します。通常、アーティファクトはトライアルコンポーネントやアクションへの入力または出力になります。データセット (S3 バケット URI) やイメージ (Amazon ECR レジストリパス) などが例として挙げられます。
+ [関連付け](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_AddAssociation.html) - トレーニングデータの場所とトレーニングジョブの関連付けのように、他の追跡エンティティや実験エンティティをリンクします。

  関連付けにはオプションの `AssociationType` プロパティがあります。以下の値は、各タイプの推奨使用方法と共に使用できます。SageMaker AI では使用に関する制限はありません。
  + `ContributedTo` - ソースがターゲットに貢献した、またはターゲットの有効化に関与した。例えば、トレーニングジョブに貢献したトレーニングデータ。
  + `AssociatedWith` - ソースがターゲットに接続されている。例えば、モデルデプロイに関連付けられた承認ワークフロー。
  + `DerivedFrom` - ターゲットは、ソースを変更したものである。例えば、元の入力から派生、処理ジョブのチャネル入力のダイジェスト出力。
  + `Produced` - ソースがデスティネーションを生成した。例えば、トレーニングジョブが生成したモデルアーティファクト。
  + `SameAs` - 同じ系統エンティティが異なるアカウントで使用される場合。

**一般的なプロパティ**
+ **Type プロパティ**

  アクション、アーティファクト、コンテキストのエンティティにはそれぞれ、`ActionType`、`ArtifactType`、`ContextType` の Type プロパティがあります。**このプロパティは、意味のある情報をエンティティに関連付けて、List API のフィルターとして使用できるカスタム文字列です。
+ **Source プロパティ**

  アクション、アーティファクト、コンテキストのエンティティには `Source` プロパティがあります。このプロパティは、エンティティによって表される、基になる URI を提供します。いくつか例を挙げます。
  + `UpdateEndpoint` アクション。この場合、ソースは `EndpointArn` になります。
  + 処理ジョブのイメージアーティファクト。この場合、ソースは `ImageUri` になります。
  + `Endpoint` コンテキスト。この場合、ソースは `EndpointArn` になります。
+ **Metadata プロパティ**

  アクションエンティティとアーティファクトエンティティには、オプションの `Metadata` プロパティがあります。このプロパティは、以下のような情報を提供できます。
  + `ProjectId` - モデルが属する SageMaker AI MLOps プロジェクトの ID など。
  + `GeneratedBy` - モデルパッケージのバージョンを登録した SageMaker AI パイプラインの実行など。
  + `Repository` - アルゴリズムを含むリポジトリなど。
  + `CommitId` - アルゴリズムバージョンのコミット ID など。

# Amazon SageMaker AI 作成の追跡エンティティ
<a name="lineage-tracking-auto-creation"></a>

Amazon SageMaker AI は、データが利用可能な場合、SageMaker AI ジョブ、モデル、モデルパッケージ、エンドポイントの追跡エンティティを自動的に作成します。SageMaker AI が作成するリネージエンティティの数に制限はありません。

追跡エンティティを手動で作成する方法については、「[追跡エンティティを手動で作成する](lineage-tracking-manual-creation.md)」を参照してください。

**Topics**
+ [SageMaker AI ジョブの追跡エンティティ](#lineage-tracking-auto-creation-jobs)
+ [モデルパッケージの追跡エンティティ](#lineage-tracking-auto-creation-model-package)
+ [エンドポイントの追跡エンティティ](#lineage-tracking-auto-creation-endpoint)

## SageMaker AI ジョブの追跡エンティティ
<a name="lineage-tracking-auto-creation-jobs"></a>

SageMaker AI は、各 SageMaker AI ジョブに関連付けられたトライアルコンポーネントを作成します。SageMaker AI は、ジョブのメタデータと、各アーティファクトとジョブ間の関連付けを追跡するためのアーティファクトを作成します。

アーティファクトは、以下のジョブプロパティのために作成され、SageMaker AI ジョブの Amazon リソースネーム (ARN) に関連付けられます。アーティファクト `SourceUri` は括弧で囲んで一覧に表示します。

**トレーニングジョブ**
+ トレーニングアルゴリズムを含むイメージ (`TrainingImage`)。
+ 各入力チャネルのデータソース (`S3Uri`)。
+ モデルの場所 (`S3OutputPath)`)。
+ マネージド型スポットのチェックポイントデータの場所 (`S3Uri`)。

**処理ジョブ**
+ 処理ジョブで実行するコンテナ (`ImageUri`)。
+ 各処理入力と処理出力のデータの場所 (`S3Uri`)。

**変換ジョブ**
+ 変換する入力データソース (`S3Uri`)。
+ 変換の結果 (`S3OutputPath`)。

**注記**  
Amazon Simple Storage Service (Amazon S3) アーティファクトは、Create API に提供される Amazon S3 URI 値に基づいて追跡されます (例: [CreateTrainingJob](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTrainingJob.html))。Amazon S3 キーと各ファイルのハッシュ値または etag 値は使用されません。

## モデルパッケージの追跡エンティティ
<a name="lineage-tracking-auto-creation-model-package"></a>

次のエンティティが作成されます。

**モデルパッケージ**
+ 各モデルパッケージグループのコンテキスト。
+ 各モデルパッケージのアーティファクト。
+ 各モデルパッケージアーティファクトと、パッケージが属する各モデルパッケージグループのコンテキスト間の関連付け。
+ モデルパッケージバージョンを作成するためのアクション。
+ モデルパッケージアーティファクトと作成アクション間の関連付け。
+ モデルパッケージアーティファクトと、パッケージが属する各モデルパッケージグループのコンテキスト間の関連付け。
+ 推論コンテナ
  + モデルパッケージで定義される各コンテナで使用されるイメージのアーティファクト。
  + 各コンテナで使用されるモデルのアーティファクト。
  + 各アーティファクトとモデルパッケージアーティファクト間の関連付け。
+ アルゴリズム
  + モデルパッケージで定義される各アルゴリズムのアーティファクト。
  + 各アルゴリズムによって作成されるモデルのアーティファクト。
  + 各アーティファクトとモデルパッケージアーティファクト間の関連付け。

## エンドポイントの追跡エンティティ
<a name="lineage-tracking-auto-creation-endpoint"></a>

以下のエンティティが Amazon SageMaker AI によって作成されます。

**エンドポイント**
+ 各エンドポイントのコンテキスト
+ 各エンドポイントを作成したモデルデプロイに対するアクション
+ エンドポイントにデプロイされた各モデルのアーティファクト
+ モデルで使用されるイメージのアーティファクト
+ モデルのモデルパッケージのアーティファクト
+ エンドポイントにデプロイされた各イメージのアーティファクト
+ 各アーティファクトとモデルのデプロイアクション間の関連付け。

# 追跡エンティティを手動で作成する
<a name="lineage-tracking-manual-creation"></a>

任意のプロパティの追跡エンティティを手動で作成して、モデルガバナンスを確立し、ワークフローを再現して、作業履歴の記録を保持することができます。Amazon SageMaker AI が自動作成する追跡エンティティの詳細については、「[Amazon SageMaker AI 作成の追跡エンティティ](lineage-tracking-auto-creation.md)」を参照してください。次のチュートリアルでは、SageMaker トレーニングジョブとエンドポイント間でアーティファクトを手動で作成して関連付けて、ワークフローを追跡するために必要なステップを示します。

関連付けを除くすべてのエンティティにタグを追加できます。タグはカスタム情報を提供する任意のキーと値のペアです。タグを基準にしたリストのフィルターや並べ替え、検索クエリを実行できます。詳細については、[『』の AWS 「リソースのタグ付け](https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html)」を参照してください*AWS 全般のリファレンス*。

リネージエンティティの作成方法を紹介するサンプルノートブックについては、「[Amazon SageMaker サンプル GitHub レポジトリ](https://github.com/awslabs/amazon-sagemaker-examples)」の [Amazon SageMaker AI リネージ](https://github.com/aws/amazon-sagemaker-examples/tree/master/sagemaker-lineage)ノートブックを参照してください。

**Topics**
+ [エンティティを手動で作成する](#lineage-tracking-manual-create)
+ [ワークフローを手動で追跡する](#lineage-tracking-manual-track)
+ [制限](#lineage-tracking-manual-track-limits)

## エンティティを手動で作成する
<a name="lineage-tracking-manual-create"></a>

この手順では、SageMaker AI トレーニングジョブとエンドポイントの間にアーティファクトを作成して関連付ける方法を説明します。以下のステップを実行します。

**追跡エンティティと関連付けをインポートする**

1. 系統追跡エンティティをインポートします。

   ```
   import sys
   !{sys.executable} -m pip install -q sagemaker
   
   from sagemaker import get_execution_role
   from sagemaker.session import Session
   from sagemaker.lineage import context, artifact, association, action
   
   import boto3
   boto_session = boto3.Session(region_name=region)
   sagemaker_client = boto_session.client("sagemaker")
   ```

1. 入力および出力のアーティファクトを作成します。

   ```
   code_location_arn = artifact.Artifact.create(
       artifact_name='source-code-location',
       source_uri='s3://...',
       artifact_type='code-location'
   ).artifact_arn
   
   # Similar constructs for train_data_location_arn and test_data_location_arn
   
   model_location_arn = artifact.Artifact.create(
       artifact_name='model-location',
       source_uri='s3://...',
       artifact_type='model-location'
   ).artifact_arn
   ```

1. モデルをトレーニングし、トレーニングジョブを表す `trial_component_arn` を取得します。

1. 入力アーティファクトおよび出力アーティファクトをトレーニングジョブ (トライアルコンポーネント) に関連付けます。

   ```
   input_artifacts = [code_location_arn, train_data_location_arn, test_data_location_arn]
   for artifact_arn in input_artifacts:
       try:
           association.Association.create(
               source_arn=artifact_arn,
               destination_arn=trial_component_arn,
               association_type='ContributedTo'
           )
       except:
           logging.info('association between {} and {} already exists', artifact_arn, trial_component_arn)
   
   output_artifacts = [model_location_arn]
   for artifact_arn in output_artifacts:
       try:
            association.Association.create(
               source_arn=trial_component_arn,
               destination_arn=artifact_arn,
               association_type='Produced'
           )
       except:
           logging.info('association between {} and {} already exists', artifact_arn, trial_component_arn)
   ```

1. 推論エンドポイントを作成します。

   ```
   predictor = mnist_estimator.deploy(initial_instance_count=1,
                                        instance_type='ml.m4.xlarge')
   ```

1. エンドポイントのコンテキストを作成します。

   ```
   from sagemaker.lineage import context
   
   endpoint = sagemaker_client.describe_endpoint(EndpointName=predictor.endpoint_name)
   endpoint_arn = endpoint['EndpointArn']
   
   endpoint_context_arn = context.Context.create(
       context_name=predictor.endpoint_name,
       context_type='Endpoint',
       source_uri=endpoint_arn
   ).context_arn
   ```

1. トレーニングジョブ (トライアルコンポーネント) とエンドポイントのコンテキストを関連付けます。

   ```
   association.Association.create(
       source_arn=trial_component_arn,
       destination_arn=endpoint_context_arn
   )
   ```

## ワークフローを手動で追跡する
<a name="lineage-tracking-manual-track"></a>

前のセクションで作成したワークフローは、手動で追跡できます。

前のサンプルのエンドポイントの Amazon リソースネーム (ARN) を前提として、以下の手順では、エンドポイントにデプロイされたモデルのトレーニングに使用されたデータセットまでワークフローを追跡する方法を説明します。以下のステップを実行します。

**エンドポイントからトレーニングデータソースまでのワークフローを追跡するには**

1. 追跡エンティティをインポートします。

   ```
   import sys
   !{sys.executable} -m pip install -q sagemaker
   
   from sagemaker import get_execution_role
   from sagemaker.session import Session
   from sagemaker.lineage import context, artifact, association, action
   
   import boto3
   boto_session = boto3.Session(region_name=region)
   sagemaker_client = boto_session.client("sagemaker")
   ```

1. エンドポイント ARN から、エンドポイントのコンテキストを取得します。

   ```
   endpoint_context_arn = sagemaker_client.list_contexts(
       SourceUri=endpoint_arn)['ContextSummaries'][0]['ContextArn']
   ```

1. トライアルコンポーネントとエンドポイントのコンテキストの間の関連付けからトライアルコンポーネントを取得します。

   ```
   trial_component_arn = sagemaker_client.list_associations(
       DestinationArn=endpoint_context_arn)['AssociationSummaries'][0]['SourceArn']
   ```

1. トライアルコンポーネントとエンドポイントのコンテキストの間の関連付けからトレーニングデータの場所のアーティファクトを取得します。

   ```
   train_data_location_artifact_arn = sagemaker_client.list_associations(
       DestinationArn=trial_component_arn, SourceType='Model')['AssociationSummaries'][0]['SourceArn']
   ```

1. トレーニングデータの場所のアーティファクトからトレーニングデータの場所を取得します。

   ```
   train_data_location = sagemaker_client.describe_artifact(
       ArtifactArn=train_data_location_artifact_arn)['Source']['SourceUri']
       print(train_data_location)
   ```

   レスポンス:

   ```
   s3://sagemaker-sample-data-us-east-2/mxnet/mnist/train
   ```

## 制限
<a name="lineage-tracking-manual-track-limits"></a>

関連付けは、エンティティ、実験、系統の間に作成できます。ただし、以下を除きます。
+ 2 つの実験エンティティ間には関連付けを作成できません。実験エンティティは、実験、トライアル、トライアルコンポーネントで構成されます。
+ 別の関連付けとの関連付けを作成できます。

既に存在するエンティティを作成しようとすると、エラーが発生します。

**手動で作成される系統エンティティの最大数**
+ アクション: 3,000
+ アーティファクト: 6,000
+ 関連付け: 6,000
+ コンテキスト: 500

Amazon SageMaker AI が自動的に作成するリネージエンティティの数に制限はありません。

# 系統エンティティをクエリする
<a name="querying-lineage-entities"></a>

Amazon SageMaker AI は、ユーザーの使用時にリネージエンティティのグラフを自動的に生成します。このデータをクエリすると、さまざまな質問に答えることができます。以下では、SDK for Python でこのデータをクエリする手順について説明します。

Amazon SageMaker Studio で登録済みモデルのリネージを表示する方法については、「[Studio でモデルリネージの詳細を表示する](model-registry-lineage-view-studio.md)」を参照してください。

系統エンティティをクエリして、以下の操作を実行できます。
+ モデルの作成に送られたすべてのデータセットを取得する。
+ エンドポイントの作成に送られたすべてのジョブを取得する。
+ データセットを使用するすべてのモデルを取得する。
+ モデルを使用するすべてのエンドポイントを取得する。
+ 特定のデータセットから派生したエンドポイントを取得する。
+ トレーニングジョブを作成したパイプラインの実行を取得する。
+ 調査、ガバナンス、再現性のためにエンティティ間の関係を取得する。
+ アーティファクトを使用するすべてのダウンストリーム試行を取得する。
+ アーティファクトを使用するすべてのアップストリーム試行を取得する。
+ 提供された S3 URI を使用するアーティファクトのリストを取得する。
+ データセットアーティファクトを使用するアップストリームアーティファクトを取得する。
+ データセットアーティファクトを使用するダウンストリームアーティファクトを取得する。
+ イメージアーティファクトを使用するデータセットを取得する。
+ コンテキストを使用するアクションを取得する。
+ エンドポイントを使用する処理ジョブを取得する。
+ エンドポイントを使用する変換ジョブを取得する。
+ エンドポイントを使用するトライアルコンポーネントを取得する。
+ モデルパッケージグループに関連付けられたパイプライン実行の ARN を取得する。
+ アクションを使用するすべてのアーティファクトを取得する。
+ モデルパッケージの承認アクションを使用するすべてのアップストリームデータセットを取得する。
+ モデルパッケージの承認アクションからモデルパッケージを取得する。
+ エンドポイントを使用するダウンストリームエンドポイントコンテキストを取得する。
+ トライアルコンポーネントに関連付けられたパイプライン実行の ARN を取得する。
+ トライアルコンポーネントを使用するデータセットを取得する。
+ トライアルコンポーネントを使用するモデルを取得する。
+ 可視化のために系統を調べる。

**制限事項**
+ 以下のリージョンでは、系統クエリは使用できません。
  + アフリカ (ケープタウン) - af-south
  + アジアパシフィック (ジャカルタ) – ap-southeast-3
  + アジアパシフィック (大阪) - ap-northeast-3
  + 欧州 (ミラノ) - eu-south-1
  + 欧州 (スペイン) eu-south-2
  + イスラエル (テルアビブ) – il-central-1
+ 現在、検出する関係の最大深度は 10 に制限されています。
+ フィルタリングは、最終更新日、作成日、タイプ、系統エンティティタイプのプロパティに限定されます。

**Topics**
+ [系統エンティティのクエリの開始方法](#querying-lineage-entities-getting-started)

## 系統エンティティのクエリの開始方法
<a name="querying-lineage-entities-getting-started"></a>

最も簡単な開始方法は、以下のいずれかです。
+ [Amazon SageMaker SDK for Python](https://github.com/aws/sagemaker-python-sdk/blob/master/src/sagemaker/lineage/artifact.py#L397) では、多くの一般的なユースケースが定義されています。
+ SageMaker AI Lineage API を使ってリネージグラフ全体にわたる関係をクエリする方法を解説したノートブックについては、[sagemaker-lineage-multihop-queries.ipynb](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-lineage/sagemaker-lineage-multihop-queries.ipynb) を参照してください。

以下の例は、`LineageQuery` と `LineageFilter` の API を使用して、系統グラフに関する質問に答え、いくつかのユースケースのエンティティ関係を抽出するためのクエリを構築する方法を示しています。

**Example `LineageQuery` API を使用して、エンティティの関連付けを見つける**  

```
from sagemaker.lineage.context import Context, EndpointContext
from sagemaker.lineage.action import Action
from sagemaker.lineage.association import Association
from sagemaker.lineage.artifact import Artifact, ModelArtifact, DatasetArtifact

from sagemaker.lineage.query import (
    LineageQuery,
    LineageFilter,
    LineageSourceEnum,
    LineageEntityEnum,
    LineageQueryDirectionEnum,
)
# Find the endpoint context and model artifact that should be used for the lineage queries.

contexts = Context.list(source_uri=endpoint_arn)
context_name = list(contexts)[0].context_name
endpoint_context = EndpointContext.load(context_name=context_name)
```

**Example エンドポイントに関連付けられているすべてのデータセットを見つける**  

```
# Define the LineageFilter to look for entities of type `ARTIFACT` and the source of type `DATASET`.

query_filter = LineageFilter(
    entities=[LineageEntityEnum.ARTIFACT], sources=[LineageSourceEnum.DATASET]
)

# Providing this `LineageFilter` to the `LineageQuery` constructs a query that traverses through the given context `endpoint_context`
# and find all datasets.

query_result = LineageQuery(sagemaker_session).query(
    start_arns=[endpoint_context.context_arn],
    query_filter=query_filter,
    direction=LineageQueryDirectionEnum.ASCENDANTS,
    include_edges=False,
)

# Parse through the query results to get the lineage objects corresponding to the datasets
dataset_artifacts = []
for vertex in query_result.vertices:
    dataset_artifacts.append(vertex.to_lineage_object().source.source_uri)

pp.pprint(dataset_artifacts)
```

**Example エンドポイントに関連付けられているモデルを見つける**  

```
# Define the LineageFilter to look for entities of type `ARTIFACT` and the source of type `MODEL`.

query_filter = LineageFilter(
    entities=[LineageEntityEnum.ARTIFACT], sources=[LineageSourceEnum.MODEL]
)

# Providing this `LineageFilter` to the `LineageQuery` constructs a query that traverses through the given context `endpoint_context`
# and find all datasets.

query_result = LineageQuery(sagemaker_session).query(
    start_arns=[endpoint_context.context_arn],
    query_filter=query_filter,
    direction=LineageQueryDirectionEnum.ASCENDANTS,
    include_edges=False,
)

# Parse through the query results to get the lineage objects corresponding to the model
model_artifacts = []
for vertex in query_result.vertices:
    model_artifacts.append(vertex.to_lineage_object().source.source_uri)

# The results of the `LineageQuery` API call return the ARN of the model deployed to the endpoint along with
# the S3 URI to the model.tar.gz file associated with the model
pp.pprint(model_artifacts)
```

**Example エンドポイントに関連付けられているトライアルコンポーネントを見つける**  

```
# Define the LineageFilter to look for entities of type `TRIAL_COMPONENT` and the source of type `TRAINING_JOB`.

query_filter = LineageFilter(
    entities=[LineageEntityEnum.TRIAL_COMPONENT],
    sources=[LineageSourceEnum.TRAINING_JOB],
)

# Providing this `LineageFilter` to the `LineageQuery` constructs a query that traverses through the given context `endpoint_context`
# and find all datasets.

query_result = LineageQuery(sagemaker_session).query(
    start_arns=[endpoint_context.context_arn],
    query_filter=query_filter,
    direction=LineageQueryDirectionEnum.ASCENDANTS,
    include_edges=False,
)

# Parse through the query results to get the ARNs of the training jobs associated with this Endpoint
trial_components = []
for vertex in query_result.vertices:
    trial_components.append(vertex.arn)

pp.pprint(trial_components)
```

**Example 系統の焦点を変更する**  
`LineageQuery` を変更して異なる `start_arns` を持たせると、系統の焦点を変更できます。また、`LineageFilter` で複数のソースとエンティティを取れば、クエリの範囲を拡大できます。  
以下では、モデルを系統の焦点として使用し、それに関連付けられているエンドポイントとデータセットを見つけます。  

```
# Get the ModelArtifact

model_artifact_summary = list(Artifact.list(source_uri=model_package_arn))[0]
model_artifact = ModelArtifact.load(artifact_arn=model_artifact_summary.artifact_arn)
query_filter = LineageFilter(
    entities=[LineageEntityEnum.ARTIFACT],
    sources=[LineageSourceEnum.ENDPOINT, LineageSourceEnum.DATASET],
)

query_result = LineageQuery(sagemaker_session).query(
    start_arns=[model_artifact.artifact_arn],  # Model is the starting artifact
    query_filter=query_filter,
    # Find all the entities that descend from the model, i.e. the endpoint
    direction=LineageQueryDirectionEnum.DESCENDANTS,
    include_edges=False,
)

associations = []
for vertex in query_result.vertices:
    associations.append(vertex.to_lineage_object().source.source_uri)

query_result = LineageQuery(sagemaker_session).query(
    start_arns=[model_artifact.artifact_arn],  # Model is the starting artifact
    query_filter=query_filter,
    # Find all the entities that ascend from the model, i.e. the datasets
    direction=LineageQueryDirectionEnum.ASCENDANTS,
    include_edges=False,
)

for vertex in query_result.vertices:
    associations.append(vertex.to_lineage_object().source.source_uri)

pp.pprint(associations)
```

**Example `LineageQueryDirectionEnum.BOTH` を使用して祖先と子孫の関係を見つける**  
方向が `BOTH` に設定されている場合、クエリはグラフを横断して、祖先と子孫の関係を見つけます。この横断は、開始ノードだけでなく、訪問先の各ノードから行われます。例えば、トレーニングジョブが 2 回実行され、トレーニングジョブによって生成されたモデルの両方がエンドポイントにデプロイされている場合、方向が `BOTH` に設定されたクエリの結果には両方のエンドポイントが示されます。これは、モデルのトレーニングとデプロイに同じイメージが使用されているためです。イメージはモデルと共通であるため、`start_arn` と両方のエンドポイントがクエリ結果に表示されます。  

```
query_filter = LineageFilter(
    entities=[LineageEntityEnum.ARTIFACT],
    sources=[LineageSourceEnum.ENDPOINT, LineageSourceEnum.DATASET],
)

query_result = LineageQuery(sagemaker_session).query(
    start_arns=[model_artifact.artifact_arn],  # Model is the starting artifact
    query_filter=query_filter,
    # This specifies that the query should look for associations both ascending and descending for the start
    direction=LineageQueryDirectionEnum.BOTH,
    include_edges=False,
)

associations = []
for vertex in query_result.vertices:
    associations.append(vertex.to_lineage_object().source.source_uri)

pp.pprint(associations)
```

**Example `LineageQuery` の方向 (`ASCENDANTS` と `DESCENDANTS`)**  
系統グラフの方向を理解するために、次のエンティティ関係グラフを取得します ([Dataset] (データセット) -> [Training Job] (トレーニングジョブ) -> [Model] (モデル) -> [Endpoint] (エンドポイント))。  
エンドポイントはモデルの子孫であり、モデルはデータセットの子孫です。同様に、モデルはエンドポイントの祖先です。`direction` パラメータを使用すると、`start_arns` のエンティティの子孫または祖先のエンティティをクエリで返すかどうかを指定できます。`start_arns` にモデルが含まれており、方向が `DESCENDANTS` の場合は、クエリはエンドポイントを返します。方向が `ASCENDANTS` の場合、クエリはデータセットを返します。  

```
# In this example, we'll look at the impact of specifying the direction as ASCENDANT or DESCENDANT in a `LineageQuery`.

query_filter = LineageFilter(
    entities=[LineageEntityEnum.ARTIFACT],
    sources=[
        LineageSourceEnum.ENDPOINT,
        LineageSourceEnum.MODEL,
        LineageSourceEnum.DATASET,
        LineageSourceEnum.TRAINING_JOB,
    ],
)

query_result = LineageQuery(sagemaker_session).query(
    start_arns=[model_artifact.artifact_arn],
    query_filter=query_filter,
    direction=LineageQueryDirectionEnum.ASCENDANTS,
    include_edges=False,
)

ascendant_artifacts = []

# The lineage entity returned for the Training Job is a TrialComponent which can't be converted to a
# lineage object using the method `to_lineage_object()` so we extract the TrialComponent ARN.
for vertex in query_result.vertices:
    try:
        ascendant_artifacts.append(vertex.to_lineage_object().source.source_uri)
    except:
        ascendant_artifacts.append(vertex.arn)

print("Ascendant artifacts : ")
pp.pprint(ascendant_artifacts)

query_result = LineageQuery(sagemaker_session).query(
    start_arns=[model_artifact.artifact_arn],
    query_filter=query_filter,
    direction=LineageQueryDirectionEnum.DESCENDANTS,
    include_edges=False,
)

descendant_artifacts = []
for vertex in query_result.vertices:
    try:
        descendant_artifacts.append(vertex.to_lineage_object().source.source_uri)
    except:
        # Handling TrialComponents.
        descendant_artifacts.append(vertex.arn)

print("Descendant artifacts : ")
pp.pprint(descendant_artifacts)
```

**Example 系統クエリを簡単にする SDK ヘルパー関数**  
クラス`EndpointContext`、`ModelArtifact`、`DatasetArtifact` には、`LineageQuery` API のラッパーであるヘルパー関数が備わっており、特定の系統クエリが活用しやすくなっています。以下の例は、これらのヘルパー関数の使用方法を示しています。  

```
# Find all the datasets associated with this endpoint

datasets = []
dataset_artifacts = endpoint_context.dataset_artifacts()
for dataset in dataset_artifacts:
    datasets.append(dataset.source.source_uri)
print("Datasets : ", datasets)

# Find the training jobs associated with the endpoint
training_job_artifacts = endpoint_context.training_job_arns()
training_jobs = []
for training_job in training_job_artifacts:
    training_jobs.append(training_job)
print("Training Jobs : ", training_jobs)

# Get the ARN for the pipeline execution associated with this endpoint (if any)
pipeline_executions = endpoint_context.pipeline_execution_arn()
if pipeline_executions:
    for pipeline in pipelines_executions:
        print(pipeline)

# Here we use the `ModelArtifact` class to find all the datasets and endpoints associated with the model

dataset_artifacts = model_artifact.dataset_artifacts()
endpoint_contexts = model_artifact.endpoint_contexts()

datasets = [dataset.source.source_uri for dataset in dataset_artifacts]
endpoints = [endpoint.source.source_uri for endpoint in endpoint_contexts]

print("Datasets associated with this model : ")
pp.pprint(datasets)

print("Endpoints associated with this model : ")
pp.pprint(endpoints)

# Here we use the `DatasetArtifact` class to find all the endpoints hosting models that were trained with a particular dataset
# Find the artifact associated with the dataset

dataset_artifact_arn = list(Artifact.list(source_uri=training_data))[0].artifact_arn
dataset_artifact = DatasetArtifact.load(artifact_arn=dataset_artifact_arn)

# Find the endpoints that used this training dataset
endpoint_contexts = dataset_artifact.endpoint_contexts()
endpoints = [endpoint.source.source_uri for endpoint in endpoint_contexts]

print("Endpoints associated with the training dataset {}".format(training_data))
pp.pprint(endpoints)
```

**Example 系統グラフの視覚化を取得する**  
ヘルパークラス `Visualizer` は、サンプルノートブック [visualizer.py](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-lineage/visualizer.py) で提供され、系統グラフのプロットをサポートします。クエリレスポンスがレンダリングされると、`StartArns` の系統関係を合わせたグラフが表示されます。`StartArns` からの視覚化には、`query_lineage` API アクションで返されたその他の系統エンティティとの関係が示されます。  

```
# Graph APIs
# Here we use the boto3 `query_lineage` API to generate the query response to plot.

from visualizer import Visualizer

query_response = sm_client.query_lineage(
    StartArns=[endpoint_context.context_arn], Direction="Ascendants", IncludeEdges=True
)

viz = Visualizer()
viz.render(query_response, "Endpoint")
        
        query_response = sm_client.query_lineage(
    StartArns=[model_artifact.artifact_arn], Direction="Ascendants", IncludeEdges=True
)
viz.render(query_response, "Model")
```

# クロスアカウントのリネージを追跡する
<a name="xaccount-lineage-tracking"></a>

Amazon SageMaker AI は、別の AWS アカウントからの系統エンティティの追跡をサポートしています。他の AWS アカウントは自身のリネージエンティティを共有でき、これらのリネージエンティティには直接 API コールまたは SageMaker AI リネージクエリを介してアクセスできます。

リネージリソースを安全に共有できるように、SageMaker AI では [AWS Resource Access Manager](https://docs.aws.amazon.com/ram/latest/userguide/what-is.html) が使用されます。リソースは [AWS RAM コンソール](https://console.aws.amazon.com/ram/home)から共有できます。



## クロスアカウントの系統追跡を設定する
<a name="setup-xaccount-lineage-tracking"></a>

Amazon SageMaker AI では、リネージグループを使用して[系統追跡エンティティ](lineage-tracking-entities.md)をグループ化して共有できます。SageMaker AI は、アカウントごとに 1 つのデフォルトのリネージグループのみをサポートします。アカウントにリネージエンティティが作成される都度、SageMaker AI はデフォルトのリネージグループを作成します。アカウントが所有するそれぞれの系統エンティティは、このデフォルトの系統グループに割り当てられます。系統エンティティを別のアカウントと共有する場合は、そのアカウントとこのデフォルトの系統グループを共有します。

**注記**  
系統グループ内のすべての系統追跡エンティティを共有できるほか、すべて共有しないようにも設定できます。

 AWS Resource Access Manager コンソールを使用して系統エンティティのリソース共有を作成します。詳しくは、AWS Resource Access Manager ユーザーガイドの「[AWS リソースを共有する](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html)」を参照してください。**

**注記**  
リソース共有の作成後、リソースとプリンシパルの関連付けが完了するまでに数分かかることがあります。関連付けが設定されると、リソース共有に参加するための招待が共有アカウントに届きます。共有リソースにアクセスするには、共有アカウントが招待を受理する必要があります。でリソース共有の招待を受け入れる方法の詳細については AWS RAM、*AWS 「 Resource Access Manager* [ユーザーガイド」の「共有 AWS リソース](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-shared.html)の使用」を参照してください。

### クロスアカウント系統追跡のリソースポリシー
<a name="setup-xaccount-lineage-tracking-resource-policy"></a>

Amazon SageMaker AI でサポートされるリソースポリシーは、単一のタイプのみです。SageMaker AI リソースポリシーでは、以下のすべてのオペレーションを許可する必要があります。

```
"sagemaker:DescribeAction"
"sagemaker:DescribeArtifact"
"sagemaker:DescribeContext"
"sagemaker:DescribeTrialComponent"
"sagemaker:AddAssociation"
"sagemaker:DeleteAssociation"
"sagemaker:QueryLineage"
```

**Example 以下は、アカウント系統グループのリソース共有を作成 AWS Resource Access Manager するために を使用して作成された SageMaker AI リソースポリシーです。**    
****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "FullLineageAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "111122223333"
      },
      "Action": [
        "sagemaker:DescribeAction",
        "sagemaker:DescribeArtifact",
        "sagemaker:DescribeContext",
        "sagemaker:DescribeTrialComponent",
        "sagemaker:AddAssociation",
        "sagemaker:DeleteAssociation",
        "sagemaker:QueryLineage"
      ],
      "Resource": "arn:aws:sagemaker:us-west-2:111111111111:lineage-group/sagemaker-default-lineage-group"
    }
  ]
}
```

## クロスアカウントで系統エンティティを追跡する
<a name="tracking-lineage-xaccount"></a>

クロスアカウントの系統追跡を使用すると、同じ `AddAssociation` API アクションを用いて、異なるアカウントの系統エンティティを関連付けることができます。2 つのリネージエンティティを関連付けると、SageMaker AI は、両方の系統エンティティに `AddAssociation` API アクションを実行するアクセス許可があるかどうかを検証します。その後、SageMaker AI で関連付けが確立されます。アクセス許可がない場合は、SageMaker AI で関連付けが作成*されません*。クロスアカウントの関連付けが確立されると、`QueryLineage` API アクションを通じて、いずれかの系統エンティティにもう一方からアクセスできます。詳細については、「[系統エンティティをクエリする](querying-lineage-entities.md)」を参照してください。

SageMaker AI は、リネージエンティティを自動的に作成するだけでなく、クロスアカウントアクセスがある場合、同じオブジェクトまたはデータを参照するアーティファクトを接続します。あるアカウントのデータが複数のアカウントによるリネージ追跡に使用されている場合、SageMaker AI は各アカウントにアーティファクトを作成し、そのデータを追跡します。クロスアカウントリネージでは、SageMaker AI が新しいアーティファクトを作成する都度、同じデータに対して作成され、ユーザーと共有されている他のアーティファクトがあるかどうかを SageMaker AI は確認します。その後、SageMaker AI は、`AssociationType` を `SameAs` に設定して、新しく作成されたアーティファクトと共有されている各アーティファクトとの関連付けを確立します。そうすると、`[QueryLineage](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_QueryLineage.html)` API アクションを使用することによって、自分のアカウントの系統エンティティから、自分と共有されているが別の AWS アカウントが所有している系統ティティへと通過することができます。詳細については、「[系統エンティティをクエリする](querying-lineage-entities.md)」を参照してください。

**Topics**
+ [別のアカウントから系統リソースにアクセスする](#tracking-lineage-xaccount-accessing-resources)
+ [クロスアカウントの系統エンティティのクエリの承認](#tracking-lineage-xaccount-authorization)

### 別のアカウントから系統リソースにアクセスする
<a name="tracking-lineage-xaccount-accessing-resources"></a>

系統を共有するためのクロスアカウントアクセスを設定すると、ARN で以下の SageMaker API アクションを直接呼び出すことによって、別のアカウントの共有系統エンティティを記述できます。
+ [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeAction.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeAction.html)
+ [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeArtifact.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeArtifact.html)
+ [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeContext.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeContext.html)
+ [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeTrialComponent.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DescribeTrialComponent.html)

以下の SageMaker API アクションを使用すると、自分と共有されているが別のアカウントが所有している系統エンティティの[関連付け](https://docs.aws.amazon.com/sagemaker/latest/dg/lineage-tracking-entities.html)を管理できます。
+ [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_AddAssociation.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_AddAssociation.html)
+ [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DeleteAssociation.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_DeleteAssociation.html)

SageMaker AI Lineage API を使ってアカウント間におわたってリネージをクエリする方法を解説したノートブックについては、[sagemaker-lineage-cross-account-with-ram.ipynb](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-lineage/sagemaker-lineage-cross-account-with-ram.ipynb) を参照してください。

### クロスアカウントの系統エンティティのクエリの承認
<a name="tracking-lineage-xaccount-authorization"></a>

Amazon SageMaker AI は、`StartArns` で`QueryLineage` API アクションを実行するアクセス許可があるかどうかを検証する必要があります。これは、`LineageGroup` にアタッチされたリソースポリシーによって適用されます。このアクションの結果には、自分のアカウントが所有しているのか、別のアカウントによって共有されているかにかかわらず、自分がアクセス権を持つすべての系統エンティティが含まれます。詳細については、「[系統エンティティをクエリする](querying-lineage-entities.md)」を参照してください。