# Inspect AI コンテナで評価する
<a name="nova-eval-inspect-ai-container"></a>

SageMaker Inspect AI コンテナは、SageMaker トレーニングジョブで LLM モデル評価を実行します。コンテナは [Inspect AI](https://inspect.ai-safety-institute.org.uk/) を使用して、Amazon Nova 1.0 (Micro、Lite、Pro) モデルや Amazon Nova 2.0 (Lite 2) モデルなど、SageMaker 推論エンドポイントまたは Amazon Bedrock にデプロイされたモデルの標準化された評価プロセスを提供します。

以前の[評価アプローチ](https://docs.aws.amazon.com//nova/latest/nova2-userguide/nova-model-evaluation.html) ([lighteval](https://github.com/huggingface/lighteval) に基づく) では、オフライン推論と評価ロジックが緊密に結合され、モデルの提供方法とテスト方法の柔軟性が制限されていました。Inspect AI コンテナは、評価ロジックを推論から完全に切り離します。

## 概要
<a name="nova-eval-container-overview"></a>

その他の主な利点には以下が含まれます:
+ **独自のベンチマークを導入する** – 評価タスクを Inspect AI 形式で記述し、一元化されたチームに依存せずにドメイン固有の評価タスクをプラグインしてオンボードします。
+ **さまざまな推論オプションで評価する** – SageMaker 推論 (既存のエンドポイントまたはその場で作成)、Amazon Bedrock、およびその他の今後追加される推論バックエンドに対応しています。
+ **反復処理を高速化** – インフラストラクチャを変更することなく、ベンチマーク開発から本番稼働用評価に移行します。以前は数日かかった新しいベンチマークのオンボーディングは数分で行われます。
+ **大規模な実行** – 1 つのジョブで複数のベンチマークを連鎖させ、検査評価ライブラリの標準ベンチマークを同じジョブ内の独自のカスタムタスクと組み合わせます。
+ **すべてのトレーニング手法に 1 つのエントリポイント** – モデルが SFT (SMTJ、SMHP)、CPT (SMHP)、または RFT (SMTJ、SMHP) でファインチューニングされたかどうかにかかわらず、コンテナが同じインターフェイスを介して評価します。特定のステップ (ステップ 500、ステップ 1000 など) で保存されたトレーニング中のチェックポイントの評価も、`model_s3_uri` をチェックポイントのパスに指定することでサポートされています。

### 仕組み
<a name="nova-eval-container-how-it-works"></a>

コンテナには 2 つの入力を指定します。

1. 推論プロバイダー、ベンチマーク、評価パラメータを定義する YAML 設定ファイル (レシピ)

1. Amazon S3 にアップロードされたベンチマークファイル (`@task` デコレータ付きの Python スクリプト)

コンテナは、エンドポイント管理、評価実行、結果収集を処理します。トレーニングジョブが完了すると、結果は指定された S3 出力場所に書き込まれます。

## コンテナイメージ
<a name="nova-eval-container-images"></a>

次の表に、AWS リージョン別の Inspect AI コンテナイメージ URI を示します。


| リージョン | コンテナイメージ URI | 
| --- | --- | 
| us-east-1 | 763104351884.dkr.ecr.us-east-1.amazonaws.com/sagemaker-inspect-ai:latest | 
| us-west-2 | 763104351884.dkr.ecr.us-west-2.amazonaws.com/sagemaker-inspect-ai:latest | 
| eu-west-2 | 763104351884.dkr.ecr.eu-west-2.amazonaws.com/sagemaker-inspect-ai:latest | 

## 前提条件
<a name="nova-eval-container-prerequisites"></a>

開始する前に、次のリソースとアクセスが準備されていることを確認してください。


| 要件 | 説明 | 
| --- | --- | 
| SageMaker アクセスを持つ AWS アカウント | SageMaker トレーニングジョブを作成するアクセス許可を持つアクティブな AWS アカウント | 
| S3 バケット | 評価レシピ、ベンチマークファイル、出力結果を保存するバケット | 
| IAM 実行ロール | SageMaker がリソースにアクセスするために引き受けることができるロール | 
| SageMaker 推論エンドポイントまたは Amazon Bedrock アクセス | 評価するモデルのデプロイされたモデルエンドポイントまたは Amazon Bedrock モデルアクセス | 
| AWS CLI または SageMaker Python SDK | トレーニングジョブを送信し、リソースを管理するツール | 
| キャパシティ予約 (大規模モデル) | 高速インスタンスを必要とするモデル (Nova Lite 2 の p5 など) については、 AWS サポートに連絡して SageMaker Inference または Amazon Bedrock の容量を予約してください | 

## ステップ 1: IAM アクセス許可の設定
<a name="nova-eval-container-step1"></a>

SageMaker トレーニングジョブは、指定した実行ロールで実行されます。このロールには、S3 からのベンチマークの読み取り、結果の書き込み、推論エンドポイントの呼び出し、CloudWatch ログの書き込みを行うためのアクセス許可が必要です。

**1.1 信頼ポリシーを作成する**

次を `trust_policy.json` として保存します。

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "sagemaker.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```

**1.2 ロールを作成する**

```
aws iam create-role \
  --role-name InspectLensEvalRole \
  --assume-role-policy-document file://trust_policy.json
```

**1.3 アクセス許可ポリシーをアタッチする**

以下を `eval_policy.json` として保存し、すべてのプレースホルダー値 (`REGION`、`ACCOUNT_ID`、バケット名) を自分の値に置き換えます。

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "S3ReadBenchmarkData",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::YOUR_BENCHMARK_BUCKET",
        "arn:aws:s3:::YOUR_BENCHMARK_BUCKET/*"
      ]
    },
    {
      "Sid": "S3WriteResults",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject", "s3:ListBucket"],
      "Resource": [
        "arn:aws:s3:::YOUR_RESULTS_BUCKET",
        "arn:aws:s3:::YOUR_RESULTS_BUCKET/*"
      ]
    },
    {
      "Sid": "SageMakerInvokeExistingEndpoint",
      "Effect": "Allow",
      "Action": [
        "sagemaker:InvokeEndpoint",
        "sagemaker:InvokeEndpointWithResponseStream",
        "sagemaker:DescribeEndpoint"
      ],
      "Resource": "arn:aws:sagemaker:REGION:ACCOUNT_ID:endpoint/*"
    },
    {
      "Sid": "BedrockInference",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": [
        "arn:aws:bedrock:REGION::foundation-model/*",
        "arn:aws:bedrock:REGION:ACCOUNT_ID:inference-profile/*",
        "arn:aws:bedrock:REGION:ACCOUNT_ID:provisioned-model/*",
        "arn:aws:bedrock:REGION:ACCOUNT_ID:custom-model/*",
        "arn:aws:bedrock:REGION:ACCOUNT_ID:imported-model/*",
        "arn:aws:bedrock:REGION:ACCOUNT_ID:custom-model-deployment/*"
      ]
    },
    {
      "Sid": "BedrockCustomModelAccess",
      "Effect": "Allow",
      "Action": [
        "bedrock:GetCustomModel",
        "bedrock:GetImportedModel",
        "bedrock:GetProvisionedModelThroughput",
        "bedrock:GetCustomModelDeployment",
        "bedrock:GetInferenceProfile"
      ],
      "Resource": [
        "arn:aws:bedrock:REGION:ACCOUNT_ID:custom-model/*",
        "arn:aws:bedrock:REGION:ACCOUNT_ID:imported-model/*",
        "arn:aws:bedrock:REGION:ACCOUNT_ID:provisioned-model/*",
        "arn:aws:bedrock:REGION:ACCOUNT_ID:custom-model-deployment/*",
        "arn:aws:bedrock:REGION:ACCOUNT_ID:inference-profile/*"
      ]
    },
    {
      "Sid": "SageMakerCreateEndpointLifecycle",
      "Effect": "Allow",
      "Action": [
        "sagemaker:CreateModel",
        "sagemaker:DescribeModel",
        "sagemaker:DeleteModel",
        "sagemaker:CreateEndpointConfig",
        "sagemaker:DescribeEndpointConfig",
        "sagemaker:DeleteEndpointConfig",
        "sagemaker:CreateEndpoint",
        "sagemaker:DescribeEndpoint",
        "sagemaker:DeleteEndpoint",
        "sagemaker:InvokeEndpoint",
        "sagemaker:InvokeEndpointWithResponseStream"
      ],
      "Resource": [
        "arn:aws:sagemaker:REGION:ACCOUNT_ID:model/inspectlens-*",
        "arn:aws:sagemaker:REGION:ACCOUNT_ID:endpoint/inspectlens-*",
        "arn:aws:sagemaker:REGION:ACCOUNT_ID:endpoint-config/inspectlens-*"
      ]
    },
    {
      "Sid": "ECRAuth",
      "Effect": "Allow",
      "Action": "ecr:GetAuthorizationToken",
      "Resource": "*"
    },
    {
      "Sid": "PassRoleToSageMaker",
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::ACCOUNT_ID:role/InspectLensEvalRole",
      "Condition": {
        "StringEquals": {
          "iam:PassedToService": "sagemaker.amazonaws.com"
        }
      }
    },
    {
      "Sid": "VPCNetworkingForEndpoint",
      "Effect": "Allow",
      "Action": [
        "ec2:CreateNetworkInterface",
        "ec2:CreateNetworkInterfacePermission",
        "ec2:DeleteNetworkInterface",
        "ec2:DeleteNetworkInterfacePermission",
        "ec2:DescribeNetworkInterfaces",
        "ec2:DescribeVpcs",
        "ec2:DescribeDhcpOptions",
        "ec2:DescribeSubnets",
        "ec2:DescribeSecurityGroups"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudWatchLogs",
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents",
        "logs:DescribeLogStreams"
      ],
      "Resource": [
        "arn:aws:logs:REGION:ACCOUNT_ID:log-group:/aws/sagemaker/TrainingJobs:*",
        "arn:aws:logs:REGION:ACCOUNT_ID:log-group:/aws/sagemaker/Endpoints/*"
      ]
    },
    {
      "Sid": "MLflowTrackingServer",
      "Effect": "Allow",
      "Action": [
        "sagemaker:DescribeMlflowTrackingServer",
        "sagemaker:CreatePresignedMlflowTrackingServerUrl"
      ],
      "Resource": "arn:aws:sagemaker:REGION:ACCOUNT_ID:mlflow-tracking-server/*"
    },
    {
      "Sid": "MLflowTrackingOperations",
      "Effect": "Allow",
      "Action": [
        "sagemaker-mlflow:AccessUI",
        "sagemaker-mlflow:CreateExperiment",
        "sagemaker-mlflow:GetExperiment",
        "sagemaker-mlflow:GetExperimentByName",
        "sagemaker-mlflow:SearchExperiments",
        "sagemaker-mlflow:CreateRun",
        "sagemaker-mlflow:GetRun",
        "sagemaker-mlflow:UpdateRun",
        "sagemaker-mlflow:SearchRuns",
        "sagemaker-mlflow:LogMetric",
        "sagemaker-mlflow:LogParam",
        "sagemaker-mlflow:LogBatch",
        "sagemaker-mlflow:SetTag",
        "sagemaker-mlflow:LogArtifact",
        "sagemaker-mlflow:ListArtifacts"
      ],
      "Resource": "arn:aws:sagemaker:REGION:ACCOUNT_ID:mlflow-tracking-server/*"
    },
    {
      "Sid": "KMSForVolumeEncryption",
      "Effect": "Allow",
      "Action": [
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:GenerateDataKey",
        "kms:CreateGrant",
        "kms:DescribeKey"
      ],
      "Resource": "arn:aws:kms:REGION:ACCOUNT_ID:key/*"
    }
  ]
}
```

ロールにポリシーをアタッチします。

```
aws iam put-role-policy \
  --role-name InspectLensEvalRole \
  --policy-name InspectLensEvalPolicy \
  --policy-document file://eval_policy.json
