# 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) 및 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 및 향후 제공될 더 많은 추론 백엔드에서 작동합니다.
+ **더 빠른 반복** - 인프라를 변경하지 않고도 벤치마크 개발에서 프로덕션 평가로 이동합니다. 이전에는 며칠이 걸리던 새로운 벤치마크 온보딩이 몇 분이면 됩니다.
+ **대규모 실행** - 하나의 작업에서 여러 벤치마크를 연결하고, inspect-evals 라이브러리의 표준 벤치마크를 동일한 작업의 자체 사용자 지정 태스크와 혼합합니다.
+ **모든 훈련 기법에 대한 하나의 진입점** - 모델이 SFT(SMTJ, SMHP), CPT(SMHP) 또는 RFT(SMTJ, SMHP)로 미세 조정되었는지에 관계없이 컨테이너는 동일한 인터페이스를 통해 모델을 평가합니다. 체크포인트 경로에서 `model_s3_uri`를 가리키면 특정 단계에 저장된 중간 훈련 체크포인트 평가도 지원됩니다(예: 500단계, 1,000단계).

### 작동 방식
<a name="nova-eval-container-how-it-works"></a>

사용자가 컨테이너에 다음과 같은 두 가지 입력을 제공합니다.

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 Support에 문의하여 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 기본 모델 또는 미세 조정 모델을 배포하고 평가를 실행하며 엔드포인트를 자동으로 분리하게 하려면 이 옵션을 사용합니다. 일회성 평가 실행에 권장되는 접근 방식입니다. [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` 섹션에서는 실행할 평가 태스크를 정의합니다. 단일 작업에서 여러 벤치마크를 연결할 수 있습니다.


| Field | 필수 | 기본값 | 설명 | 
| --- | --- | --- | --- | 
| name | 예 | — | 벤치마크 실행을 설명하는 이름 | 
| path | 예 | — | S3 벤치마크 디렉터리에서 벤치마크 Python 파일에 대한 상대 경로 | 
| limit | 아니요 | 없음(모든 샘플) | 평가할 최대 샘플 수입니다. 전체 실행 전에 테스트에 대해 사용합니다. | 
| epochs | 아니요 | 1 | 통계적 유의성에 대한 평가를 반복하는 횟수 | 
| task\_args | 아니요 | — | 벤치마크 태스크 함수에 인수로 전달되는 키 값 페어 | 

**평가 구성**

`eval` 섹션에서는 컨테이너가 평가를 실행하는 방법을 제어합니다.


| 파라미터 | 필수 | 기본값 | 설명 | 
| --- | --- | --- | --- | 
| fail\_on\_error | 아니요 | false | 샘플이 실패하면 평가를 중지합니다. 엄격한 검증 시 true로 설정합니다. | 
| max\_connections | 아니요 | 10 | 추론 엔드포인트에 대한 병렬 요청 수 | 
| max\_retries | 아니요 | 3 | 실패한 추론 요청에 대한 재시도 횟수 | 
| timeout | 아니요 | 600 | 각 추론 직접 호출에 대한 요청 제한 시간(초) | 
| extra\_args | 아니요 | — | Inspect AI 평가 명령에 직접 전달되는 추가 키 값 페어 | 

**디코딩 파라미터**

`eval.decoding` 섹션 내에서 모델 디코딩 파라미터를 구성합니다.


| 파라미터 | 필수 | 기본값 | 설명 | 
| --- | --- | --- | --- | 
| 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` 섹션에서는 평가 결과가 저장되는 위치와 방법을 정의합니다.


| Field | 필수 | 기본값 | 설명 | 
| --- | --- | --- | --- | 
| s3\_path | 예 | — | 평가 결과를 쓰는 S3 URI | 
| output\_format | 아니요 | eval | 결과 파일의 형식입니다. 옵션은 다음 표를 참조하세요. | 

다음 출력 형식을 사용할 수 있습니다.


| 형식 | 설명 | 
| --- | --- | 
| eval | 네이티브 Inspect AI 형식입니다. 대화형 분석의 경우 inspect view와 호환됩니다. | 
| csv | 쉼표로 구분된 값입니다. 스프레드시트 분석 및 데이터 파이프라인에 적합합니다. | 
| jsonl | JSON Lines 형식입니다. 스트리밍 처리를 위한 라인당 하나의 JSON 객체입니다. | 
| json | 표준 JSON 형식입니다. 단일 정형 파일의 전체 결과입니다. | 

**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
```


| Field | 필수 | 기본값 | 설명 | 
| --- | --- | --- | --- | 
| mlflow\_tracking\_arn | 아니요 | null | SageMaker MLflow 추적 서버의 ARN입니다. 이 옵션을 설정하면 MLflow 로깅을 활성화합니다. 생략하거나 null로 설정하여 비활성화합니다. | 
| mlflow\_experiment\_name | 아니요 | inspectlens | 실행을 기록할 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"] | 이름에 '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 코드 확장**

[Inspect AI VS Code 확장](https://inspect.aisi.org.uk/vscode.html)을 사용하면 먼저 다운로드하지 않고도 S3에서 직접 평가 로그를 찾아볼 수 있습니다.

1. VS Code 마켓플레이스에서 확장 프로그램 설치('Inspect AI' 검색)

1. Inspect 활동 표시줄에서 로그 창을 찾아 폴더 아이콘 선택

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 엔드포인트의 경우 호환되는 모델에 대해 도구 직접 호출은 기본적으로 지원됩니다. 자세한 내용은 [Tool use with 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)를 참조하세요.
+ 도구 직접 호출 지원은 [Tool use with 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 액세스 권한이 있는 컴퓨팅 환경에서 [Inspect AI SDK](nova-eval-on-sagemaker-inference.md)(예: Docker가 설치된 Amazon EC2 인스턴스 또는 SageMaker 노트북)를 사용합니다.

## 문제 해결
<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`를 사용하는 경우 다음과 같은 문제가 발생할 수 있습니다.


| 오류 | Solution | 
| --- | --- | 
| 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 services opt-out policies](https://docs.aws.amazon.com//organizations/latest/userguide/orgs_manage_policies_ai-opt-out.html)를 참조하세요.


| 추론 공급자 | 옵트아웃이 필요함 | 세부 정보 | 
| --- | --- | --- | 
| SageMaker 엔드포인트 | 아니요 | 데이터는 계정에서 유지됩니다. AI 옵트아웃 정책에 포함되지 않습니다. | 
| Amazon Bedrock | 예 | 데이터가 서비스를 개선하는 데 사용되지 않도록 Organizations 수준에서 AWS AI 서비스 옵트아웃 정책을 활성화합니다. |