翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # グラフ上の機械学習のための Amazon Neptune ML 多くの場合、大きな接続データセットには、人間の直感だけに基づくクエリを使用して抽出するのが難しい貴重な情報があります。機械学習 (ML) 手法は、数十億もの関係を持つグラフの隠れた相関を見つけるのに役立ちます。これらの相関関係は、製品の推奨、信用力の予測、詐欺の特定、その他多くの事柄に役立ちます。 Neptune ML 機能を使用すると、数週間ではなく数時間で、大きなグラフで便利な機械学習モデルを構築し、トレーニングすることができます。これを達成するために、Neptune ML は、[Amazon SageMaker AI](https://aws.amazon.com/sagemaker/) と [Deep Graph Library (DGL)](https://www.dgl.ai/) (これは[オープンソース](https://github.com/dmlc/dgl/)です) を活用したグラフニューラルネットワーク (GNN) 技術を使用しています。グラフニューラルネットワークは、人工知能における新たな分野です（例えば、[グラフニューラルネットワークに関する包括的な調査](https://arxiv.org/abs/1901.00596)を参照してください)。DGL での GNN の使用に関する実践的なチュートリアルについては、[ディープグラフライブラリを使用したグラフニューラルネットワークの学習](https://www.amazon.science/videos-webinars/learning-graph-neural-networks-with-deep-graph-library)を参照してください。 **注記** グラフの頂点は、Neptune ML モデルでは「ノード」として識別されます。例えば、頂点分類ではノード分類機械学習モデルを使用し、頂点リグレッションはノードリグレッションモデルを使用します。 ## Neptune MLができること Neptune は、トレーニング時に事前に計算された予測をその時点のグラフデータに基づいて返すトランスダクティブ推論と、現在のデータに基づいて適用データ処理とモデル評価をリアルタイムで返す帰納的推論の両方をサポートしています。「[帰納的推論とトランスダクティブ推論の違い](machine-learning-overview-evolving-data.md#inductive-vs-transductive-inference)」を参照してください。 Neptune ML は、次の 5 つの異なるカテゴリの推論をサポートするように機械学習モデルをトレーニングできます。 **Neptune ML で現在サポートされている推論タスクのタイプ** + **ノード分類** — 頂点プロパティのカテゴリカル特徴を予測します。 たとえば、*ショーシャンクの空に*という映画について、Neptune ML はその `genre` プロパティを `[story, crime, action, fantasy, drama, family, ...]` の候補集合から `story` として予測できます。 ノード分類タスクには 2 つのタイプがあります。 + **単一クラス分類**: この種のタスクでは、各ノードにはターゲットフィーチャが 1 つしかありません。たとえば、プロパティ、`Alan Turing` の `Place_of_birth` には `UK` 値があります。 + **複数クラス分類**: この種のタスクでは、各ノードにはターゲットフィーチャが 1 つしかありません。たとえば、映画*ゴッドファーザー*のプロパティ `genre` には `crime` および `story` の値があります。 + **ノードリグレッション** — 頂点の数値プロパティを予測します。 たとえば、映画*[アベンジャーズ/エンドゲーム]*では、Neptune MLはそのプロパティ `popularity` は `5.0` の値を有すると予測できます。 + **ノード分類** — 頂点プロパティのカテゴリカル特徴を予測します。 ノード分類タスクには 2 つのタイプがあります。 + **単一クラス分類**: この種のタスクでは、各ノードにはターゲットフィーチャが 1 つしかありません。たとえば、ユーザーと映画の間の評価エッジには、「はい」または「いいえ」のいずれかの値を持つ、プロパティ `liked` が含まれる場合があります。 + **複数クラス分類**: この種のタスクでは、各ノードにはターゲットフィーチャが 1 つしかありません。たとえば、ユーザーと映画の間の評価には、「面白い」、「心温まる」、「リラックスできる」などのプロパティタグに対する複数の値が含まれる場合があります。 + **エッジリグレッション** — エッジの数値プロパティを予測します。 たとえば、ユーザーと映画の間の評価エッジには、数値プロパティ `score` が含まれる場合があります。このためにNeptune MLは、ユーザーと映画を特定する値を予測できます。 + **リンク予測** — 特定のソースノードと発信エッジの最も可能性の高いデスティネーションノード、または特定のデスティネーションノードと着信エッジの最も可能性の高いソースノードを予測します。 例えば、薬物疾患の知識グラフでは、ソースノードとして `Aspirin`、出力エッジとして `treats`があり、Neptune ML は最も関連性の高い宛先ノードを `heart disease`、`fever`、などと予測できます。 または、ウィキメディアのナレッジグラフで与えられたエッジ `President-of` またはデスティネーションノードとしてリレーションおよび `United-States`の場合、Neptune MLは、最も関連性の高いヘッドを `George Washington`、`Abraham Lincoln`、`Franklin D. Roosevelt`、などのように予測できます。 **注記** ノード分類とエッジ分類は文字列値のみをサポートします。つまり、`0` や `1` などの数値プロパティ値はサポートされませんが、該当する文字列 `"0"` および `"1"` はサポートされます。同様に、ブールのプロパティ値 `true` および `false` は機能しませんが、`"true"` および `"false"` は機能します。 Neptune ML では、次の 2 つの一般的なカテゴリに分類される機械学習モデルを使用できます。 **Neptune ML で現在サポートされている機械学習モデルの種類** + **グラフニューラルネットワーク (GNN) モデル** — [ここにはリレーショナルグラフ畳み込みネットワーク (R-GCNS)](https://arxiv.org/abs/1703.06103) が含まれます。GNN モデルは、上記の 3 種類のタスクすべてに対して機能します。 + **ナレッジグラフ埋め込み (KGE) モデル** — ここには `TransE`、`DistMult`、`RotatE` モデルが含まれます。リンク予測のみに機能します。 **ユーザー定義のモデル** — Neptune ML では、上記のすべてのタイプのタスクに対して独自のカスタムモデル実装を提供することもできます。[Neptune ML ツールキット](https://github.com/awslabs/neptuneml-toolkit)で Neptune ML トレーニング API を使用する前に、Python ベースのカスタムモデル実装を開発およびテストします。Neptune ML のトレーニングインフラストラクチャと互換性があるように、実装を構造化して編成する方法の詳細については、[Neptune ML のカスタムモデル](machine-learning-custom-models.md) を参照してください。 # Neptune ML の設定 Neptune ML の使用を開始する最も簡単な方法は、[CloudFormation クイックスタートテンプレートを使用すること](machine-learning-quick-start.md)です。このテンプレートは、新しい Neptune DB クラスター、必要なすべての IAM ロール、新しい Neptune グラフノートブックなど、Neptune ML での作業を容易にするために必要なすべてのコンポーネントをインストールします。 [クイックスタート CloudFormation テンプレートを使用せずに Neptune ML をセットアップする](machine-learning-manual-setup.md) で説明されているように、Neptune ML を手動でインストールすることもできます。 # 新しい DB クラスターをすぐに使用し始めるための Neptune ML AWS CloudFormation テンプレートを使う Neptune ML の使用を開始する最も簡単な方法は、 CloudFormation クイックスタートテンプレートを使用することです。このテンプレートは、新しい Neptune DB クラスター、すべての必要な IAM ロール、新しい Neptune グラフノートブックなど、Neptune ML での作業を容易にするために必要なすべてのコンポーネントをインストールします。 **Neptune ML クイックスタートスタックを作成するには** 1. CloudFormation コンソールで CloudFormation スタックを起動するには、以下の表でいずれかの [**Launch Stack (スタックの起動)**] ボタンを選択します。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/neptune/latest/userguide/machine-learning-quick-start.html) 1. **[テンプレートを選択]** ページで、**[次へ]** を選択します。 1. [**詳細の指定**] ページで [**次へ**] を選択します。 1. [**Options(オプション)**] ページで、[**Next(次へ)**] を選択します。 1. **[Review]** (確認) ページでは、次の 2 つのチェックボックスをオンにする必要があります。 + 最初のもの AWS CloudFormation は、カスタム名で IAM リソースを作成する場合があることを認めます。 + 2 つ目は、AWS CloudFormation には新しいスタックの `CAPABILITY_AUTO_EXPAND` が必要になるかもしれないことを認識します。`CAPABILITY_AUTO_EXPAND` は明示的に CloudFormation がスタックの作成時に事前の確認なしにマクロを自動的に展開できるようにします。 カスタマーは、処理されたテンプレートから変更セットを作成することが多いため、実際にスタックを作成する前にマクロによって行われた変更を確認できます。詳細については、「CloudFormation [CreateStack](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) API」を参照してください。 次に **[作成]** を選択します。 クイックスタートテンプレートは以下を作成し、設定します。 + Neptune DB クラスター + 必要な IAM ロール (およびそれらをアタッチする)。 + 必要な Amazon EC2 セキュリティグループ。 + 必要な SageMaker AI VPC エンドポイント。 + Neptune ML の DB クラスターパラメータグループ。 + そのパラメータグループ内の必要なパラメータ。 + Neptune ML 用のノートブックサンプルが事前に入力された SageMaker AI ノートブック。すべてのリージョンですべてのインスタンスサイズが使用できるわけではないため、選択したノートブックインスタンスサイズが、リージョンでサポートされているサイズであることを確認する必要があります。 + Neptune-Export サービスとして。 クイックスタートスタックの準備ができたら、テンプレートが作成した SageMaker AI ノートブックに移動し、あらかじめ入力された例をチェックしてください。これらは、Neptune ML 機能の実験に使用するサンプルデータセットをダウンロードするのに役立ちます。 また、Neptune MLを使用しているときに多くの時間を節約できます。例えば、[%neptune\$1ml](notebooks-magics.md#notebooks-line-magics-neptune_ml) ラインマジック、およびこれらのノートブックがサポートする [%%neptune\$1ml](notebooks-magics.md#notebooks-cell-magics-neptune_ml) セルマジックを参照してください。 また、クイックスタート CloudFormation テンプレートを実行する次の AWS CLI コマンドテンプレートを使用することもできます。 ``` aws cloudformation create-stack \ --stack-name neptune-ml-fullstack-$(date '+%Y-%m-%d-%H-%M') \ --template-url https://aws-neptune-customer-samples.s3.amazonaws.com/v2/cloudformation-templates/neptune-ml-nested-stack.json \ --parameters ParameterKey=EnableIAMAuthOnExportAPI,ParameterValue=(true if you have IAM auth enabled, or false otherwise) \ ParameterKey=Env,ParameterValue=test$(date '+%H%M')\ --capabilities CAPABILITY_IAM \ --region (the AWS region, like us-east-1) \ --disable-rollback \ --profile (optionally, a named CLI profile of yours) ``` # クイックスタート CloudFormation テンプレートを使用せずに Neptune ML をセットアップする このガイドでは、 AWS CloudFormation クイックスタートテンプレートを使用せずに Amazon Neptune ML を設定するstep-by-stepについて説明します。Neptune DB クラスターが既に動作していることを前提としており、Neptune-Export サービスのインストール、カスタム IAM ロールの作成、Neptune ML を有効にするための DB クラスターの設定など、必要なセットアップについて説明します。Neptune エンジンに必要な SageMaker AI 管理 API へのアクセスを与えるために、ガイドで説明されているように、Neptune VPC に 2 つの SageMaker AI エンドポイントを作成する必要があります。これらの手順に従って、 CloudFormation テンプレートに依存することなく、既存の Neptune インフラストラクチャに Neptune ML を設定できます。 ## 動作中の Neptune DB クラスターから始める CloudFormation クイックスタートテンプレートを使用して Neptune ML をセットアップしない場合は、既存の Neptune DB クラスターを使用する必要があります。必要な場合は、既存のものを使用することも、既に使用しているものを複製することも、新しいものを作成することもできます (「[Neptune クラスターを作成する](get-started-create-cluster.md)」を参照)。 ## Neptune-Export サービスをインストールする まだの場合は、[Neptune-Export サービスを使用して Neptune データをエクスポートする](export-service.md) で説明されているように、Neptune-Export サービスをインストールしてください。 インストールによって作成される `NeptuneExportSecurityGroup` セキュリティグループに、以下の設定でインバウンドルールを追加します。 + *タイプ*: `Custom TCP` + *プロトコル*: `TCP` + *[Port range]* (ポート範囲): `80 - 443` + *ソース*: *(Neptune DB クラスターセキュリティグループ ID)* ## カスタム NeptuneLoadFromS3 IAM ロールを作成する まだ作成していない場合は、[Amazon S3 にアクセスするための IAM ロールの作成](bulk-load-tutorial-IAM-CreateRole.md) で説明されているように、カスタム `NeptuneLoadFromS3` IAM ロールを作成します。 ## カスタム NeptuneSageMakerIAMRole ロールを作成する 以下のポリシーを使用して、[IAM コンソール](https://console.aws.amazon.com/iam/)を使用し、カスタム `NeptuneSageMakerIAMRole` を作成します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "ec2:CreateNetworkInterface", "ec2:CreateNetworkInterfacePermission", "ec2:CreateVpcEndpoint", "ec2:DeleteNetworkInterface", "ec2:DeleteNetworkInterfacePermission", "ec2:DescribeDhcpOptions", "ec2:DescribeNetworkInterfaces", "ec2:DescribeRouteTables", "ec2:DescribeSecurityGroups", "ec2:DescribeSubnets", "ec2:DescribeVpcEndpoints", "ec2:DescribeVpcs" ], "Resource": "*", "Effect": "Allow" }, { "Action": [ "ecr:GetAuthorizationToken", "ecr:GetDownloadUrlForLayer", "ecr:BatchGetImage", "ecr:BatchCheckLayerAvailability" ], "Resource": "*", "Effect": "Allow" }, { "Action": [ "iam:PassRole" ], "Resource": [ "arn:aws:iam::*:role/*" ], "Condition": { "StringEquals": { "iam:PassedToService": [ "sagemaker.amazonaws.com" ] } }, "Effect": "Allow" }, { "Action": [ "kms:CreateGrant", "kms:Decrypt", "kms:GenerateDataKey*" ], "Resource": "arn:aws:kms:*:*:key/*", "Effect": "Allow" }, { "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogGroups", "logs:DescribeLogStreams", "logs:GetLogEvents" ], "Resource": [ "arn:aws:logs:*:*:log-group:/aws/sagemaker/*" ], "Effect": "Allow" }, { "Action": [ "sagemaker:AddTags", "sagemaker:CreateEndpoint", "sagemaker:CreateEndpointConfig", "sagemaker:CreateHyperParameterTuningJob", "sagemaker:CreateModel", "sagemaker:CreateProcessingJob", "sagemaker:CreateTrainingJob", "sagemaker:CreateTransformJob", "sagemaker:DeleteEndpoint", "sagemaker:DeleteEndpointConfig", "sagemaker:DeleteModel", "sagemaker:DescribeEndpoint", "sagemaker:DescribeEndpointConfig", "sagemaker:DescribeHyperParameterTuningJob", "sagemaker:DescribeModel", "sagemaker:DescribeProcessingJob", "sagemaker:DescribeTrainingJob", "sagemaker:DescribeTransformJob", "sagemaker:InvokeEndpoint", "sagemaker:ListTags", "sagemaker:ListTrainingJobsForHyperParameterTuningJob", "sagemaker:StopHyperParameterTuningJob", "sagemaker:StopProcessingJob", "sagemaker:StopTrainingJob", "sagemaker:StopTransformJob", "sagemaker:UpdateEndpoint", "sagemaker:UpdateEndpointWeightsAndCapacities" ], "Resource": [ "arn:aws:sagemaker:*:*:*" ], "Effect": "Allow" }, { "Action": [ "sagemaker:ListEndpointConfigs", "sagemaker:ListEndpoints", "sagemaker:ListHyperParameterTuningJobs", "sagemaker:ListModels", "sagemaker:ListProcessingJobs", "sagemaker:ListTrainingJobs", "sagemaker:ListTransformJobs" ], "Resource": "*", "Effect": "Allow" }, { "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:AbortMultipartUpload", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::*" ], "Effect": "Allow" } ] } ``` ------ このロールを作成するときに、以下のように信頼関係を編集します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "ec2.amazonaws.com", "rds.amazonaws.com", "sagemaker.amazonaws.com" ] }, "Action": "sts:AssumeRole" } ] } ``` ------ 最後に、この新しい `NeptuneSageMakerIAMRole` ロールに割り当てられた ARN をコピーします。 **重要** `NeptuneSageMakerIAMRole` 内の Amazon S3 アクセス許可が上記のものと一致していることを確認してください。 ユニバーサル ARN の場合、`arn:aws:s3:::*` は、上記のポリシーの Amazon S3 リソースに使用されます。何らかの理由でユニバーサル ARN を使用できない場合は、`arn:aws:s3:::graphlytics*` と、NeptuneML コマンドが使用する他のカスタマー Amazon S3 リソースの ARN をリソースセクションに追加する必要があります。 ## Neptune ML を有効にするように DB クラスターを設定する **Neptune ML の DB クラスターを設定するには** 1. [Neptune コンソール](https://console.aws.amazon.com/neptune)で、**[パラメータグループ]** に移動し、次に、使用する DB クラスターに関連付けられた DB クラスターパラメータグループに移動します。`neptune_ml_iam_role` パラメータを、作成した `NeptuneSageMakerIAMRole` ロールに割り当てられた ARN に設定します。 1. [データベース] に移動し、Neptune ML に使用する DB クラスターを選択します。**[アクション]**、**[IAM ロールの管理]** の順に選択します。 1. **[IAM ロールの管理]** ページで、**[ロールを追加]** を選択し、`NeptuneSageMakerIAMRole` を追加します。次に、`NeptuneLoadFromS3` ロールを追加します。 1. DB クラスターのライターインスタンスを再起動します。 ## Neptune VPC に SageMaker AI の 2 つのエンドポイントを作成します。 最後に、Neptune エンジンに必要な SageMaker AI 管理 API へのアクセスを与えるために、[Neptune VPC で SageMaker AI の 2 つのエンドポイントを作成します。](machine-learning-cluster-setup.md#machine-learning-sm-endpoints) で説明されているように、Neptune VPC に 2 つの SageMaker AI エンドポイントを作成する必要があります。 # Neptune ML 用の Neptune ノートブックの手動設定 Neptune SageMaker AI ノートブックには、Neptune ML 用のさまざまなサンプルノートブックがプリロードされています。これらのサンプルは、[オープンソースのグラフノートブック GitHub リポジトリ](https://github.com/aws/graph-notebook/tree/main/src/graph_notebook/notebooks/04-Machine-Learning)でプレビューできます。 既存の Neptune ノートブックを使用することも、必要に応じて独自のノートブックを作成することもできます。手順については、[Neptune ワークベンチを使用して Neptune ノートブックをホストする](graph-notebooks.md#graph-notebooks-workbench) を参照してください。 次の手順に従って、デフォルトの Neptune ノートブックを Neptune ML で使用するように設定することもできます。 **Neptune ML 用にノートブックを変更する** 1. Amazon SageMaker AI コンソール ([https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/)) を開きます。 1. 左側のナビゲーションペインで **[ノートブック]** を選択し、**[ノートブックインスタンス]** を選択します。Neptune ML に使用する Neptune ノートブックの名前を探して選択し、詳細ページに移動します。 1. ノートブックインスタンスが実行中の場合は、ノートブックの詳細ページの右上にある **[停止]** ボタンを選択します。 1. **[ノートブックインスタンス設定]** の **[ライフサイクル設定]** で、ノートブックのライフサイクルのページを開くリンクを選択します。 1. 右上の **[編集]** を選択し、**[続行]** を選択します。 1. **[ノートブックの開始]** タブで、スクリプトを変更して追加のエクスポートコマンドを含め、Neptune ML IAM ロールとエクスポートサービス URI のフィールドに入力します。シェルによっては以下のようになります。 ``` echo "export NEPTUNE_ML_ROLE_ARN=(your Neptune ML IAM role ARN)" >> ~/.bashrc echo "export NEPTUNE_EXPORT_API_URI=(your export service URI)" >> ~/.bashrc ``` 1. **[更新]** を選択します。 1. ノートブックインスタンスページに戻ります。**[アクセス許可と暗号化]** に、**[IAM ロール ARN]** のフィールドがあります。このフィールドのリンクを選択して、このノートブックインスタンスが実行される IAM ロールに移動します。 1. 次のような新しいインラインポリシーを作成します。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "cloudwatch:PutMetricData" ], "Resource": "arn:aws:cloudwatch:us-east-1:111122223333:*", "Sid": "AllowPutMetrics", "Effect": "Allow" }, { "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:DescribeLogStreams", "logs:PutLogEvents", "logs:GetLogEvents" ], "Resource": "arn:aws:logs:us-east-1:111122223333:*", "Sid": "AllowCreateLogs", "Effect": "Allow" }, { "Action": [ "s3:Put*", "s3:Get*", "s3:List*" ], "Resource": "arn:aws:s3:::*", "Sid": "AllowS3Actions", "Effect": "Allow" }, { "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:us-east-1:111122223333:*/*", "Sid": "AllowExecute", "Effect": "Allow" }, { "Action": [ "sagemaker:CreateModel", "sagemaker:CreateEndpointConfig", "sagemaker:CreateEndpoint", "sagemaker:DescribeModel", "sagemaker:DescribeEndpointConfig", "sagemaker:DescribeEndpoint", "sagemaker:DeleteModel", "sagemaker:DeleteEndpointConfig", "sagemaker:DeleteEndpoint" ], "Resource": "arn:aws:sagemaker:us-east-1:111122223333:*/*", "Sid": "AllowApiActions", "Effect": "Allow" }, { "Action": [ "iam:PassRole" ], "Resource": "arn:aws:iam::111122223333:role/role-name", "Sid": "AllowPassRole", "Effect": "Allow" } ] } ``` ------ 1. この新しいポリシーを保存し、ステップ 8 で IAM ロールにアタッチします。 1. SageMaker AI ノートブックインスタンスの詳細ページの右上にある **[開始]** を選択して、ノートブックインスタンスを起動します。 # を使用して DB クラスターで Neptune ML を AWS CLI セットアップする CloudFormation クイックスタートテンプレートと に加えて AWS マネジメントコンソール、 を使用して Neptune ML を設定することもできます AWS CLI。 ## 新しい Neptune ML クラスター用の DB クラスターパラメータグループを作成します。 次の AWS CLI コマンドは、新しい DB クラスターパラメータグループを作成し、Neptune ML で動作するように設定します。 **Neptune ML 用の DB クラスターパラメータグループを作成して設定するには** 1. 新しい DB クラスターのパラメータグループを作成します。 ``` aws neptune create-db-cluster-parameter-group \ --db-cluster-parameter-group-name (name of the new DB cluster parameter group) \ --db-parameter-group-family neptune1 --description "(description of your machine learning project)" \ --region (AWS region, such as us-east-1) ``` 1. SageMaker AI を呼び出してジョブを作成し、ホストされた ML モデルから予測を取得するときに使用する、DB クラスターの `SageMakerExcecutionIAMRole` の ARN に設定された `neptune_ml_iam_role` DB クラスターパラメータを作成します。 ``` aws neptune modify-db-cluster-parameter-group \ --db-cluster-parameter-group-name (name of the new DB cluster parameter group) \ --parameters "ParameterName=neptune_ml_iam_role, \ ParameterValue=ARN of the SageMakerExcecutionIAMRole, \ Description=NeptuneMLRole, \ ApplyMethod=pending-reboot" \ --region (AWS region, such as us-east-1) ``` このパラメータを設定すると、Neptune はコールごとにロールを渡す必要なく SageMaker AI にアクセスできます。 `SageMakerExcecutionIAMRole` を作成する方法については、[カスタム NeptuneSageMakerIAMRole ロールを作成する](machine-learning-manual-setup.md#ml-manual-setup-sm-role) を参照してください。 1. 最後に、新しい DB クラスターパラメーターグループのすべてのパラメータが希望通りに設定されていることを確認するには、`describe-db-cluster-parameters` を実行します。 ``` aws neptune describe-db-cluster-parameters \ --db-cluster-parameter-group-name (name of the new DB cluster parameter group) \ --region (AWS region, such as us-east-1) ``` ## Neptune ML で使用する DB クラスターに新しい DB クラスターパラメータグループをアタッチします。 これで、次のコマンドを使用して、作成した新しい DB クラスターパラメータグループを既存の DB クラスターにアタッチできます。 ``` aws neptune modify-db-cluster \ --db-cluster-identifier (the name of your existing DB cluster) \ --apply-immediately --db-cluster-parameter-group-name (name of your new DB cluster parameter group) \ --region (AWS region, such as us-east-1) ``` すべてのパラメータを有効にするために、DB クラスターを再起動します。 ``` aws neptune reboot-db-instance --db-instance-identifier (name of the primary instance of your DB cluster) \ --profile (name of your AWS profile to use) \ --region (AWS region, such as us-east-1) ``` または、Neptune ML で使用する新しい DB クラスターを作成する場合は、次のコマンドを使用して新しいパラメータグループがアタッチされたクラスターを作成し、新しいプライマリ (ライター) インスタンスを作成できます。 ``` cluster-name=(the name of the new DB cluster) aws neptune create-db-cluster --db-cluster-identifier ${cluster-name} --engine graphdb \ --engine-version 1.0.4.1 \ --db-cluster-parameter-group-name (name of your new DB cluster parameter group) \ --db-subnet-group-name (name of the subnet to use) \ --region (AWS region, such as us-east-1) aws neptune create-db-instance --db-cluster-identifier ${cluster-name} --db-instance-identifier ${cluster-name}-i \ --db-instance-class (the instance class to use, such as db.r5.xlarge) --engine graphdb \ --region (AWS region, such as us-east-1) ``` ## SageMaker AI および Amazon S3 リソースにアクセスできるように DB クラスターに `NeptuneSageMakerIAMRole` をアタッチする 最後に、[カスタム NeptuneSageMakerIAMRole ロールを作成する](machine-learning-manual-setup.md#ml-manual-setup-sm-role) に記載されている手順に従って、DB クラスターが SageMaker AI および Amazon S3 と通信できるようにする IAM ロールを作成します。次に、以下のコマンドを使用して、作成した `NeptuneSageMakerIAMRole` ロールを DB クラスターにアタッチします。 ``` aws neptune add-role-to-db-cluster --db-cluster-identifier ${cluster-name} --role-arn arn:aws:iam::(the ARN number of the role's ARN):role/NeptuneMLRole \ --region (AWS region, such as us-east-1) ``` ## Neptune VPC で SageMaker AI の 2 つのエンドポイントを作成します。 Neptune ML は、Neptune DB クラスターの VPC に 2 つの SageMaker AI エンドポイントを必要とします。 + `com.amazonaws.(AWS region, like us-east-1).sagemaker.runtime` + `com.amazonaws.(AWS region, like us-east-1).sagemaker.api` クイックスタート CloudFormation テンプレートを使用していない場合は、これらを自動的に作成します。次の AWS CLI コマンドを使用して作成できます。 これは、`sagemaker.runtime` エンドポイントを作成します。 ``` aws ec2 create-vpc-endpoint --vpc-id (the ID of your Neptune DB cluster's VPC) --vpc-endpoint-type Interface --service-name com.amazonaws.(AWS region, like us-east-1).sagemaker.runtime --subnet-ids (the subnet ID or IDs that you want to use) --security-group-ids (the security group for the endpoint network interface, or omit to use the default) --private-dns-enabled ``` そしてこれは、`sagemaker.api` エンドポイントを作成します。 ``` aws ec2 create-vpc-endpoint --vpc-id (the ID of your Neptune DB cluster's VPC) --vpc-endpoint-type Interface --service-name com.amazonaws.(AWS region, like us-east-1).sagemaker.api --subnet-ids (the subnet ID or IDs that you want to use) --security-group-ids (the security group for the endpoint network interface, or omit to use the default) --private-dns-enabled ``` また、[VPC コンソール](https://console.aws.amazon.com/vpc/) を使用して、これらのエンドポイントを作成することもできます。「[Secure prediction calls in Amazon SageMaker with AWS PrivateLink](https://aws.amazon.com/blogs/machine-learning/secure-prediction-calls-in-amazon-sagemaker-with-aws-privatelink/)」および[「Securing all Amazon SageMaker API calls with AWS PrivateLink](https://aws.amazon.com/blogs/machine-learning/securing-all-amazon-sagemaker-api-calls-with-aws-privatelink/)」を参照してください。 ## DB クラスターパラメータグループに SageMaker AI 推論エンドポイントパラメータを作成します。 すべてのクエリで使用しているモデルの SageMaker AI 推論エンドポイントを指定する必要がないようにするには、Neptune ML の DB クラスターパラメータグループで `neptune_ml_endpoint` という名前の DB クラスターパラメータを作成します。パラメータを、対象のインスタンスエンドポイントの `id` に設定します。 これを行うには、次の AWS CLI コマンドを使用します。 ``` aws neptune modify-db-cluster-parameter-group \ --db-cluster-parameter-group-name neptune-ml-demo \ --parameters "ParameterName=neptune_ml_endpoint, \ ParameterValue=(the name of the SageMaker AI inference endpoint you want to query), \ Description=NeptuneMLEndpoint, \ ApplyMethod=pending-reboot" \ --region (AWS region, such as us-east-1) ``` # Neptune ML 特徴の使い方の概要 Amazon Neptune の Neptune ML 機能は、グラフデータベース内の機械学習モデルを活用するための合理化されたワークフローを提供します。このプロセスには、Neptune から CSV 形式にデータをエクスポートする、データを前処理してモデルトレーニングの準備する、Amazon SageMaker AI を使用して機械学習モデルをトレーニングする、予測を処理する推論エンドポイントを作成する、Gremlin クエリから直接モデルをクエリする、といういくつかの重要なステップが含まれます。Neptune ワークベンチは、これらのステップの管理と自動化に役立つ便利なラインマジックコマンドとセルマジックコマンドを提供します。Neptune ML は、機械学習の機能をグラフデータベースに直接統合することで、Neptune グラフに保存されている豊富なリレーショナルデータを使用して貴重なインサイトを取得し、予測を行うことができます。 ## Neptune ML を使用するためのワークフローの開始 Amazon Neptune で Neptune ML 特徴を使用するには、通常、まず次の 5 つの手順が必要です。 ![\[Neptune ML ワークフロー図\]](http://docs.aws.amazon.com/ja_jp/neptune/latest/userguide/images/neptune-ML-workflow.png) 1. **データのエクスポートと設定** — データエクスポートステップでは、Neptune-Export サービスまたはNeptune から Amazon Simple Storage Service (Amazon S3) にデータを CSV 形式でエクスポートするための `neptune-export` コマンドラインツールを使用します。`training-data-configuration.json` という構成ファイルが同時に自動的に生成されます。これにより、エクスポートされたデータをトレーニング可能なグラフにロードする方法が指定されます。 1. **データの前処理** — このステップでは、エクスポートされたデータセットは標準的な手法を使用して前処理され、モデルトレーニング用に準備されます。数値データに対して特徴の正規化を実行でき、テキスト特徴は `word2vec` を使用して符号化できます。この手順の最後に、エクスポートされたデータセットから DGL (ディープグラフライブラリ) グラフが生成され、モデルトレーニングステップで使用できるようになります。 この手順は、アカウントの SageMaker AI 処理ジョブを使用して実装され、結果のデータは指定した Amazon S3 ロケーションに保存されます。 1. **モデルトレーニング** — モデルトレーニングステップは、予測に使用される機械学習モデルをトレーニングします。 モデルトレーニングは、次の2つの段階で行われます。 + 最初のステージでは、SageMaker AI 処理ジョブを使用して、モデルトレーニングに使用するモデルおよびモデルのハイパーパラメータ範囲のタイプを指定するモデルトレーニング戦略構成セットを生成します。 + 次に、第 2 段階では SageMaker AI モデルチューニングジョブを使用して、さまざまなハイパーパラメータ構成を試し、最もパフォーマンスの高いモデルを生成したトレーニングジョブを選択します。チューニングジョブは、処理されたデータに対して事前に指定された数のモデルトレーニングジョブ試行を実行します。このステージの最後に、最適なトレーニングジョブのトレーニング済みモデルパラメータを使用して、推論のためのモデルアーティファクトを生成します。 1. **Amazon SageMaker AI で推論エンドポイントを作成する** — 推論エンドポイントは、最適なトレーニングジョブによって生成されたモデルアーティファクトで起動される SageMaker AI エンドポイントインスタンスです。各モデルは 1 つのエンドポイントに関連付けられています。エンドポイントは、グラフデータベースからの受信リクエストを受け入れ、リクエストの入力に対するモデル予測を返すことができます。エンドポイントを作成した後も、削除するまでアクティブなままになります。 1. **Gremlin を使用して機械学習モデルを照会する** — Gremlin クエリ言語の拡張機能を使用して、推論エンドポイントから予測を照会できます。 **注記** [Neptune workbench](graph-notebooks.md#graph-notebooks-workbench) ラインマジックとセルマジックが含まれており、これらの手順の管理に多大な時間を節約できます。 [%neptune\$1ml](notebooks-magics.md#notebooks-line-magics-neptune_ml) [%%neptune\$1ml](notebooks-magics.md#notebooks-cell-magics-neptune_ml) # 変化するグラフデータに基づいて予測を行う 継続的に変化するグラフでは、新しいデータを使用して、定期的に新しいバッチ予測を作成する必要があるかもしれません。最新のデータに基づいて新しい予測をその場で生成する (帰納的推論) よりも、事前に計算された予測 (トランスダクティブ推論) をクエリするほうがはるかに高速です。どちらの方法にも、データの変化の速さやパフォーマンス要件に応じて弱点があります。 ## 帰納的推論とトランスダクティブ推論の違い トランスダクティブ推論を実行する場合、Neptune はトレーニング時に事前に計算された予測を検索して返します。 帰納的推論を実行する場合、Neptune は関連するサブグラフを作成し、そのプロパティを取得します。次に、DGL GNN モデルはデータ処理とモデル評価をリアルタイムで適用します。 そのため、帰納的推論では、トレーニング時には存在しなかったノードやエッジに関する予測や、グラフの現在の状態を反映した予測を生成できます。ただし、これにはレイテンシが大きくなるという代償が伴います。 グラフが動的な場合は、最新のデータを考慮に入れるために帰納的推論を使用することもできますが、グラフが静的な場合は、トランスダクティブ推論の方が速くて効率的です。 帰納的推論は、デフォルトでは無効です。クエリで Gremlin [Neptune\$1ml.inductiveInference](machine-learning-gremlin-inference-query-predicates.md#machine-learning-gremlin-inference-neptune-ml-inductiveInference) 述語を次のように使用することで、クエリで有効にできます。 ``` .with( "Neptune#ml.inductiveInference") ``` # インクリメンタルトランスダクティブワークフロー ステップ 1 ～ 3 (**データのエクスポートと設定**から**モデル変換**まで) を再実行するだけで、モデルアーティファクトを更新できますが、Neptune ML は、新しいデータを使用してバッチ ML 予測を更新する、より簡単な方法をサポートしています。1 つは、[インクリメンタルモデルワークフロー](#machine-learning-overview-incremental)を使用する方法で、もう 1 つは[ウォームスタートによるモデルの再トレーニング](#machine-learning-overview-model-retraining)です。 ## インクリメンタルモデルワークフロー このワークフローでは、ML モデルを再トレーニングせずに ML 予測を更新します。 **注記** これは、グラフデータが新しいノードやエッジで更新された場合にのみ実行できます。ノードが削除されると、今のところ動作しません。 1. **データのエクスポートと設定** — このステップは、メインワークフローと同じです。 1. **増分データの前処理** — このステップは、メインワークフローのデータ前処理ステップと似ていますが、特定のトレーニング済みモデルに対応する、以前に使用したのと同じ処理構成を使用します。 1. **モデルの変換** — モデルトレーニングステップではなく、このモデル変換ステップは、メインワークフローと増分データの前処理ステップの結果からトレーニング済みモデルを取得し、推論に使用する新しいモデルアーティファクトを生成します。モデル変換ステップは SageMaker AI 処理ジョブを起動して、更新されたモデルアーティファクトを生成する計算を実行します。 1. **Amazon SageMaker AI 推論エンドポイントを更新する** — オプションで、既存の推論エンドポイントがある場合、このステップでは、モデル変換ステップによって生成された新しいモデルアーティファクトでエンドポイントを更新します。または、新しいモデルのアーティファクトを使用して新しい推論エンドポイントを作成することもできます。 ## ウォームスタートでモデル再トレーニング このワークフローを使用して、増分グラフデータを使用して予測を行うための新しい ML モデルをトレーニングおよび展開できますが、メインワークフローを使用して生成された既存のモデルから開始します。 1. **データのエクスポートと設定** — このステップは、メインワークフローと同じです。 1. **増分データの前処理** — この手順は、増分モデル推論ワークフローの場合と同じです。新しいグラフデータは、以前にモデルトレーニングに使用したのと同じ処理方法で処理する必要があります。 1. **ウォームスタートでモデルトレーニング** — モデルトレーニングはメインワークフローで発生するものと似ていますが、前のモデルトレーニングタスクの情報を活用して、モデルのハイパーパラメータ検索を高速化できます。 1. **Amazon SageMaker AI 推論エンドポイントを更新する** — この手順は、増分モデル推論ワークフローの場合と同じです。 # Neptune ML のカスタムモデルのワークフロー Neptune ML では、Neptune ML がサポートする任意のタスクに対して、独自のカスタムモデルを実装、トレーニング、デプロイできます。カスタムモデルの開発およびデプロイのワークフローは、組み込みモデルの場合と基本的に同じですが、[カスタムモデルのワークフロー](machine-learning-custom-model-overview.md#machine-learning-custom-model-workflow) で説明するように、いくつかの違いがあります。 # Neptune ML ステージのインスタンス選択 Neptune ML 処理のさまざまなステージでは、異なる SageMaker AI インスタンスが使用されます。ここでは、ステージごとに適切なインスタンスタイプを選択する方法について説明します。SageMaker AI インスタンスタイプと価格については、「[Amazon SageMaker の料金](https://aws.amazon.com/sagemaker/pricing/)」を参照してください。 ## データ処理用のインスタンスの選択 SageMaker AI [データ処理](machine-learning-on-graphs-processing.md)ステップには入力、中間、および出力データを格納するための十分なメモリとディスクストレージがある[処理インスタンス](https://docs.aws.amazon.com/sagemaker/latest/dg/processing-job.html)を要します。必要なメモリとディスクストレージの特定の量は、Neptune ML グラフの特性とエクスポートされた機能によって異なります。 デフォルトでは、Neptune ML は、ディスク上にエクスポートされたグラフデータのサイズの 10 倍のメモリを持つ最も小さい `ml.r5` インスタンスを選択します。。 ## モデルトレーニングとモデル変換のインスタンスの選択 タスクタイプ、グラフサイズ、およびターンアラウンド要件によって異なる、[モデルトレーニング](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-training.html)または[モデルの変換](https://docs.aws.amazon.com/sagemaker/latest/dg/how-it-works-batch.html)の適切なインスタンスタイプの選択。GPU インスタンスは、最高のパフォーマンスを提供します。一般的に `p3` および `g4dn` シリアルインスタンスを推奨します。また、`p2` または `p4d` インスタンスもご使用いただけます。 デフォルトでは、Neptune ML はモデルトレーニングとモデル変換が必要とするよりも多くのメモリを持つ最小の GPU インスタンスを選択します。その選択内容については、Amazon S3 データ処理の出力場所に格納されている `train_instance_recommendation.json` ファイルに説明されています。この `train_instance_recommendation.json` ファイルの内容の例を示します。 ``` { "instance": "(the recommended instance type for model training and transform)", "cpu_instance": "(the recommended instance type for base processing instance)", "disk_size": "(the estimated disk space required)", "mem_size": "(the estimated memory required)" } ``` ## 推論エンドポイントのインスタンスを選択する タスクタイプ、グラフサイズ、予算に応じた[推論エンドポイント](machine-learning-on-graphs-inference-endpoint.md)に適切なインスタンスタイプの選択。デフォルトでは、Neptune ML は推論エンドポイントが必要とするメモリが多い最小の `ml.m5d` インスタンスを選択します。 **注記** 384 GB 以上のメモリが必要な場合は、Neptune MLは `ml.r5d.24xlarge` インスタンスを使用します。 Neptune ML が推奨するインスタンスタイプは、モデルトレーニングに使用している Amazon S3 の場所にある `infer_instance_recommendation.json` ファイルに記載されています。このファイルの内容例を示します。 ``` { "instance" : "(the recommended instance type for an inference endpoint)", "disk_size" : "(the estimated disk space required)", "mem_size" : "(the estimated memory required)" } ``` # Neptune-Export ツールまたは Neptune-Export サービスを使用して Neptune ML 用に Neptune からデータをエクスポートする Neptune ML では、[ディープグラフライブラリ (DGL)](https://www.dgl.ai/) にトレーニングデータを提供して、モデルを作成および評価する必要があります。 [Neptune-Export サービス](export-service.md) または [`neptune-export` ユーティリティ](export-utility.md)のいずれかの方法で、Neptune からデータをエクスポートできます。。サービスとコマンドラインツールの両方は、Amazon S3 サーバー側の暗号化 (`SSE-S3`) により暗号化された Amazon Simple Storage Service (Amazon S3) に CSV 形式でデータを公開します。「[Neptune-Export と `neptune-export` でエクスポートされたファイル](exported-files.md)」を参照してください。 さらに、Neptune ML のトレーニングデータのエクスポートを構成すると、エクスポートジョブは、エクスポートされたデータとともに暗号化されたモデルトレーニング構成ファイルを作成し、発行します。デフォルトでは、このファイルには `training-data-configuration.json` という名前が付けられます。 # Neptune-Export サービスを使用してトレーニングデータをNeptune ML へエクスポートする例 このリクエストは、ノード分類タスクのプロパティグラフトレーニングデータをエクスポートします。 ``` curl \ (your NeptuneExportApiUri) \ -X POST \ -H 'Content-Type: application/json' \ -d '{ "command": "export-pg", "outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export", "params": { "endpoint": "(your Neptune endpoint DNS name)", "profile": "neptune_ml" }, "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "node": "Movie", "property": "genre", "type": "classification" } ] } } }' ``` このリクエストは、ノード分類タスクの RDF トレーニングデータをエクスポートします。 ``` curl \ (your NeptuneExportApiUri) \ -X POST \ -H 'Content-Type: application/json' \ -d '{ "command": "export-rdf", "outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export", "params": { "endpoint": "(your Neptune endpoint DNS name)", "profile": "neptune_ml" }, "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "node": "http://aws.amazon.com/neptune/csv2rdf/class/Movie", "predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/genre", "type": "classification" } ] } } }' ``` # トレーニングデータをエクスポートするとき params オブジェクトで設定するフィールド エクスポートリクエストの `params` オブジェクトには、[`params` ドキュメンテーション](export-params-fields.md)で説明されているように、さまざまなフィールドを含めることができます。次のものは、機械学習トレーニングデータのエクスポートに最も関連性があります。 **** + **`endpoint`** — `endpoint` を使用してエクスポートプロセスでクエリを実行してデータを抽出できる DB クラスター内の Neptune インスタンスのエンドポイントを指定します。 + **`profile`** — `params` オブジェクト内の `profile` フィールドは **`neptune-ml`** に設定する必要があります。 これにより、エクスポートプロセスでは、エクスポートされたデータが Neptune ML モデルトレーニング、プロパティグラフデータ用の CSV 形式、または RDF データの場合は N トリプルとして適切にフォーマットされます。また、エクスポートされたトレーニングデータと同じ Amazon S3 の場所にファイル `training-data-configuration.json` が作成されび書き込まれます。 + **`cloneCluster`** — `true` に設定されている場合、エクスポートプロセスによって DB クラスターのクローンが作成され、クローンからエクスポートされ、完了するとクローンが削除されます。 + **`useIamAuth`** — DB クラスターが [ IAM 認証](iam-auth-enable.md)有効となっている場合は、このフィールドを `true` に設定する必要があります。 エクスポートプロセスでは、エクスポートするデータをフィルタリングする方法もいくつかあります ([これらの例](export-filtering-examples.md)を参照)。 # モデルトレーニング情報のエクスポートを調整する additionalParams オブジェクトの使用 `additionalParams` オブジェクトには、トレーニング目的で機械学習クラスのラベルと特徴を指定し、トレーニングデータ設定ファイルの作成をガイドするために使用できるフィールドが含まれています。 エクスポートプロセスでは、トレーニング用の例として使用するために、機械学習クラスラベルにするノードとエッジプロパティを自動的に推論することはできません。また、数値、カテゴリ、およびテキストプロパティの最適な特徴エンコーディングを自動的に推論することもできないため、`additionalParams` オブジェクトのフィールドを使用してこれらを指定するか、デフォルトのエンコーディングを上書きします。 プロパティグラフデータの場合、エクスポートリクエストにおける `additionalParams` の最上位構造は次のとおりです。 ``` { "command": "export-pg", "outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export", "params": { "endpoint": "(your Neptune endpoint DNS name)", "profile": "neptune_ml" }, "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ (an array of node and edge class label targets) ], "features": [ (an array of node feature hints) ] } } } ``` RDF データの場合、最上位の構造は次のようになります。 ``` { "command": "export-rdf", "outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export", "params": { "endpoint": "(your Neptune endpoint DNS name)", "profile": "neptune_ml" }, "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ (an array of node and edge class label targets) ] } } } ``` また、`jobs` フィールドを使用して複数のエクスポート設定を指定することもできます。 ``` { "command": "export-pg", "outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export", "params": { "endpoint": "(your Neptune endpoint DNS name)", "profile": "neptune_ml" }, "additionalParams" : { "neptune_ml" : { "version": "v2.0", "jobs": [ { "name" : "(training data configuration name)", "targets": [ (an array of node and edge class label targets) ], "features": [ (an array of node feature hints) ] }, { "name" : "(another training data configuration name)", "targets": [ (an array of node and edge class label targets) ], "features": [ (an array of node feature hints) ] } ] } } } ``` # additionalParams の neptune\$1ml フィールドの最上位要素 ## neptune\$1ml のバージョン要素 生成するトレーニングデータ設定のバージョンを指定します。 (*オプション*)、*タイプ*: 文字列、*デフォルト値*:"v2.0"。 `version` を含める場合、それを `v2.0` に設定します。 ## neptune\$1ml のジョブフィールド トレーニングデータ構成オブジェクトの配列を格納し、それぞれがデータ処理ジョブを定義し、以下を含みます。 + **`name`** — 作成するトレーニングデータ構成の名前。 たとえば、「job-number-1」 という名前のトレーニングデータ構成では、`job-number-1.json` という名前のトレーニングデータ構成ファイルが作成されます。 + **`targets`** — トレーニング用の機械学習クラスラベルを表すノードおよびエッジクラスラベルターゲットの JSON 配列。「[neptune\$1ml オブジェクトのターゲットフィールド](machine-learning-neptune_ml-targets.md)」を参照してください。 + **`features`** — ノードプロパティ特徴の JSON 配列。「[neptune\$1ml の機能フィールド](machine-learning-neptune_ml-features.md)」を参照してください。 # neptune\$1ml オブジェクトのターゲットフィールド JSON トレーニングデータエクスポート設定の `targets` フィールドには、トレーニングタスク、およびこのタスクを学習するための機械学習クラスラベルを指定するターゲットオブジェクトの配列が含まれます。ターゲットオブジェクトの内容は、プロパティグラフデータと RDF データのどちらについてトレーニングしているかによって異なります。 プロパティグラフノードの分類とリグレッションタスクでは、配列内のターゲットオブジェクトは次のようになります。 ``` { "node": "(node property-graph label)", "property": "(property name)", "type" : "(used to specify classification or regression)", "split_rate": [0.8,0.2,0.0], "separator": "," } ``` プロパティグラフのエッジ分類、リグレッション、またはリンク予測タスクでは、次のようになります。 ``` { "edge": "(edge property-graph label)", "property": "(property name)", "type" : "(used to specify classification, regression or link_prediction)", "split_rate": [0.8,0.2,0.0], "separator": "," } ``` RDF 分類とリグレッションタスクでは、配列内のターゲットオブジェクトは次のようになります。 ``` { "node": "(node type of an RDF node)", "predicate": "(predicate IRI)", "type" : "(used to specify classification or regression)", "split_rate": [0.8,0.2,0.0] } ``` RDF リンク予測タスクの場合、配列内のターゲットオブジェクトは次のようになります。 ``` { "subject": "(source node type of an edge)", "predicate": "(relation type of an edge)", "object": "(destination node type of an edge)", "type" : "link_prediction", "split_rate": [0.8,0.2,0.0] } ``` ターゲットオブジェクトには、次のフィールドを含めることができます。 **Contents** + [プロパティグラフのターゲットフィールド](#machine-learning-property-graph-neptune_ml-targets) + [ノード](#machine-learning-property-graph-neptune_ml-targets-node) + [エッジ](#machine-learning-property-graph-neptune_ml-targets-edge) + [property](#machine-learning-property-graph-neptune_ml-targets-property) + [型](#machine-learning-property-graph-neptune_ml-targets-type) + [split\$1rate](#machine-learning-property-graph-neptune_ml-targets-split_rate) + [separator](#machine-learning-property-graph-neptune_ml-targets-separator) + [RDF ターゲットフィールド](#machine-learning-RDF-neptune_ml-targets) + [ノード](#machine-learning-RDF-neptune_ml-targets-node) + [subject](#machine-learning-RDF-neptune_ml-targets-subject) + [述語](#machine-learning-RDF-neptune_ml-targets-predicate) + [オブジェクト](#machine-learning-RDF-neptune_ml-targets-object) + [型](#machine-learning-RDF-neptune_ml-targets-type) + [split\$1rate](#machine-learning-RDF-neptune_ml-targets-split_rate) ## プロパティグラフターゲットオブジェクトのフィールド ### ターゲットオブジェクトのノード (頂点) フィールド ターゲットノード (頂点) のプロパティグラフラベル。ターゲットオブジェクトには、`node` 要素または `edge` 要素を含めますが、両方ではありません。 ある `node` は次のように、単一の値を取ることができます。 ``` "node": "Movie" ``` または、マルチラベル頂点の場合、次のように値の配列をとることができます。 ``` "node": ["Content", "Movie"] ``` ### プロパティグラフターゲットオブジェクトのエッジフィールド ターゲットエッジを、開始ノードラベル、独自のラベル、および終了ノードラベルで指定します。ターゲットオブジェクトには、`edge` 要素または `node` 要素を含めますが、両方ではありません。 `edge` フィールドの値は、開始ノードのプロパティグラフラベル、エッジ自体のプロパティグラフラベル、および終了ノードのプロパティグラフラベルを表す 3 つの文字列からなる JSON 配列です。 ``` "edge": ["Person_A", "knows", "Person_B"] ``` 開始ノードや終了ノードに複数のラベルがある場合は、次のように配列で囲みます。 ``` "edge": [ ["Admin", Person_A"], "knows", ["Admin", "Person_B"] ] ``` ### プロパティグラフターゲットオブジェクトのプロパティフィールド ターゲットの頂点またはエッジのプロパティを次のように指定します。 ``` "property" : "rating" ``` このフィールドは、ターゲットタスクがリンク予測の場合を除き、必須です。 ### プロパティグラフターゲットオブジェクトのタイプフィールド 次のように、`node` または `edge` で実行されるターゲットタスクのタイプを示します。 ``` "type" : "regression" ``` ノードでサポートされているタスクタイプは次のとおりです。 + `classification` + `regression` エッジでサポートされているタスクタイプは次のとおりです。 + `classification` + `regression` + `link_prediction` このフィールドは必須です。 ### プロパティグラフターゲットオブジェクトの split\$1rate フィールド (*オプション*) トレーニング、検証、テストの各段階でそれぞれ使用するノードまたはエッジの比率の推定。これらの比率は、ゼロから 1 までの間の 3 つの数値の JSON 配列で表されます。 ``` "split_rate": [0.7, 0.1, 0.2] ``` オプションの `split_rate` フィールドを指定しない場合、デフォルトの推定値は分類タスクとリグレッションタスク用に `[0.9, 0.1, 0.0]` であり、リンク予測タスク用は `[0.9,0.05, 0.05]` です。 ### プロパティグラフターゲットオブジェクトの区切りフィールド (*オプション*) 分類タスクで使用します。 `separator` フィールドは、文字列に複数のカテゴリ値を格納する場合に、ターゲットプロパティ値を複数のカテゴリ値に分割するために使用する文字を指定します。例: ``` "separator": "|" ``` `separator` フィールドの存在は、そのタスクがマルチターゲット分類タスクであることを示します。 ## RDF ターゲットオブジェクトのフィールド ### RDF ターゲットオブジェクトのノードフィールド ターゲットノードのノードタイプを定義します。ノード分類タスクまたはノードリグレッションタスクで使用されます。RDF のノードのノードタイプは、以下で定義されます。 ``` node_id, , node_type ``` RDF `node` は次のように、単一の値を取ることができます。 ``` "node": "http://aws.amazon.com/neptune/csv2rdf/class/Movie" ``` ### RDF ターゲットオブジェクトの subject フィールド リンク予測タスクの場合、`subject` はターゲットエッジの始点ノードタイプを定義します。 ``` "subject": "http://aws.amazon.com/neptune/csv2rdf/class/Director" ``` **注記** リンク予測タスクの場合、`subject` は `predicate` および `object` とともに使用する必要があります。これら 3 つのいずれかが指定されていない場合、すべてのエッジがトレーニングターゲットとして扱われます。 ### RDF ターゲットオブジェクトの述語フィールド ノード分類およびノードリグレッションタスクの場合、`predicate` はターゲットノードのターゲットノード特徴として使用されるリテラルデータを定義します。 ``` "predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/genre" ``` **注記** ターゲットノードにターゲットノードの特徴を定義する述語が 1 つしかない場合は、`predicate` フィールドは省略できます。 リンク予測タスクの場合、`predicate` はターゲットエッジの関連タイプを定義します。 ``` "predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/direct" ``` **注記** リンク予測タスクの場合、`predicate` は `subject` および `object` とともに使用する必要があります。これら 3 つのいずれかが指定されていない場合、すべてのエッジがトレーニングターゲットとして扱われます。 ### RDF ターゲットオブジェクトのオブジェクトフィールド リンク予測タスクの場合、`object` はターゲットエッジの終点ノードタイプを定義します。 ``` "object": "http://aws.amazon.com/neptune/csv2rdf/class/Movie" ``` **注記** リンク予測タスクの場合、`object` は `subject` および `predicate` とともに使用する必要があります。これら 3 つのいずれかが指定されていない場合、すべてのエッジがトレーニングターゲットとして扱われます。 ### RDF ターゲットオブジェクトのタイプフィールド 次のように、実行するターゲットタスクのタイプを示します。 ``` "type" : "regression" ``` RDF データでサポートされているタスクタイプは次のとおりです。 + `link_prediction` + `classification` + `regression` このフィールドは必須です。 ### プロパティグラフターゲットオブジェクトの `split_rate` フィールド (*オプション*) トレーニング、検証、テストの各段階でそれぞれ使用するノードまたはエッジの比率の推定。これらの比率は、ゼロから 1 までの間の 3 つの数値の JSON 配列で表されます。 ``` "split_rate": [0.7, 0.1, 0.2] ``` オプション `split_rate` フィールドを指定しない場合、デフォルトの推定値は `[0.9, 0.1, 0.0]` です。 # neptune\$1ml の機能フィールド プロパティ値と RDF リテラルには、さまざまな形式とデータ型があります。機械学習で優れたパフォーマンスを実現するには、これらの値を*特徴*として知られる数値エンコーディングに変換することが不可欠です。 Neptune ML は、[Neptune ML での特徴エンコーディング](machine-learning-feature-encoding.md) で説明されているように、データのエクスポートおよびデータ処理手順の一部として、特徴抽出とエンコーディングを実行します。 プロパティグラフデータセットの場合、エクスポートプロセスにより、文字列プロパティおよび複数の値を含む数値プロパティの `auto` 特徴が自動的に推論されます。単一の値を含む数値プロパティの場合、`numerical` 特徴を推論します。します。日付のプロパティについては、`datetime` 特徴を推論します。 自動推論特徴仕様をオーバーライドする場合、またはプロパティにバケット数値、TF-IDF、FastText、または SBERT 仕様を追加する場合は、特徴フィールドを使用して特徴のエンコーディングを制御できます。 **注記** 使用できるのは `features` フィールドのみで、RDF データではなく、プロパティグラフデータの特徴仕様を制御します。 自由形式のテキストの場合、Neptune ML はいくつかの異なるモデルを使用して、文字列プロパティ値内のトークンのシーケンスを固定サイズの実数値ベクトルに変換できます。 + [`text_fasttext`](machine-learning-feature-encoding.md#machine-learning-fasttext-features) — [fastText](https://fasttext.cc/) エンコーディングを使用します。これは、fastText がサポートする 5 つの言語のうちの 1 つだけを使用するフィーチャに推奨されるエンコーディングです。 + [`text_sbert`](machine-learning-feature-encoding.md#machine-learning-sbert-features) — [Sentence BERT](https://www.sbert.net/docs/pretrained_models.html#sentence-embedding-models) (SBERT) エンコーディングモデルを使用します。これは、`text_fasttext` がサポートしていないテキストについて推奨されるエンコーディングです。 + [`text_word2vec`](machine-learning-feature-encoding.md#machine-learning-word2vec-features) — [Google](https://code.google.com/archive/p/word2vec/) が最初に公開した [Word2Vec](https://wikipedia.org/wiki/Word2vec) アルゴリズムを使用して、テキストをエンコードします。Word2Vec は英語のみをサポートしています。 + [`text_tfidf`](machine-learning-feature-encoding.md#machine-learning-tfidf-features) — [term frequency–inverse document frequency](https://wikipedia.org/wiki/Tf-idf) (TF-IDF) ベクタライザを使用して、テキストのエンコードを行います。TF-IDF エンコーディングは、他のエンコーディングにはない統計機能をサポートします。 `features` フィールドには、ノードプロパティ特徴の JSON 配列が含まれます。ターゲットオブジェクトには、次のフィールドを含めることができます。 **Contents** + [ノード](#machine-learning-neptune_ml-features-node) + [エッジ](#machine-learning-neptune_ml-features-edge) + [property](#machine-learning-neptune_ml-features-property) + [型](#machine-learning-neptune_ml-feature-types) + [norm](#machine-learning-neptune_ml-features-norm) + [言語](#machine-learning-neptune_ml-features-language) + [max\$1length](#machine-learning-neptune_ml-features-max_length) + [separator](#machine-learning-neptune_ml-features-separator) + [範囲](#machine-learning-neptune_ml-features-range) + [bucket\$1cnt](#machine-learning-neptune_ml-features-bucket_cnt) + [slide\$1window\$1size](#machine-learning-neptune_ml-features-slide_window_size) + [imputer](#machine-learning-neptune_ml-features-imputer) + [maxfeatures](#machine-learning-neptune_ml-features-max_features) + [min\$1df](#machine-learning-neptune_ml-features-min_df) + [ngram\$1range](#machine-learning-neptune_ml-features-ngram_range) + [datetime\$1parts](#machine-learning-neptune_ml-features-datetime_parts) ## 機能のノードフィールド `node` フィールドは、特徴頂点のプロパティグラフラベルを指定します。例: ``` "node": "Person" ``` 頂点に複数のラベルがある場合は、配列を使用してそれらを含めます。例えば、次のようになります。 ``` "node": ["Admin", "Person"] ``` ## 機能のエッジフィールド `edge` フィールドは、特徴エッジのエッジタイプを指定します。エッジタイプは、始点頂点のプロパティグラフラベル、エッジのプロパティグラフラベル、および終点頂点のプロパティグラフラベルを含む配列で構成されます。エッジ特徴を指定するときは、3 つの値すべてを指定する必要があります。例: ``` "edge": ["User", "reviewed", "Movie"] ``` エッジタイプの始点または終点頂点に複数のラベルがある場合は、別の配列を使用してラベルを格納します。例えば、次のようになります。 ``` "edge": [["Admin", "Person"]. "edited", "Post"] ``` ## 機能のプロパティフィールド プロパティパラメータを使用して、`node` パラメータで識別される頂点のプロパティを指定します。例えば、次のようになります。 ``` "property" : "age" ``` ## 特徴のタイプフィールドで使用できる値 `type` パラメータは、定義するフィーチャのタイプを指定します。例: ``` "type": "bucket_numerical" ``` **`type` パラメータの使用できる値** + **`"auto"`** — Neptune ML がプロパティタイプを自動的に検出し、適切な特徴エンコーディングを適用するように指定します。`auto` 特徴には、オプションで `separator` フィールドも使用できます。 「[Neptune ML での自動特徴エンコーディング](machine-learning-feature-encoding.md#machine-learning-auto-encoding)」を参照してください。 + **`"category"`** — この特徴エンコーディングは、プロパティ値をいくつかのカテゴリの 1 つとして表します。つまり、特徴は 1 つ以上の離散値を取ることができます。`category` 特徴には、オプションで `separator` フィールドも使用できます。 「[Neptune MLのカテゴリ別特徴](machine-learning-feature-encoding.md#machine-learning-categorical-features)」を参照してください。 + **`"numerical"`** — この特徴エンコーディングは、数値プロパティ値を「より大きい」と「より小さい」が意味を持つ連続間隔の数値として表します。 `numerical` 特徴には、オプションで `norm`、`imputer`、`separator` フィールドも使用できます。 「[Neptune MLのカテゴリ別特徴](machine-learning-feature-encoding.md#machine-learning-numerical-features)」を参照してください。 + **`"bucket_numerical"`** — この特徴エンコーディングは、数値のプロパティ値を*バケット*またはカテゴリのセットに分割します。 たとえば、人の年齢を、子供 (0 ～20 歳)、若年大人 (20 ～ 40 歳)、中年 (40 ～ 60 歳)、および高齢者 (60歳以上) の 4 つのバケットで符号化できます。 `bucket_numerical` 特徴には `range` と `bucket_cnt` フィールドが必須で、オプションで、`imputer` および/または `slide_window_size` フィールドを使用できます。 「[Neptune MLの Bucket-numerical 特徴](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features)」を参照してください。 + **`"datetime"`** — この特徴エンコーディングは、datetime プロパティ値を、年、月、曜日、および時間の分類的特徴の配列として表します。 これら 4 つのカテゴリのうち 1 つ以上は、`datetime_parts` パラメータを使って排除できます。 「[Neptune ML のDatetime 特徴](machine-learning-feature-encoding.md#machine-learning-datetime-features)」を参照してください。 + **`"text_fasttext"`** — この特徴エンコーディングは、[fastText](https://fasttext.cc/) モデルを使用して、文または自由形式のテキストで構成されるプロパティ値を数値ベクトルに変換します。英語 (`en`)、中国語 (`zh`)、ヒンディー語 (`hi`)、スペイン語 (`es`)、フランス語 (`fr`) の 5 つの言語をサポートしています。この 5 つの言語のいずれかのテキストプロパティ値の場合、`text_fasttext`が推奨されるエンコーディングです。ただし、同じ文に複数の言語の単語が含まれている場合は処理できません。 fastText がサポートする言語以外の言語では、`text_sbert` エンコーディングを使用してください。 例えば、120 トークンを超えるプロパティ値のテキスト文字列が多数ある場合は、`max_length` フィールドを使用して、`"text_fasttext"` がエンコードする各文字列のトークンの数を制限します。 「[Neptune ML でのテキストプロパティ値の *fastText* エンコーディング](machine-learning-feature-encoding.md#machine-learning-fasttext-features)」を参照してください。 + **`"text_sbert"`** — このエンコーディングは、[Sententh BERT](https://www.sbert.net/docs/pretrained_models.html#sentence-embedding-models) (SBERT) モデルを使用してテキストプロパティ値を数値ベクトルに変換します。Neptune は 2 つの SBERT メソッドをサポートしています。すなわち、`text_sbert128` (`text_sbert` とだけ指定した場合のデフォルト) と `text_sbert512` です。両者の違いは、エンコードされるテキストプロパティ内のトークンの最大数です。`text_sbert128` エンコーディングでは最初の 128 トークンのみがエンコードされるのに対し、`text_sbert512` は最大 512 トークンをエンコードします。その結果、`text_sbert512` を使用する場合は、`text_sbert128` よりも処理時間が長くなる可能性があります。どちらの方法も、`text_fasttext` より遅くなります。 `text_sbert*` の方法は、多くの言語をサポートしており、複数の言語を含む文をエンコードできます。 「[Neptune MLにおけるテキストフィーチャの Sentence BERT (SBERT) エンコーディング](machine-learning-feature-encoding.md#machine-learning-sbert-features)」を参照してください。 + **`"text_word2vec"`** — このエンコーディングは、[Word2Vec](https://wikipedia.org/wiki/Word2vec) アルゴリズムを使用して、テキストプロパティ値を数値ベクトルに変換します。英語のみをサポートしています。 「[Neptune ML でのテキストフィーチャの Word2Vec エンコーディング](machine-learning-feature-encoding.md#machine-learning-word2vec-features)」を参照してください。 + **`"text_tfidf"`** — このエンコーディングは、[term frequency–inverse document frequency](https://wikipedia.org/wiki/Tf-idf) (TF-IDF) ベクタライザーを使用して、テキストプロパティ値を数値ベクトルに変換します。 `text_tfidf` 機能エンコーディングのパラメータは、`ngram_range` フィールド、`min_df` フィールド、および `max_features` フィールドを使用して定義します。 「[Neptune ML でのテキストフィーチャの TF-IDF エンコーディング](machine-learning-feature-encoding.md#machine-learning-tfidf-features)」を参照してください。 + **`"none"`** — `none` タイプを使用すると、特徴エンコーディングは実行されません。代わりに生プロパティ値が解析され、保存されます。 カスタムモデルトレーニングの一部として独自のカスタム特徴エンコーディングを実行する予定の場合のみ `none` を使用します。 ## norm フィールド このフィールドは数値特徴に必須です。数値に使用する正規化方法を指定します。 ``` "norm": "min-max" ``` 次の正規化メソッドがサポートされています。 + **"min-max"** — 最小値を減算し、最大値と最小値の差で除算して、各値を正規化します。 + **"standard"** — すべての値の合計で割って、各値を正規化します。 + **"none"** — エンコーディング中に数値を正規化しないでください。 「[Neptune MLのカテゴリ別特徴](machine-learning-feature-encoding.md#machine-learning-numerical-features)」を参照してください。 ## language フィールド 言語フィールドは、テキストプロパティ値に使用される言語を指定します。その使用法は、テキストのエンコード方法によって異なります。 + [`text_fasttext`](machine-learning-feature-encoding.md#machine-learning-fasttext-features) エンコーディングの場合、このフィールドは必須であり、以下の言語のいずれかを指定する必要があります。 + `en`   (英語) + `zh`   (中国語) + `hi`   (ヒンディー語) + `es`   (スペイン語) + `fr`   (フランス語) + [`text_sbert`](machine-learning-feature-encoding.md#machine-learning-fasttext-features) エンコーディングの場合、SBERT エンコーディングは多言語であるため、このフィールドは使用されません。 + [`text_word2vec`](machine-learning-feature-encoding.md#machine-learning-word2vec-features) エンコーディングの場合、`text_word2vec` は英語のみをサポートするため、このフィールドはオプションです。存在する場合は、英語言語モデルの名前を指定する必要があります。 ``` "language" : "en_core_web_lg" ``` + [`text_tfidf`](machine-learning-feature-encoding.md#machine-learning-tfidf-features) エンコーディングの場合、このフィールドは使用されません。 ## max\$1length フィールド `max_length` フィールドは、`text_fasttext` 機能についてはオプションであり、入力テキストフィーチャ内のエンコードされるトークンの最大数を指定します。`max_length` より長い入力テキストは切り捨てられます。例えば、max\$1length を 128 に設定すると、テキストシーケンス内の 128 番目より後のトークンは無視されます。 ``` "max_length": 128 ``` ## separator フィールド このフィールドはオプションで `category`、`numerical` および `auto` と使用されます。プロパティ値を複数のカテゴリ値または数値に分割するために使用できる文字を指定します。 ``` "separator": ";" ``` たとえば、`"Actor;Director"`または`"0.1;0.2"`といった、プロパティが複数の区切り値を 1 つの文字列に格納する場合にのみ、この `separator` フィールドを使用してください。 - [カテゴリ別特徴](machine-learning-feature-encoding.md#machine-learning-categorical-features)、[数値特徴](machine-learning-feature-encoding.md#machine-learning-numerical-features)、[自動エンコーディング](machine-learning-feature-encoding.md#machine-learning-auto-encoding) フィールド ## range フィールド このフィールドは `bucket_numerical` 特徴に必須です。バケットに分割する数値の範囲を、`[lower-bound, upper-bound]` の形式で指定します。 ``` "range" : [20, 100] ``` プロパティ値が下限より小さい場合は、最初のバケットに割り当てられます。上限よりも大きい場合は最後のバケットに割り当てられます。 「[Neptune MLの Bucket-numerical 特徴](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features)」を参照してください。 ## bucket\$1cnt フィールド このフィールドは `bucket_numerical` 特徴に必須です。これは、`range` パラメータにより定義される数値範囲が分割されるバケットの数を指定します。 ``` "bucket_cnt": 10 ``` 「[Neptune MLの Bucket-numerical 特徴](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features)」を参照してください。 ## slide\$1window\$1size フィールド このフィールドはオプションで `bucket_numerical` 特徴と使用して複数のバケットに値を割り当てます。 ``` "slide_window_size": 5 ``` スライドウィンドウの仕組みでは、Neptune ML はウィンドウサイズ **`s`** を取り、プロパティの各数値 **`v`** を ` v - s/2 ` から ` v + s/2 ` の範囲内へ変換します。この値は、範囲が重なるすべてのバケットに割り当てられます。 「[Neptune MLの Bucket-numerical 特徴](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features)」を参照してください。 ## imputer フィールド このフィールドはオプションで `numerical` および `bucket_numerical` 特徴と使用して欠損値を埋めるためのインプテーション手法を提供します。 ``` "imputer": "mean" ``` サポートされているインプテーション手法は次のとおりです。 + `"mean"` + `"median"` + `"most-frequent"` imputer パラメータを含めない場合、欠落した値が見つかったときにデータの前処理が停止し、終了します。 「[Neptune MLのカテゴリ別特徴](machine-learning-feature-encoding.md#machine-learning-numerical-features)」および「[Neptune MLの Bucket-numerical 特徴](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features)」を参照してください。 ## max\$1features フィールド このフィールドはオプションで `text_tfidf` 特徴と使用して符号化する項の最大数を指定します。 ``` "max_features": 100 ``` 100 に設定すると、TF-IDF ベクタライザーは最も一般的な項を 100 個だけ符号化します。指定しない場合、デフォルト値は `max_features` 5,000 です。 「[Neptune ML でのテキストフィーチャの TF-IDF エンコーディング](machine-learning-feature-encoding.md#machine-learning-tfidf-features)」を参照してください。 ## min\$1df フィールド このフィールドはオプションで `text_tfidf` 特徴と使用して符号化する項の最低ドキュメント頻度を指定します。 ``` "min_df": 5 ``` 5 に設定されている場合、符号化されるためには、少なくとも 5 つの異なるプロパティ値に項が含まれている必要があります。 この `min_df` パラメータを使用しない場合、デフォルト値は `2` です。 「[Neptune ML でのテキストフィーチャの TF-IDF エンコーディング](machine-learning-feature-encoding.md#machine-learning-tfidf-features)」を参照してください。 ## ngram\$1range フィールド このフィールドはオプションで `text_tfidf` 特徴と使用して、符号化する可能性のある個々の項として考慮すべき単語またはトークンのサイズを指定します。 ``` "ngram_range": [2, 4] ``` 値 `[2, 4]` は、2、3、4 語のシーケンスが潜在的な個別項として考慮されることを指定します。 `ngram_range` と明示的に設定しない場合のデフォルトは `[1, 1]` で、符号化する項として単一の単語またはトークンのみを考慮することを意味します。 「[Neptune ML でのテキストフィーチャの TF-IDF エンコーディング](machine-learning-feature-encoding.md#machine-learning-tfidf-features)」を参照してください。 ## datetime\$1parts フィールド このフィールドはオプションで `datetime` 特徴と使用して datetime 値のどの部分をカテゴリ別に符号化するかを指定します。 ``` "datetime_parts": ["weekday", "hour"] ``` `datetime_parts` を含めない場合、デフォルトでは、Neptune ML は datetime 値の年、月、曜日、および時間の部分を符号化します。値 `["weekday", "hour"]` は、datetime 値の曜日と時間のみを特徴内でカテゴリ的に符号化する必要があることを示します。 パートの 1 つがトレーニングセットに複数の固有値を持たない場合、そのパートは符号化されません。 「[Neptune ML のDatetime 特徴](machine-learning-feature-encoding.md#machine-learning-datetime-features)」を参照してください。 # モデルトレーニング構成のチューニング用に additionalParams 内のパラメータを使用する例 次の例は、プロパティグラフおよび RDF データモデルで「additionalParams」機能を使用して、Neptune ML アプリケーションのモデルトレーニングプロセスのさまざまな側面を設定する方法を示しています。この例では、training/validation/test データのデフォルトの分割レートの指定、ノード分類、リグレッション、リンク予測タスクの定義、数値バケット、テキスト埋め込み、日時、カテゴリ別データなどのさまざまな機能タイプの設定など、さまざまな機能について説明します。これらの詳細な設定により、機械学習パイプラインを特定のデータとモデリング要件に合わせて調整し、Neptune ML 機能の可能性を最大限に引き出すことができます。 **Contents** + [additionalParams を使用したプロパティグラフの例](#machine-learning-property-graph-additionalParams-examples) + [モデルトレーニングコン構成のデフォルトの分割レートの指定](#machine-learning-property-graph-additionalParams-default-split-rate-example) + [モデルトレーニング構成のノード分類タスクの指定](#machine-learning-property-graph-additionalParams-node-classification-example) + [モデルトレーニング構成のマルチクラスノード分類タスクの指定](#machine-learning-property-graph-additionalParams-multi-class-example) + [モデルトレーニング構成のノードリグレッションタスクの指定](#machine-learning-property-graph-additionalParams-node-regression-example) + [モデルトレーニング構成のエッジ分類タスクの指定](#machine-learning-property-graph-additionalParams-edge-classification-example) + [モデルトレーニング構成のマルチクラスエッジ分類タスクの指定](#machine-learning-property-graph-additionalParams-multi-edge-classification-example) + [モデルトレーニング構成のエッジリグレッションの指定](#machine-learning-property-graph-additionalParams-edge-regression-example) + [モデルトレーニング構成のノード回帰タスクの指定](#machine-learning-property-graph-additionalParams-link-prediction-example) + [数値バケット特徴の指定](#machine-learning-property-graph-additionalParams-numeric-bucket-example) + [`Word2Vec` 特徴の指定](#machine-learning-property-graph-additionalParams-word2vec-example) + [`FastText` 特徴の指定](#machine-learning-property-graph-additionalParams-fasttext-example) + [`Sentence BERT` 特徴の指定](#machine-learning-property-graph-additionalParams-sbert-example) + [`TF-IDF` 特徴の指定](#machine-learning-property-graph-additionalParams-tf-idf-example) + [`datetime` 特徴の指定](#machine-learning-property-graph-additionalParams-datetime-example) + [`category` 特徴の指定](#machine-learning-property-graph-additionalParams-category-example) + [`numerical` 特徴の指定](#machine-learning-property-graph-additionalParams-numerical-example) + [`auto` 特徴の指定](#machine-learning-property-graph-additionalParams-auto-example) + [`additionalParams` を使用した RDF の例](#machine-learning-RDF-additionalParams-examples) + [モデルトレーニングコン構成のデフォルトの分割レートの指定](#machine-learning-RDF-additionalParams-default-split-rate-example) + [モデルトレーニング構成のノード分類タスクの指定](#machine-learning-RDF-additionalParams-node-classification-example) + [モデルトレーニング構成のノードリグレッションタスクの指定](#machine-learning-RDF-additionalParams-node-regression-example) + [特定のエッジのリンク予測タスクの指定](#machine-learning-RDF-additionalParams-link-prediction-example) + [すべてのエッジのリンク予測タスクの指定](#machine-learning-RDF-additionalParams-link-prediction-example) ## additionalParams を使用したプロパティグラフの例 ### モデルトレーニングコン構成のデフォルトの分割レートの指定 次の例で、`split_rate` パラメーターは、モデルトレーニングの既定の分割率を設定します。デフォルトの分割レートが指定されていない場合、トレーニングでは [0.9, 0.1, 0.0] の値が使用されます。ターゲット単位でデフォルト値を上書きするには、各ターゲットに対して `split_rate` を指定します。 次の例は、`default split_rate` フィールドは、ターゲット単位で上書きしない限り `[0.7,0.1,0.2]` の分割レートが使用されることを示します。 ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "split_rate": [0.7,0.1,0.2], "targets": [ (...) ], "features": [ (...) ] } } ``` ### モデルトレーニング構成のノード分類タスクの指定 トレーニング目的でラベル付きの例が含まれているノードプロパティがどれかを示すには、ノード分類要素を `targets` 配列に追加し、`"type" : "classification"` を使用します。デフォルトの分割レートを上書きする場合は、`split_rate` フィールドをの追加します。 次の例で、`node` ターゲットは、各 `Movie` ノードの `genre` プロパティはノードクラスラベルとして扱われることを示しています。`split_rate` 値は、デフォルトの分割レートを上書きします。 ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "node": "Movie", "property": "genre", "type": "classification", "split_rate": [0.7,0.1,0.2] } ], "features": [ (...) ] } } ``` ### モデルトレーニング構成のマルチクラスノード分類タスクの指定 トレーニング目的で複数のラベル付き例が含まれているノードプロパティがどれかを示すには、次のようにしてターゲット配列にノード分類要素を追加します。`"type" : "classification"`、および `separator` を使用し、ターゲットプロパティ値を複数のカテゴリ値に分割するために使用できる文字を指定します。デフォルトの分割レートを上書きする場合は、`split_rate` フィールドをの追加します。 次の例で、`node` ターゲットは、各 `Movie` ノードの `genre` プロパティはノードクラスラベルとして扱われることを示しています。`separator` フィールドは、各ジャンルプロパティに複数のセミコロン区切り値が含まれていることを示します。 ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "node": "Movie", "property": "genre", "type": "classification", "separator": ";" } ], "features": [ (...) ] } } ``` ### モデルトレーニング構成のノードリグレッションタスクの指定 トレーニング目的でラベル付きのリグレッションが含まれているノードプロパティがどれかを示すには、`"type" : "regression"` を使用してノード分類要素をターゲット配列に追加します。デフォルトの分割レートを上書きする場合は、split\$1rate フィールドを追加します。 次の `node` ターゲットは、各 `rating` ノードの `Movie` プロパティはリグレッションラベルとして扱われることを示しています。 ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "node": "Movie", "property": "rating", "type" : "regression", "split_rate": [0.7,0.1,0.2] } ], "features": [ ... ] } } ``` ### モデルトレーニング構成のエッジ分類タスクの指定 トレーニング目的のラベル付きの例が含まれているエッジプロパティがどれかを示すには、エッジ要素を `targets` 配列に追加し、`"type" : "regression"` を使用します。デフォルトの分割レートを上書きする場合は、split\$1rate フィールドを追加します。 次の `edge` ターゲットは、各 `knows` エッジの `metAtLocation` プロパティはエッジクラスラベルとして扱われることを示しています。 ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "edge": ["Person", "knows", "Person"], "property": "metAtLocation", "type": "classification" } ], "features": [ (...) ] } } ``` ### モデルトレーニング構成のマルチクラスエッジ分類タスクの指定 トレーニング目的で複数のラベル付き例が含まれているエッジプロパティを指定するには、エッジ要素を `targets` 配列に追加し、`"type" : "classification"`、および `separator` フィールドを使用して、ターゲットプロパティ値を複数のカテゴリ値に分割するために使用される文字を指定します。デフォルトの分割レートを上書きする場合は、`split_rate` フィールドをの追加します。 次の `edge` ターゲットは、各 `repliedTo` エッジの `sentiment` プロパティはエッジクラスラベルとして扱われることを示しています。区切りフィールドは、各センチメントプロパティに複数のカンマ区切り値が含まれていることを示します。 ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "edge": ["Person", "repliedTo", "Message"], "property": "sentiment", "type": "classification", "separator": "," } ], "features": [ (...) ] } } ``` ### モデルトレーニング構成のエッジリグレッションの指定 トレーニング目的のラベル付きリグレッションの例が含まれているエッジプロパティがどれかを示すには、`edge` 要素を `targets` 配列に追加し、`"type" : "regression"` を使用します。デフォルトの分割レートを上書きする場合は、`split_rate` フィールドをの追加します。 次の `edge` ターゲットは、各 `rating` エッジの `reviewed` プロパティはエッジリグレッションとして扱われることを示しています。 ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "edge": ["Person", "reviewed", "Movie"], "property": "rating", "type" : "regression" } ], "features": [ (...) ] } } ``` ### モデルトレーニング構成のノード回帰タスクの指定 リンク予測トレーニングの目的でどのエッジが使用されるかを示すには、`"type" : "link_prediction"` を使用してターゲット配列にエッジ要素を追加します。デフォルトの分割レートを上書きする場合は、`split_rate` フィールドをの追加します。 次の `edge` ターゲットは、`cites` エッジがリンク予測に使用されることを示しています。 ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "edge": ["Article", "cites", "Article"], "type" : "link_prediction" } ], "features": [ (...) ] } } ``` ### 数値バケット特徴の指定 ノードプロパティの数値データ特徴を指定するには、`"type": "bucket_numerical"` を `features` 配列に追加します。 次の `node` 特徴は、それぞれの `Person` ノード の `age` プロパティが数値バケット特徴として処理されることを示しています。 ``` "additionalParams": { "neptune_ml": { "targets": [ ... ], "features": [ { "node": "Person", "property": "age", "type": "bucket_numerical", "range": [1, 100], "bucket_cnt": 5, "slide_window_size": 3, "imputer": "median" } ] } } ``` ### `Word2Vec` 特徴の指定 `"type": "text_word2vec"` を `features` 配列に追加することでノードプロパティの `Word2Vec` 特徴を指定できます。 次の `node` 特徴は、それぞれの `Movie` ノード の `description` プロパティが `Word2Vec` 特徴として処理されることを示しています。 ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ ... ], "features": [ { "node": "Movie", "property": "description", "type": "text_word2vec", "language": "en_core_web_lg" } ] } } ``` ### `FastText` 特徴の指定 `"type": "text_fasttext"` を `features` 配列に追加することでノードプロパティの `FastText` 特徴を指定できます。`language` フィールドは必須であり、次のいずれかの言語コードを指定する必要があります。 + `en`   (英語) + `zh`   (中国語) + `hi`   (ヒンディー語) + `es`   (スペイン語) + `fr`   (フランス語) `text_fasttext` エンコーディングでは、1 つの機能で同時に複数の言語を処理できないことに注意してください。 次の `node` 機能は、それぞれの `Movie` ノード のフランス語の `description` プロパティが `FastText` 機能として処理されることを示しています。 ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ ... ], "features": [ { "node": "Movie", "property": "description", "type": "text_fasttext", "language": "fr", "max_length": 1024 } ] } } ``` ### `Sentence BERT` 特徴の指定 `"type": "text_sbert"` を `features` 配列に追加することでノードプロパティの `Sentence BERT` 特徴を指定できます。このメソッドは多言語言語モデルを使用してテキストフィーチャを自動的にエンコードするため、言語を指定する必要はありません。 次の `node` 特徴は、それぞれの `Movie` ノード の `description` プロパティが `Sentence BERT` 特徴として処理されることを示しています。 ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ ... ], "features": [ { "node": "Movie", "property": "description", "type": "text_sbert128", } ] } } ``` ### `TF-IDF` 特徴の指定 `"type": "text_tfidf"` を `features` 配列に追加することでノードプロパティの `TF-IDF` 特徴を指定できます。 次の `node` 特徴は、それぞれの `Person` ノード の `bio` プロパティが `TF-IDF` 特徴として処理されることを示しています。 ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ ... ], "features": [ { "node": "Movie", "property": "bio", "type": "text_tfidf", "ngram_range": [1, 2], "min_df": 5, "max_features": 1000 } ] } } ``` ### `datetime` 特徴の指定 エクスポートプロセスにより、`datetime` 日付プロパティの特徴が自動的に推論されます。ただし、通常は `auto` 特徴として処理されるプロパティが明示的に `datetime` 特徴として処理されるように `datetime` 特徴に使用される `datetime_parts` を制限する、または特徴仕様を上書きする場合は、`"type": "datetime"` 特徴を追加します。 次の `node` 特徴は、それぞれの `Post` ノード の `createdAt` プロパティが `datetime` 特徴として処理されることを示しています。 ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ ... ], "features": [ { "node": "Post", "property": "createdAt", "type": "datetime", "datetime_parts": ["month", "weekday", "hour"] } ] } } ``` ### `category` 特徴の指定 エクスポートプロセスにより、文字列プロパティおよび複数の値を含む数値プロパティの `auto` 特徴が自動的に推論されます。単一の値を含む数値プロパティの場合、`numerical` 特徴を推論します。します。日付のプロパティについては、`datetime` 特徴を推論します。 プロパティがカテゴリ特徴として扱われるように、特徴仕様を上書きする場合は、`"type": "category"` を特徴配列に追加します。プロパティに複数の値が含まれている場合は、`separator` フィールドを含めます。例: ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ ... ], "features": [ { "node": "Post", "property": "tag", "type": "category", "separator": "|" } ] } } ``` ### `numerical` 特徴の指定 エクスポートプロセスにより、文字列プロパティおよび複数の値を含む数値プロパティの `auto` 特徴が自動的に推論されます。単一の値を含む数値プロパティの場合、`numerical` 特徴を推論します。します。日付のプロパティについては、`datetime` 特徴を推論します。 プロパティを `numerical` 特徴として処理するために特徴仕様を上書きしたい場合は、`"type": "numerical"` を特徴配列に追加します。プロパティに複数の値が含まれている場合は、`separator` フィールドを含めます。例: ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ ... ], "features": [ { "node": "Recording", "property": "duration", "type": "numerical", "separator": "," } ] } } ``` ### `auto` 特徴の指定 エクスポートプロセスにより、文字列プロパティおよび複数の値を含む数値プロパティの `auto` 特徴が自動的に推論されます。単一の値を含む数値プロパティの場合、`numerical` 特徴を推論します。します。日付のプロパティについては、`datetime` 特徴を推論します。 プロパティを `auto` 特徴として処理するために特徴仕様を上書きしたい場合は、`"type": "auto"` を特徴配列に追加します。プロパティに複数の値が含まれている場合は、`separator` フィールドを含めます。例: ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ ... ], "features": [ { "node": "User", "property": "role", "type": "auto", "separator": "," } ] } } ``` ## `additionalParams` を使用した RDF の例 ### モデルトレーニングコン構成のデフォルトの分割レートの指定 次の例で、`split_rate` パラメーターは、モデルトレーニングの既定の分割率を設定します。デフォルトの分割レートが指定されていない場合、トレーニングでは [0.9, 0.1, 0.0] の値が使用されます。ターゲット単位でデフォルト値を上書きするには、各ターゲットに対して `split_rate` を指定します。 次の例は、`default split_rate` フィールドは、ターゲット単位で上書きしない限り `[0.7,0.1,0.2]` の分割レートが使用されることを示します。 ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "split_rate": [0.7,0.1,0.2], "targets": [ (...) ] } } ``` ### モデルトレーニング構成のノード分類タスクの指定 トレーニング目的のラベル付きの例が含まれているノードプロパティがどれかを示すには、ノード分類要素を `targets` 配列に追加し、`"type" : "classification"` を使用します。ノードフィールドを追加して、ターゲットノードのノードタイプを指定します。`predicate` フィールドを追加して、ターゲットノードのターゲットノード特徴として使用されるリテラルデータを定義します。デフォルトの分割レートを上書きする場合は、`split_rate` フィールドをの追加します。 次の例で、`node` ターゲットは、各 `Movie` ノードの `genre` プロパティはノードクラスラベルとして扱われることを示しています。`split_rate` 値は、デフォルトの分割レートを上書きします。 ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "node": "http://aws.amazon.com/neptune/csv2rdf/class/Movie", "predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/genre", "type": "classification", "split_rate": [0.7,0.1,0.2] } ] } } ``` ### モデルトレーニング構成のノードリグレッションタスクの指定 トレーニング目的でラベル付きのリグレッションが含まれているノードプロパティがどれかを示すには、`"type" : "regression"` を使用してノード分類要素をターゲット配列に追加します。`node` フィールドを追加して、ターゲットノードのノードタイプを指定します。`predicate` フィールドを追加して、ターゲットノードのターゲットノード特徴として使用されるリテラルデータを定義します。デフォルトの分割レートを上書きする場合は、`split_rate` フィールドをの追加します。 次の `node` ターゲットは、各 `rating` ノードの `Movie` プロパティはリグレッションラベルとして扱われることを示しています。 ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "node": "http://aws.amazon.com/neptune/csv2rdf/class/Movie", "predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/rating", "type": "regression", "split_rate": [0.7,0.1,0.2] } ] } } ``` ### 特定のエッジのリンク予測タスクの指定 リンク予測トレーニングの目的に使用するエッジを指定するには、`"type" : "link_prediction"` を使用してターゲット配列にエッジ要素を追加します。`subject`、`predicate` および `object` フィールドを追加して、エッジタイプを指定します。デフォルトの分割レートを上書きする場合は、`split_rate` フィールドをの追加します。 次の `edge` ターゲットは、`Directors` を `Movies` に接続する `directed` エッジがリンク予測に使用されることを示しています。 ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "subject": "http://aws.amazon.com/neptune/csv2rdf/class/Director", "predicate": "http://aws.amazon.com/neptune/csv2rdf/datatypeProperty/directed", "object": "http://aws.amazon.com/neptune/csv2rdf/class/Movie", "type" : "link_prediction" } ] } } ``` ### すべてのエッジのリンク予測タスクの指定 リンク予測トレーニングの目的に使用するエッジを指定するには、`"type" : "link_prediction"` を使用してターゲット配列に `edge` 要素を追加します。`subject`、`predicate` または `object` フィールドは追加しません。デフォルトの分割レートを上書きする場合は、`split_rate` フィールドをの追加します。 ``` "additionalParams": { "neptune_ml": { "version": "v2.0", "targets": [ { "type" : "link_prediction" } ] } } ``` # Neptune からエクスポートされたグラフデータをトレーニング用に処理する データ処理ステップでは、エクスポートプロセスによって Neptune グラフデータが取得され、トレーニング中に[ディープグラフライブラリ (DGL)](https://www.dgl.ai/) が使用する情報が作成されます。これには、さまざまなデータマッピングと変換の実行が含まれます。 + ノードとエッジを解析して、DGL で必要とされるグラフおよび ID マッピングファイルを構築する。 + ノードとエッジプロパティを DGL で必要なノードおよびエッジ特徴に変換する。 + データをトレーニング、検証、およびテストセットに分割します。 ## Neptune ML のデータ処理ステップを管理する モデルトレーニングに使用するデータを Neptune からエクスポートした後、`curl` (または `awscurl`) コマンドを使用してデータ処理ジョブを開始できます。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/dataprocessing \ -H 'Content-Type: application/json' \ -d '{ "inputDataS3Location" : "s3://(Amazon S3 bucket name)/(path to your input folder)", "id" : "(a job ID for the new job)", "processedDataS3Location" : "s3://(S3 bucket name)/(path to your output folder)", "configFileName" : "training-job-configuration.json" }' ``` このコマンドの使用方法の詳細については、[データ処理コマンド](machine-learning-api-dataprocessing.md) を参照してください。また、実行中のジョブのステータスの取得方法、実行中のジョブの停止方法、実行中のすべてのジョブの一覧表示方法について説明した情報もご覧ください。 ## Neptune ML の更新されたグラフデータの処理 また、`previousDataProcessingJobId` をAPI に追加して、新しいデータ処理ジョブが前のジョブと同じ処理方法を使用するようにします。これは、新しいデータで古いモデルを再学習するか、新しいデータのモデルアーティファクトを再計算することによって、Neptune で更新されたグラフデータの予測を取得する場合に必要です。 これを行うには、次のような `curl` (または `awscurl`) コマンドを使います。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/dataprocessing \ -H 'Content-Type: application/json' \ -d '{ "inputDataS3Location" : "s3://(Amazon S3 bucket name)/(path to your input folder)", "id" : "(a job ID for the new job)", "processedDataS3Location" : "s3://(Amazon S3 bucket name)/(path to your output folder)", "previousDataProcessingJobId", "(the job ID of the previous data-processing job)"}' ``` トレーニング済みモデルに対応する前のデータ処理ジョブのジョブ ID に `previousDataProcessingJobId` パラメータの値を設定します。 **注記** 更新されたグラフでのノードの削除は、現在サポートされていません。更新されたグラフでノードが削除されている場合は、`previousDataProcessingJobId` を使用するのではなく、まったく新しいデータ処理ジョブを開始する必要があります。 # Neptune ML での特徴エンコーディング プロパティ値と RDF リテラルには、さまざまな形式とデータ型があります。機械学習で優れたパフォーマンスを実現するには、これらの値を*特徴*として知られる数値エンコーディングに変換することが不可欠です。 Neptune ML は、ここで説明されているように、データのエクスポートおよびデータ処理手順の一部として、特徴抽出とエンコーディングを実行します。 **注記** カスタムモデルの実装で独自の特徴エンコーディングを実装する場合は、データの前処理段階で `none` を特徴エンコーディングタイプとして選択することで自動特徴エンコーディングを無効にすることができます。その後、そのノードまたはエッジプロパティで特徴エンコーディングは発生せず、代わりに生プロパティ値が解析され、ディクショナリに保存されます。データの前処理では、エクスポートされたデータセットから DGL グラフが作成されますが、構築された DGL グラフにはトレーニング用の前処理特徴がありません。 カスタムモデルトレーニングの一部として独自のカスタム特徴エンコーディングを実行する予定の場合のみこの選択肢を使用します。詳細については、「[Neptune ML のカスタムモデル](machine-learning-custom-models.md)」を参照してください。 ## Neptune MLのカテゴリ別特徴 可能な値の固定リストから 1 つ以上の異なる値を取得できるプロパティは、カテゴリ別特徴です。Neptune ML では、カテゴリ別特徴は [one-hot エンコーディング](https://en.wikipedia.org/wiki/One-hot)を使用して符号化されます。次の例は、さまざまな食品のプロパティ名がそのカテゴリに従って one-hot 符号化される方法を示しています。 ``` Food Veg. Meat Fruit Encoding --------- ---- ---- ----- -------- Apple 0 0 1 001 Chicken 0 1 0 010 Broccoli 1 0 0 100 ``` **注記** カテゴリ別特徴の最大数は 100 です。プロパティの値のカテゴリが 100 を超える場合、最も一般的なカテゴリの 99 のみが個別のカテゴリに配置され、残りは `OTHER` という名前の特別なカテゴリに配置されます。 ## Neptune MLのカテゴリ別特徴 値が実数であるプロパティは、Neptune ML で数値特徴として符号化できます。数値特徴は、浮動小数点数を使用して符号化されます。 次のように、数値特徴を符号化するときに使用するデータ正規化方法を指定できます。`"norm": "normalization technique"`。次の正規化手法がサポートされています。 + **"none"** — エンコーディング中に数値を正規化しないでください。 + **"min-max"** — 最小値を減算し、最大値と最小値の差で除算して、各値を正規化します。 + **"standard"** — すべての値の合計で割って、各値を正規化します。 ## Neptune MLの Bucket-numerical 特徴 生の数値を使用して数値プロパティを表すのではなく、数値をカテゴリに集約できます。たとえば、人の年齢を、子供 (0 ～20 歳)、若年大人 (20 ～ 40 歳)、中年 (40 ～ 60 歳)、および高齢者 (60歳以上) などのカテゴリに分類できます。これらの数値バケットを使用すると、数値プロパティを一種のカテゴリ特徴に変換することになります。 Neptune ML では、数値プロパティをバケット数値特徴として符号化できます。次の 2 つを指定する必要があります。 + 数値範囲、` "range": [a, b] ` 形式では、`a` および `b` は整数です。 + バケットカウント、` "bucket_cnt": c ` 形式では、`c` はバケットの数であり、整数でもあります。 次に、Neptune ML は各バケットのサイズを ` ( b - a ) / c ` と計算し、各数値を格納するバケットの数として符号化します。`a` 未満の値は最初のバケットに属していると見なされ、`b` より大きい任意の値は最後のバケットに属していると見なされます。 オプションで、次のようにスライドウィンドウサイズを ` "slide_window_size": s ` のように (`s` は数字) 指定することで、数値を複数のバケットに分類することもできます。Neptune ML はプロパティの各数値 `v` を` v - s/2 ` から ` v + s/2 ` 範囲内へ変換し、範囲がカバーするすべてのバケットに値 `v` を代入します。 最後に、オプションで、数値特徴と bucket-numerical 特徴の欠損値を埋める方法を提供することもできます。これは、` "imputer": "imputation technique "` を使用して行います。ここで、帰属技法は`"mean"`、`"median"` または `"most-frequent"` のうちの 1 つです。中央値を指定しなかった場合、値が欠落していると、処理が停止する可能性があります。 ## Neptune ML でのテキストフィーチャエンコーディング 自由形式のテキストの場合、Neptune ML はいくつかの異なるモデルを使用して、プロパティ値文字列内のトークンのシーケンスを固定サイズの実数値ベクトルに変換できます。 + [`text_fasttext`](#machine-learning-fasttext-features) — [fastText](https://fasttext.cc/) エンコーディングを使用します。これは、fastText がサポートする 5 つの言語のうちの 1 つだけを使用するフィーチャに推奨されるエンコーディングです。 + [`text_sbert`](#machine-learning-sbert-features) — [Sentence BERT](https://www.sbert.net/docs/pretrained_models.html#sentence-embedding-models) (SBERT) エンコーディングモデルを使用します。これは、`text_fasttext` がサポートしていないテキストについて推奨されるエンコーディングです。 + [`text_word2vec`](#machine-learning-word2vec-features) — [Google](https://code.google.com/archive/p/word2vec/) が最初に公開した [Word2Vec](https://wikipedia.org/wiki/Word2vec) アルゴリズムを使用して、テキストをエンコードします。Word2Vec は英語のみをサポートしています。 + [`text_tfidf`](#machine-learning-tfidf-features) — [term frequency–inverse document frequency](https://wikipedia.org/wiki/Tf-idf) (TF-IDF) ベクタライザを使用して、テキストのエンコードを行います。TF-IDF エンコーディングは、他のエンコーディングにはない統計機能をサポートします。 ### Neptune ML でのテキストプロパティ値の *fastText* エンコーディング Neptune ML は [fastText](https://fasttext.cc/) モデルを使用して、テキストプロパティ値を固定サイズの実数値ベクトルに変換できます。これは、FastText がサポートする 5 つの言語のいずれかのテキストプロパティ値の推奨エンコーディング方法です。 + `en`   (英語) + `zh`   (中国語) + `hi`   (ヒンディー語) + `es`   (スペイン語) + `fr`   (フランス語) fastText は複数の言語の単語を含む文を処理できないことに注意してください。 `text_fasttext` メソッドは、エンコードされるテキストプロパティ値のトークンの最大数を指定する `max_length` フィールドをオプションで取得できます。この数を超えると、文字列は切り捨てられます。これによって、テキストプロパティ値に長い文字列が含まれる場合のパフォーマンスが向上します。`max_length` が指定されなかった場合、fastText は文字列の長さに関係なく、すべてのトークンをエンコードするためです。 次の例では、フランス語の映画タイトルが fastText を使用してエンコードされるように指定しています。 ``` { "file_name" : "nodes/movie.csv", "separator" : ",", "node" : ["~id", "movie"], "features" : [ { "feature": ["title", "title", "text_fasttext"], "language": "fr", "max_length": 1024 } ] } ``` ### Neptune MLにおけるテキストフィーチャの Sentence BERT (SBERT) エンコーディング Neptune ML は、[Sententh BERT](https://www.sbert.net/docs/pretrained_models.html#sentence-embedding-models) (SBERT) モデルを使用して、文字列プロパティ値内のトークンのシーケンスを固定サイズの実数値ベクトルに変換できます。Neptune は 2 つの SBERT メソッドをサポートしています。すなわち、`text_sbert128` (`text_sbert` を指定した場合のデフォルト) と `text_sbert512` です。この 2 つの違いは、エンコードされるテキストプロパティ値文字列の最大長です。`text_sbert128` エンコーディングでは、128 トークンをエンコードするとテキスト文字列が切り捨てられますが、`text_sbert512` では、512 トークンをエンコードした後にテキスト文字列が切り捨てられます。その結果、`text_sbert512` を使用する場合は、`text_sbert128` よりも処理時間が長くなる可能性があります。どちらの方法も、`text_fasttext` より遅くなります。 SBERT エンコーディングは多言語対応なので、エンコードするプロパティ値のテキストについて言語を指定する必要はありません。SBERT は多くの言語をサポートしており、複数の言語を含む文をエンコードできます。fastText がサポートしていない言語のテキストを含むプロパティ値をエンコードする場合は、SBERT が推奨されるエンコード方法です。 次の例では、映画のタイトルを最大 128 トークンまで SBERT としてエンコードするように指定しています。 ``` { "file_name" : "nodes/movie.csv", "separator" : ",", "node" : ["~id", "movie"], "features" : [ { "feature": ["title", "title", "text_sbert128"] } ] } ``` ### Neptune ML でのテキストフィーチャの Word2Vec エンコーディング Neptune ML は、文字列プロパティ値を Word2Vec 機能としてエンコードできます ([Word2Vec](https://wikipedia.org/wiki/Word2vec) アルゴリズムは元々 [Google](https://code.google.com/archive/p/word2vec/) によって公開されました)。`text_word2vec` メソッドは、[spaCy でトレーニング済みモデル](https://spacy.io/models)のいずれかを使用して、文字列内のトークンを密なベクトルとしてエンコードします。これは [en\$1core\$1web\$1lg](https://spacy.io/models/en#en_core_web_lg) モデルを使用する英語のみをサポートしています。 次の例では、映画のタイトルを Word2Vec を使用してエンコードするように指定しています。 ``` { "file_name" : "nodes/movie.csv", "separator" : ",", "node" : ["~id", "movie"], "features" : [ { "feature": ["title", "title", "text_word2vec"], "language": "en_core_web_lg" } ] } ``` Neptune がサポートしているのは英語 `en_core_web_lg` モデルだけなので、言語フィールドはオプションであることに注意してください。 ### Neptune ML でのテキストフィーチャの TF-IDF エンコーディング Neptune ML は、テキストプロパティ値を `text_tfidf` フィーチャとしてエンコードできます。このエンコーディングは、[term frequency–inverse document frequency](https://wikipedia.org/wiki/Tf-idf) (TF-IDF) ベクタライザを使用して、テキスト内の単語のシーケンスを数値ベクトルに変換し、その後に次元削減操作を実行します。 [TF-IDF](https://en.wikipedia.org/wiki/Tf%E2%80%93idf) (項の頻度 — 逆ドキュメントの頻度) は、文書セット内の単語の重要性を測定するための数値です。これは、特定のプロパティ値に単語が表示される回数をそのプロパティ値の合計数で割って計算されます。 例えば、ある映画のタイトルに「キス」という単語が2回登場し (例えば「キス・キス・バン・バン」)、4本の映画のタイトルすべてに「キス」が登場する場合、「キス・バンバン」タイトルの「キス」の TF-IDF 値は、` 2 / 4 ` となります。 最初に作成されるベクトルは ***d*** ディメンションで、ここで ***d*** は、そのタイプのすべてのプロパティ値の一意の項の数です。次元削減オペレーションでは、ランダムなスパース投影を使用して、その数値を最大 100 に減らします。グラフのボキャブラリーは、その中の `text_tfidf` 特徴をすべて合わせて生成されます。 TF-IDF ベクタライザーは、いくつかの方法で制御できます。 + **`max_features`** — `max_features` パラメータを使用して、最も一般的な特徴に `text_tfidf` 特徴の項数を制限できます。たとえば、`max_features` を 100 に設定した場合、最も一般的に使用される項の上位 100 のみが含まれます。`max_features` のデフォルト値を明示的に設定しなかった場合、5,000 となります。 + **`min_df`** — `min_df` パラメータを使用して、少なくとも指定されたドキュメント頻度を持つ特徴へ `text_tfidf` 特徴の項数を制限できます。たとえば、`min_df` を 5 に設定した場合、少なくとも 5 つの異なるプロパティ値に含まれる項のみが使用されます。`min_df` のデフォルト値を明示的に設定しなかった場合、2 となります。 + **`ngram_range`** — `ngram_range` パラメータは、項として扱われる単語の組み合わせを決定します。たとえば、`ngram_range` を `[2, 4]` に設定した場合、「キス・キス・バン・バン」のタイトルで以下の 6 項が見つかることになります。 + *2 単語項*：「キス・キス」、「キス・バン」、「バン・バン」。 + *3 単語項*：「キス・キス・バン」と「キス・バン・バン」。 + *4 単語項*：「キス・キス・バン・バン」。 `ngram_range` のデフォルトの設定は `[1, 1]` です。 ## Neptune ML のDatetime 特徴 Neptune ML は `datetime` プロパティ値の一部を、[one-hot 配列](https://en.wikipedia.org/wiki/One-hot)として符号化してカテゴリ別特徴に変換できます `datetime_parts` パラメータを使用して、符号化する次のパートの `["year", "month", "weekday", "hour"]` のうち 1 つまたは複数を指定します。`datetime_parts` を設定しなければで、デフォルトで 4 つの部分すべてが符号化されます。 たとえば、datetime 値の範囲が 2010 年から 2012 年にわたる場合、datetime 入力 `2011-04-22 01:16:34` の 4 つの部分は次のとおりです。 + **year**   –   `[0, 1, 0]`。 スパンには 3 年 (2010、2011、2012) しかないため、one-hot 配列には各年に 1 つずつ、3 つの入力値があります。 + **month**   –   `[0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0]`。 ここでは、one-hot 配列には、その年の各月の入力値があります。 + **weekday**   –   `[0, 0, 0, 0, 1, 0, 0]`。 ISO 8601 規格では、月曜日が週の最初の曜日であると定められており、2011 年 4 月 22 日は金曜日であったため、対応するone-hot weekday 配列は 5 番目の位置で hot です。 + **hour**   –   `[0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]`。 午前 1 時の時間は 24-member one-hot 配列で設定されます。 月、分、秒の曜日はカテゴリ的に符号化されません。 総 `datetime` 対象範囲に 1 年以内の日付のみが含まれている場合、`year` 配列はどれも符号化されません。 `imputer` パラメータと、数値特徴に使用できる戦略の 1 つを使用して、欠落した`datetime`値を保管するためのインピュテーション戦略を指定できます。 ## Neptune ML での自動特徴エンコーディング グラフのプロパティに使用する特徴エンコーディングメソッドを手動で指定する代わりに、特徴エンコーディングメソッドとして `auto` を設定できます。次に、Neptune ML は、基礎となるデータ型に基づいて、各プロパティの最適な特徴エンコーディングを推論しようとします。 Neptune ML が適切な特徴エンコーディングを選択する際に使用する発見的手法をいくつか紹介します。 + プロパティが数値のみを持ち、数値データ型にキャストできる場合、Neptune ML は通常、それを数値として符号化します。ただし、プロパティの一意の値の数が値の合計数の 10% 未満で、それらの一意の値のカーディナリティが 100 未満の場合、Neptune ML はカテゴリ別エンコーディングを使用します。 + プロパティ値を `datetime` 型にキャストできる場合、Neptune ML はそれらを `datetime` 特徴に符号化します。 + プロパティ値をブール値 (1/0 または True/False) に強制できる場合、Neptune ML はカテゴリエンコーディングを使用します。 + プロパティがその値の 10% を超える一意の文字列であり、値あたりの平均トークン数が 3 以上の場合、Neptune ML はプロパティタイプをテキストとして推論し、使用されている言語を自動的に検出します。検出された言語が [fastText](#machine-learning-fasttext-features) によってサポートされている言語、つまり、英語、中国語、ヒンディー語、スペイン語、フランス語のいずれかである場合、Neptune ML は `text_fasttext` を使用してテキストをエンコードします。それ以外の場合、Neptune ML は [`text_sbert`](#machine-learning-sbert-features) を使用します。 + プロパティがテキスト特徴として分類されない文字列の場合、Neptune ML はカテゴリ別特徴であると仮定し、カテゴリエンコーディングを使用します。 + 各ノードがカテゴリ特徴であると推論されるプロパティに固有の値がある場合、Neptune ML は学習に有益ではない ID であるため、トレーニンググラフからプロパティを削除します。 + プロパティにセミコロン (「;」) などの有効な Neptune 区切り文字が含まれていることがわかっている場合、Neptune ML はプロパティを `MultiNumerical` または `MultiCategorical` とのみ扱えます。 + Neptune ML は、まず値を数値特徴として符号化しようとします。これが成功すると、Neptune ML は数値エンコーディングを使用して数値ベクトル特徴を作成します。 + それ以外の場合、Neptune ML は値をマルチカテゴリとして符号化します。 + Neptune ML がプロパティの値のデータ型を推論できない場合、Neptune MLはトレーニンググラフからプロパティを削除します。 # トレーニングデータ設定ファイルの編集 Neptune エクスポートプロセスは、Neptune DB クラスターから S3 バケットに Neptune ML データをエクスポートします。ノードとエッジを `nodes/` と `edges/` の別々のフォルダにエクスポーします。また、デフォルトでは `training-data-configuration.json` という名前の JSON トレーニングデータ設定ファイルも作成します。このファイルには、グラフのスキーマ、特徴の型、特徴変換と正規化操作、分類または回帰タスクのターゲット特徴に関する情報が含まれています。 設定ファイルを直接変更したい場合があります。このようなケースの 1 つは、解析する機械学習タスクの仕様を変更するたびにエクスポートを再実行しなくても、特徴の処理方法やグラフの作成方法を変更する場合です。 **トレーニングデータ設定ファイルを編集するには** 1. **ファイルをローカルマシンにダウンロードします。** エクスポートプロセスで渡された `additionalParams/neptune_ml` パラメータで 1 つ以上の名前付きジョブを指定していない限り、ファイルはデフォルトの名前 `training-data-configuration.json` になります。次のような AWS CLI コマンドを使用して、 ファイルをダウンロードすることができます。 ``` aws s3 cp \ s3://(your Amazon S3 bucket)/(path to your export folder)/training-data-configuration.json \ ./ ``` 1. **テキストエディタを使用してファイルを編集します。** 1. **変更したファイルをアップロードします。**次のように AWS CLI コマンドを使用して、変更したファイルを、ダウンロード元の Amazon S3 の同じ場所にアップロードします。 ``` aws s3 cp \ training-data-configuration.json \ s3://(your Amazon S3 bucket)/(path to your export folder)/training-data-configuration.json ``` # JSON トレーニングデータ設定ファイルの例 ノード分類タスクのグラフを説明するトレーニングデータ設定ファイルの例を次に示します。 ``` { "version" : "v2.0", "query_engine" : "gremlin", "graph" : [ { "edges" : [ { "file_name" : "edges/(movie)-included_in-(genre).csv", "separator" : ",", "source" : ["~from", "movie"], "relation" : ["", "included_in"], "dest" : [ "~to", "genre" ] }, { "file_name" : "edges/(user)-rated-(movie).csv", "separator" : ",", "source" : ["~from", "movie"], "relation" : ["rating", "prefixname"], # [prefixname#value] "dest" : ["~to", "genre"], "features" : [ { "feature" : ["rating", "rating", "numerical"], "norm" : "min-max" } ] } ], "nodes" : [ { "file_name" : "nodes/genre.csv", "separator" : ",", "node" : ["~id", "genre"], "features" : [ { "feature": ["name", "genre", "category"], "separator": ";" } ] }, { "file_name" : "nodes/movie.csv", "separator" : ",", "node" : ["~id", "movie"], "features" : [ { "feature": ["title", "title", "word2vec"], "language": ["en_core_web_lg"] } ] }, { "file_name" : "nodes/user.csv", "separator" : ",", "node" : ["~id", "user"], "features" : [ { "feature": ["age", "age", "numerical"], "norm" : "min-max", "imputation": "median", }, { "feature": ["occupation", "occupation", "category"], } ], "labels" : [ { "label": ["gender", "classification"], "split_rate" : [0.8, 0.2, 0.0] } ] } ] }, "warnings" : [ ] ] } ``` # JSON トレーニングデータ設定ファイルの構造 トレーニング設定ファイルは、エクスポートプロセスによって `nodes/` および `edges/` フォルダに保存された CSV ファイルを参照します。 `nodes/` の下にある各ファイルは、同じプロパティグラフノードラベルを持つノードに関する情報を格納します。ノードファイルの各列には、ノード ID またはノードプロパティが格納されます。ファイルの最初の行には、`~id` または、各列のプロパティ名を指定するヘッダーが含まれます。 `edges/` の下にある各ファイルは、同じプロパティグラフエッジラベルを持つノードに関する情報を格納します。ノードファイルの各列には、始点ノード ID、終点ノード ID、またはエッジプロパティが格納されます。ファイルの最初の行には、`~from`、`~to` または各列のプロパティ名を指定するヘッダーが含まれます。 トレーニングデータ設定ファイルには、次の 3 つの最上位要素があります。 ``` { "version" : "v2.0", "query_engine" : "gremlin", "graph" : [ ... ] } ``` + `version` — (文字列) 使用されているコンフィギュレーションファイルのバージョン。 + `query_engine` — (文字列) グラフデータのエクスポートに使用するクエリ言語。現在、有効なのは「gremlin」のみです。 + `graph` — (JSON 配列) 使用される各ノードとエッジのモデルパラメーターを含む 1 つ以上の設定オブジェクトを一覧表示します。 グラフ配列の構成オブジェクトは、次のセクションで説明する構造です。 ## `graph` 配列に一覧表示されている構成オブジェクトの内容 `graph` 配列内の構成オブジェクトには 3 つの最上位ノードを含めることができます。 ``` { "edges" : [ ... ], "nodes" : [ ... ], "warnings" : [ ... ], } ``` + `edges` — (JSON オブジェクトの配列) 各 JSON オブジェクトは、モデルの処理およびトレーニング中にグラフ内のエッジがどのように処理されるかを定義するパラメータのセットを指定します。これは Gremlin エンジンでのみ使用されます。 + `nodes` — (JSON オブジェクトの配列) 各 JSON オブジェクトは、モデルの処理およびトレーニング中にグラフ内のノードがどのように処理されるかを定義するパラメータのセットを指定します。これは Gremlin エンジンでのみ使用されます。 + `warnings` — (JSON オブジェクトの配列) 各オブジェクトには、データのエクスポートプロセス中に生成された警告が含まれています。 ## `edges` 配列に一覧表示されているエッジ構成オブジェクトの内容 `edges` 配列に一覧表示されているエッジ構成オブジェクトは、次の最上位のフィールドを含めることができます。 ``` { "file_name" : "(path to a CSV file)", "separator" : "(separator character)", "source" : ["(column label for starting node ID)", "(starting node type)"], "relation" : ["(column label for the relationship name)", "(the prefix name for the relationship name)"], "dest" : ["(column label for ending node ID)", "(ending node type)"], "features" : [(array of feature objects)], "labels" : [(array of label objects)] } ``` + **`file_name`** — 同じプロパティグラフラベルを持つエッジに関する情報を格納する CSV ファイルへのパスを指定する文字列。 そのファイルの最初の行には、列ラベルのヘッダー行が含まれています。 最初の 2 つの列ラベルは `~from` および `~to` です。最初の列 (`~from` 列) は、エッジの開始ノードの ID を格納し、2 番目 (`~to`列) は、エッジの終了ノードの ID を格納します。 ヘッダー行の残りの列ラベルは、残りの列ごとに、その列に値がエクスポートされたエッジプロパティの名前を指定します。 + **`separator`** — その CSV ファイル内の列を区切る区切り文字を含む文字列。 + **`source`** — エッジの開始ノードを指定する 2 つの文字列を含む JSON 配列。最初の文字列には、開始ノード ID が格納されているカラムのヘッダー名が含まれます。2 番目の文字列は、ノードタイプを指定します。 + **`relation`** — エッジのリレーションタイプを指定する 2 つの文字列を含む JSON 配列。最初の文字列には、リレーション名 (`relname`) が格納されているカラムのヘッダー名が含まれます。2 番目の文字列には、リレーション名 (`prefixname`) のプレフィックスが含まれています。 完全なリレーションタイプは、`prefixname-relname` のように 2 つの文字列を結合し、それらの間にハイフン文字を組み合わせて構成します。 最初の文字列が空の場合、すべてのエッジが同じリレーションタイプになります。つまり、`prefixname` 文字列です。 + **`dest`** — エッジの終了ノードを指定する 2 つの文字列を含む JSON 配列。最初の文字列には、ノード ID が格納されているカラムのヘッダー名が含まれます。2 番目の文字列は、ノードタイプを指定します。 + **`features`** — プロパティ値特徴オブジェクトの JSON 配列。各プロパティ値特徴オブジェクトには、次のフィールドが含まれています。 + **feature** — 3 つの文字列の JSON 配列。最初の文字列には、プロパティ値を含むカラムのヘッダー名が含まれます。2 番目の文字列には、特徴名が含まれます。3 番目の文字列には、特徴型が含まれます。 + **norm** — (*オプション*) プロパティ値に適用する正規化方法を指定します。 + **`labels`** — オブジェクトの JSON 配列。各オブジェクトは、エッジのターゲット特徴を定義し、トレーニングおよび検証段階で取るエッジの比率を指定します。各オブジェクトには、以下のフィールドが含まれています。 + **label** — 2 つの文字列の JSON 配列。最初の文字列には、ターゲット特徴のプロパティ値を格納する列のヘッダー名が含まれます。2 番目の文字列は、以下のいずれかのターゲットタスク型を指定します。 + `"classification"` — エッジ分類タスク。列に表示されるプロパティ値は、`label` 配列の最初の文字列で識別され、カテゴリ別値として扱われます。エッジ分類タスクの場合、`label` 配列の最初の文字列を空にすることはできません。 + `"regression"` — エッジ回帰タスク。列に表示されるプロパティ値は、`label` 配列の最初の文字列で識別され、数値として扱われます。エッジ回帰タスクの場合、`label` 配列の最初の文字列を空にすることはできません。 + `"link_prediction"` — リンク予測タスク。プロパティ値は必要ありません。リンク予測タスクの場合、`label` 配列の最初の文字列は無視されます。 + **`split_rate`** — ゼロから 1 までの、足して 1 になる 3 つの数値を含む JSON 配列。トレーニング、検証、およびテストの各ステージで使用されるノードの比率の推定値を表します。このフィールドまたは `custom_split_filenames` のいずれかを定義できますが、両方は定義できません。[split\$1rate](machine-learning-neptune_ml-targets.md#machine-learning-property-graph-neptune_ml-targets-split_rate) を参照してください。 + **`custom_split_filenames`** — トレーニング、検証、およびテストの母集団を定義するファイルのファイル名を指定する JSON オブジェクト。このフィールドまたは `split_rate` のいずれかを定義できますが、両方は定義できません。詳細については「[カスタムのトレイン、検証、テストの比率](#machine-learning-custom-stages-splits)」を参照してください。 ## `nodes` 配列に一覧表示されているノード構成オブジェクトの内容 `nodes` 配列に一覧表示されているノード設定オブジェクトには、次のフィールドを含めることができます。 ``` { "file_name" : "(path to a CSV file)", "separator" : "(separator character)", "node" : ["(column label for the node ID)", "(node type)"], "features" : [(feature array)], "labels" : [(label array)], } ``` + **`file_name`** — 同じプロパティグラフラベルを持つノードに関する情報を格納する CSV ファイルへのパスを指定する文字列。 そのファイルの最初の行には、列ラベルのヘッダー行が含まれています。 最初の列ラベルは `~id` であり、最初の列 (`~id` 列) には、ノード ID が保存されます。 ヘッダー行の残りの列ラベルは、残りの列ごとに、その列に値がエクスポートされたノードプロパティの名前を指定します。 + **`separator`** — その CSV ファイル内の列を区切る区切り文字を含む文字列。 + **`node`** — 2 つの文字列を含む JSON 配列。最初の文字列には、ノード ID が格納されているカラムのヘッダー名が含まれます。2 番目の文字列は、グラフ内のノード型を指定します。これは、ノードのプロパティグラフラベルに対応します。 + **`features`** — ノード特徴オブジェクトの JSON 配列。「[ノードまたはエッジの `features` 配列に一覧表示されている特徴オブジェクトの内容](#machine-learning-graph-node-features-config)」を参照してください。 + **`labels`** — ノードラベルオブジェクトの JSON 配列。「[ノード `labels` 配列に一覧表示されたノードラベルオブジェクトの内容](#machine-learning-graph-node-labels-config)」を参照してください。 ## ノードまたはエッジの `features` 配列に一覧表示されている特徴オブジェクトの内容 ノード `features` 配列に一覧表示されているノード特徴オブジェクトには、次の最上位フィールドを含めることができます。 + **`feature`** — 3 つの文字列の JSON 配列。最初の文字列には、特徴のプロパティ値を格納する列のヘッダー名が含まれます。2 番目の文字列には、特徴名が含まれます。 3 番目の文字列には、特徴型が含まれます。有効な特徴型の一覧を [特徴のタイプフィールドで使用できる値](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-feature-types) に示します。 + **`norm`** - このフィールドは数値特徴に必須です。数値に使用する正規化方法を指定します。有効な値は、`"none"`、`"min-max"`、「標準」です。詳細については、「[norm フィールド](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-norm)」を参照してください。 + **`language`** - 言語フィールドは、テキストプロパティ値に使用されている言語を指定します。その使用法は、テキストのエンコード方法によって異なります。 + [`text_fasttext`](machine-learning-feature-encoding.md#machine-learning-fasttext-features) エンコーディングの場合、このフィールドは必須であり、以下の言語のいずれかを指定する必要があります。 + `en`   (英語) + `zh`   (中国語) + `hi`   (ヒンディー語) + `es`   (スペイン語) + `fr`   (フランス語) ただし、`text_fasttext` は、一度に複数の言語を処理することはできません。 + [`text_sbert`](machine-learning-feature-encoding.md#machine-learning-fasttext-features) エンコーディングの場合、SBERT エンコーディングは多言語対応であるため、このフィールドは使用されません。 + [`text_word2vec`](machine-learning-feature-encoding.md#machine-learning-word2vec-features) エンコーディングの場合、`text_word2vec` は英語のみをサポートするため、このフィールドはオプションです。存在する場合は、英語言語モデルの名前を指定する必要があります。 ``` "language" : "en_core_web_lg" ``` + [`tfidf`](machine-learning-feature-encoding.md#machine-learning-tfidf-features) エンコーディングの場合、このフィールドは使用されません。 + **`max_length`** - このフィールドは、[`text_fasttext`](machine-learning-feature-encoding.md#machine-learning-fasttext-features) 機能についてはオプションであり、エンコードされる入力テキストフィーチャ内のトークンの最大数を指定します。`max_length` に達した後の入力テキストは無視されます。例えば、max\$1length を 128 に設定すると、テキストシーケンス内の 128 番目より後のトークンは無視されます。 + **`separator`** - このフィールドはオプションで 、`category`、`numerical` および `auto` と使用されます。プロパティ値を複数のカテゴリ値または数値に分割するために使用できる文字を指定します。 「[separator フィールド](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-separator)」を参照してください。 + **`range`** - このフィールドは `bucket_numerical` 特徴に必須です。バケットに分割する数値の範囲を指定します。 「[range フィールド](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-range)」を参照してください。 + **`bucket_cnt`** - このフィールドは `bucket_numerical` 特徴に必須です。これは、`range` パラメータにより定義される数値範囲が分割されるバケットの数を指定します。 「[Neptune MLの Bucket-numerical 特徴](machine-learning-feature-encoding.md#machine-learning-bucket_numerical-features)」を参照してください。 + **`slide_window_size`** - このフィールドはオプションで `bucket_numerical` 特徴と使用して複数のバケットに値を割り当てます。 「[slide\$1window\$1size フィールド](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-slide_window_size)」を参照してください。 + **`imputer`** - このフィールドはオプションで `numerical`、`bucket_numerical` および `datetime` 特徴と使用して欠損値を埋めるためのインプテーション手法を提供します。サポートされているインプテーションテクニックは、`"mean"`、`"median"` および `"most_frequent"` です。 「[imputer フィールド](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-imputer)」を参照してください。 + **`max_features`** - このフィールドはオプションで `text_tfidf` 特徴と使用して符号化する項の最大数を指定します。 「[max\$1features フィールド](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-max_features)」を参照してください。 + **`min_df`** - このフィールドはオプションで `text_tfidf` 特徴と使用して符号化する項の最低ドキュメント頻度を指定します。 「[min\$1df フィールド](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-min_df)」を参照してください。 + **`ngram_range`** — このフィールドは、`text_tfidf` 特徴にオプションで使用され、符号化する可能性のある個々の項と見なされる単語またはトークンの数の範囲を指定します。 「[ngram\$1range フィールド](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-ngram_range)」を参照してください。 + **`datetime_parts`** - このフィールドはオプションで `datetime` 特徴と使用して datetime 値のどの部分をカテゴリ別に符号化するかを指定します。 「[datetime\$1parts フィールド](machine-learning-neptune_ml-features.md#machine-learning-neptune_ml-features-datetime_parts)」を参照してください。 ## ノード `labels` 配列に一覧表示されたノードラベルオブジェクトの内容 ノード `labels` 配列に一覧表示されたラベルオブジェクトは、ノードターゲット特徴を定義し、トレーニング、検証、およびテストの各段階で使用するノードの比率を指定します。各オブジェクトには次のフィールドの要素を含めることができます。 ``` { "label" : ["(column label for the target feature property value)", "(task type)"], "split_rate" : [(training proportion), (validation proportion), (test proportion)], "custom_split_filenames" : {"train": "(training file name)", "valid": "(validation file name)", "test": "(test file name)"}, "separator" : "(separator character for node-classification category values)", } ``` + **`label`** — 2 つの文字列を含む JSON 配列。最初の文字列には、特徴のプロパティ値を格納する列のヘッダー名が含まれます。2 番目の文字列は、ターゲットタスクの種類を指定します。次のようになります。 + `"classification"` — ノード分類タスク。指定した列のプロパティ値は、カテゴリ特徴の作成に使用されます。 + `"regression"` — ノード回帰タスク。指定した列のプロパティ値は、数値特徴の作成に使用されます。 + **`split_rate`** — ゼロから 1 の間の 3 つの数値を含む JSON 配列。最大 1 を足し、トレーニング、検証、およびテストの各ステージで使用されるノードの比率の推定値を表します。「[split\$1rate](machine-learning-neptune_ml-targets.md#machine-learning-property-graph-neptune_ml-targets-split_rate)」を参照してください。 + **`custom_split_filenames`** — トレーニング、検証、およびテストの母集団を定義するファイルのファイル名を指定する JSON オブジェクト。このフィールドまたは `split_rate` のいずれかを定義できますが、両方は定義できません。詳細については「[カスタムのトレイン、検証、テストの比率](#machine-learning-custom-stages-splits)」を参照してください。 + **`separator`** — 分類タスクのカテゴリ別特徴値を区切る区切り文字を含む文字列。 **注記** エッジとノードの両方にラベルオブジェクトを指定しない場合、タスクは自動的にリンク予測と見なされ、エッジはトレーニングのために 90%、検証のために 10% にランダムに分割されます。 ## カスタムのトレイン、検証、テストの比率 デフォルトでは、`split_rate` パラメータは Neptune ML によって、このパラメータで定義された比率を使用してグラフをトレーニング、検証、およびテストの母集団にランダムに分割するために使用されます。これらの異なる母集団でどのエンティティを使用するかをより正確に制御するには、それらを明示的に定義するファイルを作成し、[トレーニングデータ設定ファイルを編集して](machine-learning-processing-training-config-file.md)、これらのインデックスファイルを母集団にマッピングすることができます。このマッピングは、トレーニング設定ファイルの [`custom_split_filesnames`](#custom_split_filenames) キーの JSON オブジェクトによって指定されます。このオプションを使用する場合、`train` および `validation` キーにはファイル名を指定する必要がありますが、`test` キーでは省略可能です。 これらのファイルの形式は [Gremlin データ形式](bulk-load-tutorial-format-gremlin.md#bulk-load-tutorial-format-gremlin-systemheaders)に一致する必要があります。具体的には、ノードレベルのタスクでは、各ファイルにノード ID を一覧表示する `~id` ヘッダー付きの列が含まれている必要があります。エッジレベルのタスクでは、ファイルは `~from` および `~to` を指定して、エッジのソースノードとデスティネーションノードをそれぞれ示す必要があります。これらのファイルは、データ処理に使用されるエクスポートデータと同じ Amazon S3 の場所に配置する必要があります (「[`outputS3Path`](export-parameters.md#export-parameters-outputS3Path)」を参照)。 プロパティの分類や回帰タスクでは、これらのファイルで機械学習タスクのラベルをオプションで定義できます。その場合、ファイルには、[トレーニングデータ設定ファイルで定義](#machine-learning-graph-node-labels-config)されているのと同じヘッダー名のプロパティ列が必要です。エクスポートされたノードおよびエッジファイルとカスタム分割ファイルの両方でプロパティラベルが定義されている場合、カスタム分割ファイルが優先されます。 # Neptune ML を使用したモデルのトレーニング モデルトレーニングのために Neptune からエクスポートするデータを処理した後、次のように `curl` (または `awscurl`) コマンドを使用してモデルトレーニングジョブを開始できます。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/modeltraining -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique model-training job ID)", "dataProcessingJobId" : "(the data-processing job-id of a completed job)", "trainModelS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-graph-autotrainer" }' ``` このコマンドの使用方法の詳細については、[モデルトレーニングコマンド](machine-learning-api-modeltraining.md) を参照してください。また、実行中のジョブのステータスの取得方法、実行中のジョブの停止方法、実行中のすべてのジョブの一覧表示方法について説明する情報も併せてご確認ください。 完了した Neptune ML モデルトレーニングジョブの情報を使用して、新しいトレーニングジョブでハイパーパラメータ検索を高速化するために `previousModelTrainingJobId` を指定することもできます。これは、[新しいグラフデータのモデルの再トレーニング](machine-learning-overview-evolving-data-incremental.md#machine-learning-overview-model-retraining)であり、[同じグラフデータに対するインクリメンタルトレーニング](machine-learning-overview-evolving-data-incremental.md#machine-learning-overview-incremental)でもあります。次のようなコマンドを使用します。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/modeltraining -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique model-training job ID)", "dataProcessingJobId" : "(the data-processing job-id of a completed job)", "trainModelS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-graph-autotrainer" "previousModelTrainingJobId" : "(the model-training job-id of a completed job)" }' ``` Neptune ML トレーニングインフラストラクチャで、次のように `customModelTrainingParameters` オブジェクトを指定して独自のモデル実装をトレーニングできます。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/modeltraining -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique model-training job ID)", "dataProcessingJobId" : "(the data-processing job-id of a completed job)", "trainModelS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-graph-autotrainer" "modelName": "custom", "customModelTrainingParameters" : { "sourceS3DirectoryPath": "s3://(your Amazon S3 bucket)/(path to your Python module)", "trainingEntryPointScript": "(your training script entry-point name in the Python module)", "transformEntryPointScript": "(your transform script entry-point name in the Python module)" } }' ``` 実行中のジョブのステータスの取得方法、実行中のジョブの停止方法、実行中のすべてのジョブの一覧表示方法などの詳細については、[モデルトレーニングコマンド](machine-learning-api-modeltraining.md) を参照してください。カスタムモデルの実装と使用方法の詳細については、[Neptune ML のカスタムモデル](machine-learning-custom-models.md) を参照してください。 **Topics** + [Amazon Neptune ML でのモデルとモデルトレーニング](machine-learning-models-and-training.md) + [Neptune ML でのモデルのハイパーパラメータ設定のカスタマイズ](machine-learning-customizing-hyperparams.md) + [モデルトレーニングのベストプラクティス](machine-learning-improve-model-performance.md) # Amazon Neptune ML でのモデルとモデルトレーニング Neptune ML は、グラフニューラルネットワーク (GNN) を使用して、さまざまな機械学習タスクのモデルを作成します。グラフニューラルネットワークは、グラフ機械学習タスクに関する最先端の結果を得るため、グラフ構造化データから情報パターンを抽出するのに優れています。 ## Neptune ML のグラフニューラルネットワーク (GNN) グラフニューラルネットワーク (GNN) は、近傍のノードの構造と特徴を考慮してノード表現を計算するニューラルネットワークのファミリーに属します。GNN は、グラフデータには適していない他の従来の機械学習とニューラルネットワーク手法を補完します。 GNN は、ノード分類とリグレッション (ノードの特性の予測)、エッジ分類とリグレッション (エッジの特性の予測) やリンク予測 (グラフ内の 2 つのノードを接続すべきかどうかを予測) などの機械学習タスクを実行するために使用されます。 一般に、GNN を機械学習タスクに使用するには、次の 2 つの段階があります。 + 符号化段階。GNN がグラフ内の各ノードの d 次元ベクトルを計算します。これらのベクトルは、*表現*または*埋め込み*です。 + 符号化された表現に基づいて予測を行う復号化ステージ。 ノードの分類とリグレッションでは、ノード表現が分類およびリグレッションタスクに直接使用されます。エッジ分類とリグレッションでは、エッジ上のインシデントノードのノード表現が分類またはリグレッションの入力として使用されます。リンク予測の場合、エッジ尤度スコアは、ノード表現とエッジタイプ表現のペアを使用して計算されます。 [ディープグラフライブラリ (DGL)](https://www.dgl.ai/) は、これらのタスクの GNN の効率的な定義とトレーニングを容易にします。 メッセージパッシングの定式化の下で異なる GNN モデルが統一されます。このビューでは、グラフ内のノードの表現は、ノードの近傍の表現 (メッセージ) とノードの初期表現を使用して計算されます。NeptuneML では、ノードの初期表現は、ノードのプロパティから抽出された特徴から導出されるか、または学習可能であり、ノードのアイデンティティに依存します。 Neptune ML には、ノード特徴と学習可能なノード表現を連結して、元のノード表現として機能するオプションも用意されています。 ノードプロパティを持つグラフを含む Neptune ML のさまざまなタスクについては、[リレーショナルグラフ畳み込みネットワーク](https://arxiv.org/abs/1703.06103) (R-GCN)) で符号化段階を行います。R-GCN は、複数のノードタイプとエッジタイプを持つグラフに適した GNN アーキテクチャです (これらは異種グラフと呼ばれます)。 R-GCN ネットワークは固定数のレイヤーで構成され、次々に積み重ねられます。R-GCN の各レイヤーは、学習可能なモデルパラメータを使用して、ノードの直近 1 ホップ近傍からの情報を集約します。後続のレイヤーは前のレイヤーの出力表現を入力として使用するため、ノードの最終的な埋め込みに影響するグラフ近傍の半径は、R-GCN ネットワークのレイヤーの数 (`num-layer`) によって異なります。 たとえば、これは、2 層ネットワークが 2 ホップ離れたノードからの情報を使用することを意味します。 GNN の詳細については、[グラフニューラルネットワークに関する包括的な調査](https://arxiv.org/abs/1901.00596)を参照してください。Deep Graph Library (DGL) の詳細については、DGL [ウェブページ](https://www.dgl.ai/)を参照してください。DGL での GNN の使用に関する実践的なチュートリアルについては、[ディープグラフライブラリを使用したグラフニューラルネットワークの学習](https://www.amazon.science/videos-webinars/learning-graph-neural-networks-with-deep-graph-library)を参照してください。 ## トレーニンググラフニューラルネットワーク 機械学習では、タスクに対して適切な予測を行う方法を学ぶためにモデルを取得するプロセスをモデルトレーニングと呼びます。これは、通常、最適化する具体的な目的と、この最適化を実行するために使用するアルゴリズムを指定することによって実行されます。 このプロセスは、下流のタスクに対する適切な表現を学ぶための GNN のトレーニングにも使用されます。モデルトレーニング中に最小化される、そのタスクの目的関数を作成します。たとえば、ノード分類の場合、[CrossentropyLoss](https://pytorch.org/docs/stable/generated/torch.nn.CrossEntropyLoss.html) を目標とし、誤分類にペナルティを科し、ノードリグレッションでは [SquareError](https://pytorch.org/docs/stable/generated/torch.nn.MSELoss.html) を最小限に抑えます。 目的は通常、特定のデータポイントのモデル予測を取得し、そのデータポイントのグラウンドトゥルース値と比較する損失関数です。これは、モデルの予測がどれくらい離れているかを示す損失値を返します。トレーニングプロセスの目標は、損失を最小限に抑え、モデルの予測がグラウンドトゥルースに近いことを確認することです。 トレーニングプロセスのディープラーニングで使用される最適化アルゴリズムは、通常、勾配降下の一種です。Neptune MLでは、[Adam](https://arxiv.org/pdf/1412.6980.pdf) を使用します。これは、低次モーメントの適応的推定に基づいて、確率的目的関数を一次勾配に基づいて最適化するアルゴリズムです。 モデルトレーニングプロセスでは、学習したモデルパラメータが目的関数の最小値に近いことを確認しようとしますが、モデルの全体的なパフォーマンスは、モデルの*ハイパーパラメータ*に依存し、これは、トレーニングアルゴリズムで学習されないモデル設定です。たとえば、学習したノード表現、`num-hidden`、の次元性は、モデルのパフォーマンスに影響するハイパーパラメータです。したがって、機械学習では、ハイパーパラメータ最適化 (HPO) を実行して適切なハイパーパラメータを選択することが一般的です。 Neptune ML は SageMaker AI ハイパーパラメータチューニングジョブを使用して、さまざまなハイパーパラメータ構成によりモデルトレーニングの複数のインスタンスを起動し、ハイパーパラメータ設定範囲に最適なモデルを見つけようとします。「[Neptune ML でのモデルのハイパーパラメータ設定のカスタマイズ](machine-learning-customizing-hyperparams.md)」を参照してください。 ## Neptune ML にモデルを埋め込むナレッジグラフ ナレッジグラフ (KG) は、異なるエンティティ (ノード) とその関係 (エッジ) に関する情報をエンコードするグラフです。Neptune ML では、グラフにノードプロパティが含まれず、他のノードとの関係のみが含まれている場合に、リンク予測を実行するためにデフォルトでナレッジグラフ埋め込みモデルが適用されます。ただし、学習可能な埋め込みを持つ R-GCN モデルは、モデル型を `"rgcn"` のように指定することで、これらのグラフにも使用できます。一方、知識グラフ埋め込みモデルはより単純であり、大規模な知識グラフの表現を学ぶのに有効になるように設計されています。 ナレッジグラフ埋め込みモデルは、リンク予測タスクで使用され、`h` が始点ノードであり、`r` がリレーションタイプ、`t` が終点ノードであるトリプル `(h, r, t)` を完了するノードまたはリレーションを予測します。 Neptune MLで実装されたナレッジグラフ埋め込みモデルは `distmult`、`transE` および `rotatE` です。ナレッジグラフの埋め込みモデルの詳細については、[「DGL-KE」](https://github.com/awslabs/dgl-ke)を参照してください。 ## Neptune ML のカスタムモデルのトレーニング Neptune ML では、特定のシナリオに対して、独自のカスタムモデルを定義して実装できます。カスタムモデルの実装方法と、Neptune ML インフラストラクチャを使用してトレーニングする方法については、[Neptune ML のカスタムモデル](machine-learning-custom-models.md) を参照してください。 # Neptune ML でのモデルのハイパーパラメータ設定のカスタマイズ Neptune ML モデルトレーニングジョブを開始すると、Neptune ML は先行する[データ処理](machine-learning-on-graphs-processing.md)ジョブから推測された情報を自動的に使用します。この情報を使用して、タスク用に複数のモデルをトレーニングするための [SageMaker AI ハイパーパラメータチューニングジョブ](https://docs.aws.amazon.com/sagemaker/latest/dg/automatic-model-tuning-how-it-works.html)の作成に使用されるハイパーパラメータ構成範囲を生成します。そうすれば、トレーニングの対象となるモデルのハイパーパラメータ値の長いリストを指定する必要はありません。代わりに、モデルのハイパーパラメータの範囲とデフォルトは、タスクタイプ、グラフタイプ、およびチューニングジョブ設定に基づいて選択されます。 ただし、データ処理ジョブが生成する JSON 設定ファイルを変更して、デフォルトのハイパーパラメータ設定を上書きし、カスタムハイパーパラメータを指定することもできます。 Neptune MLを使う [modelTraining API](machine-learning-api-modeltraining.md) では、`maxHPONumberOfTrainingJobs`、`maxHPOParallelTrainingJobs` および `trainingInstanceType` のようなハイレベルハイパーパラメータチューニングジョブ設定をいくつか制御できます。モデルのハイパーパラメータをよりきめ細かく制御するには、データ処理ジョブが生成する `model-HPO-configuration.json` ファイルをカスタマイズします。ファイルは、処理ジョブの出力用に指定した Amazon S3 の場所に保存されます。 ファイルをダウンロードし、デフォルトのハイパーパラメータ設定を上書きするように編集し、同じ Amazon S3 の場所にアップロードし直すことができます。ファイルの名前を変更しないでください。編集の際は、次の手順に従うよう注意してください。 Amazon S3 からファイルをダウンロードするには: ``` aws s3 cp \ s3://(bucket name)/(path to output folder)/model-HPO-configuration.json \ ./ ``` 編集が終わったら、ファイルを元の場所にアップロードし直します。 ``` aws s3 cp \ model-HPO-configuration.json \ s3://(bucket name)/(path to output folder)/model-HPO-configuration.json ``` ## `model-HPO-configuration.json` ファイルの構造 `model-HPO-configuration.json` ファイルは、学習するモデル、機械学習 `task_type` およびモデルトレーニングのさまざまな実行に対して変更または固定する必要のあるハイパーパラメータを指定します。 ハイパーパラメータは、ハイパーパラメータチューニングジョブが呼び出されたときにハイパーパラメータに与えられる優先順位を示すさまざまな階層に属するものとして分類されます。 + Tier-1 ハイパーパラメータの優先順位は最優先されます。`maxHPONumberOfTrainingJobs` を10 未満の値に設定すると、Tier-1 ハイパーパラメータのみが調整され、残りはデフォルト値になります。 + Tier-2 ハイパーパラメータの優先順位は低いため、チューニングジョブの合計トレーニングジョブが 10 以上あっても 50 未満の場合は、Tier-1 と Tier-2 の両方のハイパーパラメータが調整されます。 + Tier 3 のハイパーパラメータは、合計 50 を超えるトレーニングジョブがある場合にのみ、Tier-1 および Tier-2 とともに調整されます。 + ハイパーパラメータを特定の層に配置し、その範囲を編集し、そのデフォルト値が適切に設定されていることを確認して、ハイパーパラメータの優先順位を変更します。 ### `model-HPO-configuration.json` ファイルの例 次に、`model-HPO-configuration.json` ファイルの例を示します。 ``` { "models": [ { "model": "rgcn", "task_type": "node_class", "eval_metric": { "metric": "acc" }, "eval_frequency": { "type": "evaluate_every_epoch", "value": 1 }, "1-tier-param": [ { "param": "num-hidden", "range": [16, 128], "type": "int", "inc_strategy": "power2" }, { "param": "num-epochs", "range": [3,30], "inc_strategy": "linear", "inc_val": 1, "type": "int", "node_strategy": "perM" }, { "param": "lr", "range": [0.001,0.01], "type": "float", "inc_strategy": "log" } ], "2-tier-param": [ { "param": "dropout", "range": [0.0,0.5], "inc_strategy": "linear", "type": "float", "default": 0.3 }, { "param": "layer-norm", "type": "bool", "default": true } ], "3-tier-param": [ { "param": "batch-size", "range": [128, 4096], "inc_strategy": "power2", "type": "int", "default": 1024 }, { "param": "fanout", "type": "int", "options": [[10, 30],[15, 30], [15, 30]], "default": [10, 15, 15] }, { "param": "num-layer", "range": [1, 3], "inc_strategy": "linear", "inc_val": 1, "type": "int", "default": 2 }, { "param": "num-bases", "range": [0, 8], "inc_strategy": "linear", "inc_val": 2, "type": "int", "default": 0 } ], "fixed-param": [ { "param": "concat-node-embed", "type": "bool", "default": true }, { "param": "use-self-loop", "type": "bool", "default": true }, { "param": "low-mem", "type": "bool", "default": true }, { "param": "l2norm", "type": "float", "default": 0 } ] } ] } ``` ### `model-HPO-configuration.json` 要素のリスト。 このファイルには、モデル設定オブジェクトが 1 つ含まれる `models` という名前のトップレベル配列が 1 つある JSON オブジェクトが含まれています。ファイルをカスタマイズするときは、`models` 配列にはモデル設定オブジェクトが 1 つしかないことを確認してください。ファイルに複数のモデル設定オブジェクトが含まれている場合、チューニングジョブは警告とともに失敗します。 モデル設定オブジェクトには、次の最上位要素が含まれます。 + **`model`** — (*文字列*) トレーニングするモデルタイプ (**変更しない**)。次の値を指定できます。 + `"rgcn"` — これは、ノード分類およびリグレッションタスク、および異種リンク予測タスクのデフォルトです。 + `"transe"` — これは、KGE リンク予測タスクのデフォルトです。 + `"distmult"` — これは KGE リンク予測タスクの代替モデルタイプです。 + `"rotate"` — これは KGE リンク予測タスクの代替モデルタイプです。 原則として、`model` 値は直接変更しないでください。モデルタイプによって適用可能なハイパーパラメータが実質的に異なることが多く、トレーニングジョブの開始後に解析エラーが発生する可能性があるためです。 モデルタイプを変更するには、`model-HPO-configuration.json` ファイルで変えるのではなく、[モデルトレーニング API](machine-learning-api-modeltraining.md#machine-learning-api-modeltraining-create-job)で `modelName` パラメータを使用します。 モデルタイプを変更し、細粒度のハイパーパラメータを変更するには、使用するモデルのデフォルトのモデル設定テンプレートをコピーして、`model-HPO-configuration.json` ファイルにペーストします。推論タスクタイプが複数のモデルをサポートしている場合は、`model-HPO-configuration.json` ファイルと同じ Amazon S3 の場所に `hpo-configuration-templates` という名前のフォルダがあります。このフォルダには、タスクに適用可能な他のモデルのデフォルトのハイパーパラメータ設定がすべて含まれています。 たとえば、`KGE` リンク予測タスクのためにモデルとハイパーパラメータ設定をデフォルトの `transe` モデルから `distmult` モデルに変更する場合、`hpo-configuration-templates/distmult.json` ファイルの内容を `model-HPO-configuration.json` ファイルに貼り付けるだけで、それから必要に応じてハイパーパラメータを編集します。 **注記** `modelTraining` APIで `modelName` のパラメータを設定し、また `model` とハイパーパラメータの仕様を `model-HPO-configuration.json` ファイルで変更すると、これらは異なり、`model-HPO-configuration.json` ファイル内の `model` 値が優先され、`modelName` 値は無視されます。 + **`task_type`** — (*文字列*) データ処理ジョブによって推測される、またはデータ処理ジョブに直接渡される機械学習タスクタイプ (**変更しない**)。次の値を指定できます。 + `"node_class"` + `"node_regression"` + `"link_prediction"` データ処理ジョブは、エクスポートされたデータセットと生成されたトレーニングジョブ設定ファイルでデータセットのプロパティを調べて、タスクタイプを推論します。 この値は変更しないでください。別のタスクをトレーニングしたいなら、[新しいデータ処理ジョブを実行する](machine-learning-on-graphs-processing.md)必要があります。`task_type` 値が予測と異なる場合は、データ処理ジョブへの入力が正しいか確認する必要があります。これには、`modelTraining` API に対するパラメータ、およびデータエクスポートプロセスによって生成されたトレーニングジョブ設定ファイル内があります。 + **`eval_metric`** — (*文字列*) 評価指標は、モデルのパフォーマンスを評価し、HPO 実行全体で最もパフォーマンスの高いモデルを選択するために使用する必要があります。次の値を指定できます。 + `"acc"` — 標準の分類精度。これは、データ処理中に不均衡なラベルが検出されない限り、単一ラベル分類タスクのデフォルトです。この場合、デフォルトは `"F1"` です。 + `"acc_topk"` — **`k`** 予測の中で正しいラベルが一番上にある回数。追加のキーとして `topk` で受け渡すことで **`k`** 値も設定できます。 + `"F1"` — [F1 スコア](https://en.wikipedia.org/wiki/F-score)。 + `"mse"` – [平均二乗誤差メトリクス](https://en.wikipedia.org/wiki/Mean_squared_error)。リグレッションタスクの場合。 + `"mrr"` – [平均逆数ランクメトリクス](https://en.wikipedia.org/wiki/Mean_reciprocal_rank)。 + `"precision"` — 予測された陽性に対する真陽性の比率として計算されたモデルの精度。`= true-positives / (true-positives + false-positives)`。 + `"recall"` — 実際の陽性に対する真陽性の比率として計算されたモデルのリコール。`= true-positives / (true-positives + false-negatives)`。 + `"roc_auc"` — [ROC カーブ](https://en.wikipedia.org/wiki/Receiver_operating_characteristic)下のエリア。これは、マルチラベル分類のデフォルトです。 たとえば、メトリクスを `F1` に変更するには、`eval_metric` 値を次のように変更します。 ``` " eval_metric": { "metric": "F1", }, ``` または、メトリクスを `topk` 精度スコアに変更するには、`eval_metric` 値を次のように変更します。 ``` "eval_metric": { "metric": "acc_topk", "topk": 2 }, ``` + **`eval_frequency`** — (*オブジェクト*) トレーニング中に検証セット上のモデルのパフォーマンスをチェックする頻度を指定します。検証のパフォーマンスに基づいて、早期停止を開始し、最適なモデルを保存できます。 `eval_frequency` オブジェクトには いわゆる `"type"` および `"value"` の、2 つの要素が含まれています。例: ``` "eval_frequency": { "type": "evaluate_every_pct", "value": 0.1 }, ``` 有効な `type` 値は次のとおりです。 + **`evaluate_every_pct`** — 各評価で完了するトレーニングの割合を指定します。 `evaluate_every_pct` の場合、`"value"` フィールドには、そのパーセンテージを表すゼロから 1 までの浮動小数点数が含まれます。 + **`evaluate_every_batch`** — 各評価で完了するトレーニングバッチの数を指定します。 `evaluate_every_batch` の場合、`"value"` フィールドには、そのバッチ数を表す整数が含まれます。 + **`evaluate_every_epoch`** — 評価ごとのエポック数を指定します。新しいエポックは午前 0 時に開始されます。 `evaluate_every_epoch` の場合、`"value"` フィールドには、そのエポック数を表す整数が含まれます。 `eval_frequency` のデフォルトの設定は次のとおりです。 ``` "eval_frequency": { "type": "evaluate_every_epoch", "value": 1 }, ``` + **`1-tier-param`** — (*必須*) Tier-1 ハイパーパラメータの配列。 ハイパーパラメータを調整しない場合は、これを空の配列に設定できます。これは SageMaker AI ハイパーパラメータチューニングジョブによって起動されるトレーニングジョブの総数には影響しません。これは、すべてのトレーニングジョブが 1 より多いが 10 未満の場合、同じハイパーパラメータのセットで実行されることを意味します。 一方、すべての調整可能なハイパーパラメータを同じ有意で扱う場合は、すべてのハイパーパラメータをこの配列に入れることができます。 + **`2-tier-param`** — (*必須*) Tier-2 ハイパーパラメータの配列。 これらのパラメータは、`maxHPONumberOfTrainingJobs` が 10 より大きい値を持つ場合にのみ調整されます。そうしない場合は、デフォルト値が固定されます。 最大で 10 のトレーニングジョブ用のトレーニング予算がある場合、または他の理由で Tier-2 ハイパーパラメータを必要とせず、すべての調整可能なハイパーパラメータを調整する場合は、これを空の配列に設定できます。 + **`3-tier-param`** — (*必須*) Tier-3 ハイパーパラメータの配列。 これらのパラメータは、`maxHPONumberOfTrainingJobs` が 50 より大きい値を持つ場合にのみ調整されます。そうしない場合は、デフォルト値が固定されます。 Tier-3 ハイパーパラメータを調整しない場合は、これを空の配列に設定できます。 + **`fixed-param`** — (*必須*) 既定値のみを取り、さまざまなトレーニングジョブによって変化しない固定ハイパーパラメータの配列。 すべてのハイパーパラメータを変更する場合は、これを空の配列に設定し、すべての階層を変えるか、すべてのハイパーパラメータを Tier-1 にするのに十分な大きさ `maxHPONumberOfTrainingJobs` の値に設定します。 `1-tier-param`、`2-tier-param`、`3-tier-param` および `fixed-param` の各ハイパーパラメータを表す JSON オブジェクトには、次の要素が含まれます。 + **`param`** — (*文字列*) ハイパーパラメータの名前 (**変わらない**)。 フレームワークの使用の詳細については、[Neptune ML の有効なハイパーパラメータ名のリスト](#machine-learning-hyperparams-list)を参照してください。 + **`type`** — (*文字列*) ハイパーパラメータタイプ (**変わらない**)。 有効なタイプは、`bool`、`int` および `float` です。 + **`default`** — (*文字列*) ハイパーパラメータのデフォルト値。 新しいデフォルト値を設定できます。 調整可能なハイパーパラメータには、次の要素を含めることができます。 + **`range`** — (*配列*) 連続調整可能なハイパーパラメータの範囲。 これは、2つの値、すなわち範囲の最小値と最大値を持つ配列でなければなりません (`[min, max]`)。 + **`options`** — (*配列*) カテゴリカル調整可能なハイパーパラメータのオプション。 この配列には、考慮すべきすべてのオプションが含まれている必要があります。 ``` "options" : [value1, value2, ... valuen] ``` + **`inc_strategy`** — (*文字列*) 連続調整可能なハイパーパラメータ範囲に対する増分変更のタイプ (**変わらない**)。 有効な値は、`log`、`linear`、`power2` です。これは、範囲キーが設定されている場合にだけ適用されます。 これを変更すると、チューニングにハイパーパラメータの全範囲を使用しないことがあります。 + **`inc_val`** — (*浮動小数点*) 連続調整可能ハイパーパラメータで連続する増分が異なる量 (**変わらない**)。 これは、範囲キーが設定されている場合にだけ適用されます。 これを変更すると、チューニングにハイパーパラメータの全範囲を使用しないことがあります。 + **`node_strategy`** — (*文字列*) このハイパーパラメータの有効範囲は、グラフ内のノード数に基づいて変化することを示します (**変わらない**)。 有効な値は、`"perM"` (100 万当たり)、`"per10M"` (1000 万当たり)、`"per100M"` (1 億当たり) です。 この値を変更するのではなく、代わりに `range` を変更します。 + **`edge_strategy`** — (*文字列*) このハイパーパラメータの有効範囲は、グラフ内のエッジ数に基づいて変化することを示します (**変わらない**)。 有効な値は、`"perM"` (100 万当たり)、`"per10M"` (1000 万当たり)、`"per100M"` (1 億当たり) です。 この値を変更するのではなく、代わりに `range` を変更します。 ### Neptune ML のすべてのハイパーパラメータのリスト 次のリストには、Neptune ML の任意のモデルタイプおよびタスクに対して設定できるすべてのハイパーパラメータが含まれています。これらはすべて全部のモデルタイプに適用できるわけではないので、ハイパーパラメータは使用しているモデルのテンプレートに表示される `model-HPO-configuration.json` ファイルでのみ設定します。 + **`batch-size`** — 1 つのフォワードパスで使用するターゲットノードのバッチのサイズ。*タイプ*: `int`。 これをはるかに大きな値に設定すると、GPU インスタンスのトレーニングでメモリの問題が発生する可能性があります。 + **`concat-node-embed`** — モデルの表現度を高めるために、処理された特徴を学習可能な最初のノード埋め込みと連結して、ノードの初期表現を取得するかどうかを示します。*タイプ*: `bool`。 + **`dropout`** — ドロップアウトレイヤーに適用されるドロップアウトの確率。*タイプ*: `float`。 + **`edge-num-hidden`** — エッジフィーチャモジュールの非表示のレイヤーサイズまたはユニット数。`use-edge-features` が `True` に設定されている場合にのみ使用されます。*タイプ*: 浮動小数点。 + **`enable-early-stop`** — 早期停止機能を使用するかどうかを切り替えます。*タイプ*: `bool`。*デフォルト*: `true`。 このブール値パラメータを使用して、早期停止機能をオフにします。 + **`fanout`** — ネイバーサンプリング中にターゲットノードについてサンプリングするネイバーの数。*タイプ*: `int`。 この値は、`num-layers` と緊密に結合されています。また、常に同じハイパーパラメータ層内に配置する必要があります。これは、潜在的な GNN レイヤーごとにファンアウトを指定できるためです。 このハイパーパラメータによってモデルのパフォーマンスが大きく変わる可能性があるため、固定するか、Tier-2 または Tier-3 ハイパーパラメータとして設定する必要があります。これを大きな値に設定すると、GPU インスタンスのトレーニングでメモリの問題が発生する可能性があります。 + **`gamma`** — スコア関数のマージン値。*タイプ*: `float`。 これは、`KGE` リンク予測モデルのみに当てはまります。 + **`l2norm`** — オプティマイザで使用される荷重減衰値。荷重に L2 正規化ペナルティを課します。*タイプ*: `bool`。 + **`layer-norm`** — `rgcn` モデルにレイヤー正規化を使用するかどうかを示します。*タイプ*: `bool`。 + **`low-mem`** — 速度を犠牲にしてリレーションメッセージパッシング関数のメモリ不足実装を使用するかどうかを示します。*タイプ*: `bool`。 + **`lr`** — 学習レート。*タイプ*: `float`。 これは Tier-1 ハイパーパラメータとして設定する必要があります。 + **`neg-share`** — リンク予測では、正のサンプリングされたエッジが負のエッジサンプルを共有できるかどうかを示します。*タイプ*: `bool`。 + **`num-bases`** — `rgcn` モデルにおける基底分解のベース数。グラフ内のエッジタイプの数よりも小さい `num-bases` の値を使用すると、グラフは `rgcn` モデルの正則化手段として機能します。*タイプ*: `int`。 + **`num-epochs`** - 実行するトレーニングエポックの数。*タイプ*: `int`。 エポックは、グラフを通る完全なトレーニングパスです。 + **`num-hidden`** — 非表示のレイヤーのサイズまたは単位数。*タイプ*: `int`。 これにより、特徴がないノードの初期埋め込みサイズも設定されます。 これを `batch-size` を減らすことなくはるかに大きな値に設定すると、GPU インスタンスのトレーニングでメモリの問題が発生する可能性があります。 + **`num-layer`** — モデル内の GNN レイヤーの数。*タイプ*: `int`。 この値は、ファンアウトパラメータと緊密に結合されています。また、常に同じハイパーパラメータ層内にファンアウトを設定した後にこれが来る必要があります。 これによってモデルのパフォーマンスが大きく変わる可能性があるため、固定するか、Tier-2 または Tier-3 ハイパーパラメータとして設定する必要があります。 + **`num-negs`** — リンク予測では、正のサンプルあたりの負のサンプルの数。*タイプ*: `int`。 + **`per-feat-name-embed`** — 特徴を組み合わせる前に個別に変換することにより、各特徴を埋め込むかどうかを示します。*タイプ*: `bool`。 `true` に設定すると、ノードごとの各フィーチャが独立して固定次元サイズに変換され、その後、ノードのすべての変換されたフィーチャが連結され、さらに `num_hidden` 次元に変換されます。 `false` に設定すると、フィーチャ固有の変換を行わずにフィーチャが連結されます。 + **`regularization-coef`** — リンク予測では、正則化損失の係数。*タイプ*: `float`。 + **`rel-part`** — `KGE` リンク予測に対してリレーションパーティションを使用するかどうかを示します。*タイプ*: `bool`。 + **`sparse-lr`** — 学習可能なノード埋め込みの学習率。*タイプ*: `float`。 学習可能な初期ノード埋め込みは、特徴がないノードや、`concat-node-embed` が設定されたときに使用されます。スパース学習可能ノード埋め込みレイヤーのパラメータは、個別の学習率を持つことができる別のオプティマイザを使用してトレーニングされます。 + **`use-class-weight`** — 不均衡な分類タスクにクラス荷重を適用するかどうかを示します。`true` に設定すると、ラベル数を使用して、各クラスラベルの荷重が設定されます。*タイプ*: `bool`。 + **`use-edge-features`** — メッセージの受け渡し時にエッジ機能を使用するかどうかを示します。`true` に設定すると、特徴を持つエッジタイプのカスタムエッジ機能モジュールが RGCN レイヤーに追加されます。*タイプ*: `bool`。 + **`use-self-loop`** — `rgcn` モデルのトレーニングにセルフループを含めるかどうかを示します。*タイプ*: `bool`。 + **`window-for-early-stop`** - 早期停止を決定するために平均する最新の検証スコアの数を制御します。デフォルトは 3. type=int です。[Neptune ML でのモデルトレーニングプロセスの早期停止](machine-learning-improve-model-performance.md#machine-learning-model-training-early-stop) も参照してください。*タイプ*: `int`。*デフォルト*: `3`。 「」を参照してください。 ## Neptune ML でのハイパーパラメータのカスタマイズ `model-HPO-configuration.json` ファイルを編集しているときでは、最も一般的な変更の種類を以下に示します。 + `range` ハイパーパラメータの最小値および/または最大値を編集します。 + ハイパーパラメータを固定値に設定するには、`fixed-param` セクションを開き、デフォルト値を設定したい固定値に設定します。 + ハイパーパラメータを特定の層に配置し、その範囲を編集し、そのデフォルト値が適切に設定されていることを確認して、ハイパーパラメータの優先順位を変更します。 # モデルトレーニングのベストプラクティス Neptune ML モデルのパフォーマンスを向上させるためにできることはあります。 ## 適切なノードプロパティを選択する グラフ内のすべてのプロパティが機械学習タスクに有意義である、または関連性があるとは限りません。無関係なプロパティは、データのエクスポート時に除外する必要があります。 ベストプラクティスを以下に示します。 + ドメインのエキスパートを使用して、特徴の重要性とそれらを予測に使用することの実現可能性を評価します。 + データのノイズや重要でない相関を減らすために、冗長または無関係であると判断した特徴を削除します。 + モデルの構築中に反復処理を行います。特徴、特徴の組み合わせ、調整目標を調整できます。 Amazon Machine Learning Developer Guide の[特徴処理](https://docs.aws.amazon.com/machine-learning/latest/dg/feature-processing.html)には、Neptune ML に関連する特徴処理に関する追加のガイドラインが記載されています。 ## 外れ値のデータポイントの処理 外れ値は、残りのデータとは大きく異なるデータ点です。データの外れ値は、トレーニングプロセスを台無しにしたり誤解を招いたりして、トレーニング時間が長くなったり、モデルの精度が低下したりする可能性があります。これらが本当に重要でない限り、データをエクスポートする前に外れ値を排除する必要があります。 ## 重複するノードとエッジを削除する Neptune に格納されているグラフには、重複したノードまたはエッジがある場合があります。これらの冗長要素は、ML モデルトレーニングにノイズを発生させます。データをエクスポートする前に、重複するノードまたはエッジを削除してください。 ## グラフ構造の微調整 グラフをエクスポートするときに、特徴の処理方法やグラフの作成方法を変更して、モデルのパフォーマンスを向上させることができます。 ベストプラクティスを以下に示します。 + エッジプロパティがエッジのカテゴリの意味を持つ場合、場合によってはエッジタイプに変換する価値があります。 + 数値プロパティに使用されるデフォルトの正規化ポリシーは `min-max` ですが、場合によっては他の正規化ポリシーがうまくいく場合もある。[`model-HPO-configuration.json` 要素のリスト。](machine-learning-customizing-hyperparams.md#machine-learning-hyperparams-file-elements) の説明に従って、プロパティを前処理し、正規化ポリシーを変更できます。 + エクスポートプロセスでは、プロパティタイプに基づいて特徴タイプが自動的に生成されます。例えば、`String` プロパティをカテゴリ別特徴とし、`Float` および `Int` プロパティを数値特徴として処理します。必要に応じて、エクスポート後にとしタイプを変更できます ([`model-HPO-configuration.json` 要素のリスト。](machine-learning-customizing-hyperparams.md#machine-learning-hyperparams-file-elements))。 ## ハイパーパラメータの範囲とデフォルトを調整する データ処理オペレーションは、グラフからハイパーパラメータ設定範囲を推測します。生成されたモデルのハイパーパラメータの範囲とデフォルトがグラフデータでうまく機能しない場合は、HPO 設定ファイルを編集して、独自のハイパーパラメータ調整戦略を作成できます。 ベストプラクティスを以下に示します。 + グラフが大きくなると、デフォルトの非表示次元サイズがすべての情報を含むのに十分な大きさではない場合があります。`num-hidden` ハイパーパラメータを変更して非表示の寸法サイズを制御することもできます。 + Knowledge Graph Embedding (KGE) モデルの場合、グラフの構造と予算に応じて、使用されている特定のモデルを変更したい場合があります。 `TrainsE` モデルは、１対多 (1-N)、多対１ (N-1)、多対多 (N-N) の関係を扱うのが困難です。`DistMult` モデルは対称関係を扱うのが困難です。`RotatE` はあらゆる種類のリレーションのモデリングが得意ですが、トレーニング中は `TrainsE` および `DistMult` よりも高価です。 + 場合によっては、ノード識別とノード特徴情報の両方が重要な場合は、``concat-node-embed`` を使用してNeptune ML モデルに、その特徴と初期埋め込みを連結して、ノードの初期表現を取得するように指示します。 + 一部のハイパーパラメータに対して適度に良好なパフォーマンスが得られる場合は、それらの結果に応じてハイパーパラメータサーチスペースを調整できます。 ## Neptune ML でのモデルトレーニングプロセスの早期停止 早期停止により、モデルのパフォーマンスを低下させることなく、モデルトレーニングのランタイムと関連コストを大幅に削減できます。また、モデルがトレーニングデータに過適合するのを防ぎます。 早期停止は、検証セットのパフォーマンスの定期的な測定値に依存します。最初は、トレーニングが進むにつれてパフォーマンスは向上しますが、モデルが過適合となると、再び低下し始めます。早期停止機能は、モデルが過適合を開始し、その時点でモデルトレーニングを停止する点を特定します。 Neptune ML は検証メトリクスの呼び出しを監視し、最新の検証メトリクスを最後の **`n`** 評価の検証メトリクスの平均と比較します。ここで、**`n`** は `window-for-early-stop` パラメータを使用して設定された数値です。検証メトリクスがその平均よりも悪くなるとすぐに、Neptune ML はモデルトレーニングを停止し、それまでに最適なモデルを保存します。 次のパラメータを使用して、早期停止を制御できます。 + ** `window-for-early-stop`** —このパラメータの値は、早期停止を決定する際に平均する最近の検証スコアの数を指定する整数です。デフォルト値は `3` です。 + ** `enable-early-stop`** —このブール値パラメータを使用して、早期停止機能をオフにします。デフォルトでは、この値は `true` です。 ## Neptune ML での HPO プロセスの早期停止 Neptune ML の早期停止機能は、SageMaker AI HPO ウォームスタート機能を使用して、他のトレーニングジョブと比較してうまく機能しないトレーニングジョブを停止します。これにより、コストを削減し、HPO の品質を向上させることができます。 この仕組みについては、[ウォームスタートのハイパーパラメータチューニングジョブを実行する](https://docs.aws.amazon.com/sagemaker/latest/dg/automatic-model-tuning-warm-start.html)を参照してください。 ウォームスタートは、以前のトレーニングジョブから学習した情報を後続のトレーニングジョブに渡す機能を提供し、次の 2 つの異なる利点があります。 + まず、以前の調整ジョブの結果は、新しいトレーニングジョブで検索するハイパーパラメータの良い組み合わせを選択する目的で使用されます。 + 第 2 に、早期停止により多くのモデル実行にアクセスできるため、チューニング時間が短縮されます。 この機能は Neptune ML で自動的に有効になり、モデルトレーニング時間とパフォーマンスのバランスを取ることができます。現在のモデルのパフォーマンスに満足すれば、そのモデルを使用できます。そうでない場合は、以前の実行の結果でウォームスタートされるより多くの HPO を実行して、より良いモデルを発見します。 ## プロフェッショナルサポートサービスを受ける AWS は、Neptune プロジェクトでの機械学習における問題に対処するための専門的なサポートサービスを提供します。行き詰まったら、[AWS サポート](https://aws.amazon.com/premiumsupport/)をご利用ください。 # トレーニング済みモデルを使用して新しいモデルのアーティファクトを生成する Neptune ML モデル変換コマンドを使用すると、事前にトレーニングしたモデルパラメータを使用して、処理されたグラフデータに対するノード埋め込みなどのモデルアーティファクトを計算できます。 ## 増分推論のためのモデル変換 [増分モデル推論ワークフロー](machine-learning-overview-evolving-data-incremental.md#machine-learning-overview-incremental)で、Neptune からエクスポートした更新されたグラフデータを処理した後、次のような curl (または awscurl) コマンドを使用してモデル変換ジョブを開始できます。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/modeltransform -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique model-training job ID)", "dataProcessingJobId" : "(the data-processing job-id of a completed job)", "mlModelTrainingJobId": "(the ML model training job-id)", "modelTransformOutputS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-transform/" }' ``` その後、このジョブの ID を create-endpoints API 呼び出しに渡して、新しいエンドポイントを作成するか、このジョブによって生成された新しいモデルアーティファクトで既存のエンドポイントを更新できます。これにより、新しいエンドポイントまたは更新されたエンドポイントが、更新されたグラフデータのモデル予測を提供できるようになります。 ## あらゆるトレーニングジョブのモデル変換 Neptune ML モデルトレーニング中に起動された任意の SageMaker AI トレーニングジョブのモデルアーティファクトを生成する `trainingJobName` パラメータを指定することもできます。Neptune ML モデルトレーニングジョブは潜在的に多くの SageMaker AI トレーニングジョブを起動できるため、これらのいずれかの SageMaker AI トレーニングジョブに基づいて推論エンドポイントを柔軟に作成できます。 例: ``` curl \ -X POST https://(your Neptune endpoint)/ml/modeltransform -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique model-training job ID)", "trainingJobName" : "(name a completed SageMaker AI training job)", "modelTransformOutputS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-transform/" }' ``` 元のトレーニングジョブがユーザー指定のカスタムモデルを対象とした場合は、モデル変換を呼び出す際に `customModelTransformParameters` オブジェクトを含める必要があります。カスタムモデルの実装と使用方法の詳細については、[Neptune ML のカスタムモデル](machine-learning-custom-models.md) を参照してください。 **注記** `modeltransform` コマンドは常に、そのトレーニングに最適な SageMaker AI トレーニングジョブでモデル変換を実行します。 モデル変換ジョブについては、[モデルトランスフォームコマンド](machine-learning-api-modeltransform.md) を参照してください。 # Neptune MLのモデルトレーニングによって生成されたアーティファクト モデルトレーニングの後、Neptune ML は最適なトレーニング済みモデルパラメータを使用して、推論エンドポイントの起動とモデル予測の提供に必要なモデルアーティファクトを生成します。これらのアーティファクトは、トレーニングジョブによってパッケージ化され、最適な SageMaker AI トレーニングジョブの Amazon S3 出力場所に保存されます。 次のセクションでは、さまざまなタスクのモデルアーティファクトに含まれる内容と、モデル変換コマンドで既存のトレーニング済みモデルを使用して、新しいグラフデータでもアーティファクトを生成する方法について説明します。 ## 異なるタスクに対して生成されたアーティファクト トレーニングプロセスによって生成されるモデルアーティファクトの内容は、対象とする機械学習タスクによって異なります。 **** + **ノードの分類とリグレッション** — ノードプロパティ予測の場合、アーティファクトには、モデルのパラメータ、[GNN エンコーダ](machine-learning-models-and-training.md#machine-learning-gnns)からのノード埋め込み、トレーニンググラフのノードのモデル予測、および推論エンドポイントの設定ファイルが含まれます。ノードの分類およびノードリグレッションタスクでは、モデル予測は、トレーニング時に存在するノードについては事前に計算されて、クエリのレイテンシーが削減されます。 + **エッジ分類とリグレッション** — エッジプロパティ予測の場合、アーティファクトにはモデルパラメータとノードの埋め込みも含まれます。エッジの始点および終点の頂点の埋め込みにモデルデコーダを適用することにより、エッジ分類またはエッジリグレッション予測を計算するため、モデルデコーダのパラメータは推論において特に重要です。 + **リンク予測** — リンク予測では、エッジプロパティ予測で生成されたアーティファクトに加えて、トレーニンググラフが予測を実行する必要があるため、DGL グラフもアーティファクトとして含まれます。リンク予測の目的は、始点頂点と結合してグラフ内の特定のタイプのエッジを形成する可能性が高い終点頂点を予測することです。これを行うために、始点頂点のノード埋め込みとエッジタイプの学習された表現を、可能なすべての終点頂点のノード埋め込みと結合して、各終点頂点のエッジ尤度スコアを生成します。次に、スコアがソートされ、潜在的な終点頂点がランク付けされ、上位候補が返されます。 タスクタイプごとに、DGL の Graph Neural Network モデルの重みがモデルアーティファクトに保存されます。これにより、Neptune ML は、事前に計算された予測と埋め込み(*トランスダクティブ*推論) を使用してレイテンシーを短縮するだけでなく、グラフの変化に応じて新しいモデル出力を計算できます (*帰納的*推論)。 ## 新しいモデルアーティファクトの生成 Neptune ML でのモデルトレーニング後に生成されたモデルアーティファクトは、トレーニンググラフに直接結びつけられます。つまり、事前に計算された埋め込みと予測は、元のトレーニンググラフにあったエンティティについてのみ存在します。Neptune ML エンドポイントの帰納的推論モードでは、新しいエンティティの予測をリアルタイムで計算できますが、エンドポイントにクエリを実行せずに新しいエンティティのバッチ予測を生成したい場合があります。 グラフに追加された新しいエンティティのバッチモデル予測を取得するには、新しいグラフデータに対して新しいモデルアーティファクトを再計算する必要があります。これは、`modeltransform` コマンドを使用して行われます。エンドポイントを設定せずにバッチ予測のみを行いたい場合や、すべての予測を生成してグラフに書き戻せるようにする場合には、`modeltransform` コマンドを使用します。 モデルトレーニングは学習プロセスの最後にモデル変換を暗黙的に実行するため、モデルのアーティファクトはトレーニングジョブによってトレーニンググラフデータ上で常に再計算されます。ただし、`modeltransform` コマンドは、モデルのトレーニングに使用されなかったグラフデータのモデルアーティファクトを計算することもできます。そのためには、新しいグラフデータを元のグラフデータと同じ特徴エンコーディングを使用して処理し、同じグラフスキーマに従う必要があります。 これを行うには、まず、元のトレーニンググラフデータで実行されるデータ処理ジョブのクローンである新しいデータ処理ジョブを作成し、新しいグラフデータで実行します ([Neptune ML の更新されたグラフデータの処理](machine-learning-on-graphs-processing.md#machine-learning-on-graphs-processing-updated) を参照)。次に、新 `dataProcessingJobId` および旧 `modelTrainingJobId` で `modeltransform` コマンドを呼び出し、更新されたグラフデータのモデルアーティファクトを再計算します。 ノードプロパティ予測では、元のトレーニンググラフに存在していたノードであっても、ノードの埋め込みと予測は新しいグラフデータで再計算されます。 エッジプロパティ予測とリンク予測では、ノードの埋め込みも再計算され、既存のノード埋め込みも同様に上書きされます。ノードの埋め込みを再計算するために、Neptune ML は、前のトレーニング済みモデルから学習済み GNN エンコーダを新しい特徴を持つ新しいグラフデータのノードに適用します。 特徴を持たないノードの場合、元のモデルトレーニングから学習した初期表現が再使用されます。特徴を持たず、元のトレーニンググラフに存在しなかった新しいノードの場合、Neptune ML は、元のトレーニンググラフに存在するそのノードタイプの学習済み初期ノード表現の平均としてそれらの表現を初期化します。これにより、特徴を持たない新しいノードが多数ある場合、モデル予測のパフォーマンスが低下する可能性があります。これは、すべてそのノードタイプの平均初期埋め込みに初期化されるためです。 `concat-node-embed` を true に設定してモデルがトレーニングされている場合、ノード特徴と学習可能な初期表現を連結して、初期ノード表現が作成されます。したがって、更新されたグラフでは、新しいノードの初期ノード表現では、新しいノード特徴と連結された平均初期ノード埋め込みも使用されます。 さらに、ノードの削除は現在サポートされていません。更新されたグラフでノードが削除されている場合は、更新されたグラフデータでモデルを再トレーニングする必要があります。 モデルのアーティファクトを再計算すると、新しいグラフで学習したモデルパラメータが再利用され、新しいグラフが古いグラフと非常によく似ている場合にのみ実行されます。新しいグラフが十分に類似していない場合は、新しいグラフデータで同様のモデル性能を得るために、モデルを再トレーニングする必要があります。十分に類似した構成は、グラフデータの構造によって異なりますが、経験則として、新しいデータと元のトレーニンググラフデータの差異が 10 ～ 20% を超える場合は、モデルを再トレーニングする必要があります。 すべてのノードに特徴があるグラフの場合、しきい値の上端 (20% の差異) が適用されますが、多くのノードに特徴がなく、グラフに追加された新しいノードにプロパティがないグラフでは、下端 (10% の差異) が高すぎることがあります。 モデル変換ジョブについては、[モデルトランスフォームコマンド](machine-learning-api-modeltransform.md) を参照してください。 # Neptune ML のカスタムモデル **注記** Neptune ML カスタムモデルのサポートは、古いバージョンの Python 3 に依存しています。up-to-date依存関係を持つカスタム GNN モデルを作成して実行するには、[SageMaker で GraphStorm ](https://graphstorm.readthedocs.io/en/v0.3.1/cli/model-training-inference/distributed/sagemaker.html)を使用します。 [リアルタイムの帰納的推論](machine-learning-overview-evolving-data.md#inductive-vs-transductive-inference)は、現在、カスタムモデルではサポートされていません。 Neptune ML では、Python を使用して独自のカスタムモデルの実装を定義できます。組み込みモデルの場合と同様に、Neptune ML インフラストラクチャを使用してカスタムモデルをトレーニングおよびデプロイし、グラフクエリを使用して予測を取得できます。 Python で独自のカスタムモデルの実装を開始するには、[Neptune ML ツールキットの例](https://github.com/awslabs/neptuneml-toolkit/tree/main/examples/custom-models/)に従い、また Neptune ML ツールキットで提供されているモデルコンポーネントを使用します。詳細については次のセクションで説明します。 **Contents** + [Neptune ML のカスタムモデルの概要](machine-learning-custom-model-overview.md) + [Neptune ML でカスタムモデルを使用する時期](machine-learning-custom-model-overview.md#machine-learning-custom-models-when-to-use) + [Neptune ML でカスタムモデルを開発して使用するためのワークフロー](machine-learning-custom-model-overview.md#machine-learning-custom-model-workflow) + [Neptune ML でのカスタムモデル開発](machine-learning-custom-model-development.md) + [Neptune ML でのカスタムモデルトレーニングスクリプト開発](machine-learning-custom-model-development.md#machine-learning-custom-model-training-script) + [Neptune ML でのカスタムモデル変換スクリプト開発](machine-learning-custom-model-development.md#machine-learning-custom-model-transform-script) + [Neptune MLのカスタム `model-hpo-configuration.json` ファイル](machine-learning-custom-model-development.md#machine-learning-custom-model-hpo-configuration-file) + [Neptune ML でのカスタムモデル実装のローカルテスト](machine-learning-custom-model-development.md#machine-learning-custom-model-testing) # Neptune ML のカスタムモデルの概要 ## Neptune ML でカスタムモデルを使用する時期 Neptune ML の組み込みモデルは、Neptune ML でサポートされているすべての標準タスクを処理しますが、特定のタスクのモデルをより細かく制御したい場合や、モデルトレーニングプロセスをカスタマイズしなければならない場合があります。たとえば、次のような場合は、カスタムモデルが適しています。 + 非常に大きなテキストモデルのテキスト機能の特徴エンコーディングは GPU で実行する必要があります。 + ディープグラフライブラリ (DGL) で開発された独自のカスタムグラフニューラルネットワーク (GNN) モデルを使いたい場合。 + ノード分類とリグレッションに表形式モデルまたはアンサンブルモデルを使用したい場合。 ## Neptune ML でカスタムモデルを開発して使用するためのワークフロー Neptune ML でのカスタムモデルのサポートは、既存の Neptune ML ワークフローにシームレスに統合するように設計されています。Neptune ML のインフラストラクチャでソースモジュールでカスタムコードを実行してモデルをトレーニングすることで機能します。組み込みモードの場合と同様に、Neptune ML は自動的に SageMaker AI ハイパーパラメータチューニングジョブを起動し、評価メトリクスに従って最適なモデルを選択します。次に、ソースモジュールで提供されている実装を使用して、デプロイ用のモデルアーティファクトを生成します。 カスタムモデルの場合、データのエクスポート、トレーニング設定、およびデータの前処理は、組み込みモデルの場合と同じです。 データの前処理の後は、Python を使用してカスタムモデルの実装を反復的かつ対話的に開発およびテストできるときです。モデルが実稼働状態になったら、作成された Python モジュールを次のようにして Amazon S3 にアップロードできます。 ``` aws s3 cp --recursive (source path to module) s3://(bucket name)/(destination path for your module) ``` 次に、モデルを本番環境にデプロイするためのノーマルな[デフォルト](machine-learning-overview.md#machine-learning-overview-starting-workflow)または[インクリメンタル](machine-learning-overview-evolving-data-incremental.md#machine-learning-overview-incremental)データワークフローを使うことができ、いくつかの違いがあります。 カスタムモデルを使用したモデルトレーニングの場合、カスタムコードが使用されていることを確認するために、Neptune ML モデルトレーニング API へ `customModelTrainingParameters` JSON オブジェクトを提供する必要があります。`customModelTrainingParameters` オブジェクトのフィールドは次のとおりです。 + **`sourceS3DirectoryPath`** — (*必須*) モデルを実装する Python モジュールがある Amazon S3 の場所へのパス。これは、少なくともトレーニングスクリプト、変換スクリプト、および `model-hpo-configuration.json` ファイルを含む有効な既存の Amazon S3 の場所を指定しなければなりません。 + **`trainingEntryPointScript`** — (*オプション*) モデルトレーニングを実行し、固定ハイパーパラメーターを含むコマンドライン引数としてハイパーパラメーターを取るスクリプトのモジュール内のエントリポイントの名前。 *デフォルト*: `training.py`。 + **`transformEntryPointScript`** — (*オプション*) モデルのデプロイに必要なモデルアーティファクトを計算するために、ハイパーパラメーター検索の最適なモデルが特定された後に実行されるスクリプトのモジュール内のエントリポイントの名前。コマンドライン引数なしで実行できるはずです。 *デフォルト*: `transform.py`。 例: ``` curl \ -X POST https://(your Neptune endpoint)/ml/modeltraining -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique model-training job ID)", "dataProcessingJobId" : "(the data-processing job-id of a completed job)", "trainModelS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-graph-autotrainer" "modelName": "custom", "customModelTrainingParameters" : { "sourceS3DirectoryPath": "s3://(your Amazon S3 bucket)/(path to your Python module)", "trainingEntryPointScript": "(your training script entry-point name in the Python module)", "transformEntryPointScript": "(your transform script entry-point name in the Python module)" } }' ``` 同様に、カスタムモデル変換を有効にするには、トレーニングジョブの保存されたモデルパラメータと互換性のあるフィールド値を持つ Neptune ML モデル変換 API へ`customModelTransformParameters` JSON オブジェクトを提供する必要があります。`customModelTransformParameters` オブジェクトには、次のフィールドが含まれます。 + **`sourceS3DirectoryPath`** — (*必須*) モデルを実装する Python モジュールがある Amazon S3 の場所へのパス。これは、少なくともトレーニングスクリプト、変換スクリプト、および `model-hpo-configuration.json` ファイルを含む有効な既存の Amazon S3 の場所を指定しなければなりません。 + **`transformEntryPointScript`** — (*オプション*) モデルのデプロイに必要なモデルアーティファクトを計算するために、ハイパーパラメーター検索の最適なモデルが特定された後に実行されるスクリプトのモジュール内のエントリポイントの名前。コマンドライン引数なしで実行できるはずです。 *デフォルト*: `transform.py`。 例： ``` curl \ -X POST https://(your Neptune endpoint)/ml/modeltransform -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique model-training job ID)", "trainingJobName" : "(name of a completed SageMaker AI training job)", "modelTransformOutputS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-transform/" "customModelTransformParameters" : { "sourceS3DirectoryPath": "s3://(your Amazon S3 bucket)/(path to your Python module)", "transformEntryPointScript": "(your transform script entry-point name in the Python module)" } }' ``` # Neptune ML でのカスタムモデル開発 カスタムモデルの開発を開始する良い方法は、以下を実行することです。[Neptune ML ツールキットの例](https://github.com/awslabs/neptuneml-toolkit/tree/main/examples/custom-models/introduction)に従ってトレーニングモジュールを構造化して記述します。Neptune ML ツールキットは、モジュール化されたグラフ ML モデルコンポーネントをスタックしてカスタムモデルを作成するために使用できる[モデルズー](https://github.com/awslabs/neptuneml-toolkit/tree/main/src/neptuneml_toolkit/modelzoo)に実装します。 さらに、ツールキットには、モデルトレーニングおよびモデル変換時に必要なアーティファクトを生成するのに役立つユーティリティ関数が用意されています。この Python パッケージは、カスタム実装にインポートできます。ツールキットで提供されている関数またはモジュールは、Neptune ML トレーニング環境でも使用できます。 Python モジュールに外部依存関係が追加されている場合は、モジュールのディレクトリにある `requirements.txt` ファイルを指定してこれらの追加依存関係を含めることができます。`requirements.txt` ファイルに一覧表示されているこのパッケージは、トレーニングスクリプトが実行される前にインストールされます。 少なくとも、カスタムモデルを実装する Python モジュールには、次のものが含まれている必要があります。 + トレーニングスクリプトのエントリポイント + トランスフォームスクリプトのエントリポイント + `model-hpo-configuration.json` ファイル ## Neptune ML でのカスタムモデルトレーニングスクリプト開発 カスタムモデルトレーニングスクリプトは、Neptune ML ツールキット [https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/train.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/train.py) の例のような実行可能な Python スクリプトである必要があります。ハイパーパラメータの名前と値をコマンドライン引数として受け入れる必要があります。モデルトレーニング中、ハイパーパラメータ名は `model-hpo-configuration.json` ファイルから取得します。ハイパーパラメータの値は、ハイパーパラメータが調整可能な場合は有効なハイパーパラメータの範囲内に入るか、調整可能でない場合はデフォルトのハイパーパラメータ値を使用します。 トレーニングスクリプトは、次のような構文を使用して SageMaker AI トレーニングインスタンスで実行されます。 ``` python3 (script entry point) --(1st parameter) (1st value) --(2nd parameter) (2nd value) (...) ``` すべてのタスクについて、Neptune ML AutoTrainer は、指定したハイパーパラメータに加えて、いくつかの必須パラメータをトレーニングスクリプトに送信しますが、適切に動作させるには、スクリプトがこれらの追加パラメータを処理できる必要があります。 これらの追加必須パラメータは、タスクによって多少異なります。 **ノード分類またはノードリグレッションの場合** + ** `task`** —Neptune ML によって内部的に使用されるタスクタイプ。ノード分類の場合、これは `node_class` であり、ノードリグレッションについては `node_regression` です。 + **`model`** — Neptune ML によって内部的に使用されるモデル名。この場合、`custom` です。 + **`name`** — Neptune ML によって内部的に使用されるタスクの名前。この場合、ノード分類の場合 `node_class-custom` で、ノードリグレッションの場合 `node_regression-custom` です。 + ** `target_ntype`** — 分類またはリグレッションのノードタイプの名前。 + ** `property`** — 分類またはリグレッションのノードプロパティの名前。 **リンク予測の場合** + ** `task`** —Neptune ML によって内部的に使用されるタスクタイプ。リンク予測の場合、これは `link_predict` です。 + **`model`** — Neptune ML によって内部的に使用されるモデル名。この場合、`custom` です。 + **`name`** — Neptune ML によって内部的に使用されるタスク名。この場合、`link_predict-custom` です。 **エッジ分類またはエッジリグレッションの場合** + ** `task`** —Neptune ML によって内部的に使用されるタスクタイプ。エッジ分類の場合、これは `edge_class` であり、エッジリグレッションについては `edge_regression` です。 + **`model`** — Neptune ML によって内部的に使用されるモデル名。この場合、`custom` です。 + **`name`** — Neptune ML によって内部的に使用されるタスクの名前。この場合、エッジ分類の場合 `edge_class-custom` で、エッジリグレッションの場合 `edge_regression-custom` です。 + ** `target_etype`** — 分類またはリグレッションのエッジタイプの名前。 + ** `property`** — 分類またはリグレッションのエッジプロパティの名前。 スクリプトは、モデルのパラメータと、トレーニングの終了時に必要となるその他のアーティファクトを保存する必要があります。 Neptune ML Toolkit ユーティリティ関数を使用して、処理されたグラフデータの場所、モデルパラメータを保存する場所、およびトレーニングインスタンスで使用可能な GPU デバイスを決定できます。フレームワークの使用の詳細については、これらのユーティリティ関数の使用方法の例を示す [train.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/train.py) サンプルトレーニングスクリプトを参照してください。 ## Neptune ML でのカスタムモデル変換スクリプト開発 モデルの再トレーニングを行わずに進化するグラフのモデル推論のための Neptune ML [増分ワークフロー](machine-learning-overview-evolving-data-incremental.md#machine-learning-overview-incremental)を利用するには、トランスフォームスクリプトが必要です。モデルのデプロイに必要なすべてのアーティファクトがトレーニングスクリプトによって生成された場合でも、モデルを再トレーニングせずに更新されたモデルを生成する場合は、変換スクリプトを提供する必要があります。 **注記** [リアルタイムの帰納的推論](machine-learning-overview-evolving-data.md#inductive-vs-transductive-inference)は、現在、カスタムモデルではサポートされていません。 カスタムモデルトレーニングスクリプトは、Neptune ML ツールキット [transform.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/transform.py) の例スクリプトのような実行可能な Python スクリプトである必要があります。このスクリプトは、コマンドライン引数なしでモデルトレーニング中に呼び出されるため、スクリプトが受け入れるコマンドライン引数はデフォルトである必要があります。 このスクリプトは、次のような構文で SageMaker AI トレーニングインスタンスで実行されます。 ``` python3 (your transform script entry point) ``` トランスフォームスクリプトには、次のようなさまざまな情報が必要です。 + 処理されたグラフデータの場所。 + モデルパラメータが保存され、新しいモデルアーティファクトが保存される場所。 + そのインスタンスで使用可能なデバイス。 + 最適なモデルを生成したハイパーパラメータ。 これらの入力は、スクリプトが呼び出すことができる Neptune ML ユーティリティ関数を使用して取得されます。その方法の例としてツールキットのサンプル [transform.py](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/transform.py) スクリプトを参照してください。 スクリプトは、ノード埋め込み、ノード ID マッピング、および各タスクのモデル展開に必要なその他のアーティファクトを保存する必要があります。さまざまな Neptune ML タスクに必要なモデルアーティファクトの詳細については、[モデルアーティファクトのドキュメント](machine-learning-model-artifacts.md)を参照してください。 ## Neptune MLのカスタム `model-hpo-configuration.json` ファイル `model-hpo-configuration.json` ファイルは、カスタムモデルのハイパーパラメータを定義します。それは Neptune ML 組み込みモデルで使用される `model-hpo-configuration.json` ファイルと同じ[フォーマット](machine-learning-customizing-hyperparams.md)で、Neptune ML によって自動生成され、処理されたデータの場所にアップロードされるバージョンよりも優先されます。 新しいハイパーパラメータをモデルに追加するときは、ハイパーパラメータがトレーニングスクリプトに渡されるように、このファイルにハイパーパラメータのエントリを追加する必要があります。 ハイパーパラメータを調整できるようにするには、ハイパーパラメータの範囲を指定し、`tier-1`、`tier-2` または `tier-3` param に設定します。ハイパーパラメータは、構成されたトレーニングジョブの総数で、階層内のハイパーパラメータの調整ができる場合に調整されます。調整不可能なパラメータの場合は、デフォルト値を指定し、ハイパーパラメータをファイルの `fixed-param` セクションに追加します。その方法の例についてはツールキットのサンプル[サンプル `model-hpo-configuration.json` ファイル](https://github.com/awslabs/neptuneml-toolkit/blob/main/examples/custom-models/introduction/movie-lens-rgcn/node-class/src/model-hpo-configuration.json)を参照してください。 また、SageMaker AI ハイパーパラメータ最適化ジョブがトレーニングした候補モデルの評価に使用するメトリクス定義も指定する必要があります。これを行うには、次のように `eval_metric` JSON オブジェクトを `model-hpo-configuration.json` ファイルに追加します。 ``` "eval_metric": { "tuning_objective": { "MetricName": "(metric_name)", "Type": "Maximize" }, "metric_definitions": [ { "Name": "(metric_name)", "Regex": "(metric regular expression)" } ] }, ``` `eval_metric` オブジェクトの `metric_definitions` 配列は、SageMaker AI がトレーニングインスタンスから抽出する各指標のメトリクス定義オブジェクトを一覧表示します。各メトリクス定義オブジェクトには、メトリクスの名前 (「精度」、「f1」など) を指定できる `Name` キーがあります。`Regex` キーを使用すると、特定のメトリックがトレーニングログに出力される方法に一致する正規表現文字列を指定できます。メトリクスの定義方法の詳細については、[SageMaker AI ハイパーパラメータチューニングのページ](https://docs.aws.amazon.com/sagemaker/latest/dg/automatic-model-tuning-define-metrics.html)を参照してください。 `eval_metric` の `tuning_objective` オブジェクトでは、`metric_definitions` のどのメトリクスをハイパーパラメータ最適化の目標指標として機能する評価メトリクスとして使用するかを指定できます。`MetricName` の値は、`metric_definitions` の定義の 1 つである `Name` の値と一致する必要があります。メトリクスが greater-is-better (「精度」など) または less-is-better (「平均二乗誤差」など) のどちらで解釈されるべきかに応じて、`Type` の値は「最大化」または「最小化」のいずれかになります。 `model-hpo-configuration.json` ファイルのこのセクションのエラーは、SageMaker AI ハイパーパラメータチューニングジョブが最適なモデルを選択できないため、Neptune ML モデルトレーニング API ジョブが失敗する可能性があります。 ## Neptune ML でのカスタムモデル実装のローカルテスト Neptune ML ツールキット Conda 環境を使用して、モデルをテストおよび検証するために、コードをローカルで実行できます。Neptune ノートブックインスタンスで開発している場合、この Conda 環境は Neptune Notebook インスタンスにプレインストールされます。別のインスタンスで開発する場合は、Neptune ML ツールキットの[ローカルセットアップ手順](https://github.com/awslabs/neptuneml-toolkit#local-installation)に入っています。 Conda 環境は、[モデルトレーニング API](machine-learning-api-modeltraining.md) を呼び出す際にモデルが実行する環境を正確に再現します。トレーニングスクリプトと変換スクリプトの例はすべて、簡単にデバッグできるように、ローカル環境でスクリプトを実行するコマンドライン `--local` フラグを渡すことができます。これは、モデルの実装を対話的かつ反復的にテストできるので、独自のモデルを開発する際には良い方法です。Neptune ML プロダクショントレーニング環境でのモデルトレーニング中は、このパラメータは省略されます。 # 照会のための推論エンドポイントの作成 推論エンドポイントを使用すると、モデルトレーニングプロセスによって構築された 1 つの特定のモデルを照会できます。エンドポイントは、トレーニングプロセスで生成できた特定のタイプの最もパフォーマンスの高いモデルにアタッチします。エンドポイントは Neptune からの Gremlin クエリを受け入れ、クエリ内の入力に対するモデルの予測を返すことができます。推論エンドポイントを作成した後も、削除するまでアクティブなままになります。 ## Neptune ML の推論エンドポイントの管理 Neptune からエクスポートしたデータに関するモデルトレーニングを完了したら、`curl` ( または`awscurl` ) コマンドを使って、以下のような推論コマンドが記述されます。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/endpoints -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique ID for the new endpoint)", "mlModelTrainingJobId": "(the model-training job-id of a completed job)" }' ``` また、ほぼ同じ方法で、完成したモデル変換ジョブによって作成されたモデルから推論エンドポイントを作成することもできます。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/endpoints -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique ID for the new endpoint)", "mlModelTransformJobId": "(the model-transform job-id of a completed job)" }' ``` これらのコマンドの使用方法の詳細については、[エンドポイントコマンド](machine-learning-api-endpoints.md) を参照してください。また、エンドポイントのステータスの取得方法、エンドポイントの削除方法、およびすべての推論エンドポイントの一覧表示方法に関する情報も記載されています。 # Neptune ML での推論クエリ Gremlin または SPARQL のいずれかを使用して、Neptune ML 推論エンドポイントを照会できます。ただし、[リアルタイムの帰納的推論](machine-learning-overview-evolving-data.md#inductive-vs-transductive-inference)は、現時点では、Gremlin クエリでのみサポートされています。 # Neptune ML の Gremlin 推論クエリ [Neptune ML 機能](machine-learning.md#machine-learning-capabilities) で説明しているように、Neptune ML は次の種類の推論タスクを実行できるトレーニングモデルをサポートしています。 + **ノード分類** — 頂点プロパティのカテゴリカル特徴を予測します。 + **ノードリグレッション** — 頂点の数値プロパティを予測します。 + **エッジ分類** — エッジプロパティのカテゴリ別特徴を予測します。 + **エッジリグレッション** — エッジの数値プロパティを予測します。 + **リンク予測** — 始点ノードと送信エッジが与えられた終点ノード、または終点ノードと着信エッジを指定した始点ノードを予測します。 これらのさまざまなタスクを、[GroupLens Reserch](https://grouplens.org/datasets/movielens/) 提供の [MovieLens 100k データセット](https://grouplens.org/datasets/movielens/100k/)​ を使用する例で示すことができます。このデータセットは、映画、ユーザー、およびユーザーによる映画の評価から構成され、そこから次のようなプロパティグラフを作成しました。 ![\[MovieLens 100k データセットを使用した映画プロパティグラフの例\]](http://docs.aws.amazon.com/ja_jp/neptune/latest/userguide/images/movie_property_graph_example.png) **ノード分類**: 上記のデータセットでは、`Genre` は、エッジ `included_in` によって頂点タイプ `Movie` に接続されている頂点タイプです。ただし、データセットを微調整して `Genre` を頂点タイプ `Movie` の[カテゴリ別](https://en.wikipedia.org/wiki/Categorical_variable)特徴にすると、ナレッジグラフに追加された新しい映画の推論の問題 `Genre` は、ノード分類モデルを使用して解くことができます。 **ノードリグレッション**: 頂点タイプ `Rating` を、`timestamp` および `score` のようなプロパティを持つと考えると、`Rating` に対する数値 `Score` を推論する問題は、ノードリグレッションモデルを使用して解くことができます。 **エッジ分類**: 同様に、`Rated` エッジに関して、`Love`、`Like`、`Dislike`、`Neutral`、`Hate` のうち 1 つの値となる可能性があるプロパティ `Scale` がある場合、新しい映画/レーティング `Rated` エッジに対する推論の問題 `Scale` は、エッジ分類モデルを使用して解けます。 **エッジリグレッション**: 同様に、同じように `Rated` エッジに関して、レーティングの数値を保持する `Score` プロパティがある場合、これはエッジリグレッションモデルから推測できます。 **リンク予測**: 特定の映画を評価する可能性が最も高い上位 10 人のユーザーを見つけたり、特定のユーザーが評価する可能性が最も高い上位 10 本の映画を見つけたりするなどの問題は、リンク予測に該当します。 **注記** Neptune ML ユースケースについては、各ユースケースについて実践的に理解できるように設計された非常に豊富なノートブックセットがあります。Neptune [ML CloudFormation テンプレート](machine-learning-quick-start.md)を使用して Neptune ML クラスターを作成するときに、これらのノートブックを Neptune クラスターと一緒に作成できます。これらのノートブックは、[GitHub](https://github.com/aws/graph-notebook/tree/main/src/graph_notebook/notebooks/04-Machine-Learning) でも利用できます。 **Topics** + [Gremlin 推論クエリで使用される Neptune ML 述語](machine-learning-gremlin-inference-query-predicates.md) + [Neptune ML の Gremlin ノード分類クエリ](machine-learning-gremlin-vertex-classification-queries.md) + [Neptune ML での Gremlin ノードリグレッションクエリ](machine-learning-gremlin-vertex-regression-queries.md) + [Neptune ML の Gremlin エッジ分類クエリ](machine-learning-gremlin-edge-classification-queries.md) + [Neptune ML での Gremlin エッジリグレッションクエリ](machine-learning-gremlin-edge-regression.md) + [Neptune ML のリンク予測モデルを使用した Gremlin リンク予測クエリ](machine-learning-gremlin-link-prediction-queries.md) + [Neptune ML Gremlin 推論クエリの例外のリスト](machine-learning-gremlin-exceptions.md) # Gremlin 推論クエリで使用される Neptune ML 述語 ## `Neptune#ml.deterministic` この述語は、帰納的推論クエリ、つまり [`Neptune#ml.inductiveInference`](#machine-learning-gremlin-inference-neptune-ml-inductiveInference) 述語を含むクエリではオプションです。 帰納的推論を使用する場合、Neptune エンジンはトレーニング済みの GNN モデルを評価するための適切なサブグラフを作成します。このサブグラフの要件は、最終モデルのパラメータによって異なります。具体的には、`num-layer` パラメータによってターゲットノードまたはエッジからのトラバーサルホップ数が決まり、`fanouts` パラメータによって各ホップでサンプリングするネイバーの数を指定します ([HPO パラメータ](machine-learning-customizing-hyperparams.md)を参照)。 デフォルトでは、帰納的推論クエリは非決定論的モードで実行されます。このモードでは、Neptune は近傍をランダムに構築します。予測を行う場合、この通常のランダム近傍サンプリングによって予測が異なる場合があります。 帰納的推論クエリに `Neptune#ml.deterministic` を含めると、Neptune エンジンは、同じクエリを複数回呼び出しても毎回同じ結果が返されるように、決定論的な方法で近傍をサンプリングしようとします。ただし、基礎となるグラフの変更や分散システムのアーティファクトによって変動が生じる可能性があるため、結果が完全に決定的であることは保証できません。 次のように、クエリに `Neptune#ml.deterministic` 述語を含めます。 ``` .with("Neptune#ml.deterministic") ``` `Neptune#ml.deterministic` 述語が `Neptune#ml.inductiveInference` も含まないクエリに含まれている場合は、単に無視されます。 ## `Neptune#ml.disableInductiveInferenceMetadataCache` この述語は、帰納的推論クエリ、つまり [`Neptune#ml.inductiveInference`](#machine-learning-gremlin-inference-neptune-ml-inductiveInference) 述語を含むクエリではオプションです。 帰納的推論クエリでは、Neptune は Amazon S3 に保存されているメタデータファイルを使用して、近傍を構築する際のホップ数とファンアウトを決定します。Neptune は通常、Amazon S3 からファイルを繰り返し取得しないように、このモデルメタデータをキャッシュします。クエリに `Neptune#ml.disableInductiveInferenceMetadataCache` 述語を含めることでキャッシュを無効にできます。Neptune が Amazon S3 から直接メタデータを取得するほうが時間がかかる場合がありますが、再トレーニングまたは変換後に SageMaker AI エンドポイントが更新され、キャッシュが古い場合に役立ちます。 次のように、クエリに `Neptune#ml.disableInductiveInferenceMetadataCache` 述語を含めます。 ``` .with("Neptune#ml.disableInductiveInferenceMetadataCache") ``` Jupyter ノートブックでサンプルクエリがどのように表示されるかを次に示します。 ``` %%gremlin g.with("Neptune#ml.endpoint", "ep1") .with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole") .with("Neptune#ml.disableInductiveInferenceMetadataCache") .V('101').properties("rating") .with("Neptune#ml.regression") .with("Neptune#ml.inductiveInference") ``` ## `Neptune#ml.endpoint` `Neptune#ml.endpoint` 述語は、必要に応じて、`with()` 手順に従い推論エンドポイントを指定するために使用します。 ``` .with("Neptune#ml.endpoint", "the model's SageMaker AI inference endpoint") ``` エンドポイントは、`id` またはその URL のいずれかで識別できます。例: ``` .with( "Neptune#ml.endpoint", "node-classification-movie-lens-endpoint" ) ``` または: ``` .with( "Neptune#ml.endpoint", "https://runtime.sagemaker.us-east-1.amazonaws.com/endpoints/node-classification-movie-lens-endpoint/invocations" ) ``` **注記** Neptune DB クラスターのパラメータグループで[`neptune_ml_endpoint` パラメータを](machine-learning-cluster-setup.md#machine-learning-set-inference-endpoint-cluster-parameter)エンドポイント `id` または URL に設定すれば、各クエリの `Neptune#ml.endpoint` 述語を含む必要はありません。 ## `Neptune#ml.iamRoleArn` 必要に応じて、SageMaker AI 実行 IAM ロールの ARN を指定するために、`with()` ステップで `Neptune#ml.iamRoleArn` が使用されます。 ``` .with("Neptune#ml.iamRoleArn", "the ARN for the SageMaker AI execution IAM role") ``` SageMaker AI 実行 IAM ロールを作成する方法については、[カスタム NeptuneSageMakerIAMRole ロールを作成する](machine-learning-manual-setup.md#ml-manual-setup-sm-role) を参照してください。 **注記** Neptune DB クラスターのパラメータグループで SageMaker AI 実行 IAM ロールの ARN に [`neptune_ml_iam_role` パラメータを設定](machine-learning-cluster-setup.md#machine-learning-enabling-create-param-group)すれば、各クエリの `Neptune#ml.iamRoleArn` 述語を含む必要はありません。 ## Neptune\$1ml.inductiveInference Gremlin では、トランスダクティブ推論はデフォルトで有効です。[リアルタイムの帰納的推論](machine-learning-overview-evolving-data.md#inductive-vs-transductive-inference)クエリを作成するには、次のように `Neptune#ml.inductiveInference` 述語を含めます。 ``` .with("Neptune#ml.inductiveInference") ``` グラフが動的な場合、多くの場合、機能的推論は最善の選択ですが、グラフが静的な場合、トランスダクティブ推論の方が速くて効率的です。 ## `Neptune#ml.limit` `Neptune#ml.limit` 述語は、必要に応じてエンティティごとに返される結果の数を制限します。 ``` .with( "Neptune#ml.limit", 2 ) ``` デフォルトでは、上限は 1 であり、設定できる最大数は 100 です。 ## `Neptune#ml.threshold` `Neptune#ml.threshold` 述語はオプションで、結果スコアの切り捨てしきい値を設定します。 ``` .with( "Neptune#ml.threshold", 0.5D ) ``` これにより、指定したしきい値を下回るスコアを持つすべての結果を破棄できます。 ## `Neptune#ml.classification` `Neptune#ml.classification` 述語は、ノード分類モデルの SageMaker AI エンドポイントから取得する必要があるプロパティを確立するために `properties()` ステップに追加されています。 ``` .properties( "property key of the node classification model" ).with( "Neptune#ml.classification" ) ``` ## `Neptune#ml.regression` `Neptune#ml.regression` 述語は、ノードリグレッションモデルの AI SageMaker エンドポイントから取得する必要があるプロパティを確立するために `properties()` ステップに添付されています。 ``` .properties( "property key of the node regression model" ).with( "Neptune#ml.regression" ) ``` ## `Neptune#ml.prediction` `Neptune#ml.prediction` 述語は、これがリンク予測クエリであることを確立するために `in()` および `out()` ステップに添付されています。 ``` .in("edge label of the link prediction model").with("Neptune#ml.prediction").hasLabel("target node label") ``` ## `Neptune#ml.score` `Neptune#ml.score` 述語は Gremlin ノードまたはエッジ分類クエリで、機械学習の信頼スコアを取得するために使用されます。`Neptune#ml.score` 述語は、ノードまたはエッジ分類クエリの ML 信頼度スコアを取得するために、`properties()` ステップでクエリ述語とともに渡されます。 ノード分類の例については、[その他のノード分類の例](machine-learning-gremlin-vertex-classification-queries.md#machine-learning-gremlin-node-class-other-queries)で、また、[エッジ分類セクション](machine-learning-gremlin-edge-classification-queries.md)のエッジ分類の例でご確認いただけます。 # Neptune ML の Gremlin ノード分類クエリ Neptune ML の Gremlin ノード分類について + モデルは、頂点の 1 つのプロパティで学習されます。このプロパティの一意の値のセットは、ノードクラスのセット、または単にクラスと呼ばれます。 + 頂点のプロパティのノードクラスまたはカテゴリプロパティ値は、ノード分類モデルから推測できます。これは、このプロパティがまだ頂点にアタッチされていない場合に便利です。 + ノード分類モデルから 1 つ以上のクラスを取得するには、`with()` ステップで述語 `Neptune#ml.classification` を使い `properties()` ステップを設定する必要があります。出力形式は、それらが頂点プロパティである場合に予想されるものと似ています。 **注記** ノード分類は、文字列プロパティ値でのみ機能します。つまり、`0` や `1` などの数値プロパティ値はサポートされませんが、該当する文字列 `"0"` および `"1"` はサポートされます。同様に、ブールのプロパティ値 `true` および `false` は機能しませんが、`"true"` および `"false"` は機能します。 ノード分類クエリの例を次に示します。 ``` g.with( "Neptune#ml.endpoint","node-classification-movie-lens-endpoint" ) .with( "Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role" ) .with( "Neptune#ml.limit", 2 ) .with( "Neptune#ml.threshold", 0.5D ) .V( "movie_1", "movie_2", "movie_3" ) .properties("genre").with("Neptune#ml.classification") ``` このクエリの出力は、次のようになります。 ``` ==>vp[genre->Action] ==>vp[genre->Crime] ==>vp[genre->Comedy] ``` 上記のクエリでは、`V()` および `properties()` ステップは次のように使用されます。 `V()` ステップには、ノード分類モデルからクラスを取得する頂点のセットが含まれます。 ``` .V( "movie_1", "movie_2", "movie_3" ) ``` `properties()` ステップには、モデルがトレーニングされたキーが含まれており、これがノード分類 ML 推論クエリであることを示す `.with("Neptune#ml.classification")` があります。 現在、複数のプロパティキーは、`properties().with("Neptune#ml.classification")` ステップではサポートされていません。たとえば、次のクエリでは例外が発生します。 ``` g.with("Neptune#ml.endpoint", "node-classification-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .V( "movie_1", "movie_2", "movie_3" ) .properties("genre", "other_label").with("Neptune#ml.classification") ``` 具体的なエラーメッセージについては、[Neptune ML 例外の一覧](machine-learning-gremlin-exceptions.md)を参照してください。 `properties().with("Neptune#ml.classification")` ステップは、以下のいずれかのステップと組み合わせて使用できます。 + `value()` + `value().is()` + `hasValue()` + `has(value,"")` + `key()` + `key().is()` + `hasKey()` + `has(key,"")` + `path()` ## その他のノード分類クエリ 推論エンドポイントと対応する IAM ロールの両方が DB クラスターパラメータグループに保存されている場合、ノード分類クエリは次のようになります。 ``` g.V("movie_1", "movie_2", "movie_3").properties("genre").with("Neptune#ml.classification") ``` `union()`ステップを使用して、クエリに頂点プロパティとクラスを混在させることができます。 ``` g.with("Neptune#ml.endpoint","node-classification-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .V( "movie_1", "movie_2", "movie_3" ) .union( properties("genre").with("Neptune#ml.classification"), properties("genre") ) ``` 次のような無制限クエリを作成することもできます。 ``` g.with("Neptune#ml.endpoint","node-classification-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .V() .properties("genre").with("Neptune#ml.classification") ``` ノードクラスを頂点とともに取得するには、`select()` ステップと `as()` ステップを一緒に使用します。 ``` g.with("Neptune#ml.endpoint","node-classification-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .V( "movie_1", "movie_2", "movie_3" ).as("vertex") .properties("genre").with("Neptune#ml.classification").as("properties") .select("vertex","properties") ``` 次の例に示すように、ノードクラスでフィルタリングすることもできます。 ``` g.with("Neptune#ml.endpoint", "node-classification-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .V( "movie_1", "movie_2", "movie_3" ) .properties("genre").with("Neptune#ml.classification") .has(value, "Horror") g.with("Neptune#ml.endpoint","node-classification-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .V( "movie_1", "movie_2", "movie_3" ) .properties("genre").with("Neptune#ml.classification") .has(value, P.eq("Action")) g.with("Neptune#ml.endpoint","node-classification-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .V( "movie_1", "movie_2", "movie_3" ) .properties("genre").with("Neptune#ml.classification") .has(value, P.within("Action", "Horror")) ``` ノード分類の信頼スコアは、`Neptune#ml.score` 述語を使用して取得できます。 ``` g.with("Neptune#ml.endpoint","node-classification-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .V( "movie_1", "movie_2", "movie_3" ) .properties("genre", "Neptune#ml.score").with("Neptune#ml.classification") ``` また、レスポンスは次のようになります。 ``` ==>vp[genre->Action] ==>vp[Neptune#ml.score->0.01234567] ==>vp[genre->Crime] ==>vp[Neptune#ml.score->0.543210] ==>vp[genre->Comedy] ==>vp[Neptune#ml.score->0.10101] ``` ## ノード分類クエリでの帰納的推論の使用 Jupyter ノートブックの既存のグラフに、次のように新しいノードを追加するとします。 ``` %%gremlin g.addV('label1').property(id,'101').as('newV') .V('1').as('oldV1') .V('2').as('oldV2') .addE('eLabel1').from('newV').to('oldV1') .addE('eLabel2').from('oldV2').to('newV') ``` その場合、帰納的推論クエリを使用して、新しいノードを反映したジャンルと信頼度スコアを取得できます。 ``` %%gremlin g.with("Neptune#ml.endpoint", "nc-ep") .with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole") .V('101').properties("genre", "Neptune#ml.score") .with("Neptune#ml.classification") .with("Neptune#ml.inductiveInference") ``` ただし、クエリを複数回実行すると、結果が多少異なる可能性があります。 ``` # First time ==>vp[genre->Action] ==>vp[Neptune#ml.score->0.12345678] # Second time ==>vp[genre->Action] ==>vp[Neptune#ml.score->0.21365921] ``` 同じクエリを決定論的にすることもできます。 ``` %%gremlin g.with("Neptune#ml.endpoint", "nc-ep") .with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole") .V('101').properties("genre", "Neptune#ml.score") .with("Neptune#ml.classification") .with("Neptune#ml.inductiveInference") .with("Neptune#ml.deterministic") ``` その場合、結果は毎回ほぼ同じになります。 ``` # First time ==>vp[genre->Action] ==>vp[Neptune#ml.score->0.12345678] # Second time ==>vp[genre->Action] ==>vp[Neptune#ml.score->0.12345678] ``` # Neptune ML での Gremlin ノードリグレッションクエリ ノードリグレッションは、各ノードのリグレッションモデルから推測される値が数値であることを除いて、ノード分類に似ています。次の違いを除いて、ノード分類の場合と同じ Gremlin クエリをノードリグレッションに使用できます。 + 繰り返しますが、Neptune ML では、ノードは頂点を指します。 + `properties()` ステップは `properties().with("Neptune#ml.classification")` の代わりに `properties().with("Neptune#ml.regression")` 形式を取ります。 + `"Neptune#ml.limit`" と `"Neptune#ml.threshold"` 述語は適用されません。 + 値をフィルタリングするときは、数値を指定する必要があります。 頂点分類クエリの例を次に示します。 ``` g.with("Neptune#ml.endpoint","node-regression-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn", "arn:aws:iam::0123456789:role/sagemaker-role") .V("movie_1","movie_2","movie_3") .properties("revenue").with("Neptune#ml.regression") ``` 次の例に示すように、リグレッションモデルを使用して推論された値をフィルタリングできます。 ``` g.with("Neptune#ml.endpoint","node-regression-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .V("movie_1","movie_2","movie_3") .properties("revenue").with("Neptune#ml.regression") .value().is(P.gte(1600000)) g.with("Neptune#ml.endpoint","node-regression-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .V("movie_1","movie_2","movie_3") .properties("revenue").with("Neptune#ml.regression") .hasValue(P.lte(1600000D)) ``` ## ノードリグレッションクエリでの帰納的推論の使用 Jupyter ノートブックの既存のグラフに、次のように新しいノードを追加するとします。 ``` %%gremlin g.addV('label1').property(id,'101').as('newV') .V('1').as('oldV1') .V('2').as('oldV2') .addE('eLabel1').from('newV').to('oldV1') .addE('eLabel2').from('oldV2').to('newV') ``` その場合、帰納的推論クエリを使用して、新しいノードを考慮した評価を得ることができます。 ``` %%gremlin g.with("Neptune#ml.endpoint", "nr-ep") .with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole") .V('101').properties("rating") .with("Neptune#ml.regression") .with("Neptune#ml.inductiveInference") ``` このクエリは決定論的ではないため、複数回実行すると、近傍によって多少異なる結果が返される可能性があります。 ``` # First time ==>vp[rating->9.1] # Second time ==>vp[rating->8.9] ``` より一貫性のある結果が必要な場合は、クエリを決定論的にすることもできます。 ``` %%gremlin g.with("Neptune#ml.endpoint", "nc-ep") .with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole") .V('101').properties("rating") .with("Neptune#ml.regression") .with("Neptune#ml.inductiveInference") .with("Neptune#ml.deterministic") ``` これで、結果は毎回ほぼ同じになります。 ``` # First time ==>vp[rating->9.1] # Second time ==>vp[rating->9.1] ``` # Neptune ML の Gremlin エッジ分類クエリ Neptune MLにおける Gremlin エッジ分類について + モデルは、エッジの 1 つのプロパティで学習されます。このプロパティの一意の値のセットは、クラスのセットと呼ばれます。 + エッジのクラスまたはカテゴリプロパティ値は、エッジ分類モデルから推測できます。これは、このプロパティがエッジにまだ添付されていない場合に便利です。 + エッジ分類モデルから 1 つ以上のクラスを取得するには、`with()` ステップで述語 `"Neptune#ml.classification"` を使い `properties()` ステップを設定する必要があります。出力形式は、それらがエッジプロパティである場合に予想されるものと似ています。 **注記** エッジ分類は、文字列プロパティ値でのみ機能します。つまり、`0` や `1` などの数値プロパティ値はサポートされませんが、該当する文字列 `"0"` および `"1"` はサポートされます。同様に、ブールのプロパティ値 `true` および `false` は機能しませんが、`"true"` および `"false"` は機能します。 次に示すのは、`Neptune#ml.score` 述語を使用して信頼スコアを要求するエッジ分類クエリの例です。 ``` g.with("Neptune#ml.endpoint","edge-classification-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .E("relationship_1","relationship_2","relationship_3") .properties("knows_by", "Neptune#ml.score").with("Neptune#ml.classification") ``` また、レスポンスは次のようになります。 ``` ==>p[knows_by->"Family"] ==>p[Neptune#ml.score->0.01234567] ==>p[knows_by->"Friends"] ==>p[Neptune#ml.score->0.543210] ==>p[knows_by->"Colleagues"] ==>p[Neptune#ml.score->0.10101] ``` ## Gremlin エッジ分類クエリの構文 `User` は先頭と末尾のノードであり、`Relationship` はそれらを接続するエッジである単純なグラフの場合、エッジ分類クエリの例は次のとおりです。 ``` g.with("Neptune#ml.endpoint","edge-classification-social-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .E("relationship_1","relationship_2","relationship_3") .properties("knows_by").with("Neptune#ml.classification") ``` このクエリの出力は、次のようになります。 ``` ==>p[knows_by->"Family"] ==>p[knows_by->"Friends"] ==>p[knows_by->"Colleagues"] ``` 上記のクエリでは、`E()` および `properties()` ステップは次のように使用されます。 + `E()` ステップには、エッジ分類モデルからクラスを取得するエッジのセットが含まれます。 ``` .E("relationship_1","relationship_2","relationship_3") ``` + `properties()` ステップには、モデルがトレーニングされたキーが含まれており、これがエッジ分類 ML 推論クエリであることを示す `.with("Neptune#ml.classification")` があります。 現在、複数のプロパティキーは、`properties().with("Neptune#ml.classification")` ステップではサポートされていません。たとえば、次のクエリでは、例外がスローされます。 ``` g.with("Neptune#ml.endpoint","edge-classification-social-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .E("relationship_1","relationship_2","relationship_3") .properties("knows_by", "other_label").with("Neptune#ml.classification") ``` 具体的なエラーメッセージについては、[Neptune ML Gremlin 推論クエリの例外のリスト](machine-learning-gremlin-exceptions.md) を参照してください。 `properties().with("Neptune#ml.classification")` ステップは、以下のいずれかのステップと組み合わせて使用できます。 + `value()` + `value().is()` + `hasValue()` + `has(value,"")` + `key()` + `key().is()` + `hasKey()` + `has(key,"")` + `path()` ## エッジ分類クエリでの帰納的推論の使用 Jupyter ノートブックの既存のグラフに、次のように新しいエッジを追加するとします。 ``` %%gremlin g.V('1').as('fromV') .V('2').as('toV') .addE('eLabel1').from('fromV').to('toV').property(id, 'e101') ``` その場合、帰納的推論クエリを使用して、新しいエッジを考慮したスケールを得ることができます。 ``` %%gremlin g.with("Neptune#ml.endpoint", "ec-ep") .with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole") .E('e101').properties("scale", "Neptune#ml.score") .with("Neptune#ml.classification") .with("Neptune#ml.inductiveInference") ``` このクエリは決定論的ではないため、複数回実行すると、ランダム近傍によって多少異なる結果が返される可能性があります。 ``` # First time ==>vp[scale->Like] ==>vp[Neptune#ml.score->0.12345678] # Second time ==>vp[scale->Like] ==>vp[Neptune#ml.score->0.21365921] ``` より一貫性のある結果が必要な場合は、クエリを決定論的にすることもできます。 ``` %%gremlin g.with("Neptune#ml.endpoint", "ec-ep") .with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole") .E('e101').properties("scale", "Neptune#ml.score") .with("Neptune#ml.classification") .with("Neptune#ml.inductiveInference") .with("Neptune#ml.deterministic") ``` これで、クエリを実行するたびに結果がほぼ同じになります。 ``` # First time ==>vp[scale->Like] ==>vp[Neptune#ml.score->0.12345678] # Second time ==>vp[scale->Like] ==>vp[Neptune#ml.score->0.12345678] ``` # Neptune ML での Gremlin エッジリグレッションクエリ エッジリグレッションは、モデルから推測される値が数値であることを除いて、エッジ分類に似ています。エッジリグレッションの場合、Neptune ML は分類と同じクエリをサポートします。 注意すべき重要な点は次のとおりです。 + このユースケースの `properties()` ステップを設定するために、ML 述語 `"Neptune#ml.regression"` を使用する必要があります。 + `"Neptune#ml.limit"` および `"Neptune#ml.threshold"` 述語はこのユースケースでは適用されません。 + 値をフィルタリングするには、値を数値として指定する必要があります。 ## Gremlin エッジリグレッションクエリの構文 `User` は先頭ノード、`Movie` は末尾ノード、`Rated` はそれらを接続するエッジである単純なグラフの場合、エッジ `Rated` についてスコアと呼ばれる数値評価値を見つけるエッジリグレッションクエリの例をここに示します。 ``` g.with("Neptune#ml.endpoint","edge-regression-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .E("rating_1","rating_2","rating_3") .properties("score").with("Neptune#ml.regression") ``` ML リグレッションモデルから推論された値でフィルタリングすることもできます。`"rating_1"`、`"rating_2"`、`"rating_3"` によって識別される既存の `Rated` エッジ (`User` から `Movie` へ) である、ここで、エッジプロパティ `Score` はこれらの評価には存在しません。9 以上のエッジに対して、次のようなクエリを使用して `Score` を推論できます。 ``` g.with("Neptune#ml.endpoint","edge-regression-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .E("rating_1","rating_2","rating_3") .properties("score").with("Neptune#ml.regression") .value().is(P.gte(9)) ``` ## エッジリグレッションクエリでの帰納的推論の使用 Jupyter ノートブックの既存のグラフに、次のように新しいエッジを追加するとします。 ``` %%gremlin g.V('1').as('fromV') .V('2').as('toV') .addE('eLabel1').from('fromV').to('toV').property(id, 'e101') ``` この場合、帰納的推論クエリを使用して、新しいエッジを考慮したスコアを取得できます。 ``` %%gremlin g.with("Neptune#ml.endpoint", "er-ep") .with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole") .E('e101').properties("score") .with("Neptune#ml.regression") .with("Neptune#ml.inductiveInference") ``` このクエリは決定論的ではないため、複数回実行すると、ランダム近傍によって多少異なる結果が返される可能性があります。 ``` # First time ==>ep[score->96] # Second time ==>ep[score->91] ``` より一貫性のある結果が必要な場合は、クエリを決定論的にすることもできます。 ``` %%gremlin g.with("Neptune#ml.endpoint", "er-ep") .with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole") .E('e101').properties("score") .with("Neptune#ml.regression") .with("Neptune#ml.inductiveInference") .with("Neptune#ml.deterministic") ``` これで、クエリを実行するたびに結果がほぼ同じになります。 ``` # First time ==>ep[score->96] # Second time ==>ep[score->96] ``` # Neptune ML のリンク予測モデルを使用した Gremlin リンク予測クエリ リンク予測モデルでは、次のような問題が解けます。 + **先頭ノード予測**: 頂点とエッジタイプを指定すると、その頂点からリンクする可能性が高い頂点はどれか? + **末尾ノード予測**: 頂点とエッジラベルを指定すると、その頂点へとリンクする可能性が高い頂点はどれか? **注記** エッジ予測は Neptune ML ではまだサポートされていません。 以下の例では、エッジ `Rated` でリンクされている `User` および `Movie` 頂点を持つ単純なグラフを考えてみましょう。 以下は、映画 `"movie_1"`、`"movie_2"` および `"movie_3"` を評価する可能性が最も高い上位 5 人のユーザーを予測するために使用されるサンプルヘッドノード予測クエリです。 ``` g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .with("Neptune#ml.limit", 5) .V("movie_1", "movie_2", "movie_3") .in("rated").with("Neptune#ml.prediction").hasLabel("user") ``` これは、ユーザー `"user_1"` が評価する可能性が高い上位 5 本の映画を予測するために使用する、テールノード予測の類似のものです。 ``` g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .V("user_1") .out("rated").with("Neptune#ml.prediction").hasLabel("movie") ``` エッジラベルと予測頂点ラベルの両方が必要です。いずれかが省略されると、例外がスローされます。たとえば、頂点ラベルが予測されていない次のクエリでは、例外がスローされます。 ``` g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .V("user_1") .out("rated").with("Neptune#ml.prediction") ``` 同様に、エッジラベルのない次のクエリでは、例外がスローされます。 ``` g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .V("user_1") .out().with("Neptune#ml.prediction").hasLabel("movie") ``` これらの例外が返される具体的なエラーメッセージについては、[Neptune ML 例外の一覧](machine-learning-gremlin-exceptions.md)を参照してください。 ## その他のリンク予測クエリ `select()` ステップと `as(` ステップを併用して、予測頂点を入力頂点とともに出力しすることができます。 ``` g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .V("movie_1").as("source") .in("rated").with("Neptune#ml.prediction").hasLabel("user").as("target") .select("source","target") g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .V("user_1").as("source") .out("rated").with("Neptune#ml.prediction").hasLabel("movie").as("target") .select("source","target") ``` 次のような無制限クエリを作成できます。 ``` g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .V("user_1") .out("rated").with("Neptune#ml.prediction").hasLabel("movie") g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint") .with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role") .V("movie_1") .in("rated").with("Neptune#ml.prediction").hasLabel("user") ``` ## リンク予測クエリでの帰納的推論の使用 Jupyter ノートブックの既存のグラフに、次のように新しいノードを追加するとします。 ``` %%gremlin g.addV('label1').property(id,'101').as('newV1') .addV('label2').property(id,'102').as('newV2') .V('1').as('oldV1') .V('2').as('oldV2') .addE('eLabel1').from('newV1').to('oldV1') .addE('eLabel2').from('oldV2').to('newV2') ``` その場合、帰納的推論クエリを使用して、新しいノードを考慮に入れたヘッドノードを予測できます。 ``` %%gremlin g.with("Neptune#ml.endpoint", "lp-ep") .with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole") .V('101').out("eLabel1") .with("Neptune#ml.prediction") .with("Neptune#ml.inductiveInference") .hasLabel("label2") ``` 結果: ``` ==>V[2] ``` 同様に、帰納的推論クエリを使用して、新しいノードを考慮に入れたテールノードを予測できます。 ``` %%gremlin g.with("Neptune#ml.endpoint", "lp-ep") .with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole") .V('102').in("eLabel2") .with("Neptune#ml.prediction") .with("Neptune#ml.inductiveInference") .hasLabel("label1") ``` 結果: ``` ==>V[1] ``` # Neptune ML Gremlin 推論クエリの例外のリスト これは、Neptune ML Gremlin 推論クエリの実行時に発生する可能性のある例外の包括的なリストです。これらの例外は、指定された IAM ロールまたはエンドポイントの問題から、サポートされていない Gremlin ステップやクエリあたりの ML 推論クエリ数の制限まで、さまざまな問題を対象としています。各エントリには、問題を説明する詳細なメッセージが含まれています。 + **`BadRequestException`** — 指定されたロールの認証情報を読み込めません。 *メッセージ*: `Unable to load credentials for role: the specified IAM Role ARN.` + **`BadRequestException`** — 指定された IAM ロールは SageMaker AI エンドポイントを呼び出す権限がありません。 *メッセージ*: `User: the specified IAM Role ARN is not authorized to perform: sagemaker:InvokeEndpoint on resource: the specified endpoint.` + **`BadRequestException`** — 指定されたエンドポイントは存在しません。 *メッセージ*: `Endpoint the specified endpoint not found.` + **`InternalFailureException`** — Neptune ML のリアルタイム帰納的推論メタデータを Amazon S3 から取得することはできません。 *メッセージ*: `Unable to fetch Neptune ML - Real-Time Inductive Inference metadata from S3. Check the permissions of the S3 bucket or if the Neptune instance can connect to S3.` + **`InternalFailureException`** — Neptune ML は、Amazon S3 でリアルタイム帰納的推論のメタデータファイルを見つけることができません。 *メッセージ*: `Neptune ML cannot find the metadata file for Real-Time Inductive Inference in S3.` + **`InvalidParameterException`** — 指定されたエンドポイントは構文的に有効ではありません。 *メッセージ*: `Invalid endpoint provided for external service query.` + **`InvalidParameterException`** — 指定された SageMaker 実行 IAM ロール ARN は構文的に有効ではありません。 *メッセージ*: `Invalid IAM role ARN provided for external service query.` + **`InvalidParameterException`** — クエリの `properties()` ステップで複数のプロパティキーが指定されます。 *メッセージ*: `ML inference queries are currently supported for one property key.` + **`InvalidParameterException`** — クエリで複数のエッジラベルが指定されます。 *メッセージ*: `ML inference are currently supported only with one edge label.` + **`InvalidParameterException`** — クエリで複数の頂点ラベル制約が指定されます。 *メッセージ*: `ML inference are currently supported only with one vertex label constraint.` + **`InvalidParameterException`** — `Neptune#ml.classification` および `Neptune#ml.regression` 述語の両方が同じクエリに存在します。 *メッセージ*: `Both regression and classification ML predicates cannot be specified in the query.` + **`InvalidParameterException`** — リンク予測クエリの `in()` または `out()` ステップで複数のエッジラベルが指定されます。 *メッセージ*: `ML inference are currently supported only with one edge label.` + **`InvalidParameterException`** — Neptune\$1ml.score で複数のプロパティキーが指定されました。 *メッセージ*: `Neptune ML inference queries are currently supported for one property key and one Neptune#ml.score property key.` + **`MissingParameterException`** — エンドポイントがクエリで、または DB クラスターパラメータとして指定されていません。 *メッセージ*: `No endpoint provided for external service query.` + **``MissingParameterException** — SageMaker AI 実行 IAM ロールがクエリで、または DB クラスターパラメータとして指定されていません。 *メッセージ*: `No IAM role ARN provided for external service query.` + **`MissingParameterException`** — プロパティキーがクエリの `properties()` ステップにありません。 *メッセージ*: `Property key needs to be specified using properties() step for ML inference queries.` + **`MissingParameterException`**　— リンク予測クエリの `in()` または `out()` ステップでエッジラベルが指定されていません。 *メッセージ*: `Edge label needs to be specified while using in() or out() step for ML inference queries.` + **`MissingParameterException`** — Neptune\$1ml.score でプロパティキーが指定されませんでした。 *メッセージ*: `Property key needs to be specified along with Neptune#ml.score property key while using the properties() step for Neptune ML inference queries.` + **`UnsupportedOperationException`** — `both()` ステップは、リンク予測クエリで使用されます。 *メッセージ*: `ML inference queries are currently not supported with both() step.` + **`UnsupportedOperationException`** — リンク予測クエリの `in()` または `out()` ステップとともに`has()` ステップで予測された頂点ラベルが指定されませんでした。 *メッセージ*: `Predicted vertex label needs to be specified using has() step for ML inference queries.` + **`UnsupportedOperationException`** — Gremlin ML の帰納的推論クエリは、現在、最適化されていないステップではサポートされていません。 *メッセージ*: `Neptune ML - Real-Time Inductive Inference queries are currently not supported with Gremlin steps which are not optimized for Neptune. Check the Neptune User Guide for a list of Neptune-optimized steps.` + **`UnsupportedOperationException`** — Neptune ML 推論クエリは、現在、`repeat` ステップ内ではサポートされていません。 *メッセージ*: `Neptune ML inference queries are currently not supported inside a repeat step.` + **`UnsupportedOperationException`** — 現在、1 つの Gremlin クエリでサポートされている Neptune ML 推論クエリは 1 つだけです。 *メッセージ*: `Neptune ML inference queries are currently supported only with one ML inference query per gremlin query.` # Neptune ML での SPARQL 推論クエリ Neptune ML は、RDF グラフをプロパティグラフにマッピングし、ML タスクをモデル化します。現在、次のユースケースをサポートしています。 + **オブジェクト分類** — オブジェクトのカテゴリ別特徴を予測します。 + **オブジェクト回帰** — オブジェクトの数値プロパティを予測します。 + **オブジェクト予測**— 対象と関係が与えられたオブジェクトを予測します。 + **件名の予測** — オブジェクトと関係が与えられた対象を予測します。 **注記** Neptune ML は SPARQL での主題分類と回帰のユースケースをサポートしていません。 # SPARQL 推論クエリで使用されるNeptune ML 述語 SPARQL 推論では、次の述語が使用されます。 ## `neptune-ml:timeout` 述語 リモートサーバーとの接続のタイムアウトを指定します。サーバーが要求を満たすのにかかる最大時間であるクエリ要求のタイムアウトと混同しないでください。 クエリタイムアウトが、`neptune-ml:timeout` 述語発生で指定されたサービスタイムアウトの前に発生した場合は、サービス接続もキャンセルされます。 ## `neptune-ml:outputClass` 述語 `neptune-ml:outputClass` 述語は、オブジェクト予測の予測オブジェクトのクラスまたはサブジェクト予測の予測対象を定義するためにのみ使用されます。 ## `neptune-ml:outputScore` 述語 `neptune-ml:outputScore` 述語は、機械学習モデルの出力が正しい可能性を表す正の数です。 ## `neptune-ml:modelType` 述語 `neptune-ml:modelType` 述語は、学習する機械学習モデルのタイプを指定します。 + `OBJECT_CLASSIFICATION` + `OBJECT_REGRESSION` + `OBJECT_PREDICTION` + `SUBJECT_PREDICTION` ## `neptune-ml:input` 述語 `neptune-ml:input` 述語は、Neptune ML の入力として使用される URI のリストを指します。 ## `neptune-ml:output` 述語 `neptune-ml:output` 述語は、Neptune ML が結果を返す結合集合のリストを指します。 ## `neptune-ml:predicate` 述語 `neptune-ml:predicate` 述語は、実行されるタスクに応じて異なる方法で使用されます。 + **オブジェクトまたはサブジェクト予測**の場合: 述語のタイプ (エッジまたはリレーションシップタイプ) を定義します。 + **オブジェクトの分類と回帰**の場合: 予測するリテラル (プロパティ) を定義します。 ## `neptune-ml:batchSize` 述語 `neptune-ml:batchSize` はリモートサービスコールの入力サイズを指定します。 # SPARQL オブジェクト分類の例 Neptune ML での SPARQL オブジェクト分類では、モデルは述語値の 1 つに基づいてトレーニングされます。これは、その述語が特定の主語にまだ存在していない場合に便利です。 オブジェクト分類モデルを使用すると、カテゴリカル述語値のみを推論できます。 次のクエリは、`foaf:Person` タイプのすべての入力の 述語値を予測しようとします。 ``` SELECT * WHERE { ?input a foaf:Person . SERVICE neptune-ml:inference { neptune-ml:config neptune-ml:modelType 'OBJECT_CLASSIFICATION' ; neptune-ml:input ?input ; neptune-ml:predicate ; neptune-ml:output ?output . } } ``` このクエリは、次のようにカスタマイズできます。 ``` SELECT * WHERE { ?input a foaf:Person . SERVICE neptune-ml:inference { neptune-ml:config neptune-ml:endpoint 'node-prediction-account-balance-endpoint' ; neptune-ml:iamRoleArn 'arn:aws:iam::0123456789:role/sagemaker-role' ; neptune-ml:batchSize "40"^^xsd:integer ; neptune-ml:timeout "1000"^^xsd:integer ; neptune-ml:modelType 'OBJECT_CLASSIFICATION' ; neptune-ml:input ?input ; neptune-ml:predicate ; neptune-ml:output ?output . } } ``` # SPARQL オブジェクト回帰の例 オブジェクト回帰は、各ノードの回帰モデルから推定される数値の述語値を除いて、オブジェクト分類に似ています。オブジェクト回帰には、オブジェクト分類の場合と同じ SPARQL クエリを使用できます。ただし、`the Neptune#ml.limit` および `Neptune#ml.threshold` 述語は適用されません。 次のクエリは、`foaf:Person` タイプのすべての入力の 述語値を予測しようとします。 ``` SELECT * WHERE { ?input a foaf:Person . SERVICE neptune-ml:inference { neptune-ml:config neptune-ml:modelType 'OBJECT_REGRESSION' ; neptune-ml:input ?input ; neptune-ml:predicate ; neptune-ml:output ?output . } } ``` このクエリは、次のようにカスタマイズできます。 ``` SELECT * WHERE { ?input a foaf:Person . SERVICE neptune-ml:inference { neptune-ml:config neptune-ml:endpoint 'node-prediction-account-balance-endpoint' ; neptune-ml:iamRoleArn 'arn:aws:iam::0123456789:role/sagemaker-role' ; neptune-ml:batchSize "40"^^xsd:integer ; neptune-ml:timeout "1000"^^xsd:integer ; neptune-ml:modelType 'OBJECT_REGRESSION' ; neptune-ml:input ?input ; neptune-ml:predicate ; neptune-ml:output ?output . } } ``` # SPARQL オブジェクト予測の例 *オブジェクト予測*は、指定されたサブジェクトと述語のオブジェクト値を予測します。 次のオブジェクト予測クエリは、タイプ `foaf:Person` の入力がどの映画を好むのかを予測します。 ``` ?x a foaf:Person . ?x ?m . ?m a . ## Query SELECT * WHERE { ?input a foaf:Person . SERVICE neptune-ml:inference { neptune-ml:config neptune-ml:modelType 'OBJECT_PREDICTION' ; neptune-ml:input ?input ; neptune-ml:predicate ; neptune-ml:output ?output ; neptune-ml:outputClass . } } ``` クエリ自体は、次のようにカスタマイズできます。 ``` SELECT * WHERE { ?input a foaf:Person . SERVICE neptune-ml:inference { neptune-ml:config neptune-ml:endpoint 'node-prediction-user-movie-prediction-endpoint' ; neptune-ml:iamRoleArn 'arn:aws:iam::0123456789:role/sagemaker-role' ; neptune-ml:limit "5"^^xsd:integer ; neptune-ml:batchSize "40"^^xsd:integer ; neptune-ml:threshold "0.1"^^xsd:double ; neptune-ml:timeout "1000"^^xsd:integer ; neptune-ml:outputScore ?score ; neptune-ml:modelType 'OBJECT_PREDICTION' ; neptune-ml:input ?input ; neptune-ml:predicate ; neptune-ml:output ?output ; neptune-ml:outputClass . } } ``` # SPARQL サブジェクト予測の例 *件名の予測*は、述語とオブジェクトが与えられた主語を予測します。 たとえば、次のクエリは、特定の映画を視聴するのは誰か (タイプ `foaf:User`) を予測します。 ``` SELECT * WHERE { ?input (a foaf:Movie) . SERVICE neptune-ml:inference { neptune-ml:config neptune-ml:modelType 'SUBJECT_PREDICTION' ; neptune-ml:input ?input ; neptune-ml:predicate ; neptune-ml:output ?output ; neptune-ml:outputClass ; } } ``` # Neptune ML SPARQL 推論クエリの例外のリスト **** + ** `BadRequestException`** -*メッセージ*:`The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference expects at least 1 value for the parameter (parameter name), found zero.` 。 + ** `BadRequestException`** -*メッセージ*:`The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference expects at most 1 value for the parameter (parameter name), found (a number) values.` 。 + ** `BadRequestException`** -*メッセージ*:`Invalid predicate (predicate name) provided for external service http://aws.amazon.com/neptune/vocab/v01/services/ml#inference query.` 。 + **`BadRequestException`** -*メッセージ*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference expects the predicate (predicate name) to be defined`。 + ** `BadRequestException`** -*メッセージ*:`The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference expects the value of (parameter) (parameter name) to be a variable, found: (type)"` 。 + **`BadRequestException`** -*メッセージ*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference expects the input (parameter name) to be a constant, found: (type)`。 + **`BadRequestException`** -*メッセージ*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference is expected to return only 1 value`。 + **`BadRequestException`** -*メッセージ*: `"The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference only allows StatementPatternNodes`。 + **`BadRequestException`** -*メッセージ*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference does not allow the predicate (predicate name)`。 + **`BadRequestException`** -*メッセージ*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference predicates cannot be variables, found: (type)`。 + **`BadRequestException`** -*メッセージ*: `The SERVICE http://aws.amazon.com/neptune/vocab/v01/services/ml#inference predicates are expected to be part of the namespace (namespace name), found: (namespace name)`。 # Neptune ML 管理 API リファレンス **Contents** + [データ処理コマンド](machine-learning-api-dataprocessing.md) + [データ処理ジョブを作成する](machine-learning-api-dataprocessing.md#machine-learning-api-dataprocessing-create-job) + [ジョブステータスの取得](machine-learning-api-dataprocessing.md#machine-learning-api-dataprocessing-get-job-status) + [ジョブを停止する](machine-learning-api-dataprocessing.md#machine-learning-api-dataprocessing-stop-job) + [ジョブの一覧表示](machine-learning-api-dataprocessing.md#machine-learning-api-dataprocessing-list-jobs) + [モデルトレーニングコマンド](machine-learning-api-modeltraining.md) + [モデルのトレーニングジョブを作成する](machine-learning-api-modeltraining.md#machine-learning-api-modeltraining-create-job) + [ジョブステータスの取得](machine-learning-api-modeltraining.md#machine-learning-api-modeltraining-get-job-status) + [ジョブを停止する](machine-learning-api-modeltraining.md#machine-learning-api-modeltraining-stop-job) + [ジョブの一覧表示](machine-learning-api-modeltraining.md#machine-learning-api-modeltraining-list-jobs) + [モデルトランスフォームコマンド](machine-learning-api-modeltransform.md) + [モデル変換ジョブを作成する](machine-learning-api-modeltransform.md#machine-learning-api-modeltransform-create-job) + [ジョブステータスの取得](machine-learning-api-modeltransform.md#machine-learning-api-modeltransform-get-job-status) + [ジョブを停止する](machine-learning-api-modeltransform.md#machine-learning-api-modeltransform-stop-job) + [ジョブの一覧表示](machine-learning-api-modeltransform.md#machine-learning-api-modeltransform-list-jobs) + [エンドポイントコマンド](machine-learning-api-endpoints.md) + [推論エンドポイントの作成](machine-learning-api-endpoints.md#machine-learning-api-endpoints-create-job) + [エンドポイントを取得する](machine-learning-api-endpoints.md#machine-learning-api-endpoints-get-endpoint-status) + [エンドポイントを削除します](machine-learning-api-endpoints.md#machine-learning-api-endpoints-delete-endpoint) + [推論エンドポイントの一覧表示](machine-learning-api-endpoints.md#machine-learning-api-endpoints-list-endpoints) + [例外](machine-learning-api-exceptions.md) # `dataprocessing` コマンドを使用したデータ処理 Neptune ML `dataprocessing` コマンドを実行して、データ処理ジョブの作成、ステータスの確認、停止、またはアクティブなデータ処理ジョブの一覧を表示します。 ## Neptune ML `dataprocessing` コマンドを使用したデータ処理ジョブの作成 新しいジョブを作成するための典型的なNeptune ML `dataprocessing` コマンドは次のようになります。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/dataprocessing \ -H 'Content-Type: application/json' \ -d '{ "inputDataS3Location" : "s3://(Amazon S3 bucket name)/(path to your input folder)", "id" : "(a job ID for the new job)", "processedDataS3Location" : "s3://(S3 bucket name)/(path to your output folder)" }' ``` インクリメンタル再処理を開始するコマンドは次のようになります。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/dataprocessing \ -H 'Content-Type: application/json' \ -d '{ "inputDataS3Location" : "s3://(Amazon S3 bucket name)/(path to your input folder)", "id" : "(a job ID for this job)", "processedDataS3Location" : "s3://(S3 bucket name)/(path to your output folder)" "previousDataProcessingJobId" : "(the job ID of a previously completed job to update)" }' ``` **`dataprocessing` ジョブ作成のパラメータ** + **`id`** — (*オプション*) 新しいジョブの一意の識別子。 *タイプ*: 文字列。*デフォルト値*: 自動生成された UUID。 + **`previousDataProcessingJobId`** — (*オプション*) 以前のバージョンのデータで実行された完了したデータ処理ジョブのジョブ ID。 *タイプ*: 文字列。*デフォルト*: *なし*。 *注意*: グラフデータが変更されたときにモデルを更新するために、増分データ処理にこれを使用します (ただし、データが削除された場合を除く)。 + **`inputDataS3Location`** — (*必須*) データ処理ジョブの実行に必要なデータを SageMaker AI にダウンロードする Amazon S3 ロケーションの URI。 *タイプ*: 文字列。 + **`processedDataS3Location`** — (*必須*) SageMaker AI にデータ処理ジョブの結果を保存する Amazon S3 ロケーションの URI。 *タイプ*: 文字列。 + **`sagemakerIamRoleArn`** — (*オプション*) SageMaker AI 実行のための IAM ロールの ARN。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーが発生します。 + **`neptuneIamRoleArn`** — (*オプション*) SageMaker AI がユーザーに代わってタスクを実行するために引き受けることができる IAM ロールの Amazon リソースネーム (ARN)。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーが発生します。 + **`processingInstanceType`** — (*オプション*) データ処理中に使用される ML インスタンスのタイプ。処理されたデータセットを保持できる十分なメモリ容量が必要です。 *タイプ*: 文字列。*デフォルト値*: ディスク上にエクスポートされたグラフデータのサイズの 10 倍のメモリを持つ最も小さい `ml.r5` タイプ。 *注意*: Neptune ML はインスタンスタイプを自動的に選択できます。「[データ処理用のインスタンスの選択](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-processing-instance-size)」を参照してください。 + **`processingInstanceVolumeSizeInGB`** — (*オプション*) 処理インスタンスのディスクボリュームサイズ。入力データと処理されたデータの両方がディスクに保存されるため、ボリュームサイズは両方のデータセットを保持するのに十分な大きさでなければなりません。 *タイプ*: 整数。*デフォルト*: `0`。 *注意*: 指定しない場合、または 0 の場合、Neptune ML はデータサイズに基づいてボリュームサイズを自動的に選択します。 + **`processingTimeOutInSeconds`** — (*オプション*) データ処理ジョブの秒単位で指定されたタイムアウト。 *タイプ*: 整数。*デフォルト*: `86,400` (日単位) + **`modelType`** — (*オプション*) Neptune ML が現在サポートしている 2 つのモデルタイプ、異種グラフモデル (`heterogeneous`)、ナレッジグラフ (`kge`) のうちの 1 つ。 *タイプ*: 文字列。*デフォルト*: *なし*。 *注意*: 指定しない場合、Neptune ML はデータに基づいてモデルタイプを自動的に選択します。 + **`configFileName`** — (*オプション*) トレーニング用にエクスポートされたグラフデータをロードする方法を説明するデータ仕様ファイル。ファイルは Neptune エクスポートツールキットによって自動的に生成されます。 *タイプ*: 文字列。*デフォルト*: `training-data-configuration.json`。 + **`subnets`** — (*オプション*) Neptune VPC 内のサブネットの ID。 *タイプ*: 文字列のリスト。*デフォルト*: *なし*。 + **`securityGroupIds`** — (*オプション*) VPC セキュリティグループ ID。 *タイプ*: 文字列のリスト。*デフォルト*: *なし*。 + **`volumeEncryptionKMSKey`**   –   (*オプション*) 処理ジョブを実行する ML コンピューティングインスタンスにアタッチされたストレージボリュームのデータを暗号化するために SageMaker AI が使用する AWS Key Management Service (AWS KMS) キー。 *タイプ*: 文字列。*デフォルト*: *なし*。 + **`enableInterContainerTrafficEncryption`** — (*オプション*) トレーニングジョブまたはハイパーパラメータチューニングジョブでのコンテナ間トラフィック暗号化を有効または無効にします。 *タイプ*：ブール値 *デフォルト*: *true*。 **注記** `enableInterContainerTrafficEncryption` パラメータは、[エンジンリリース 1.2.0.2.R3](engine-releases-1.2.0.2.R3.md) でのみ使用できます。 + **`s3OutputEncryptionKMSKey`**   –   (*オプション*) SageMaker AI がトレーニングジョブの出力を暗号化するために使用する AWS Key Management Service (AWS KMS) キー。 *タイプ*: 文字列。*デフォルト*: *なし*。 ## Neptune ML `dataprocessing` コマンドを使用したデータ処理ジョブのステータスの取得 ジョブのステータスのサンプル Neptune ML `dataprocessing` コマンドは、次のようになります。 ``` curl -s \ "https://(your Neptune endpoint)/ml/dataprocessing/(the job ID)" \ | python -m json.tool ``` **`dataprocessing` ジョブステータスのパラメータ** + **`id`** — (*必須*) データ処理ジョブの一意の識別子。 *タイプ*: 文字列。 + **`neptuneIamRoleArn`** — (*オプション*) SageMaker AI および Amazon S3 リソースへの Neptune アクセスを提供する IAM ロールの ARN。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーが発生します。 ## Neptune ML `dataprocessing` コマンドを使用したデータ処理ジョブの停止 ジョブのを停止するサンプル Neptune ML `dataprocessing` コマンドは、次のようになります。 ``` curl -s \ -X DELETE "https://(your Neptune endpoint)/ml/dataprocessing/(the job ID)" ``` または、このようになります。 ``` curl -s \ -X DELETE "https://(your Neptune endpoint)/ml/dataprocessing/(the job ID)?clean=true" ``` **`dataprocessing` 停止ジョブのパラメータ** + **`id`** — (*必須*) データ処理ジョブの一意の識別子。 *タイプ*: 文字列。 + **`neptuneIamRoleArn`** — (*オプション*) SageMaker AI および Amazon S3 リソースへの Neptune アクセスを提供する IAM ロールの ARN。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーが発生します。 + **`clean`** — (*オプション*) このフラグは、ジョブが停止したときにすべての Amazon S3 アーティファクトを削除する必要があることを指定します。 *タイプ*: ブール値。*デフォルト*: `FALSE`。 ## Neptune ML `dataprocessing` コマンドを使用したアクティブなデータ処理ジョブの一覧表示 アクティブジョブの一覧表示のサンプル Neptune ML `dataprocessing` コマンドは、次のようになります。 ``` curl -s "https://(your Neptune endpoint)/ml/dataprocessing" ``` または、このようになります。 ``` curl -s "https://(your Neptune endpoint)/ml/dataprocessing?maxItems=3" ``` **`dataprocessing` ジョブの一覧表示のパラメータ** + **`maxItems`** — (*オプション*) 返される項目の最大数。 *タイプ*: 整数。*デフォルト*: `10`。*最大許容値*: `1024`。 + **`neptuneIamRoleArn`** — (*オプション*) SageMaker AI および Amazon S3 リソースへの Neptune アクセスを提供する IAM ロールの ARN。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーが発生します。 # `modeltraining` コマンドを使用したモデルトレーニング Neptune ML `modeltraining` コマンドを使用すると、モデルトレーニングジョブを作成したり、そのステータスを確認したり、停止したり、アクティブなモデルトレーニングジョブをすべて一覧表示したりできます。 ## Neptune ML `modeltraining`コマンドを使用したモデルトレーニングジョブの作成 まったく新しいジョブを作成するための Neptune ML `modeltraining` コマンドは次のようになります。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/modeltraining -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique model-training job ID)", "dataProcessingJobId" : "(the data-processing job-id of a completed job)", "trainModelS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-graph-autotrainer" }' ``` インクリメンタルモデルトレーニングの更新ジョブを作成するための Neptune ML `modeltraining` コマンドは、次のようになります。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/modeltraining -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique model-training job ID)", "dataProcessingJobId" : "(the data-processing job-id of a completed job)", "trainModelS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-graph-autotrainer" "previousModelTrainingJobId" : "(the job ID of a completed model-training job to update)", }' ``` ユーザー指定のカスタムモデル実装で新しいジョブを作成するための Neptune ML `modeltraining` コマンドは次のようになります。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/modeltraining -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique model-training job ID)", "dataProcessingJobId" : "(the data-processing job-id of a completed job)", "trainModelS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-graph-autotrainer" "modelName": "custom", "customModelTrainingParameters" : { "sourceS3DirectoryPath": "s3://(your Amazon S3 bucket)/(path to your Python module)", "trainingEntryPointScript": "(your training script entry-point name in the Python module)", "transformEntryPointScript": "(your transform script entry-point name in the Python module)" } }' ``` **`modeltraining` ジョブ作成のパラメータ** + **`id`** — (*オプション*) 新しいジョブの一意の識別子。 *タイプ*: 文字列。*デフォルト値*: 自動生成された UUID。 + **`dataProcessingJobId`** — (*必須*) トレーニングで使用するデータを作成した、完了したデータ処理ジョブのジョブ ID。 *タイプ*: 文字列。 + **`trainModelS3Location`** — (*必須*) モデルアーティファクトが保存される Amazon S3 内の場所。 *タイプ*: 文字列。 + **`previousModelTrainingJobId`** — (*オプション*) 更新されたデータに基づいて段階的に更新する、完了したモデルトレーニングジョブのジョブ ID。 *タイプ*: 文字列。*デフォルト*: *なし*。 + **`sagemakerIamRoleArn`** — (*オプション*) SageMaker AI 実行のための IAM ロールの ARN。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーが発生します。 + **`neptuneIamRoleArn`** — (*オプション*) SageMaker AI および Amazon S3 リソースへの Neptune アクセスを提供する IAM ロールの ARN。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーが発生します。 + **`modelName`** — (*オプション*) トレーニングのモデルタイプ。デフォルトでは、`modelType` に基づき ML モデルは自動的にデータ処理で使用されますが、ここで別のモデルタイプを指定できます。 *タイプ*: 文字列。*デフォルト値*: `rgcn` の場合異種グラフと `kge` の場合ナレッジグラフ。*有効な値*: 異種グラフの場合: `rgcn`。`kge` グラフの場合: `transe`、`distmult` または `rotate`。カスタムモデル実装の場合: `custom`。 + **`baseProcessingInstanceType`** — (*オプション*) ML モデルのトレーニングの準備と管理に使用される ML インスタンスのタイプ。 *タイプ*: 文字列。*注意*: これは、トレーニングデータとモデルの処理に必要なメモリに基づいて選択された CPU インスタンスです。「[モデルトレーニングとモデル変換のインスタンスの選択](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-training-transform-instance-size)」を参照してください。 + **`trainingInstanceType`** — (*オプション*) モデルトレーニングに使用される ML インスタンスのタイプ。すべてのNeptune ML モデルは、CPU、GPU、MultiGPU トレーニングをサポートしています。 *タイプ*: 文字列。*デフォルト*: `ml.p3.2xlarge`。 *注意*: トレーニングに適したインスタンスタイプは、タスクタイプ、グラフサイズ、および予算によって異なります。「[モデルトレーニングとモデル変換のインスタンスの選択](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-training-transform-instance-size)」を参照してください。 + **`trainingInstanceVolumeSizeInGB`** — (*オプション*) トレーニングインスタンスのディスクボリュームサイズ。入力データと出力モデルの両方がディスクに保存されるため、ボリュームサイズは両方のデータセットを保持するのに十分な大きさでなければなりません。 *タイプ*: 整数。*デフォルト*: `0`。 *注意*: 指定しない場合、または 0 の場合、Neptune ML はデータ処理ステップで生成された推奨に基づいてディスクボリュームサイズを選択します。「[モデルトレーニングとモデル変換のインスタンスの選択](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-training-transform-instance-size)」を参照してください。 + **`trainingTimeOutInSeconds`** — (*オプション*) トレーニングジョブの秒単位で指定したタイムアウト。 *タイプ*: 整数。*デフォルト*: `86,400` (日単位) + **`maxHPONumberOfTrainingJobs`** — ハイパーパラメータ調整ジョブで開始するトレーニングジョブの最大総数。 *タイプ*: 整数。*デフォルト*: `2`。 *注意*: Neptune ML は、機械学習モデルのハイパーパラメーターを自動的に調整します。うまく機能するモデルを得るには、少なくとも 10 個のジョブを使用します (つまり、`maxHPONumberOfTrainingJobs` を 10 と設定)。一般的に、チューニングの実行が多いほど、結果は良くなります。 + **`maxHPOParallelTrainingJobs`** — ハイパーパラメータ調整ジョブで開始する並列トレーニングジョブの最大総数。 *タイプ*: 整数。*デフォルト*: `2`。 *注意*: 実行できる並列ジョブの数は、トレーニングインスタンスで使用可能なリソースによって制限されます。 + **`subnets`** — (*オプション*) Neptune VPC 内のサブネットの ID。 *タイプ*: 文字列のリスト。*デフォルト*: *なし*。 + **`securityGroupIds`** — (*オプション*) VPC セキュリティグループ ID。 *タイプ*: 文字列のリスト。*デフォルト*: *なし*。 + **`volumeEncryptionKMSKey`**   –   (*オプション*) トレーニングジョブを実行する ML コンピューティングインスタンスにアタッチされたストレージボリュームのデータを暗号化するために SageMaker AI が使用する AWS Key Management Service (AWS KMS) キー。 *タイプ*: 文字列。*デフォルト*: *なし*。 + **`s3OutputEncryptionKMSKey`**   –   (*オプション*) SageMaker AI が処理ジョブの出力を暗号化するために使用する AWS Key Management Service (AWS KMS) キー。 *タイプ*: 文字列。*デフォルト*: *なし*。 + **`enableInterContainerTrafficEncryption`** — (*オプション*) トレーニングジョブまたはハイパーパラメータチューニングジョブでのコンテナ間トラフィック暗号化を有効または無効にします。 *タイプ*：ブール値 *デフォルト*: *true*。 **注記** `enableInterContainerTrafficEncryption` パラメータは、[エンジンリリース 1.2.0.2.R3](engine-releases-1.2.0.2.R3.md) でのみ使用できます。 + **`enableManagedSpotTraining`** — (*オプション*) Amazon Elastic Compute Cloud スポットインスタンスを使用して、機械学習モデルのトレーニングのコストを最適化します。詳細については、[Amazon SageMaker でのマネージドスポットトレーニング](https://docs.aws.amazon.com/sagemaker/latest/dg/model-managed-spot-training.html)を参照してください。 *タイプ*: ブール値。*デフォルト*: *False*。 + **`customModelTrainingParameters`** — (*オプション*) カスタムモデルトレーニングの設定。これは、次の構造を持つ JSON オブジェクトです。 + **`sourceS3DirectoryPath`** — (*必須*) モデルを実装する Python モジュールがある Amazon S3 の場所へのパス。これは、少なくともトレーニングスクリプト、変換スクリプト、および `model-hpo-configuration.json` ファイルを含む有効な既存の Amazon S3 の場所を指定しなければなりません。 + **`trainingEntryPointScript`** — (*オプション*) モデルトレーニングを実行し、固定ハイパーパラメーターを含むコマンドライン引数としてハイパーパラメーターを取るスクリプトのモジュール内のエントリポイントの名前。 *デフォルト*: `training.py`。 + **`transformEntryPointScript`** — (*オプション*) モデルのデプロイに必要なモデルアーティファクトを計算するために、ハイパーパラメーター検索の最適なモデルが特定された後に実行されるスクリプトのモジュール内のエントリポイントの名前。コマンドライン引数なしで実行できるはずです。 *デフォルト*: `transform.py`。 + **`maxWaitTime`** — (*オプション*) スポットインスタンスを使用してモデルトレーニングを実行する場合の最大待機時間 (秒単位)。`trainingTimeOutInSeconds` より大きくなければなりません。 *タイプ*: 整数。 ## Neptune ML `modeltraining` コマンドを使用したデータ処理ジョブのステータスの取得 ジョブのステータスのサンプル Neptune ML `modeltraining` コマンドは、次のようになります。 ``` curl -s \ "https://(your Neptune endpoint)/ml/modeltraining/(the job ID)" \ | python -m json.tool ``` **`modeltraining` ジョブステータスのパラメータ** + **`id`** — (*必須*) モデルトレーニングジョブの一意の識別子。 *タイプ*: 文字列。 + **`neptuneIamRoleArn`** — (*オプション*) SageMaker AI および Amazon S3 リソースへの Neptune アクセスを提供する IAM ロールの ARN。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーが発生します。 ## Neptune ML `modeltraining` コマンドを使用したモデルトレーニングジョブの停止 ジョブのを停止するサンプル Neptune ML `modeltraining` コマンドは、次のようになります。 ``` curl -s \ -X DELETE "https://(your Neptune endpoint)/ml/modeltraining/(the job ID)" ``` または、このようになります。 ``` curl -s \ -X DELETE "https://(your Neptune endpoint)/ml/modeltraining/(the job ID)?clean=true" ``` **`modeltraining` 停止ジョブのパラメータ** + **`id`** — (*必須*) モデルトレーニングジョブの一意の識別子。 *タイプ*: 文字列。 + **`neptuneIamRoleArn`** — (*オプション*) SageMaker AI および Amazon S3 リソースへの Neptune アクセスを提供する IAM ロールの ARN。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーが発生します。 + **`clean`** — (*オプション*) このフラグは、ジョブが停止したときにすべての Amazon S3 アーティファクトを削除する必要があることを指定します。 *タイプ*: ブール値。*デフォルト*: `FALSE`。 ## Neptune ML `modeltraining` コマンドを使用したアクティブなモデルトレーニングジョブの一覧表示 アクティブジョブの一覧表示のサンプル Neptune ML `modeltraining` コマンドは、次のようになります。 ``` curl -s "https://(your Neptune endpoint)/ml/modeltraining" | python -m json.tool ``` または、このようになります。 ``` curl -s "https://(your Neptune endpoint)/ml/modeltraining?maxItems=3" | python -m json.tool ``` **`modeltraining` ジョブの一覧表示のパラメータ** + **`maxItems`** — (*オプション*) 返される項目の最大数。 *タイプ*: 整数。*デフォルト*: `10`。*最大許容値*: `1024`。 + **`neptuneIamRoleArn`** — (*オプション*) SageMaker AI および Amazon S3 リソースへの Neptune アクセスを提供する IAM ロールの ARN。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーが発生します。 # モデル変換を使用して `modeltransform` コマンド Neptune ML `modeltransform` コマンドを使用すると、モデル変換ジョブを作成したり、そのステータスを確認したり、停止したり、アクティブなモデルトレーニングジョブをすべて一覧表示したりできます。 ## Neptune ML `modeltransform` コマンドを使用したモデル変換ジョブの作成 インクリメンタル変換ジョブを作成するための、モデルの再トレーニングなしでの Neptune ML `modeltransform` コマンドは、次のようになります。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/modeltransform -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique model-transform job ID)", "dataProcessingJobId" : "(the job-id of a completed data-processing job)", "mlModelTrainingJobId" : "(the job-id of a completed model-training job)", "modelTransformOutputS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-transform" }' ``` 完了した SageMaker AI トレーニングジョブからジョブを作成するための Neptune ML `modeltransform` コマンドは次のようになります。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/modeltransform -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique model-transform job ID)", "trainingJobName" : "(name of a completed SageMaker AI training job)", "modelTransformOutputS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-transform", "baseProcessingInstanceType" : "" }' ``` カスタムモデル実装を使用してジョブを作成するための Neptune ML `modeltransform` コマンドは次のようになります。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/modeltransform -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique model-training job ID)", "trainingJobName" : "(name of a completed SageMaker AI training job)", "modelTransformOutputS3Location" : "s3://(your Amazon S3 bucket)/neptune-model-transform/" "customModelTransformParameters" : { "sourceS3DirectoryPath": "s3://(your Amazon S3 bucket)/(path to your Python module)", "transformEntryPointScript": "(your transform script entry-point name in the Python module)" } }' ``` **`modeltransform` ジョブ作成のパラメータ** + **`id`** — (*オプション*) 新しいジョブの一意の識別子。 *タイプ*: 文字列。*デフォルト値*: 自動生成された UUID。 + **`dataProcessingJobId`** — 完了したデータ処理ジョブのジョブ ID。 *タイプ*: 文字列。 *注意*: `dataProcessingJobId` および `mlModelTrainingJobId` の両方を、または `trainingJobName` 含める必要があります。 + **`mlModelTrainingJobId`** — 完了したモデルトレーニングジョブのジョブ ID。 *タイプ*: 文字列。 *注意*: `dataProcessingJobId` および `mlModelTrainingJobId` の両方を、または `trainingJobName` 含める必要があります。 + **`trainingJobName`** — 完了した SageMaker AI トレーニングジョブの名前。 *タイプ*: 文字列。 *注意*: `dataProcessingJobId` および `mlModelTrainingJobId` パラメータの両方を、または `trainingJobName`パラメータを含める必要があります。 + **`sagemakerIamRoleArn`** — (*オプション*) SageMaker AI 実行のための IAM ロールの ARN。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーが発生します。 + **`neptuneIamRoleArn`** — (*オプション*) SageMaker AI および Amazon S3 リソースへの Neptune アクセスを提供する IAM ロールの ARN。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーが発生します。 + **`customModelTransformParameters `** — (*オプション*) カスタムモデルを使用したモデル変換の構成情報。`customModelTransformParameters` オブジェクトには次のフィールドが含まれています。これらのフィールドには、トレーニングジョブの保存されたモデルパラメーターと互換性のある値が必要です。 + **`sourceS3DirectoryPath`** — (*必須*) モデルを実装する Python モジュールがある Amazon S3 の場所へのパス。これは、少なくともトレーニングスクリプト、変換スクリプト、および `model-hpo-configuration.json` ファイルを含む有効な既存の Amazon S3 の場所を指定しなければなりません。 + **`transformEntryPointScript`** — (*オプション*) モデルのデプロイに必要なモデルアーティファクトを計算するために、ハイパーパラメーター検索の最適なモデルが特定された後に実行されるスクリプトのモジュール内のエントリポイントの名前。コマンドライン引数なしで実行できるはずです。 *デフォルト*: `transform.py`。 + **`baseProcessingInstanceType`** — (*オプション*) ML モデルのトレーニングの準備と管理に使用される ML インスタンスのタイプ。 *タイプ*: 文字列。*注意*: これは、変換データとモデルの処理に必要なメモリに基づいて選択された CPU インスタンスです。「[モデルトレーニングとモデル変換のインスタンスの選択](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-training-transform-instance-size)」を参照してください。 + **`baseProcessingInstanceVolumeSizeInGB`** — (*オプション*) トレーニングインスタンスのディスクボリュームサイズ。入力データと出力モデルの両方がディスクに保存されるため、ボリュームサイズは両方のデータセットを保持するのに十分な大きさでなければなりません。 *タイプ*: 整数。*デフォルト*: `0`。 *注意*: 指定しない場合、または 0 の場合、Neptune ML はデータ処理ステップで生成された推奨に基づいてディスクボリュームサイズを選択します。「[モデルトレーニングとモデル変換のインスタンスの選択](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-training-transform-instance-size)」を参照してください。 + **`subnets`** — (*オプション*) Neptune VPC 内のサブネットの ID。 *タイプ*: 文字列のリスト。*デフォルト*: *なし*。 + **`securityGroupIds`** — (*オプション*) VPC セキュリティグループ ID。 *タイプ*: 文字列のリスト。*デフォルト*: *なし*。 + **`volumeEncryptionKMSKey`**   –   (*オプション*) 変換ジョブを実行する ML コンピューティングインスタンスにアタッチされたストレージボリュームのデータを暗号化するために SageMaker AI が使用する AWS Key Management Service (AWS KMS) キー。 *タイプ*: 文字列。*デフォルト*: *なし*。 + **`enableInterContainerTrafficEncryption`** — (*オプション*) トレーニングジョブまたはハイパーパラメータチューニングジョブでのコンテナ間トラフィック暗号化を有効または無効にします。 *タイプ*：ブール値 *デフォルト*: *true*。 **注記** `enableInterContainerTrafficEncryption` パラメータは、[エンジンリリース 1.2.0.2.R3](engine-releases-1.2.0.2.R3.md) でのみ使用できます。 + **`s3OutputEncryptionKMSKey`**   –   (*オプション*) SageMaker AI が処理ジョブの出力を暗号化するために使用する AWS Key Management Service (AWS KMS) キー。 *タイプ*: 文字列。*デフォルト*: *なし*。 ## Neptune ML `modeltransform` コマンドを使用したモデル変換ジョブのステータスの取得 ジョブのステータスのサンプル Neptune ML `modeltransform` コマンドは、次のようになります。 ``` curl -s \ "https://(your Neptune endpoint)/ml/modeltransform/(the job ID)" \ | python -m json.tool ``` **`modeltransform` ジョブステータスのパラメータ** + **`id`** — (*必須*) モデル変換ジョブの一意の識別子。 *タイプ*: 文字列。 + **`neptuneIamRoleArn`** — (*オプション*) SageMaker AI および Amazon S3 リソースへの Neptune アクセスを提供する IAM ロールの ARN。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーが発生します。 ## Neptune ML `modeltransform` コマンドを使用したモデル変換ジョブの停止 ジョブのを停止するサンプル Neptune ML `modeltransform` コマンドは、次のようになります。 ``` curl -s \ -X DELETE "https://(your Neptune endpoint)/ml/modeltransform/(the job ID)" ``` または、このようになります。 ``` curl -s \ -X DELETE "https://(your Neptune endpoint)/ml/modeltransform/(the job ID)?clean=true" ``` **`modeltransform` 停止ジョブのパラメータ** + **`id`** — (*必須*) モデル変換ジョブの一意の識別子。 *タイプ*: 文字列。 + **`neptuneIamRoleArn`** — (*オプション*) SageMaker AI および Amazon S3 リソースへの Neptune アクセスを提供する IAM ロールの ARN。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーが発生します。 + **`clean`** — (*オプション*) このフラグは、ジョブが停止したときにすべての Amazon S3 アーティファクトを削除する必要があることを指定します。 *タイプ*: ブール値。*デフォルト*: `FALSE`。 ## Neptune ML `modeltransform` コマンドを使用したアクティブなモデル変換ジョブの一覧表示 アクティブジョブの一覧表示のサンプル Neptune ML `modeltransform` コマンドは、次のようになります。 ``` curl -s "https://(your Neptune endpoint)/ml/modeltransform" | python -m json.tool ``` または、このようになります。 ``` curl -s "https://(your Neptune endpoint)/ml/modeltransform?maxItems=3" | python -m json.tool ``` **`modeltransform` ジョブの一覧表示のパラメータ** + **`maxItems`** — (*オプション*) 返される項目の最大数。 *タイプ*: 整数。*デフォルト*: `10`。*最大許容値*: `1024`。 + **`neptuneIamRoleArn`** — (*オプション*) SageMaker AI および Amazon S3 リソースへの Neptune アクセスを提供する IAM ロールの ARN。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーが発生します。 # `endpoints` コマンドを使用して推論エンドポイントを管理する Neptune ML `endpoints` コマンドを使用して、推論エンドポイントの作成、そのステータスの確認、削除、または既存の推論エンドポイントのリストを表示します。 ## Neptune ML `endpoints` コマンドを使用した推論エンドポイントの作成 トレーニングジョブによって作成されたモデルから推論エンドポイントを作成するための Neptune ML `endpoints` コマンドは、次のようになります。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/endpoints -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique ID for the new endpoint)", "mlModelTrainingJobId": "(the model-training job-id of a completed job)" }' ``` トレーニングジョブによって作成されたモデルから既存の推論エンドポイントを更新するための Neptune ML `endpoints` コマンドは、次のようになります。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/endpoints -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique ID for the new endpoint)", "update" : "true", "mlModelTrainingJobId": "(the model-training job-id of a completed job)" }' ``` モデル変換ジョブによって作成されたモデルから推論エンドポイントを作成するための Neptune ML `endpoints` コマンドは、次のようになります。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/endpoints -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique ID for the new endpoint)", "mlModelTransformJobId": "(the model-training job-id of a completed job)" }' ``` モデル変換ジョブによって作成されたモデルから既存の推論エンドポイントを更新するための Neptune ML `endpoints` コマンドは、次のようになります。 ``` curl \ -X POST https://(your Neptune endpoint)/ml/endpoints -H 'Content-Type: application/json' \ -d '{ "id" : "(a unique ID for the new endpoint)", "update" : "true", "mlModelTransformJobId": "(the model-training job-id of a completed job)" }' ``` **`endpoints` 推論エンドポイントの作成のパラメータ** + **`id`** — (*オプション*) 新しい推論エンドポイントの一意の識別子。 *タイプ*: 文字列。*デフォルト値*: 自動生成されたタイムスタンプ付きの名前。 + **`mlModelTrainingJobId`** — 推論エンドポイントが指すモデルを作成した、完了したモデルトレーニングジョブのジョブ ID。 *タイプ*: 文字列。 *注意*: 次のいずれかを支給する必要があります。`mlModelTrainingJobId` または `mlModelTransformJobId`。 + **`mlModelTransformJobId`** — 完了したモデル変換ジョブのジョブ ID。 *タイプ*: 文字列。 *注意*: 次のいずれかを支給する必要があります。`mlModelTrainingJobId` または `mlModelTransformJobId`。 + **`update`** — (*オプション*) 存在する場合、このパラメータはこれが更新リクエストであることを示します。 *タイプ*: ブール値。*デフォルト*: `false` *注意*: 次のいずれかを支給する必要があります。`mlModelTrainingJobId` または `mlModelTransformJobId`。 + **`neptuneIamRoleArn`** — (*オプション*) SageMaker AI および Amazon S3 リソースへの Neptune アクセスを提供する IAM ロールの ARN。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーがスローされます。 + **`modelName`** — (*オプション*) トレーニングのモデルタイプ。デフォルトでは、`modelType` に基づき ML モデルは自動的にデータ処理で使用されますが、ここで別のモデルタイプを指定できます。 *タイプ*: 文字列。*デフォルト値*: `rgcn` の場合異種グラフと `kge` の場合ナレッジグラフ。*有効な値*: 異種グラフの場合: `rgcn`。ナレッジグラフの場合: `kge`、`transe`、`distmult` または `rotate`。 + **`instanceType`** — (*オプション*) オンラインサービスに使用される ML インスタンスのタイプ。 *タイプ*: 文字列。*デフォルト*: `ml.m5.xlarge`。 *注意*: 推論エンドポイントの ML インスタンスの選択は、タスクタイプ、グラフサイズ、および予算によって異なります。「[推論エンドポイントのインスタンスを選択する](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-inference-endpoint-instance-size)」を参照してください。 + **`instanceCount`** — (*オプション*) 予測のためにエンドポイントにデプロイする Amazon EC2 インスタンスの最小数。 *タイプ*: 整数。*デフォルト*: `1`。 + **`volumeEncryptionKMSKey`**   –   (*オプション*) エンドポイントを実行する ML コンピューティングインスタンス AWS Key Management Service (複数可AWS KMS) にアタッチされたストレージボリュームのデータを暗号化するために SageMaker AI が使用する () キー。 *タイプ*: 文字列。*デフォルト*: *なし*。 ## Neptune ML `endpoints` コマンドを使用した推論エンドポイントのステータスの取得 インスタンスエンドポイントのステータスのサンプル Neptune ML `endpoints` コマンドは、次のようになります。 ``` curl -s \ "https://(your Neptune endpoint)/ml/endpoints/(the inference endpoint ID)" \ | python -m json.tool ``` **`endpoints` インスタンスエンドポイントステータスのパラメータ** + **`id`** — (*必須*) 推論エンドポイントの一意の識別子。 *タイプ*: 文字列。 + **`neptuneIamRoleArn`** — (*オプション*) SageMaker AI および Amazon S3 リソースへの Neptune アクセスを提供する IAM ロールの ARN。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーがスローされます。 ## Neptune ML `endpoints` コマンドを使用したインスタンスエンドポイントの削除 インスタンスエンドポイントを削除するサンプル Neptune ML `endpoints` コマンドは、次のようになります。 ``` curl -s \ -X DELETE "https://(your Neptune endpoint)/ml/endpoints/(the inference endpoint ID)" ``` または、このようになります。 ``` curl -s \ -X DELETE "https://(your Neptune endpoint)/ml/endpoints/(the inference endpoint ID)?clean=true" ``` **`endpoints` 推論エンドポイントの削除のパラメータ** + **`id`** — (*必須*) 推論エンドポイントの一意の識別子。 *タイプ*: 文字列。 + **`neptuneIamRoleArn`** — (*オプション*) SageMaker AI および Amazon S3 リソースへの Neptune アクセスを提供する IAM ロールの ARN。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーがスローされます。 + **`clean`** — (*オプション*) このエンドポイントに関連するすべてのアーティファクトも削除する必要があることを示します。 *タイプ*: ブール値。*デフォルト*: `FALSE`。 ## Neptune ML `endpoints` コマンドを使用した推論エンドポイントの一覧表示 推論エンドポイントを一覧表示するための Neptune ML `endpoints` コマンドは次のようになります。 ``` curl -s "https://(your Neptune endpoint)/ml/endpoints" \ | python -m json.tool ``` または、このようになります。 ``` curl -s "https://(your Neptune endpoint)/ml/endpoints?maxItems=3" \ | python -m json.tool ``` **`dataprocessing` 推論エンドポイントの一覧表示のパラメータ** + **`maxItems`** — (*オプション*) 返される項目の最大数。 *タイプ*: 整数。*デフォルト*: `10`。*最大許容値*: `1024`。 + **`neptuneIamRoleArn`** — (*オプション*) SageMaker AI および Amazon S3 リソースへの Neptune アクセスを提供する IAM ロールの ARN。 *タイプ*: 文字列。*注意*: これは DB クラスターパラメータグループに一覧表示されている必要があります。そうしないと、エラーがスローされます。 # Neptune ML 管理 API のエラーと例外 すべての Neptune ML 管理 API 例外は 400 HTTP コードを返します。これらの例外を受け取った後、例外を生成したコマンドは再試行しないでください。 **** + ** `MissingParameterException`** -エラーメッセージ: `Required credentials are missing. Please add IAM role to the cluster or pass as a parameter to this request.` + ** `InvalidParameterException`** -エラーメッセージ (複数) : + `Invalid ML instance type.` + `Invalid ID provided. ID can be 1-48 alphanumeric characters.` + `Invalid ID provided. Must contain only letters, digits, or hyphens.` + `Invalid ID provided. Please check whether a resource with the given ID exists.` + `Another resource with same ID already exists. Please use a new ID.` + `Failed to stop the job because it has already completed or failed.` + ** `BadRequestException`** -エラーメッセージ (複数) : + `Invalid S3 URL or incorrect S3 permissions. Please check your S3 configuration.` + `Provided ModelTraining job has not completed.` + `Provided SageMaker AI Training job has not completed.` + `Provided MLDataProcessing job is not completed.` + `Provided MLModelTraining job doesn't exist.` + `Provided ModelTransformJob doesn't exist.` + `Unable to find SageMaker AI resource. Please check your input.` # Neptune ML の制限 + 現在サポートされている推論のタイプは、ノード分類、ノードリグレッション、エッジ分類、エッジリグレッション、リンク予測です ([Neptune ML 機能](machine-learning.md#machine-learning-capabilities) を参照)。 + Neptune ML がサポートできるグラフの最大サイズは、[データ準備](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-processing-instance-size)中、[モデルトレーニング](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-training-transform-instance-size)中、および[推論](machine-learning-on-graphs-instance-selection.md#machine-learning-on-graphs-inference-endpoint-instance-size)中に必要なメモリとストレージの量によって異なります。 + SageMaker AI データ処理インスタンスのメモリの最大サイズは 768 GB です。その結果、768 GB を超えるメモリが必要な場合、データ処理ステージは失敗します。 + SageMaker AI トレーニングインスタンスのメモリの最大サイズは 732 GB です。その結果、732 GB を超えるメモリが必要な場合、トレーニングステージは失敗します。 + SageMaker AI エンドポイントの推論ペイロードの最大サイズは 6 MiB です。そのため、サブグラフのペイロードがこのサイズを超えた場合、帰納的推論は失敗します。 + Neptune ML は現在、Neptune と他の依存しているサービス (AWS Lambda、Amazon API Gateway、Amazon SageMaker AI など) がすべてサポートされているリージョンでのみ利用できます。 IAM 認証のデフォルトの使用には、他の違いとともに[ここで説明](https://docs.amazonaws.cn/en_us/aws/latest/userguide/api-gateway.html#feature-diff)しているように中国 (北京) と中国 (寧夏) の違いがあります。 + Neptune ML によって起動されたリンク予測推論エンドポイントは、現在、トレーニング時にグラフに存在したノードで可能なリンクのみを予測できます。 例えば、`User` と `Movie` の頂点と `Rated` のエッジがあるグラフを考えてみましょう。対応する Neptune ML リンク予測推奨モデルを使用すると、グラフに新しいユーザーを追加し、モデルにそのユーザー向けの映画を予測させることができますが、モデルが推奨できるのは、モデルトレーニング時に存在した映画だけです。`User` ノード埋め込みは、ローカルサブグラフと GNN モデルを使用してリアルタイムで計算されるため、ユーザーが映画を評価するにつれて時間とともに変化する可能性がありますが、最終的なレコメンデーションでは、事前に計算された静的な映画の埋め込みと比較されます。 + Neptune ML でサポートされる KGE モデルは、リンク予測タスクに対してのみ機能し、表現はトレーニング中にグラフ内に存在する頂点とエッジタイプに固有です。つまり、推論クエリで参照されるすべての頂点とエッジタイプは、トレーニング中にグラフ内に存在している必要があります。新しいエッジタイプまたは頂点の予測は、モデルを再学習しなければ実行できません。 ## SageMaker AI リソース制限 アクティビティと時間経過に伴うリソースの使用状況に応じて、次のようなエラーメッセージが表示されることがあります。[リソース上限を越えました](https://docs.aws.amazon.com/sagemaker/latest/dg/regions-quotas.html) ([ResourceLimitExceeded](https://repost.aws/knowledge-center/sagemaker-resource-limit-exceeded-error))。SageMaker AI リソースをスケールアップする必要があるため、このページに記載の [SageMaker リソースのサービスクォータの引き上げリクエスト](https://docs.aws.amazon.com/sagemaker/latest/dg/regions-quotas.html#service-limit-increase-request-procedure) の手順に従い AWS サポートから上限を増えすリクエストを送ります。 SageMaker AI リソース名は、次のように Neptune ML ステージに対応します。 + SageMaker AI `ProcessingJob` は、Neptune のデータ処理、モデルトレーニング、およびモデル変換ジョブで使用されます。 + SageMaker AI `HyperParameterTuningJob` は、Neptune のモデルトレーニングジョブによって使用されています。 + SageMaker AI `TrainingJob` は、Neptune のモデルトレーニングジョブによって使用されています。 + SageMaker AI `Endpoint` は Neptune 推論エンドポイントで使用されます。