```

## ステップ 2: 評価レシピを記述する
<a name="nova-eval-container-step2"></a>

評価レシピは、コンテナが評価を実行する方法を定義する YAML 設定ファイルです。レシピは、推論プロバイダー、ベンチマーク、評価パラメータ、出力設定を指定します。

エンドツーエンドの例については、次のノートブックを参照してください。
+ [既存の SageMaker エンドポイントを評価する](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/inspect_eval_container/eval_sagemaker_endpoint.ipynb)
+ [マネージドエンドポイントで評価する](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/inspect_eval_container/eval_managed_endpoint.ipynb)
+ [Amazon Bedrock モデルを評価する](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/inspect_eval_container/eval_bedrock_model.ipynb)

**オプション A: 既存の SageMaker エンドポイントを評価する**

このオプションは、SageMaker 推論エンドポイントにモデルが既にデプロイされている場合に使用します。

```
inference_provider:
  sagemaker_endpoint:
    endpoint_name: "my-existing-endpoint"
    region: "us-east-1"

benchmarks:
  s3_path: "s3://your-bucket/benchmarks/my_benchmarks/"
  tasks:
    - name: mmlu

eval:
  max_connections: 10
  max_retries: 100
  timeout: 600

output:
  s3_path: "s3://your-bucket/eval-results/"
```

**オプション B: エンドポイントの作成、評価、クリーンアップ**

このオプションを使用して、コンテナに Amazon Nova ベースモデルまたはファインチューニングされたモデルをデプロイさせ、評価を実行し、エンドポイントを自動的に削除します。これは、1 回限りの評価の実行に推奨されるアプローチです。[Amazon Nova SageMaker 推論コンテナイメージ](https://docs.aws.amazon.com//nova/latest/userguide/nova-model-sagemaker-inference.html#nova-sagemaker-inference-container-images)のドキュメントから最新の SageMaker 推論コンテナを取得します。

```
inference_provider:
  sagemaker_endpoint:
    endpoint_name: null                 # null = create new endpoint
    model_s3_uri: "s3://your-bucket/models/nova-micro/"
    inference_image_uri: "708977205387.dkr.ecr.us-east-1.amazonaws.com/nova-inference-repo:SM-Inference-latest"
    instance_type: "ml.p5.48xlarge"
    instance_count: 1
    execution_role_arn: "arn:aws:iam::ACCOUNT_ID:role/InspectLensEvalRole"
    region: "us-east-1"
    context_length: "16000"
    max_concurrency: "32"
    cleanup_endpoint: true              # Auto-delete after eval

benchmarks:
  s3_path: "s3://your-bucket/benchmarks/my_benchmarks/"
  tasks:
    - name: mmlu_pro
    - name: arc_c
    - name: boolq

eval:
  fail_on_error: false
  decoding:
    temperature: 0.0
    top_p: 1.0
    top_k: -1
    max_tokens: 16000
    reasoning_effort: null
  max_connections: 16
  max_retries: 100
  timeout: 600
  extra_args:
    - "-M"
    - "completion_mode=True"
    - "--logprobs"
    - "--top-logprobs"
    - "5"

output:
  s3_path: "s3://your-bucket/eval-results/"
```

**`model_s3_uri` に関する注意:**
+ **Amazon Nova GA モデル (ベースチェックポイント)**: 例えば`s3://escrow-nova-model-708977205387-us-east-1/nova-lite-2/prod/` – SageMaker はアクセスを自動的に管理し、追加の S3 アクセス許可は必要ありません。
+ **カスタマイズされた Amazon Nova モデル (トレーニング後のチェックポイント)**: `s3://customer-escrow-ACCOUNT_ID-SUFFIX/YOUR_RUN_NAME/outputs/checkpoints/step_N/` – これはトレーニングジョブ出力からのエスクローバケットパスです。

**オプション C: Amazon Bedrock で評価する**

このオプションを使用すると、エンドポイントを管理することなく Amazon Bedrock で利用可能なモデルを評価できます。

```
inference_provider:
  bedrock:
    model_id: amazon.nova-pro-v1:0
    region: us-east-1

benchmarks:
  - name: mmlu
    path: benchmarks/mmlu_pro.py
    limit: 100

eval:
  fail_on_error: false
  decoding:
    temperature: 0.0
    top_p: 1.0
    top_k: -1
    max_tokens: 8192
    reasoning_effort: null
  max_connections: 10
  max_retries: 50
  timeout: 600
  extra_args:
    - "--display"
    - "plain"

output:
  s3_path: s3://your-bucket/eval/output/
```

**ベンチマーク設定**

`benchmarks` セクションでは、実行する評価タスクを定義します。1 つのジョブで複数のベンチマークを連鎖できます。


| フィールド | 必須 | デフォルト | [Description] (説明) | 
| --- | --- | --- | --- | 
| name | はい | — | ベンチマーク実行のわかりやすい名前 | 
| path | はい | — | S3 ベンチマークディレクトリ内のベンチマーク Python ファイルへの相対パス | 
| limit | いいえ | なし (すべてのサンプル) | 評価するサンプルの最大数。フル実行前のテストに使用します。 | 
| epochs | いいえ | 1 | 統計的有意性のために評価を繰り返す回数 | 
| task\_args | いいえ | — | 引数としてベンチマークタスク関数に渡されるキーと値のペア | 

**評価設定**

`eval` セクションでは、コンテナが評価を実行する方法を制御します。


| [Parameter] (パラメータ) | 必須 | デフォルト | 説明 | 
| --- | --- | --- | --- | 
| fail\_on\_error | いいえ | false | サンプルが失敗した場合、評価を停止します。厳密な検証のために true に設定します。 | 
| max\_connections | いいえ | 10 | 推論エンドポイントへの並列リクエストの数 | 
| max\_retries | いいえ | 3 | 失敗した推論リクエストの再試行回数 | 
| timeout | いいえ | 600 | 推論呼び出しごとのリクエストのタイムアウト (秒) | 
| extra\_args | いいえ | — | Inspect AI 評価コマンドに直接渡される追加のキーと値のペア | 

**デコードパラメータ**

`eval.decoding` セクション内でモデルデコードパラメータを設定します。


| [Parameter] (パラメータ) | 必須 | デフォルト | 説明 | 
| --- | --- | --- | --- | 
| temperature | いいえ | 0.0 | 生成時のランダム性を制御します。決定的で再現可能なベンチマーク結果に 0.0 を使用します。 | 
| top\_p | いいえ | 1.0 | Nucleus サンプリングしきい値。1.0 は制限がないことを意味します。 | 
| top\_k | いいえ | -1 | 単語の選択を上位 K の最も可能性の高いトークンに制限します。-1 はこのフィルターを無効にします。 | 
| max\_tokens | いいえ | 8192 | レスポンスごとに生成するトークンの最大数。長い推論チェーンを必要とするベンチマークの場合は増やします。 | 
| reasoning\_effort | いいえ | null | この機能をサポートするモデルの推論深度を制御します (例: 拡張思考を備えた Amazon Nova モデル)。オプション: low、high、または null を無効にします。 | 

**出力設定**

`output` セクションでは、評価結果の保存場所と保存方法を定義します。


| フィールド | 必須 | デフォルト | [Description] (説明) | 
| --- | --- | --- | --- | 
| s3\_path | はい | — | 評価結果が書き込まれる S3 URI | 
| output\_format | いいえ | 評価 | 結果ファイルの形式。オプションについては、次の表を参照してください。 | 

以下の出力形式が利用可能です。


| 形式 | 説明 | 
| --- | --- | 
| eval | Native Inspect AI 形式。インタラクティブ分析のために inspect view と互換性があります。 | 
| csv | カンマ区切り値。スプレッドシート分析とデータパイプラインに適しています。 | 
| jsonl | JSON Lines 形式。ストリーミング処理用に 1 行に 1 つの JSON オブジェクト。 | 
| json | 標準 JSON 形式。完全な結果を 1 つの構造化ファイルにまとめます。 | 

**MLflow 設定**

必要に応じて、MLflow 追跡サーバーに評価メトリクスを記録できます。レシピに `tracking` セクションを追加します:

```
tracking:
  mlflow_tracking_arn: null       # ARN of SageMaker MLflow tracking server
  mlflow_experiment_name: "inspectlens" # experiment name
  mlflow_tracing: true          # log full request/response traces
  mlflow_log_artifacts: true       # upload .eval files to MLflow
```


| フィールド | 必須 | デフォルト | 説明 | 
| --- | --- | --- | --- | 
| mlflow\_tracking\_arn | いいえ | null | SageMaker MLflow 追跡サーバーの ARN。これを設定すると、MLflow ログ記録が有効になります。省略するか、null に設定して無効にします。 | 
| mlflow\_experiment\_name | いいえ | インスペクトレンズ | 実行をログに記録する MLflow 実験の名前。 | 
| mlflow\_tracing | なし | true | true の場合、各サンプルの完全なリクエスト/レスポンストレースを記録します。 | 
| mlflow\_log\_artifacts | なし | true | true の場合、.eval ログファイルを MLflow アーティファクトとしてアップロードします。 | 

**完全なレシピリファレンス**

次の例は、使用可能なすべての設定オプションを含む完全なレシピを示しています。

```
inference_provider:
  sagemaker_endpoint:
    endpoint_name: my-nova-endpoint
    model_s3_uri: s3://your-bucket/models/my-model/
    inference_image_uri: "708977205387.dkr.ecr.us-east-1.amazonaws.com/nova-inference-repo:SM-Inference-latest"
    instance_type: ml.g5.12xlarge
    cleanup_endpoint: true
    region: us-west-2

benchmarks:
  - name: mmlu
    path: benchmarks/mmlu_pro.py
    limit: 100
    epochs: 3
    task_args:
      subject: math
  - name: truthfulqa
    path: benchmarks/truthfulqa.py
    limit: 50

eval:
  fail_on_error: false
  decoding:
    temperature: 0.0
    top_p: 1.0
    top_k: -1
    max_tokens: 8192
    reasoning_effort: null
  max_connections: 256
  max_retries: 50
  timeout: 600
  extra_args:
    - "--display"
    - "plain"

output:
  s3_path: s3://your-bucket/eval/output/
  output_format: eval

tracking:
  mlflow_tracking_arn: "arn:aws:sagemaker:us-west-2:123456789012:mlflow-tracking-server/my-server"
  mlflow_experiment_name: "inspectlens"
  mlflow_tracing: true
  mlflow_log_artifacts: true
```

## ステップ 3: ベンチマークファイルを準備する
<a name="nova-eval-container-step3"></a>

ベンチマークは、Inspect AI `@task` デコレータを使用して評価タスクを定義する Python ファイルです。[inspect-evals リポジトリ](https://github.com/UKGovernmentBEIS/inspect_evals)には、128 以上のすぐに使えるベンチマークが用意されています。または、独自のベンチマークを記述することもできます。

**ベンチマークの例**

次の例は、HuggingFace データセットの複数選択肢のパフォーマンスを評価する最小限のベンチマークを示しています。

```
from inspect_ai import task, Task
from inspect_ai.dataset import hf_dataset
from inspect_ai.scorer import choice
from inspect_ai.solver import multiple_choice


@task
def my_benchmark():
    return Task(
        dataset=hf_dataset(
            path="cais/mmlu",
            name="abstract_algebra",
            split="test",
        ),
        solver=multiple_choice(),
        scorer=choice(),
    )
```

**依存関係**

ベンチマークに追加の依存関係が必要な場合は、同じ S3 ディレクトリに `pyproject.toml` または `requirements.txt` を含めます。

```
[project]
name = "my-benchmark"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "datasets>=2.14.0",
]
```

**インストール済みのパッケージ**

コンテナには、次のパッケージが含まれています。これらを `pyproject.toml` に一覧表示する必要はありません。


| パッケージ | バージョン | 
| --- | --- | 
| Python | 3.12 | 
| inspect-ai | 0.3.220 | 
| boto3 | 1.40.61 | 
| aioboto3 | 15.5.0 | 
| openai | 2.36.0 | 
| mlflow | 3.12.0 | 
| pyyaml | 6.0.3 | 

**タスクの選択**

レシピの `tasks` フィールドは、ベンチマークファイル内で実行するタスクを制御します。


| 設定 | 例 | 行動 | 
| --- | --- | --- | 
| 空の tasks | tasks: [] | ベンチマークファイルで定義されたすべてのタスクを実行します | 
| 名前フィルター | tasks: ["algebra"] | サブ文字列「代数」を含む名前のタスクを実行します | 
| limit | limit: 50 | タスクごとに評価されるサンプル数の上限を設定します | 
| epochs | epochs: 3 | 評価を複数回繰り返して分散を測定します | 

## ステップ 4: S3 構造を準備する
<a name="nova-eval-container-step4"></a>

次の構造は、設定、ベンチマーク、結果を整理するための推奨事項です。コンテナを任意の S3 の場所に指定することができます。構造自体は必要ありません。

```
s3://your-bucket/
├── config/
│   └── inspect_config.yaml       # Your eval recipe
├── benchmarks/
│   └── my_benchmarks/            # Your benchmark Python files
│       ├── pyproject.toml        # Optional: benchmark dependencies
│       ├── my_task.py            # @task decorated functions
│       └── _helpers.py           # Shared utilities
└── output/                       # Results written here
```

ファイルを S3 にアップロードします。

```
# Upload benchmark files
aws s3 cp my_benchmarks/ s3://your-bucket/benchmarks/my_benchmarks/ --recursive

# Upload your eval recipe
aws s3 cp inspect_config.yaml s3://your-bucket/config/inspect_config.yaml
```

## ステップ 5: トレーニングジョブを送信する
<a name="nova-eval-container-step5"></a>

SageMaker トレーニングジョブを送信して評価を実行します。AWS CLI または SageMaker Python SDK を使用できます。

**オプション A: AWS CLI**

```
aws sagemaker create-training-job \
    --training-job-name inspect-eval-$(date +%Y%m%d-%H%M%S) \
    --algorithm-specification \
        TrainingImage=763104351884.dkr.ecr.us-east-1.amazonaws.com/sagemaker-inspect-ai:latest,TrainingInputMode=File \
    --role-arn arn:aws:iam::123456789012:role/SageMakerInspectAIRole \
    --resource-config \
        InstanceType=ml.m5.large,InstanceCount=1,VolumeSizeInGB=30 \
    --stopping-condition MaxRuntimeInSeconds=86400 \
    --input-data-config '[
        {
            "ChannelName": "config",
            "DataSource": {
                "S3DataSource": {
                    "S3DataType": "S3Prefix",
                    "S3Uri": "s3://your-bucket/eval/config/",
                    "S3DataDistributionType": "FullyReplicated"
                }
            }
        }
    ]' \
    --output-data-config S3OutputPath=s3://your-bucket/eval/output/ \
    --region us-west-2
```

**オプション B: SageMaker Python SDK V3**

```
from sagemaker.train import ModelTrainer
from sagemaker.train.configs import InputData, Compute
from sagemaker.core.shapes.shapes import StoppingCondition, OutputDataConfig

trainer = ModelTrainer(
    training_image="763104351884.dkr.ecr.us-east-1.amazonaws.com/sagemaker-inspect-ai:latest",
    compute=Compute(
        instance_type="ml.m5.large",
        instance_count=1,
        volume_size_in_gb=30,
    ),
    output_data_config=OutputDataConfig(
        s3_output_path="s3://your-bucket/eval/output/"
    ),
    role="arn:aws:iam::123456789012:role/SageMakerInspectAIRole",
    stopping_condition=StoppingCondition(max_runtime_in_seconds=86400),
)

trainer.train(
    input_data_config=[
        InputData(
            channel_name="config",
            data_source="s3://your-bucket/eval/config/",
        )
    ]
)
```

**主要パラメータ**


| パラメータ | 値 | 説明 | 
| --- | --- | --- | 
| TrainingImage | 763104351884.dkr.ecr.us-east-1.amazonaws.com/sagemaker-inspect-ai:latest | Inspect AI コンテナイメージ | 
| InstanceType | ml.m5.large | オーケストレーターインスタンスタイプ (推論インスタンスではない) | 
| VolumeSizeInGB | 30 | ベンチマークデータとログのストレージ | 
| MaxRuntimeInSeconds | 86400 | 最大ジョブ期間 (24 時間) | 
| ChannelName | config | レシピファイルとベンチマークファイルを含む入力チャネル | 

**オーケストレーターインスタンスタイプのガイダンス**

トレーニングジョブインスタンスは、モデル推論ではなく、評価オーケストレーションロジックを実行します。評価ワークロードに基づいてインスタンスタイプを選択します。


| インスタンスタイプ | ユースケース | ガイダンス | 
| --- | --- | --- | 
| ml.m5.large | 推奨されるデフォルト設定 | 中程度の並列処理を伴うほとんどの評価ワークロードには十分です | 
| ml.m5.4xlarge | 大規模なベンチマークスイート | max\_connections 値の高いベンチマークを多数実行する場合に使用します | 
| ml.c5.large | コスト重視 | 並列処理の少ない簡単な評価のための低コストな代替方法 | 

**環境変数**

認証または設定のために環境変数をコンテナに渡すことができます。`--environment` パラメータを AWS CLI コマンドに追加します:

```
aws sagemaker create-training-job \
    ...
    --environment '{
        "HF_TOKEN": "hf_your_token_here",
        "HF_HUB_DOWNLOAD_TIMEOUT": "300"
    }'
```

## ステップ 6: ジョブをモニタリングする
<a name="nova-eval-container-step6"></a>

トレーニングジョブを送信したら、AWS CLI または CloudWatch Logs を使用して進捗状況をモニタリングできます。

**ジョブステータスの確認**

```
aws sagemaker describe-training-job \
    --training-job-name your-job-name \
    --query "TrainingJobStatus" \
    --output text
```

**ログのストリーミング**

```
aws logs tail /aws/sagemaker/TrainingJobs \
    --log-stream-name-prefix your-job-name \
    --follow
```

**ログで予想されること**

コンテナログには、次のステージの進行状況が表示されます。

1. **起動** – コンテナの初期化と設定の検証

1. **ベンチマークのダウンロード** – ベンチマークファイルのダウンロードと依存関係のインストール

1. **エンドポイントのセットアップ** – 推論エンドポイントの作成または接続

1. **評価** – 進行状況インジケータを使用したベンチマークタスクの実行

1. **結果のアップロード** – S3 への結果の書き込みとオプションで MLflow へのログ記録

1. **クリーンアップ** – `cleanup_endpoint: true` の場合には、一時的なエンドポイントの削除

**推定タイムライン**


| ステージ | 推定期間 | 
| --- | --- | 
| コンテナのスタートアップ | 2～5 分 | 
| エンドポイントの作成 (該当する場合) | 15～30 分 | 
| 評価 | ベンチマークサイズとモデルレイテンシーによって異なる | 
| クリーンアップ | 1～2 分 | 

## ステップ 7: 結果を表示および解釈する
<a name="nova-eval-container-step7"></a>

ジョブが完了したら、評価結果を表示します。

**Inspect AI で表示**

Inspect AI ビューワーを使用して、S3 から直接結果をインタラクティブに探索します。

```
inspect view --log-dir s3://your-bucket/eval-results/
```

このコマンドは、スコアの参照、個々のサンプルの表示、実行の比較を行うローカルウェブインターフェイスを開きます。

**ダウンロードして共有する**

結果をローカルでダウンロードするには:

```
aws s3 cp s3://your-bucket/eval/output/ ./results/ --recursive

INSPECT_LOG_DIR=./results inspect view
```

**VS Code 拡張機能**

[Inspect AI VS Code 拡張機能](https://inspect.aisi.org.uk/vscode.html)を使用すると、評価ログを最初にダウンロードすることなく S3 から直接参照できます。

1. VS Code マーケットプレイスから拡張機能をインストールする (「Inspect AI」を検索する)

1. Inspect Activity Bar で、[ログ] ペインを見つけ、フォルダアイコンを選択します

1. S3 パスを入力します: `s3://your-bucket/eval-results/`

**出力構造**

各評価では、以下のセクションを含む `.eval` ログファイルが生成されます。
+ `results.scores` – 各メトリクスの集計スコア
+ `samples` – 入力、出力、スコアを含む個々の評価サンプル
+ `stats` – トークンの使用状況とレイテンシーを含むランタイム統計
+ `eval.config` – 評価の実行に使用される設定

**MLflow で結果を表示する (オプション)**

レシピで MLflow を設定した場合は、署名付き URL を生成して追跡サーバーにアクセスします。

```
aws sagemaker create-presigned-mlflow-tracking-server-url \
    --tracking-server-name my-server \
    --region us-west-2
```

ブラウザで返された URL を開き、メトリクスの表示、実行の比較、評価全体の傾向の分析を行います。

## 使用可能なベンチマーク
<a name="nova-eval-container-benchmarks"></a>

Inspect AI コンテナは、Inspect AI タスク形式で記述されたベンチマークで動作します。[inspect-evals リポジトリ](https://github.com/UKGovernmentBEIS/inspect_evals)には、推論、知識、コーディング、安全性などの分野をカバーする 128 以上のすぐに使えるベンチマークが用意されています。

独自のベンチマークを記述するには、「[Inspect AI タスク作成ドキュメント](https://inspect.aisi.org.uk/tasks.html)」を参照してください。inspect-evals でまだ利用できないパブリックベンチマークが見つかった場合は、[AI アシスタントのオンボーディングプロンプト](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/ai_assisted_benchmark_creation.md)を使用して、それを Inspect AI 形式に変換できます。

## エージェント評価
<a name="nova-eval-container-agentic"></a>

エージェントベンチマークは、ツールの使用、計画、反復的な推論を必要とする複数ステップのタスクを完了するモデルの能力をテストします。これらの評価は、モデルがツールを呼び出し、結果を解釈し、次のアクションを決定する必要がある実際のシナリオをシミュレートします。

**エンドポイントの要件**

エージェント評価には、次の機能をサポートするエンドポイントが必要です:
+ **ツール呼び出し** – エンドポイントは、モデルが評価中にツールを呼び出すことができるように、関数呼び出しをサポートする必要があります
+ **大きなコンテキストサイズ** – ツール結果を含むマルチターンの会話には、会話履歴を維持するために十分なコンテキスト長が必要です

**SageMaker 推論のエンドポイント設定**

エージェント評価に SageMaker 推論エンドポイントを使用する場合は、エンドポイントで次の環境変数を設定します。


| 環境変数 | 値 | 説明 | 
| --- | --- | --- | 
| ENABLE\_TOOL\_CALLING | True | 推論エンドポイントでツール呼び出しのサポートをアクティブ化します | 
| CONTEXT\_LENGTH | マルチターンには十分です | ツール結果によるマルチターン会話に対応するのに十分な大きさの値に設定します | 

SageMaker 推論で Amazon Nova エンドポイントを設定する方法については、「[SageMaker で Amazon Nova モデルをデプロイする](https://docs.aws.amazon.com//nova/latest/userguide/deploy-sagemaker.html)」を参照してください。コンテナの機能と設定の詳細については、「[コンテナの機能](https://docs.aws.amazon.com//nova/latest/userguide/container-features.html)」を参照してください。

**Amazon Bedrock エンドポイント**

Amazon Bedrock エンドポイントの場合、ツール呼び出しは互換性のあるモデルでネイティブにサポートされています。詳細については、「[Amazon Bedrock でのツールの使用](https://docs.aws.amazon.com//bedrock/latest/userguide/tool-use.html)」を参照してください。

**エージェント評価の開始方法**

エージェント評価を実行するには、次の前提条件を満たしてください。

1. ツール呼び出しを有効にしてエンドポイントをデプロイする

1. [inspect-evals リポジトリ](https://github.com/UKGovernmentBEIS/inspect_evals)からエージェントベンチマークを選択する (ツール呼び出しソルバーを使用するベンチマークを探す)

1. マルチターンインタラクションに適切な `timeout` 値と `max_tokens` 値を使用してレシピを設定する

**Amazon Bedrock エンドポイント**
+ 完全なセットアップとデプロイについては、「[Amazon Bedrock エンドポイント](https://docs.aws.amazon.com//bedrock/latest/userguide/endpoints.html)」を参照してください。
+ ツール呼び出しのサポートについては、「[Amazon Bedrock でのツールの使用](https://docs.aws.amazon.com//bedrock/latest/userguide/tool-use.html)」の「クライアント側のツール呼び出し」セクションを参照してください。

**サンプルノートブック**

次のノートブックは、Inspect AI コンテナを使用してツール呼び出しエージェントベンチマークを実行する方法を示しています。
+ [tau-bench (ジョブベース)](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/inspect_eval_container/eval_tau_bench.ipynb) – Inspect AI コンテナを使用して、カスタマーサービスタスクに関するツールで強化された推論を評価する

Docker サンドボックスを必要とするエージェントベンチマークの場合は、Inspect AI SDK を使用します。
+ [Inspect AI SDK を使用した SWE-bench](https://github.com/aws-samples/amazon-nova-samples/blob/main/customization/sagemaker-inspect-ai/local_inspect_sdk/eval_swe_bench.ipynb) – Docker サンドボックスを使用してソフトウェアエンジニアリング機能を評価する

**重要**  
Docker サンドボックス (SWE-bench など) を必要とするエージェントベンチマークは、Inspect AI コンテナエクスペリエンスではサポートされていません。SageMaker トレーニングジョブ環境は、Docker-in-Docker 機能を提供しません。これらのベンチマークを実行するには、Docker アクセスが可能なコンピューティング環境 (Amazon EC2 インスタンスや Docker がインストールされている SageMaker ノートブックなど) で [Inspect AI SDK](nova-eval-on-sagemaker-inference.md) を使用します。

## トラブルシューティング
<a name="nova-eval-container-troubleshooting"></a>

このセクションでは、Inspect AI コンテナで評価を実行する際の一般的な問題の解決策を示します。

**高速イテレーションのヒント**

SageMaker トレーニングジョブを送信する前に、Inspect AI SDK を使用してベンチマークをローカルでテストします。ローカルマシンで `inspect eval my_benchmark.py` を実行して、大規模な実行前にタスク定義、依存関係、スコアリングロジックを検証します。

**InsufficientInstanceCapacity エラー**

このエラーは、AWS がリージョンでリクエストされたインスタンスタイプに十分な容量を持っていない場合に発生します。
+ 別のインスタンスタイプを試すか、別の AWS リージョンでジョブを送信します
+ 別のインスタンスタイプを使用する (`ml.m5.large` の代わりに `ml.m5.xlarge` など)
+ 数分後にリクエストを再試行する

**AccessDenied エラー**

トレーニングジョブがアクセス拒否エラーで失敗した場合、以下を確認します。
+ ジョブ設定のロール ARN が正しい
+ 信頼ポリシーにより、`sagemaker.amazonaws.com`がロールを引き受けることができます。
+ ユーザーまたはロールに実行ロールの `iam:PassRole` アクセス許可がある
+ 実行ロールには、S3 バケット、推論エンドポイント、または Amazon Bedrock モデルにアクセスするアクセス許可があります

**エンドポイントの作成失敗**

エンドポイントの自動作成で `cleanup_endpoint: true` を使用する場合、次の問題が発生する可能性があります。


| エラー | 解決策 | 
| --- | --- | 
| ResourceLimitExceeded | リージョンの推論インスタンスタイプのサービスクォータの引き上げをリクエストする | 
| OutOfMemoryError | より大きな推論インスタンスタイプを使用するか、モデルサイズを縮小する | 
| 誤った model\_s3\_uri | S3 パスが有効なモデルアーティファクトディレクトリを指していることを確認する | 
| 誤った推論イメージ URI | イメージ URI がリージョンとモデルフレームワークに対して正しいことを確認する | 
| エンドポイントが「作成中」でスタックする | エンドポイントの CloudWatch Logs を確認します。モデルがヘルスチェックに失敗する可能性があります。エンドポイントにさらに時間が必要な場合は、MaxRuntimeInSeconds を増やします。 | 

**HuggingFace ダウンロードタイムアウト**

HuggingFace Hub からデータセットをダウンロードするベンチマークがタイムアウトした場合、`HF_HUB_DOWNLOAD_TIMEOUT` 環境変数をより高い値 (秒単位) に設定します。

```
--environment '{"HF_HUB_DOWNLOAD_TIMEOUT": "600"}'
```

**ジョブは強制終了されましたが、エンドポイントはまだ実行中です**

クリーンアップが完了する前にトレーニングジョブが中断された場合、推論エンドポイントはアクティブのままになる可能性があります。継続的な料金が発生しないように、エンドポイントを手動で削除します。

```
# List endpoints to find the orphaned one
aws sagemaker list-endpoints \
    --name-contains inspect \
    --query "Endpoints[].EndpointName" \
    --output table

# Delete the endpoint
aws sagemaker delete-endpoint \
    --endpoint-name your-endpoint-name

# Delete the endpoint configuration
aws sagemaker delete-endpoint-config \
    --endpoint-config-name your-endpoint-name

# Delete the model
aws sagemaker delete-model \
    --model-name your-endpoint-name
```

**ベンチマークの依存関係の競合**

プリインストールされたパッケージとの依存関係の競合が原因でベンチマークが失敗した場合、明示的なバージョン制約を使用してベンチマークディレクトリに `pyproject.toml` を作成します。コンテナは、競合を最小限に抑えるためにベンチマークの依存関係を個別にインストールします。

**評価スコアが間違っているようです**

評価スコアが予期せず低い、または一貫性がない場合は、レシピで次の設定を確認してください。
+ **temperature** – 決定的で再現可能な結果を得るには、`0.0` に設定します
+ **max\_tokens** – モデルがレスポンスを完了するのに十分な大きさの値であることを確認します。
+ **completion\_mode** – ベース (非チャット) モデルの場合、チャット形式の代わりに完了形式のプロンプトを使用するようにレシピで `completion_mode: true` を設定します

## データプライバシー
<a name="nova-eval-container-data-privacy"></a>

評価データは、使用する推論プロバイダーに応じて異なる方法で処理されます。

**SageMaker エンドポイント**

SageMaker 推論エンドポイントを使用する場合、すべてのデータは AWS アカウント 内に保持されます。評価プロンプトとモデルレスポンスはアカウント外に送信されず、AWS サービスの改善には使用されません。オプトアウトポリシーは必要ありません。

**Amazon Bedrock**

推論プロバイダーとして Amazon Bedrock を使用する場合、データは AWS AI サービスのオプトアウトポリシーの対象となります。AWS AI サービスの改善にデータが使用されないようにするには、AWS Organizations レベルでオプトアウトポリシーを有効にします。詳細については、「[AI サービスのオプトアウトポリシー](https://docs.aws.amazon.com//organizations/latest/userguide/orgs_manage_policies_ai-opt-out.html)」を参照してください。


| 推論プロバイダー | オプトアウトが必要 | 詳細 | 
| --- | --- | --- | 
| SageMaker エンドポイント | いいえ | データはアカウントに保持されます。AI オプトアウトポリシーの対象外です。 | 
| Amazon Bedrock | はい | Organizations レベルで AWS AI サービスのオプトアウトポリシーを有効にして、サービス改善のためのデータ使用を防止します。 |