기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# SageMaker Clarify 처리 작업 구성
SageMaker Clative를 사용하여 데이터 및 모델의 편향 및 설명 가능성을 분석하려면 반드시 SageMaker Clalify 처리 작업을 구성해야 합니다. 이 가이드는 처리 작업을 위한 입력 데이터세트 이름, 분석 구성 파일 이름 및 출력 위치를 지정하는 방법을 보여줍니다. 처리 컨테이너, 작업 입력, 출력, 리소스 및 기타 매개변수를 구성하는 데는 두 가지 옵션이 있습니다. SageMaker AI `CreateProcessingJob` API를 사용하거나, 또는 SageMaker AI Python SDK API `SageMaker ClarifyProcessor`를 사용할 수도 있습니다.
모든 처리 작업에 공통적인 매개변수에 대한 자세한 내용은 [Amazon SageMaker API Reference](https://docs.aws.amazon.com/sagemaker/latest/APIReference/Welcome.html?icmpid=docs_sagemaker_lp)를 참조하세요.
## SageMaker API를 사용한 SageMaker Clarify 처리 작업 구성
다음 지침은 `CreateProcessingJob`API를 사용하여 SageMaker Calify용 구성의 각 부분을 제공하는 방법을 보여줍니다.
1. 다음 코드 예제와 같이 SageMaker Clarify 컨테이너 이미지의 통합 자원 식별자(URI)를 `AppSpecification`매개변수 내에 입력합니다.
```
{
"ImageUri": "the-clarify-container-image-uri"
}
```
**참고**
URI는 사전 구축된 SageMaker Clarify 컨테이너 이미지를 식별해야 하며,`ContainerEntrypoint` 및 `ContainerArguments`는 지원되지 않습니다. SageMaker Clarify에 대한 자세한 내용은 [사전 구축된 SageMaker Clarify 컨테이너](clarify-processing-job-configure-container.md) 섹션을 참고하세요.
1. 분석을 위한 구성과 `ProcessingInputs`매개변수 내에 있는 입력 데이터세트의 매개변수를 모두 지정합니다.
1. 편향 분석 및 설명 가능성 분석을 위한 매개변수가 포함된 JSON 분석 구성 파일의 위치를 지정합니다. `ProcessingInput` 객체의 `InputName`매개변수는 다음 코드 예제에 표시된 것처럼 반드시 **analysis\$1config**여야 합니다.
```
{
"InputName": "analysis_config",
"S3Input": {
"S3Uri": "s3://your-bucket/analysis_config.json",
"S3DataType": "S3Prefix",
"S3InputMode": "File",
"LocalPath": "/opt/ml/processing/input/config"
}
}
```
분석 구성 파일의 스키마에 대한 자세한 내용은 [분석 구성 파일](clarify-processing-job-configure-analysis.md) 섹션을 참조하세요.
1. 입력 데이터세트의 위치를 지정하세요. `ProcessingInput` 객체의 `InputName`매개변수는 반드시 `dataset`이어야 합니다. 사용자가 분석 구성 파일에 “dataset\$1uri”를 제공한 경우, 이 매개변수는 선택사항입니다. `S3Input` 구성에는 다음 값이 필요합니다.
1. `S3Uri`의 경우 Amazon S3 객체 또는 S3 접두사일 수 있습니다.
1. `S3InputMode`는 **File**유형이어야 합니다.
1. `S3CompressionType`은 `None`유형(기본값)이어야 합니다.
1. `S3DataDistributionType`은 `FullyReplicated`유형(기본값)이어야 합니다.
1. `S3DataType`은 `S3Prefix`또는 `ManifestFile`일 수 있습니다. `ManifestFile`을 사용하려면, SageMaker API 레퍼런스 섹션 [S3Uri](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_S3DataSource.html#sagemaker-Type-S3DataSource-S3Uri)의 스키마를 따르는 매니페스트 파일의 위치를 `S3Uri`매개변수가 지정해야 합니다. 이 매니페스트 파일은 해당 작업의 입력 데이터를 포함하고 있는 S3 객체를 나열해야 합니다.
다음 코드는 입력 구성의 예제를 보여줍니다.
```
{
"InputName": "dataset",
"S3Input": {
"S3Uri": "s3://your-bucket/your-dataset.csv",
"S3DataType": "S3Prefix",
"S3InputMode": "File",
"LocalPath": "/opt/ml/processing/input/data"
}
}
```
1. `ProcessingOutputConfig` 매개변수 내에서 해당 처리 작업의 출력을 위한 구성을 지정합니다. `Outputs` 구성에는 단일 `ProcessingOutput`객체가 필요합니다. 출력 구성에는 다음 값이 필요합니다.
1. `OutputName`은 **analysis\$1result**여야 합니다.
1. `S3Uri`는 출력 위치에 대한 S3 접두사여야 합니다.
1. `S3UploadMode`를 **EndOfJob**로 설정해야 합니다.
다음 코드는 출력 구성의 예제를 보여줍니다.
```
{
"Outputs": [{
"OutputName": "analysis_result",
"S3Output": {
"S3Uri": "s3://your-bucket/result/",
"S3UploadMode": "EndOfJob",
"LocalPath": "/opt/ml/processing/output"
}
}]
}
```
1. `ProcessingResources` 매개변수 내에서 해당 처리 작업에 사용되는 리소스를 위한 구성 `ClusterConfig`를 지정합니다. `ClusterConfig` 객체 내에는 다음 매개변수가 필요합니다.
1. `InstanceCount`는 해당 처리 작업을 실행하는 클러스터 내부의 컴퓨팅 인스턴스 수를 지정합니다. 분산 처리 작업을 활성화하려면 `1`보다 큰 값을 지정하세요.
1. `InstanceType`은 해당 처리 작업을 실행하는 리소스를 나타냅니다. SageMaker AI SHAP 분석은 컴퓨팅 집약적이므로, 연산에 최적화된 인스턴스 유형을 사용하면 분석 런타임이 향상될 수 있습니다. SageMaker Clarify 처리 작업은 GPU를 사용하지 않습니다.
다음 코드는 리소스 구성의 예제를 보여줍니다.
```
{
"ClusterConfig": {
"InstanceCount": 1,
"InstanceType": "ml.m5.xlarge",
"VolumeSizeInGB": 20
}
}
```
1. `NetworkConfig` 객체 내에서 해당 처리 작업에 사용되는 네트워크의 구성을 지정합니다. 해당 구성에는 다음 값이 필요합니다.
1. 예측에 필요한 경우 SageMaker Clarify가 예측을 위해 엔드포인트를 호출할 수 있게 하려면 `EnableNetworkIsolation`은 `False`(기본값)로 설정되어 있어야 합니다.
1. 사용자가 SageMaker Clarify 작업에 제공한 모델 또는 엔드포인트가 Amazon Virtual Private Cloud(Amazon VPC) 내에 있는 경우, SageMaker Clarify 작업 역시 동일한 VPC에 있어야 합니다. [VpcConfig](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_VpcConfig.html)를 사용하여 VPC를 지정합니다. 또한 VPC에는 Amazon S3 버킷, SageMaker AI 서비스 및 SageMaker AI 런타임 서비스에 대한 엔드포인트가 있어야 합니다.
분산 처리가 활성화된 경우, 동일한 처리 작업에서 서로 다른 인스턴스 간 통신도 필수적으로 허용해야 합니다. 동일한 보안 그룹의 구성원 간 인바운드 연결을 허용하는 보안 그룹 규칙을 구성합니다. 자세한 내용은 [Amazon SageMaker Clarify 작업에 Amazon VPC의 리소스에 대한 액세스 권한 부여](clarify-vpc.md) 단원을 참조하십시오.
다음 코드는 네트워크 구성의 예제를 제공합니다.
```
{
"EnableNetworkIsolation": False,
"VpcConfig": {
...
}
}
```
1. `StoppingCondition` 매개변수를 사용하여 작업이 실행되는 최대 시간을 설정합니다. SageMaker Clarify 작업을 실행할 수 있는 가장 긴 시간은 `7`일 또는 `604800`초입니다. 이 제한 시간 이내에 작업을 완료할 수 없는 경우에는 작업이 중지되고, 분석 결과도 제공되지 않습니다. 예를 들어, 다음 구성은 작업을 실행할 수 있는 최대 시간을 3600초로 제한합니다.
```
{
"MaxRuntimeInSeconds": 3600
}
```
1. `RoleArn` 매개변수를 위한 IAM 역할을 지정합니다. 해당 역할은 반드시 Amazon SageMaker AI와 신뢰 관계를 맺고 있어야 합니다. 이는 다음 테이블에 나열된 SageMaker API 작업을 수행하는 데 사용될 수 있습니다. 여기에는 SageMaker AI에 대한 전체 액세스 권한을 부여해주는 Amazon SageMaker AIFullAccess 관리형 정책을 사용하는 것이 좋습니다. 이 정책에 대한 자세한 내용은 [AWS 관리형 정책: AmazonSageMakerFullAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonSageMakerFullAccess) 섹션을 참조하세요. 전체 액세스 권한 부여 시 우려사항이 있는 경우, 필요한 최소 권한은 사용자가 모델 이름을 제공하는지 엔드포인트 이름을 제공하는지에 따라 달라집니다. 엔드포인트 이름을 사용하면 SageMaker AI에 더 적은 권한을 부여해도 됩니다.
다음 표에는 SageMaker Clarify 처리 작업에서 사용하는 API 작업들이 나와 있습니다. **모델 이름** 및 **엔드포인트 이름** 열 아래에 표시된 **X**는 각 입력을 위해 요구되는 API 작업을 의미합니다.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ko_kr/sagemaker/latest/dg/clarify-processing-job-configure-parameters.html)
필요한 권한에 대한 자세한 내용은 [Amazon SageMaker AI API 권한: 작업, 권한 및 리소스 참조](api-permissions-reference.md) 섹션을 참조하세요.
SageMaker AI에 역할을 전달하는 방법에 대한 자세한 내용은 [역할 전달](sagemaker-roles.md#sagemaker-roles-pass-role) 섹션을 참조하세요.
처리 작업 구성의 개별적인 부분들이 완료되면, 이를 모두 결합하여 작업을 구성하세요.
## AWS SDK for Python을 사용하여 SageMaker Clarify 처리 작업 구성
다음 코드 예제는 [AWS Python용 SDK](https://aws.amazon.com/sdk-for-python/)를 사용하여 SageMaker Clarify 처리 작업을 시작하는 방법을 보여줍니다.
```
sagemaker_client.create_processing_job(
ProcessingJobName="your-clarify-job-name",
AppSpecification={
"ImageUri": "the-clarify-container-image-uri",
},
ProcessingInputs=[{
"InputName": "analysis_config",
"S3Input": {
"S3Uri": "s3://your-bucket/analysis_config.json",
"S3DataType": "S3Prefix",
"S3InputMode": "File",
"LocalPath": "/opt/ml/processing/input/config",
},
}, {
"InputName": "dataset",
"S3Input": {
"S3Uri": "s3://your-bucket/your-dataset.csv",
"S3DataType": "S3Prefix",
"S3InputMode": "File",
"LocalPath": "/opt/ml/processing/input/data",
},
},
],
ProcessingOutputConfig={
"Outputs": [{
"OutputName": "analysis_result",
"S3Output": {
"S3Uri": "s3://your-bucket/result/",
"S3UploadMode": "EndOfJob",
"LocalPath": "/opt/ml/processing/output",
},
}],
},
ProcessingResources={
"ClusterConfig": {
"InstanceCount": 1,
"InstanceType": "ml.m5.xlarge",
"VolumeSizeInGB": 20,
},
},
NetworkConfig={
"EnableNetworkIsolation": False,
"VpcConfig": {
...
},
},
StoppingCondition={
"MaxRuntimeInSeconds": 3600,
},
RoleArn="arn:aws:iam:::role/service-role/AmazonSageMaker-ExecutionRole",
)
```
AWS SDK for Python을 사용하여 SageMaker Clarify 처리 작업을 실행하기 위한 지침이 포함된 예제 노트북은 [Python용 AWS SDK를 사용하여 SageMaker Clarify를 사용한 공정성 및 설명 가능성을](http://github.com/aws/amazon-sagemaker-examples/blob/main/sagemaker-clarify/fairness_and_explainability/fairness_and_explainability_boto3.ipynb) 참조하세요. 노트북에 사용되는 모든 S3 버킷은 해당 버킷에 액세스하는 노트북 인스턴스와 동일한 AWS 리전에 있어야 합니다.
## SageMaker Python SDK를 사용하여 SageMaker Clarify 처리 작업 구성
SageMaker Python SDK API에서 [SageMaker ClarifyProcessor](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SageMakerClarifyProcessor)를 사용하여 SageMaker Clarify 처리 작업을 구성하는 것도 가능합니다. 자세한 내용은 [편향 분석 및 설명 가능성을 위한 SageMaker Clarify 처리 작업 실행](clarify-processing-job-run.md) 단원을 참조하십시오.
**Topics**
+ [사전 구축된 SageMaker Clarify 컨테이너](clarify-processing-job-configure-container.md)
+ [분석 구성 파일](clarify-processing-job-configure-analysis.md)
+ [데이터 형식 호환성 안내서](clarify-processing-job-data-format.md)
# 사전 구축된 SageMaker Clarify 컨테이너
Amazon SageMaker AI는 사전 구축된 SageMaker Clarify 컨테이너 이미지를 제공합니다.이 이미지에는 설명 가능성을 위해 편향 지표와 특성 속성을 계산하는 데 필요한 라이브러리 및 기타 종속성이 포함되어 있습니다. 이러한 이미지는 계정에서 SageMaker Clarify [처리 작업](processing-job.md)을 실행할 수 있습니다.
컨테이너의 이미지 URI는 다음과 같은 형식입니다.
```
.dkr.ecr..amazonaws.com/sagemaker-clarify-processing:1.0
```
예제:
```
111122223333.dkr.ecr.us-east-1.amazonaws.com/sagemaker-clarify-processing:1.0
```
다음 표에는 주소를 기준으로 나열되어 있습니다 AWS 리전.
SageMaker Clarify 처리 작업을 위한 도커 이미지
| 리전 | 이미지 주소 |
| --- | --- |
| 미국 동부(버지니아 북부) | 205585389593.dkr.ecr.us-east-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 미국 동부(오하이오) | 211330385671.dkr.ecr.us-east-2.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 미국 서부(캘리포니아 북부) | 740489534195.dkr.ecr.us-west-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 미국 서부(오리건) | 306415355426.dkr.ecr.us-west-2.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 아시아 태평양(홍콩) | 098760798382.dkr.ecr.ap-east-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 아시아 태평양(뭄바이) | 452307495513.dkr.ecr.ap-south-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 아시아 태평양(자카르타) | 705930551576.dkr.ecr.ap-southeast-3.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 아시아 태평양(도쿄) | 377024640650.dkr.ecr.ap-northeast-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 아시아 태평양(서울) | 263625296855.dkr.ecr.ap-northeast-2.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 아시아 태평양(오사카) | 912233562940.dkr.ecr.ap-northeast-3.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 아시아 태평양(싱가포르) | 834264404009.dkr.ecr.ap-southeast-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 아시아 태평양(시드니) | 007051062584.dkr.ecr.ap-southeast-2.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 캐나다(중부) | 675030665977.dkr.ecr.ca-central-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 유럽(프랑크푸르트) | 017069133835.dkr.ecr.eu-central-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 유럽(취리히) | 730335477804.dkr.ecr.eu-central-2.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 유럽(아일랜드) | 131013547314.dkr.ecr.eu-west-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 유럽(런던) | 440796970383.dkr.ecr.eu-west-2.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 유럽(파리) | 341593696636.dkr.ecr.eu-west-3.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 유럽(스톡홀름) | 763603941244.dkr.ecr.eu-north-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| Middle East (Bahrain) | 835444307964.dkr.ecr.me-south-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 남아메리카(상파울루) | 520018980103.dkr.ecr.sa-east-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 아프리카(케이프타운) | 811711786498.dkr.ecr.af-south-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 유럽(밀라노) | 638885417683.dkr.ecr.eu-south-1.amazonaws.com/sagemaker-clarify-processing:1.0 |
| 중국(베이징) | 122526803553---dkr---ecr---cn-north-1.amazonaws.com.rproxy.govskope.us.cn/sagemaker-clarify-processing:1.0 |
| 중국(닝샤) | 122578899357---dkr---ecr---cn-northwest-1.amazonaws.com.rproxy.govskope.us.cn/sagemaker-clarify-processing:1.0 |
# 분석 구성 파일
SageMaker Clarify를 사용하여 데이터 및 모델의 설명 가능성 및 편향을 분석하려면 처리 작업을 구성해야 합니다. 이 처리 작업을 위한 구성의 일부에는 분석 파일의 구성도 포함됩니다. 분석 파일은 편향 분석 및 설명 가능성에 대한 매개변수를 지정합니다. 처리 작업 및 분석 파일을 구성하는 방법은 [SageMaker Clarify 처리 작업 구성](clarify-processing-job-configure-parameters.md) 섹션을 참조하세요.
이 가이드에서는 이러한 분석 구성 파일의 스키마와 매개변수에 대해 설명합니다. 이 가이드에는 테이블 형식 데이터세트의 편향 지표를 계산하고 자연어 처리(NLP), 컴퓨터 비전(CV) 및 시계열(TS) 문제에 대한 설명을 생성하기 위한 분석 구성 파일의 예시도 포함되어 있습니다.
분석 구성 파일은 사용자가 생성하거나 [SageMaker Python SDK](https://sagemaker.readthedocs.io/)를 사용하여 [SageMaker ClarifyProcessor](https://sagemaker.readthedocs.io/en/stable/api/training/processing.html#sagemaker.clarify.SageMakerClarifyProcessor) API를 통해 자동으로 생성할 수도 있습니다. 파일 내용을 살펴보면 SageMaker Calify 작업에서 사용하는 기본 구성을 이해하는 데 도움이 될 수 있습니다.
**Topics**
+ [분석 구성 파일의 스키마](#clarify-processing-job-configure-schema)
+ [예제 분석 구성 파일](#clarify-processing-job-configure-analysis-examples)
## 분석 구성 파일의 스키마
다음 섹션에서는 매개변수의 요구 사항 및 설명을 포함하여 분석 구성 파일의 스키마에 대해 설명합니다.
### 분석 구성 파일을 위한 요구 사항
SageMaker Clarify 처리 작업에서는 분석 구성 파일이 다음 요구 사항을 갖추고 구조화될 것으로 예상합니다.
+ 처리 입력의 이름은 `analysis_config.`여야 합니다.
+ 분석 구성 파일은 JSON 형식으로 저장되며, UTF-8 형식으로 인코딩됩니다.
+ 분석 구성 파일이 Amazon S3 객체입니다.
분석 구성 파일에 추가적인 매개변수를 지정하는 것이 가능합니다. 다음 섹션은 해당 사용 사례 및 원하는 분석 유형에 맞게 SageMaker Clarify 처리 작업을 조정할 수 있는 다양한 옵션을 제공합니다.
### 분석 구성 파일의 매개변수
분석 구성 파일에서는 다음 매개변수를 지정할 수 있습니다.
+ **version** – (선택사항) 분석 구성 파일 스키마의 버전 문자열입니다. 버전이 제공되지 않은 경우 SageMaker Clarify는 지원되는 최신 버전을 사용합니다. 현재는 `1.0`버전만 지원 가능합니다.
+ **dataset\$1type** – 해당 데이터세트의 형식입니다. 입력 데이터세트 형식은 다음 값 중 하나일 수 있습니다.
+ 테이블 형식
+ CSV인 경우 `text/csv`
+ [SageMaker AI JSON Lines 조밀 형식](https://docs.aws.amazon.com/sagemaker/latest/dg/cdf-inference.html#cm-jsonlines)인 경우 `application/jsonlines`
+ JSON인 경우 `application/json`
+ Apache Parquet인 경우 `application/x-parquet`
+ 컴퓨터 비전 문제에 대한 설명 가능성을 활성화하려면 `application/x-image`
+ 시계열 예측 모델 설명
+ JSON인 경우 `application/json`
+ **dataset\$1uri** – (선택사항) 기본 데이터세트의 균일한 리소스 식별자(URI) 입니다. 사용자가 S3 URI 접두사를 제공하는 경우, SageMaker Clalify 처리 작업은 해당 접두사 아래에 있는 모든 S3 파일을 반복적으로 수집합니다. 컴퓨터 비전 문제의 경우 이미지 매니페스트 파일에 S3 URI 접두사 또는 S3 URI를 제공할 수 있습니다. `dataset_uri`가 제공된 경우, 이는 데이터세트 처리 작업의 입력보다 우선하게 됩니다. 이미지 및 시계열 사용 사례를 제외한 모든 형식 유형의 경우, SageMaker Clarify 처리 작업은 입력 데이터세트를 **테이블 형식의 데이터세트**로서 테이블 형식 데이터 프레임에 로드합니다. 이 형식을 사용하면 SageMaker AI에서 입력 데이터세트를 손쉽게 조작하고 분석할 수 있습니다.
+ **헤더** - (선택 사항)
+ **테이블 형식:** 테이블 형식 데이터세트의 열 이름을 포함하는 문자열 배열입니다. `headers`에 대한 값이 제공되지 않은 경우, SageMaker Clarify 처리 작업은 해당 데이터세트에서 헤더를 읽게 됩니다. 데이터세트에 헤더가 없는 경우, Clarify 처리 작업은 0으로 시작하는 열 인덱스를 기반으로 자리 표시자 이름을 자동으로 생성합니다. 예를 들어, 첫 번째 열과 두 번째 열의 자리 표시자 이름은 **column\$10**, **column\$11**처럼 지정됩니다.
**참고**
`dataset_type`이 `application/jsonlines` 또는 `application/json`인 경우 규칙에 따라 `headers`는 다음 이름을 순서대로 포함해야 합니다.
특성 이름
레이블 이름(`label`이 지정된 경우)
예측 레이블 이름(`predicted_label`이 지정된 경우)
`label`이 지정된 경우 `application/jsonlines`데이터세트 유형에 대한 `headers`의 예는 다음과 같습니다.`["feature1","feature2","feature3","target_label"]`
+ **시계열:** 데이터세트의 열 이름 목록입니다. 제공되지 않은 경우 Clarify는 내부적으로 사용할 헤더를 생성합니다. 시계열 설명 가능성 사례의 경우 헤더를 다음 순서로 제공합니다.
1. 항목 ID
1. timestamp
1. 대상 시계열
1. 모든 관련 시계열 열
1. 모든 정적 공변량 열
+ **label** – (선택사항) 문자열 또는 0으로 시작하는 정수 인덱스입니다. 제공된 경우, `label`은 테이블 형식 데이터세트에서 실측 레이블(관찰된 레이블 또는 대상 속성이라고도 함)을 찾기 위해 사용됩니다. 실측 레이블은 편향 지표를 계산하는 데 사용됩니다. `label`의 값은 `dataset_type`의 매개변수 값에 따라 다음과 같이 지정됩니다.
+ `dataset_type`이 **text/csv**인 경우, `label`은 다음 중 하나로 지정될 수 있습니다.
+ 유효한 열 이름
+ 데이터세트 열의 범위 내에 포함되어 있는 인덱스
+ `dataset_type`이 **application/parquet**인 경우, `label`은 유효한 열 이름이어야 합니다.
+ `dataset_type`이 **application/jsonlines**인 경우, `label`은 해당 데이터세트에서 실측 레이블을 추출하기 위해 작성된 [JMESPath](https://jmespath.org/) 표현식이어야 합니다. 통상적으로, `headers`가 지정된 경우라면 이는 해당 레이블 이름을 포함하게 됩니다.
+ `dataset_type`이 **application/json**인 경우, `label`은 해당 데이터세트의 각 레코드에서 실측 레이블을 추출하기 위해 작성된 [JMESPath](https://jmespath.org/) 표현식이어야 합니다. 이 JMESPath 표현식은 i번째 레이블이 i번째 레코드와 상관되는 레이블 목록을 생성해야 합니다.
+ **predicted\$1label** – (선택사항) 문자열 또는 0으로 시작하는 정수 인덱스입니다. 제공된 경우, `predicted_label`은 테이블 형식 데이터세트에서 해당 예측 레이블이 포함된 열을 찾는 데 사용됩니다. 예측 레이블은 훈련 후 **편향 지표**를 계산하는 데 사용됩니다. 데이터세트에 예측 레이블이 포함되지 않은 경우, `predicted_label`매개변수는 선택사항입니다. 계산에 예측 레이블이 필요한 경우, SageMaker Clalify 처리 작업은 해당 모델에서 예측을 가져오게 됩니다.
`predicted_label`의 값은 `dataset_type`의 값에 따라 다음과 같이 지정됩니다.
+ `dataset_type`이 **text/csv**인 경우, `predicted_label`은 다음 중 하나로 지정될 수 있습니다.
+ 유효한 열 이름. 만약 `predicted_label_dataset_uri`가 지정되었지만 `predicted_label`은 제공되지 않은 경우라면, 기본 예측 레이블 이름은 “predicted\$1label”이 됩니다.
+ 데이터세트 열의 범위 내에 포함되어 있는 인덱스. `predicted_label_dataset_uri`가 지정된 경우, 인덱스는 예측 레이블 데이터세트에서 해당 예측 레이블 열을 찾는 데 사용됩니다.
+ dataset\$1type이 **application/x-parquet**인 경우, `predicted_label`은 유효한 열 이름이어야 합니다.
+ dataset\$1type이 **application/jsonlines**인 경우, `predicted_label`은 해당 데이터세트에서 예측 레이블을 추출하기 위해 작성된 유효한 [JMESPath](https://jmespath.org/) 표현식이어야 합니다. 통상적으로, `headers`가 지정된 경우라면 이는 해당 예측 레이블 이름을 포함하게 됩니다.
+ `dataset_type`이 **application/json**인 경우, `predicted_label`은 해당 데이터세트의 각 레코드에서 예측 레이블을 추출하기 위해 작성된 [JMESPath](https://jmespath.org/) 표현식이어야 합니다. JMESPath 표현식은 i번째 예측 레이블이 i번째 레코드와 상관되는 예측 레이블 목록을 생성해야 합니다.
+ **특성** - (선택 사항) `dataset_type`이 `application/jsonlines` 또는 `application/json`인 경우 시계열이 아닌 사용 사례에 필요합니다. 입력 데이터세트에서 해당 특징을 찾기 위해 작성된 JMESPath 문자열 표현식입니다. `application/jsonlines`의 경우, JMESPath 표현식이 각 줄에 적용되어 해당 레코드의 특징을 추출하게 됩니다. `application/json`의 경우, JMESPath 표현식이 전체 입력 데이터세트에 적용됩니다. JMESPath 표현식은 i번째 레코드와 상관되는 특징이 i번째 행에 포함되어 있는 목록들의 목록 또는 특성의 2D 배열/행렬을 추출하게 됩니다. `text/csv`의 `dataset_type`또는 `application/x-parquet`의 경우, 실측 레이블과 예측 레이블 열을 제외한 모든 열이 특징으로서 자동 할당됩니다.
+ **predicted\$1label\$1dataset\$1uri** – (선택 사항) dataset\$1type이 `text/csv`인 경우에만 적용됩니다. 훈련 후 **편향 지표**를 계산하는 데 사용되는 예측 레이블을 포함하고 있는 데이터세트의 S3 URI입니다. SageMaker Clarify 처리 작업은 해당 모델에서 예측을 가져오지 않고 그 대신 제공된 URI에서 예측을 로드하게 됩니다. 이 경우, 예측 레이블 데이터세트에서 해당 예측 레이블 열을 찾으려면 `predicted_label`이 필수입니다. 만약 예측 레이블 데이터세트 또는 기본 데이터세트가 여러 파일로 분할되어 있다면, 두 데이터세트를 조인하기 위한 식별자 열이 `joinsource_name_or_index`에 의해 지정되어 있어야 합니다.
+ **predicted\$1label\$1headers** – (선택 사항) `predicted_label_dataset_uri`가 지정된 경우에만 적용됩니다. 예측 레이블 데이터세트의 열 이름을 포함하는 문자열 배열입니다. `predicted_label_headers`는 예측 레이블 헤더 외에도 예측 레이블 데이터세트와 기본 데이터세트를 조인하는 식별자 열의 헤더 역시 포함할 수 있습니다. 자세한 내용은 `joinsource_name_or_index`매개변수에 대한 다음 설명을 참조하세요.
+ **joinsource\$1name\$1or\$1index** – (선택 사항) 내부 조인을 수행하는 과정에서 식별자 열로서 사용되는 테이블 형식 데이터세트의 열 이름 또는 0으로 시작하는 인덱스입니다. 이 열은 식별자로만 사용됩니다. 편향 분석이나 특징 속성 분석과 같은 다른 종류의 계산에는 사용되지 않습니다. 다음과 같은 경우에는 `joinsource_name_or_index`에 대한 값이 필요합니다.
+ 입력 데이터세트가 여러 개 있으며, 그 중 하나는 여러 파일로 분할되어 있는 경우
+ SageMaker Clarify 처리 작업 [InstanceCount](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingClusterConfig.html#sagemaker-Type-ProcessingClusterConfig-InstanceCount)를 `1`보다 큰 값으로 설정하여 분산 처리를 활성화한 경우
+ **excluded\$1columns** – (선택사항) 모델에 예측을 위한 입력으로 전송되지 않도록 제외할 이름 또는 0으로 시작하는 열 인덱스의 배열입니다. 실측 레이블과 예측 레이블은 이미 자동으로 제외되어 있습니다. 이 특성은 시계열에 지원되지 않습니다.
+ **probability\$1threshold** – (선택사항) 부동 소수점 숫자로, 그 위에는 레이블 또는 객체가 선택되어 있습니다. 기본값은 `0.5`입니다. SageMaker Clarify 처리 작업은 다음과 같은 경우에 `probability_threshold`를 사용합니다.
+ 훈련 후 편향 분석에서, `probability_threshold`는 모델이 바이너리 분류기에 해당하는 경우 수치 모델 예측(확률 값 또는 점수)을 바이너리 레이블로 변환하게 됩니다. 임계값보다 큰 점수는 `1`로 변환됩니다. 반면, 임계값 이하인 점수는 `0`으로 변환됩니다.
+ 컴퓨터 비전 설명 가능성 문제에서, 만약 model\$1type이 **OBJECT\$1DETECTION**이라면 `, probability_threshold`는 신뢰도 점수가 임계값보다 낮게 탐지된 객체를 필터링하게 됩니다.
+ **label\$1values\$1or\$1threshold** – (선택 사항) 편향 분석에 필요합니다. 실측 데이터에 대한 긍정적인 결과를 나타내고 편향 지표에 대한 예측 레이블을 나타내는 레이블 값 또는 임계값의 배열입니다. 자세한 내용은 [편향과 공정성과 관련한 Amazon SageMaker Clarify 용어](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms)의 양수 레이블 값을 참조하세요. 레이블 값이 숫자인 경우, 해당 임계값이 긍정적인 결과를 선택하기 위한 하한값으로 적용됩니다. 다양한 문제 유형에 대한 `label_values_or_threshold`를 설정하려면 다음 예시를 참조하세요.
+ 바이너리 분류 문제인 경우, 레이블에는 `0`과 `1`의 두 가지 값이 있을 수 있습니다. 만약 레이블 값이 `1`이 표본에서 관찰한 인구통계 그룹에 대해 우호적이라면, `label_values_or_threshold`는 `[1]`로 설정됩니다.
+ 멀티클래스 분류 문제인 경우, 레이블에는 **bird**, **cat**, **dog**의 세 가지 값이 있을 수 있습니다. 만약 후자의 2개가 편향적인 인구통계 그룹을 정의하고 있다면, `label_values_or_threshold`는 `["cat","dog"]`으로 설정됩니다.
+ 회귀 문제인 경우, 레이블 값은 `0`\$1`1`범위에서 연속적이 됩니다. 만약 `0.5`보다 큰 값이 특정 샘플의 결과가 긍정적이라고 지정한다면, `label_values_or_threshold`는 `0.5`로 설정됩니다.
+ **facet** – (선택 사항) 편향 분석에 필요합니다. 편향을 측정하는 비교 대상인 민감한 속성으로 구성된 패싯 객체의 배열입니다. 민감한 속성을 사용하지 않고 모델을 훈련시킨 경우에도 패싯을 사용하여 데이터 세트와 모델의 편향 특성을 파악하는 것이 가능합니다. 자세한 내용은 [편향과 공정성과 관련한 Amazon SageMaker Clarify 용어](clarify-detect-data-bias.md#clarify-bias-and-fairness-terms)의 **패싯**을 참조하세요. 각 패싯 객체에는 다음 필드가 포함됩니다.
+ **name\$1or\$1index** - (선택 사항) 테이블 형식 데이터세트에 있는 민감한 속성 열의 이름 또는 0으로 시작하는 인덱스입니다. `facet_dataset_uri`가 지정된 경우, 인덱스는 기본 데이터세트 대신에 패싯 데이터세트를 참조하게 됩니다.
+ **value\$1or\$1threshold** – (선택 사항) `facet` 값이 숫자이고 `label_values_or_threshold`가 민감한 그룹을 선택하기 위한 하한값으로 적용된 경우 필수입니다. 편향성이 높은 민감한 인구통계 그룹을 나타내는 패싯 값 또는 임계값의 배열입니다. 패싯 데이터 유형이 범주형이고 `value_or_threshold`가 제공되지 않은 경우, 편향 지표는 (전체 값이 아니라) 모든 고유 값에 대해 하나의 그룹으로 계산됩니다. 다양한 `facet`데이터 유형에 대한 `value_or_threshold`를 설정하려면 다음 예시를 참조하세요.
+ 바이너리 패싯 데이터 유형인 경우, 해당 특징에는 `0`과 `1`의 두 가지 값이 있을 수 있습니다. 각각의 값에 대한 편향 지표를 계산하고자 하는 경우, `value_or_threshold`는 생략 가능하거나 빈 배열로 설정될 수 있습니다.
+ 범주형 패싯 데이터 유형인 경우, 해당 특징에는 **bird**, **cat**, **dog**의 세 가지 값이 있을 수 있습니다. 만약 전자의 2개가 편향적인 인구통계 그룹을 정의하고 있다면, `value_or_threshold`는 `["bird", "cat"]`으로 설정됩니다. 이 예시에서는 데이터 세트 샘플을 두 개의 인구통계 그룹으로 나눕니다. 유리한 그룹의 패싯에는 **bird**또는 **cat**값이 있는 반면, 불리한 그룹의 패싯에는 **dog**값이 있습니다.
+ 숫자로 된 패싯 데이터 유형인 경우, 해당 특징의 값은 `0`\$1`1`범위에서 연속적이 됩니다. 예를 들어, 만약 `0.5`보다 큰 값이 특정 샘플이 우호적이라고 지정한다면, `value_or_threshold`는 `0.5`로 설정됩니다. 이 예시에서는 데이터세트 샘플을 두 개의 인구통계 그룹으로 나눕니다. 유리한 그룹의 패싯에는 `0.5`보다 큰 값이 있는 반면, 불리한 그룹의 패싯에는 `0.5`이하인 값이 있습니다.
+ **group\$1variable** – (선택 사항) 편향 지표 [조건부 인구통계학적 차이(CDD)](clarify-data-bias-metric-cddl.md) 또는 [예측된 레이블의 조건부 인구통계학적 차이(CDDPL)](clarify-post-training-bias-metric-cddpl.md)에 사용할 하위 그룹을 나타내는 열의 이름 또는 0 기반 인덱스입니다.
+ **facet\$1dataset\$1uri** – (선택 사항) dataset\$1type이 `text/csv`인 경우에만 적용됩니다. 편향 분석을 위한 민감한 속성을 포함하고 있는 데이터세트의 S3 URI입니다. 민감한 속성을 사용하지 않고 모델을 훈련시킨 경우에도 패싯을 사용하여 데이터세트와 모델의 편향 특성을 파악하는 것이 가능합니다.
**참고**
만약 패싯 데이터세트 또는 기본 데이터세트가 여러 파일로 분할되어 있다면, 두 데이터세트를 조인하기 위한 식별자 열이 `joinsource_name_or_index`에 의해 지정되어 있어야 합니다. 반드시 `facet`매개변수를 사용하여 패싯 데이터세트의 각 패싯을 식별해야 합니다.
+ **facet\$1headers** - (선택 사항) `facet_dataset_uri`가 지정된 경우에만 적용됩니다. 패싯 데이터세트의 열 이름을 포함하는 문자열 배열로서, 필요 시에는 패싯 데이터세트와 기본 데이터세트를 조인하기 위한 식별자 열 헤더도 포함합니다. `joinsource_name_or_index` 섹션을 참조하세요.
+ **time\$1series\$1data\$1config** – (선택 사항) 시계열의 데이터 처리에 사용할 구성을 지정합니다.
+ **item\$1id** – 문자열 또는 0 기반 정수 인덱스입니다. 이 필드는 공유 입력 데이터세트에서 항목 ID를 찾는 데 사용됩니다.
+ **timestamp** - 문자열 또는 0 기반 정수 인덱스입니다. 이 필드는 공유 입력 데이터세트에서 타임스탬프를 찾는 데 사용됩니다.
+ **dataset\$1format** – 가능한 값은 `columns`, `item_records` 또는 `timestamp_records`입니다. 이 필드는 시계열 설명 가능성에 지원되는 유일한 형식인 JSON 데이터세트의 형식을 설명하는 데 사용됩니다.
+ **target\$1time\$1series** – JMESPath 문자열 또는 0 기반 정수 인덱스입니다. 이 필드는 공유 입력 데이터세트에서 대상 시계열을 찾는 데 사용됩니다. 이 파라미터가 문자열인 경우 `dataset_format`을 제외한 다른 모든 파라미터는 문자열 또는 문자열 목록이어야 합니다. 이 파라미터가 정수인 경우 `dataset_format`을 제외한 다른 모든 파라미터는 정수 또는 정수 목록이어야 합니다.
+ **related\$1time\$1series** – (선택 사항) JMESPath 표현식 배열입니다. 이 필드는 공유 입력 데이터세트가 있는 경우 모든 관련 시계열을 찾는 데 사용됩니다.
+ **static\$1covariates** – (선택 사항) JMESPath 표현식 배열입니다. 이 필드는 공유 입력 데이터세트가 있는 경우 모든 정적 공변량 필드를 찾는 데 사용됩니다.
예시는 [시계열 데이터세트 구성 예시](clarify-processing-job-data-format-time-series.md#clarify-processing-job-data-format-time-series-ex) 섹션을 참조하세요.
+ **methods** – 하나 이상의 분석 메서드와 해당 매개변수를 포함하는 객체입니다. 일부 메서드를 생략할 경우, 이는 분석에 사용되지도 않고 보고되지도 않습니다.
+ **pre\$1training\$1bias** – 훈련 전 편향 지표를 계산하고자 한다면 이 메서드를 포함하세요. 이 지표에 대한 자세한 설명은 [훈련 전 편향 지표](clarify-measure-data-bias.md)에서 확인할 수 있습니다. 해당 객체에는 다음 매개변수가 있습니다.
+ **methods** – 계산하고자 하는 다음 목록의 훈련 전 편향 지표 중에서 하나 이상을 포함하고 있는 배열입니다. 모든 훈련 전 편향 지표를 계산하려면 `methods`를 **all**로 설정합니다. 예를 들어, `["CI", "DPL"]`배열은 **Class Imbalance**와 **Difference in Proportions of Labels**를 계산하게 됩니다.
+ [클래스 불균형(CI)](clarify-bias-metric-class-imbalance.md)용 `CI`
+ [레이블 비율의 차이(DPL)](clarify-data-bias-metric-true-label-imbalance.md)용 `DPL`
+ [쿨백-라이블러 발산(KL)](clarify-data-bias-metric-kl-divergence.md)용 `KL`
+ [젠슨-섀넌 발산(JS)](clarify-data-bias-metric-jensen-shannon-divergence.md)용 `JS`
+ [Lp-norm(LP)](clarify-data-bias-metric-lp-norm.md)용 `LP`
+ [총 변동 거리(TVD)](clarify-data-bias-metric-total-variation-distance.md)용 `TVD`
+ [콜모고로프-스미르노프(KS)](clarify-data-bias-metric-kolmogorov-smirnov.md)용 `KS`
+ [조건부 인구통계학적 차이(CDD)](clarify-data-bias-metric-cddl.md)용 `CDDL`
+ **post\$1training\$1bias** – 훈련 후 편향 지표를 계산하고자 한다면 이 메서드를 포함하세요. 이 지표에 대한 자세한 설명은 [훈련 후 데이터 및 모델 편향 지표](clarify-measure-post-training-bias.md)에서 확인할 수 있습니다. `post_training_bias` 객체에는 다음 매개변수가 있습니다.
+ **methods** – 계산하고자 하는 다음 목록의 훈련 후 편향 지표 중에서 하나 이상을 포함하고 있는 배열입니다. 모든 훈련 후 편향 지표를 계산하려면 `methods`를 **all**로 설정합니다. 예를 들어, `["DPPL", "DI"]`배열은 **Difference in Positive Proportions in Predicted Labels**와 **Disparate Impact**를 계산하게 됩니다. 사용 가능한 메서드는 다음과 같습니다.
+ [예측된 레이블의 양수 비율 차이(DPPL)](clarify-post-training-bias-metric-dppl.md)용 `DPPL`
+ [불평등 효과(DI)](clarify-post-training-bias-metric-di.md)의 경우 `DI`
+ [조건부 승인의 차이(DCAcc)](clarify-post-training-bias-metric-dcacc.md)용 `DCA`
+ [조건부 거부의 차이(DCR)](clarify-post-training-bias-metric-dcr.md)용 `DCR`
+ [특이도 차이(SD)](clarify-post-training-bias-metric-sd.md)용 `SD`
+ [재현율 차이(RD)](clarify-post-training-bias-metric-rd.md)용 `RD`
+ [승인율 차이(DAR)](clarify-post-training-bias-metric-dar.md)용 `DAR`
+ [거부율 차이(DRR)](clarify-post-training-bias-metric-drr.md)용 `DRR`
+ [정확도 차이(AD)](clarify-post-training-bias-metric-ad.md)용 `AD`
+ [대우 평등(TE)](clarify-post-training-bias-metric-te.md)용 `TE`
+ [예측된 레이블의 조건부 인구통계학적 차이(CDDPL)](clarify-post-training-bias-metric-cddpl.md)용 `CDDPL`
+ [반사실적 플립테스트(FT)](clarify-post-training-bias-metric-ft.md)용 `FT`
+ [일반화 엔트로피(GE)](clarify-post-training-bias-metric-ge.md)용 `GE`
+ **shap** – SHAP 값을 계산하고자 한다면 이 메서드를 포함하세요. SageMaker Clarify 처리 작업은 Kernel SHAP 알고리즘을 지원합니다. `shap` 객체에는 다음 매개변수가 있습니다.
+ **baseline** - (선택 사항) SHAP 기준 데이터세트(백그라운드 데이터세트라고도 함)입니다. 테이블 형식 데이터세트 또는 컴퓨터 비전 문제에 해당하는 기준 데이터세트에 대한 추가적인 요구 사항은 다음과 같습니다. SHAP 기준에 대한 자세한 내용은 [설명 가능성에 대한 SHAP 기준](clarify-feature-attribute-shap-baselines.md) 섹션을 참조하세요.
+ **테이블 형식** 데이터세트인 경우, `baseline`은 현재 위치 기준 데이터일 수도 있고 기준 파일의 S3 URI일 수도 있습니다. `baseline`이 제공되지 않은 경우, SageMaker Clarify 처리 작업은 해당 입력 데이터세트를 클러스터링하여 기준을 계산하게 됩니다. 기준에 필요한 사항은 다음과 같습니다.
+ 형식은 `dataset_type`에 의해 지정된 데이터세트 형식과 반드시 동일해야 합니다.
+ 기준은 해당 모델이 입력으로 받아들일 수 있는 특징만을 포함할 수 있습니다.
+ 기준 데이터세트에는 하나 이상의 인스턴스가 포함될 수 있습니다. 기준 인스턴스의 수는 합성 데이터세트 크기 및 작업 런타임에 직접적인 영향을 미치게 됩니다.
+ `text_config`가 지정된 경우, 텍스트 열의 기준 값은 `granularity`에 의해 지정된 텍스트 단위를 대체하는 데 사용되는 문자열이 됩니다. 예를 들어, 누락되거나 알 수 없는 단어 또는 텍스트 조각을 나타내는 데 사용되는 “[MASK]”와 같은 자리 표시자가 흔히 사용됩니다.
다음 예제는 다양한 `dataset_type`매개변수에 대해 현재 위치 기준 데이터를 설정하는 방법을 보여줍니다.
+ 만약 `dataset_type`이 `text/csv`또는 `application/x-parquet`이라면, 해당 모델은 네 개의 숫자로 된 특징을 허용하고, 기준은 두 개의 인스턴스를 가지게 됩니다. 이 예시에서는, 한 레코드의 특징 값이 모두 0이고 다른 레코드의 특징 값은 모두 1이라고 가정했을 때, 기준은 헤더 없이 `[[0,0,0,0],[1,1,1,1]]`로 설정되어야 합니다.
+ `dataset_type`이 `application/jsonlines`인 경우, `features`는 숫자로 된 특징 값 4개가 있는 목록에 대한 키가 됩니다. 또한, 이 예시에서 모든 값이 0인 레코드 한 개가 기준에 포함되어 있다면, `baseline`은 `[{"features":[0,0,0,0]}]`이 되어야 합니다.
+ `dataset_type`이 `application/json`인 경우, `baseline`데이터세트는 해당 입력 데이터세트와 구조 및 형식이 동일해야 합니다.
+ **컴퓨터 비전** 문제인 경우, `baseline`은 해당 입력 이미지에서 특징(세그먼트)을 마스킹하는 데 사용되는 이미지의 S3 URI일 수 있습니다. SageMaker Clarify 처리 작업은 해당 마스크 이미지를 로드한 다음 그 크기를 입력 이미지와 동일한 해상도로 조정하게 됩니다. 기준이 제공되지 않은 경우, SageMaker Clarify 처리 작업은 입력 이미지와 동일한 해상도의 [백색 노이즈](https://en.wikipedia.org/wiki/White_noise)로 된 마스크 이미지를 생성합니다.
+ **features\$1to\$1explain** – (선택사항) SHAP 값을 계산하는 데 사용되는 대상 문자열 또는 0으로 시작하는 특징 열의 인덱스의 배열입니다. `features_to_explain`이 지정되지 않은 경우, SHAP 값은 모든 특징 열을 대상으로 계산됩니다. 이러한 특징 열에 레이블 열 또는 예측 레이블 열은 포함될 수 없습니다. 이 `features_to_explain`매개변수는 숫자로 된 열과 범주형 열이 있는 테이블 형식의 데이터세트에서만 지원됩니다.
+ **num\$1cluster** – (선택사항) 기준 데이터세트를 계산하기 위해 데이터세트의 분할이 이루어지는 클러스터의 수입니다. 각 클러스터는 한 개의 기준 인스턴스를 계산하는 데 사용됩니다. `baseline`이 지정되지 않은 경우, SageMaker Clarify 처리 작업은 해당 테이블 형식 데이터세트를 `1`\$1`12`의 최적의 클러스터 수로 나누어 기준 데이터세트에 대한 계산을 시도하게 됩니다. 기준 인스턴스의 수는 SHAP 분석 런타임에 직접적인 영향을 미칩니다.
+ **num\$1samples** – (선택사항) Kernel SHAP 알고리즘에서 사용되는 샘플의 수입니다. `num_samples`이 지정되지 않은 경우, SageMaker Clarify 처리 작업은 자동으로 임의의 번호를 선택합니다. 샘플의 수는 합성 데이터세트 크기 및 작업 런타임 모두에 직접적인 영향을 미치게 됩니다.
+ **seed** – (선택사항) SHAP 설명자에서 유사 난수 생성기를 초기화하여 동일한 작업에 대해 일관된 SHAP 값을 생성하기 위해 사용되는 정수입니다. 시드가 지정되지 않은 경우, 동일한 작업이 실행될 때마다 해당 모델이 약간 다른 SHAP 값을 출력하게 될 수 있습니다.
+ **use\$1logit** - (선택사항) 사용자가 로짓 함수를 모델 예측에 적용하고자 한다는 것을 나타내는 부울 값입니다. 기본값은 `false`입니다. `use_logit`이 `true`인 경우, SHAP 값의 계산은 로그-승산비로 해석될 수 있는 로지스틱 회귀 계수를 사용하여 수행되게 됩니다.
+ **save\$1local\$1shap\$1values** – (선택사항) 사용자가 해당 데이터세트에 있는 각 레코드의 로컬 SHAP 값을 분석 결과에 포함시키고자 한다는 것을 나타내는 부울 값입니다. 기본값은 `false`입니다.
만약 기본 데이터세트가 여러 개의 파일로 분할되어 있거나 분산 처리가 활성화된 상태라면, `joinsource_name_or_index`매개변수를 사용하여 식별자 열도 함께 지정하세요. 식별자 열과 로컬 SHAP 값은 해당 분석 결과에 저장됩니다. 이렇게 하면 각 레코드를 해당 로컬 SHAP 값에 매핑할 수 있게 됩니다.
+ **agg\$1method** – (선택사항) 모든 인스턴스의 로컬 SHAP 값(각 인스턴스에 대한 SHAP 값)을 전역 SHAP 값(전체 데이터세트에 대한 SHAP 값)으로 집계하는 데 사용되는 메서드입니다. 기본값은 `mean_abs`입니다. 다음 메서드를 사용하여 SHAP 값을 집계할 수 있습니다.
+ **mean\$1abs** – 모든 인스턴스의 로컬 SHAP 절대값의 평균입니다.
+ **mean\$1sq** – 모든 인스턴스의 로컬 SHAP 값 제곱의 평균입니다.
+ **median** – 모든 인스턴스의 로컬 SHAP 값의 중앙값입니다.
+ **text\$1config** – 자연어 처리의 설명 가능성을 위해 필요합니다. 텍스트 열을 텍스트 형태로 취급하고 개별 텍스트 단위에 대한 설명을 제공하려면 이 구성을 포함하세요. 자연어 처리 설명 가능성을 위한 분석 구성의 예는 [자연어 처리의 설명 가능성을 위한 분석 구성](#clarify-analysis-configure-nlp-example) 섹션을 참조하세요.
+ **granularity** – 텍스트 열 분석을 위한 세분성의 단위입니다. 유효한 값은 `token`, `sentence`또는 `paragraph`입니다. **각 텍스트 단위는 특징으로 간주되며**, 로컬 SHAP 값이 각 단위에 대해 계산됩니다.
+ **language** – 텍스트 열의 언어입니다. 유효한 값은 **chinese**, **danish**, **dutch**, **english**, **french**, **german**, **greek**, **italian**, **japanese**, **lithuanian**, **multi-language**, **norwegian bokmål**, **polish**, **portuguese**, **romanian**, **russian**, **spanish**, **afrikaans**, **albanian**, **arabic**, **armenian**, **basque**, **bengali**, **bulgarian**, **catalan**, **croatian**, **czech**, **estonian**, **finnish**, **gujarati**, **hebrew**, **hindi**, **hungarian**, **icelandic**, **indonesian**, **irish**, **kannada**, **kyrgyz**, **latvian**, **ligurian**, **luxembourgish**, **macedonian**, **malayalam**, **marathi**, **nepali**, **persian**, **sanskrit**, **serbian**, **setswana**, **sinhala**, **slovak**, **slovenian**, **swedish**, **tagalog**, **tamil**, **tatar**, **telugu**, **thai**, **turkish**, **ukrainian**, **urdu**, **vietnamese**, **yoruba**입니다. 여러 언어를 혼합하여 사용하려면 `multi-language`를 입력하세요.
+ **max\$1top\$1token** – (선택사항) 전역 SHAP 값을 기준으로 한 상위 토큰의 최대 수입니다. 기본값은 `50`입니다. 데이터세트에 같은 토큰이 여러 번 나타날 수 있습니다. SageMaker Clalify 처리 작업은 각 토큰의 SHAP 값을 집계한 다음 해당 전역 SHAP 값을 기준으로 상위 토큰을 선택합니다. 선택한 상위 토큰의 전역 SHAP 값은 analysis.json 파일의 `global_top_shap_text`섹션에 포함됩니다.
+ 집계의 로컬 SHAP 값입니다.
+ **image\$1config** – 컴퓨터 비전의 설명 가능성을 위해 필요합니다. 이미지로 구성된 입력 데이터세트가 있는데 이를 분석하여 컴퓨터 비전 문제에서 설명 가능성을 구현하고자 한다면 이 구성을 포함하세요.
+ **model\$1type** – 모델의 유형입니다. 유효한 값으로는 다음이 포함됩니다.
+ 이미지 분류 모델의 경우 `IMAGE_CLASSIFICATION`.
+ 객체 감지 모델의 경우 `OBJECT_DETECTION`.
+ **max\$1objects** – model\$1type이 **OBJECT\$1DETECTION**인 경우에만 적용할 수 있습니다.컴퓨터 비전 모델에서 감지한 최대 객체 수가 신뢰도 점수를 기준으로 정렬됩니다. 신뢰도 점수를 기준으로 상위 max\$1objects보다 순위가 낮은 모든 객체는 필터링됩니다. 기본값은 `3`입니다.
+ **context** – model\$1type이 **OBJECT\$1DETECTION**인 경우에만 적용됩니다. 탐지된 객체에서 경계 상자의 주변 영역이 기준 이미지에 의해 가려지는지 여부를 나타냅니다. 유효한 값은 모두 마스킹하려면 `0`, 전혀 마스킹하지 않으려면 `1`입니다. 기본값은 1입니다.
+ **iou\$1threshold** – `model_type`이 **OBJECT\$1DETECTION**일 때만 적용 가능합니다.원래 탐지를 기준으로 예측을 평가하기 위한 최소한의 교차겹침결합(IOU) 지표입니다. IOU 지표가 높으면 예측된 상자와 실측된 탐지 상자 간에 겹치는 면적이 넓게 발생하게 됩니다. 기본값은 `0.5`입니다.
+ **num\$1segments** – (선택사항) 입력 이미지에서 레이블을 지정할 세그먼트의 대략적인 수를 결정하는 정수입니다. 각 이미지의 세그먼트는 특징으로 간주되며, 로컬 SHAP 값이 각 세그먼트에 대해 계산됩니다. 기본값은 `20`입니다.
+ **segment\$1compactness** – (선택사항) [scikit-image slic](https://scikit-image.org/docs/dev/api/skimage.segmentation.html#skimage.segmentation.slic) 메서드를 통해 생성된 이미지 세그먼트의 모양과 크기를 결정하는 정수입니다. 기본값은 `5`입니다.
+ **pdp** – 이 메서드를 포함하면 부분 종속성 도표(PDP)를 계산할 수 있습니다. PDP를 생성하기 위한 분석 구성의 예는 [부분 종속성 도표(PDP)의 계산](#clarify-analysis-configure-csv-example-pdp) 섹션을 참조하세요.
+ **features** – `shap`메서드가 요청되지 않은 경우에는 필수입니다. PDP 플롯을 계산하고 플로팅하기 위한 특징 이름 또는 인덱스의 배열입니다.
+ **top\$1k\$1features** – (선택사항) PDP 플롯을 생성하는 데 사용되는 상위 특징의 수를 지정합니다. `features`가 제공되지 않았는데 `shap`메서드는 요청된 경우라면, SageMaker Clarify 처리 작업이 해당 SHAP 속성을 기반으로 상위 특징을 선택하게 됩니다. 기본값은 `10`입니다.
+ **grid\$1resolution** – 숫자 값의 범위를 나누게 되는 버킷의 수입니다. 이는 PDP 플롯에 대한 그리드의 세분성을 지정하는 역할을 합니다.
+ **asymmetric\$1shapley\$1value** - 시계열 예측 모델에 대한 설명 가능성 지표를 계산하려면 이 메서드를 포함합니다. SageMaker Clarify 처리 작업은 비대칭 Shapley 값 알고리즘을 지원합니다. 비대칭 Shapley 값은 대칭 공리를 삭제하는 Shapley 값의 변형입니다. 자세한 내용은 [Asymmetric Shapley values: incorporating causal knowledge into model-agnostic explainability](https://arxiv.org/abs/1910.06358)를 참조하세요. 이러한 값을 사용하여 특성이 예측 결과에 어떻게 기여하는지 확인할 수 있습니다. 비대칭 Shapley 값은 예측 모델이 입력으로 사용하는 시계열 데이터의 시간 종속성을 고려합니다.
이 알고리즘에는 다음 파라미터가 포함되어 있습니다.
+ **direction** - 사용 가능한 유형은 `chronological`, `anti_chronological` 및 `bidirectional`입니다. 시간적 구조는 시간순 또는 시간 역순 또는 둘 다로 탐색할 수 있습니다. 시간순 설명은 첫 번째 단계부터 정보를 반복적으로 추가하여 구축됩니다. 시간 역순 설명은 마지막 단계에서 시작하여 거슬러 올라가면서 정보를 추가합니다. 주가 예측과 같이 최신성 편향이 있는 경우 시간 역순이 더 적절할 수 있습니다.
+ **granularity** - 사용할 설명 세분화입니다. 사용 가능한 세분화 옵션은 다음과 같습니다.
+ **timewise** - `timewise` 설명은 저렴하며 과거 n번째 날의 정보가 향후 m번째 날의 예측에 얼마나 기여했는지 파악하는 등 특정 시간 단계에 대한 정보만 제공합니다. 결과 어트리뷰션은 개별적으로 정적 공변량을 설명하지 않으며 대상 시계열과 관련 시계열을 구분하지 않습니다.
+ **fine\$1grained** – `fine_grained` 설명은 더 컴퓨팅 집약적이지만 입력 변수의 모든 어트리뷰션에 대한 전체 분석을 제공합니다. 이 메서드는 대략적인 설명을 계산하여 런타임을 줄입니다. 자세한 내용은 다음 `num_samples` 파라미터를 참조하세요.
**참고**
`fine_grained` 설명은 `chronological` 순서만 지원합니다.
+ **num\$1samples** – (선택 사항) 이 인수는 `fine_grained` 설명에 필요합니다. 숫자가 클수록 근사치가 더 정확합니다. 이 숫자는 입력 특성의 차원에 따라 조정되어야 합니다. 일반적으로 결과가 너무 크지 않은 경우 이 변수를 *(1 \$1 max(관련 시계열 수, 정적 공변량 수))^2*로 설정합니다.
+ **baseline** – (선택 사항) 해당 데이터세트(배경 데이터라고도 함)에 대한 연합 외부의 값을 대체하는 기준 구성입니다. 다음 코드 조각은 기준 구성의 예시를 보여줍니다.
```
{
"related_time_series": "zero",
"static_covariates": {
: [0, 2],
: [-1, 1]
},
"target_time_series": "zero"
}
```
+ 대상 시계열 또는 관련 시계열과 같은 시간 데이터의 경우 기준 값 유형은 다음 값 중 하나일 수 있습니다.
+ `zero` - 모든 연합 외부 값이 0.0으로 대체됩니다.
+ `mean` - 모든 연합 외부 값이 시계열의 평균으로 대체됩니다.
+ 정적 공변량의 경우 모델 요청이 정적 공변량 값을 취하는 경우에만 기준 항목을 제공해야 하며, 이 경우 이 필드가 필요합니다. 모든 항목에 대한 기준을 목록으로 제공해야 합니다. 예를 들어 데이터세트에 정적 공변량이 두 개 있는 경우 기준 구성은 다음과 같을 수 있습니다.
```
"static_covariates": {
: [1, 1],
: [0, 1]
}
```
앞의 예에서 ** 및 **는 데이터세트의 항목 ID입니다.
+ **report** – (선택사항) 이 객체를 사용하면 분석 보고서를 사용자 지정할 수 있습니다. 시계열 설명 작업에는 이 파라미터가 지원되지 않습니다. 분석 결과에서는 동일한 내용의 보고서가 Jupyter Notebook 보고서, HTML 보고서, PDF 보고서의 3가지 사본으로 제공됩니다. 해당 객체에는 다음 매개변수가 있습니다.
+ **name** – 보고서 파일의 파일 이름입니다. 예를 들어 `name`이 **MyReport**라면, 해당 보고서 파일의 이름은 `MyReport.ipynb`, `MyReport.html`, `MyReport.pdf`가 됩니다. 기본값은 `report`입니다.
+ **title** – (선택사항) 보고서의 제목 문자열입니다. 기본값은 **SageMaker AI Analysis Report**입니다.
+ **predictor** – 분석을 위해 모델이 수행한 예측이 필요한 경우 필수입니다. `shap`, `asymmetric_shapley_value`, `pdp` 또는 `post_training_bias` 메서드를 요청했지만 예측 레이블이 입력 데이터세트의 일부로서 제공되지 않는 경우를 예로 들 수 있습니다. 다음은 `predictor`와 함께 사용되는 매개변수입니다.
+ **model\$1name** – [CreateModel](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html) API를 통해 생성한 SageMaker AI 모델의 이름입니다. 사용자가 endpoint\$1name 대신에 `model_name`을 지정할 경우, SageMaker Clarify 처리 작업은 **섀도우 엔드포인트**라고 하는 모델 이름을 사용하여 임시 엔드포인트를 생성한 다음 해당 엔드포인트에서 예측을 가져오게 됩니다. 이 작업은 계산이 완료되고 나면 해당 섀도우 엔드포인트를 삭제합니다. 모델이 다중 모델인 경우 `target_model` 파라미터를 반드시 지정해야 합니다. 다중 모델 엔드포인트에 대한 자세한 내용은 [다중 모델 엔드포인트](multi-model-endpoints.md) 섹션을 참조하세요.
+ **endpoint\$1name\$1prefix** – (선택사항) 섀도우 엔드포인트를 위한 사용자 지정 이름 접두사입니다. 사용자가 `endpoint_name`대신에 `model_name`을 제공할 경우 적용됩니다. 예를 들어, 대상 엔드포인트에 대한 액세스를 엔드포인트 이름을 기준으로 제한하려는 경우라면 `endpoint_name_prefix`를 입력하세요. 접두사는 [EndpointName](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html#sagemaker-CreateEndpoint-request-EndpointName) 패턴과 일치해야 하며, 허용되는 최대 길이는 `23`입니다. 기본값은 `sm-clarify`입니다.
+ **initial\$1instance\$1count** – 섀도우 엔드포인트의 인스턴스 수를 지정합니다. 사용자가 endpoint\$1name 대신에 model\$1name을 제공하는 경우 필수입니다. `initial_instance_count`의 값이 해당 작업의 [InstanceCount](https://docs.aws.amazon.com//sagemaker/latest/APIReference/API_ProcessingClusterConfig.html#sagemaker-Type-ProcessingClusterConfig-InstanceCount)와 달라도 되지만, 가급적 1:1 비율을 사용하는 것이 좋습니다.
+ **instance\$1type** – 섀도우 엔드포인트의 인스턴스 유형을 지정합니다. 사용자가 `endpoint_name`대신에 `model_name`을 제공할 경우 필수입니다. 예를 들어, `instance_type`은 “ml.m5.large”로 설정이 가능합니다. `instance_type`으로 지정된 값이 모델의 추론 시간을 줄이는 데 도움이 되는 경우도 있습니다. 예를 들어, 일반적으로 자연어 처리 모델 및 컴퓨터 비전 모델을 효율적으로 실행하려면 그래픽 처리 장치(GPU) 인스턴스 유형이 필요합니다.
+ **endpoint\$1name** – [CreateEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html) API를 통해 생성한 SageMaker AI 엔드포인트의 이름입니다. 제공된 경우, `endpoint_name`이 `model_name`매개변수보다 우선 적용됩니다. 기존 엔드포인트를 사용하면 섀도우 엔드포인트의 부트스트랩 시간이 단축되지만, 이로 인해 해당 엔드포인트의 부하가 크게 증가할 수도 있습니다. 또한 일부 분석 메서드(예: `shap`및 `pdp`)의 경우 합성 데이터세트를 생성하여 엔드포인트로 전송하기도 합니다. 이로 인해 엔드포인트의 지표나 캡처된 데이터가 합성 데이터로 오염되어 실제 사용량을 정확하게 반영하지 못하게 될 수 있습니다. 이러한 이유로 SageMaker Clarify 분석에 기존 프로덕션의 엔드포인트를 사용하는 것은 일반적으로 권장되지 않습니다.
+ **target\$1model** – SageMaker AI [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax) API의 TargetModel 파라미터에 전달되는 문자열 값입니다. 모델(model\$1name 매개변수로 지정됨) 또는 엔드포인트(endpoint\$1name 매개변수로 지정됨)가 다중 모델인 경우에 필요합니다. 다중 모델 엔드포인트에 대한 자세한 내용은 [다중 모델 엔드포인트](multi-model-endpoints.md) 섹션을 참조하세요.
+ **custom\$1attributes** – (선택사항) 사용자가 엔드포인트에 제출된 추론 요청에 대한 추가 정보를 제공할 수 있게 해주는 문자열입니다. SageMaker AI [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax) API의 `CustomAttributes` 파라미터에 전달되는 문자열 값입니다.
+ **content\$1type** – 엔드포인트에서 예측을 가져오는 데 사용되는 모델 입력 형식입니다. 제공 시, 이는 SageMaker AI [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax) API의 `ContentType` 파라미터에 전달됩니다.
+ 컴퓨터 비전 설명 가능성 용도인 경우, 유효한 값은 **image/jpeg**, **image/png**또는 **application/x-npy**입니다. `content_type`이 제공되지 않으면 기본값은 **image/jpeg**입니다.
+ 시계열 예측 설명 가능성의 경우 유효한 값은 **application/json**입니다.
+ 다른 유형의 설명 가능성 용도인 경우, 유효한 값은 **text/csv**, **application/jsonlines,**및 **application/json**입니다. `dataset_type`이 **application/x-parquet**인 경우 `content_type`의 값이 필요합니다. 미지정 시 `content_type`은 `dataset_type`매개변수의 값이 기본값으로 적용됩니다.
+ **accept\$1type** – 엔드포인트에서 예측을 가져오는 데 사용되는 모델 출력의 형식입니다. `accept_type`의 값이 SageMaker AI [InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#RequestSyntax) API의 `Accept` 파라미터에 전달됩니다.
+ 컴퓨터 비전 설명 가능성 용도인 경우, `model_type`이 “OBJECT\$1DETECTION”이면 `accept_type`은 **application/json**이 기본값으로 적용됩니다.
+ 시계열 예측 설명 가능성의 경우 유효한 값은 **application/json**입니다.
+ 다른 유형의 설명 가능성 용도인 경우, 유효한 값은 **text/csv**, **application/jsonlines**및 **application/json**입니다. `accept_type`의 값이 제공되지 않은 경우, `content_type`매개변수 값이 `accept_type`의 기본값으로 적용됩니다.
+ **content\$1template** – 데이터세트 레코드로부터 모델 입력을 구성하는 데 사용되는 템플릿 문자열입니다. `content_template` 매개변수는 `content_type`매개변수의 값이 `application/jsonlines`또는 `application/json`인 경우에만 필수적으로 사용됩니다.
`content_type` 매개변수가 `application/jsonlines`인 경우, 해당 템플릿에는 자리 표시자 `$features`가 하나만 있어야 하며, 이 자리 표시자는 런타임 시 특징의 목록으로 대체됩니다. 예를 들어 템플릿이 `"{\"myfeatures\":$features}"`이고 레코드에 숫자로 된 3개의 특징 값 `1`, `2`및 `3`이 있는 경우라면, 해당 레코드는 JSON Line `{"myfeatures":[1,2,3]}`의 형태로 모델에 전송됩니다.
`content_type`이 `application/json`일 때, 해당 템플릿의 자리 표시자는 `$record`또는 `records`중 하나일 수 있습니다. 만약 자리 표시자가 `record`라면, 단일 레코드는 해당 템플릿이 `record_template`에 적용되어 있는 레코드로 대체됩니다. 이 경우에는 한 번에 하나의 레코드만 모델로 전송이 이루어집니다. 만약 자리 표시자가 `$records`라면, 해당 레코드는 `record_template`에서 제공한 각각의 템플릿을 가지는 레코드 목록으로 대체됩니다.
+ **record\$1template** – 데이터세트 인스턴스로부터 모델 입력의 개별 레코드를 구성하는 데 사용되는 템플릿 문자열입니다. 이는 `content_type`이 `application/json`일 때만 필수적으로 사용됩니다. 템플릿 문자열은 다음 중 하나를 포함할 수 있습니다.
+ 특징 값의 배열로 대체될 자리 표시자 `$features`매개변수. 선택 사항인 추가적인 자리 표시자가 `$feature_names`로 특징 열 헤더 이름을 대체할 수 있습니다. 이 선택적 자리 표시자는 특징 이름의 배열로 대체되게 됩니다.
+ 키-값 쌍, 특징 이름 및 특징 값으로 대체될 단 1개의 자리 표시자(`$features_kvp`).
+ `headers` 구성에 포함된 특징. 예를 들어, 자리 표시자 구문 `"${A}"`로 표시된 `A`라는 특징 이름은 `A`의 특징 값으로 대체되게 됩니다.
`record_template`의 값은 `content_template`과 함께 모델 입력을 구성하는 데 사용됩니다. 다음은 콘텐츠 및 레코드 템플릿을 사용하여 모델 입력을 구성하는 방법을 보여주는 구성 예제입니다.
다음 코드 예제에서 헤더와 특징은 다음과 같이 정의됩니다.
+ ``headers`:["A", "B"]`
+ ``features`:[[0,1], [3,4]]`
예제 모델 입력은 다음과 같습니다.
```
{
"instances": [[0, 1], [3, 4]],
"feature_names": ["A", "B"]
}
```
이전 예제 모델 입력을 구성하기 위한 예제 매개변수 `content_template`및 `record_template`의 값은 다음과 같습니다.
+ `content_template: "{\"instances\": $records, \"feature_names\": $feature_names}"`
+ `record_template: "$features"`
다음 코드 예제에서 헤더와 특징은 다음과 같이 정의됩니다.
```
[
{ "A": 0, "B": 1 },
{ "A": 3, "B": 4 },
]
```
이전 예제 모델 입력을 구성하기 위한 예제 매개변수 ` content_template`및 `record_template`의 값은 다음과 같습니다.
+ `content_template: "$records"`
+ `record_template: "$features_kvp"`
다음은 이전 예제 모델 입력을 구성하기 위한 대체 코드의 예제입니다.
+ `content_template: "$records"`
+ `record_template: "{\"A\": \"${A}\", \"B\": \"${B}\"}"`
다음 코드 예제에서 헤더와 특징은 다음과 같이 정의됩니다.
```
{ "A": 0, "B": 1 }
```
위 예제를 구성하기 위한 예제 매개변수 content\$1template 및 record\$1template 값에 대한 이전 예제 모델의 입력은 다음과 같습니다.
+ `content_template: "$record"`
+ `record_template: "$features_kvp"`
더 많은 예시는 [시계열 데이터에 대한 엔드포인트 요청](clarify-processing-job-data-format-time-series-request-jsonlines.md)를 참조합니다.
+ **label** – (선택 사항) 편향 분석을 위해 모델 출력으로부터 예측된 레이블을 추출하는 데 사용되는 0으로 시작하는 정수 인덱스 또는 JMESPath 표현식 문자열입니다. 모델이 멀티클래스이고 `label`매개변수가 해당 모델 출력에서 예측된 레이블을 모두 추출하는 경우, 다음이 적용됩니다. 이 특성은 시계열에 지원되지 않습니다.
+ 모델 출력으로부터 일치하는 확률(또는 점수)을 가져오려면 `probability`매개변수가 필요합니다.
+ 최고 점수의 예측 레이블이 선택됩니다.
`label`의 값은 다음과 같이 accept\$1type 매개변수의 값에 따라 달라지게 됩니다.
+ 만약 `accept_type`이 **text/csv**라면, `label`은 해당 모델 출력에 포함된 모든 예측 레이블의 인덱스입니다.
+ 만약 `accept_type`이 **application/jsonlines**또는 **application/json**이라면, `label`은 예측 레이블을 가져오기 위해 해당 모델의 출력값에 적용되는 JMESPath 표현식입니다.
+ **label\$1headers** – (선택 사항) 레이블이 데이터세트에서 가져올 수 있는 값의 배열입니다. 편향 분석을 요청하는 경우, 모델 출력으로부터 일치하는 확률 값(점수)을 가져오려면 `probability`매개변수도 필요하며, 이때 가장 높은 점수의 예측 레이블이 선택됩니다. 설명 가능성 분석을 요청하는 경우, 레이블 헤더는 분석 보고서를 꾸미는 데 사용됩니다. 컴퓨터 비전의 설명 가능성을 위해서는 `label_headers`에 대한 값이 필요합니다. 예를 들어, 멀티클래스 분류 문제에서 레이블에 적용 가능한 세 개의 값 **bird**, **cat**및 **dog**이 있는 경우라면, `label_headers`를 `["bird","cat","dog"]`으로 설정해야 합니다.
+ **probability** – (선택 사항) 설명 가능성 분석(시계열 설명 가능성 제외)을 위해 확률(점수)을 추출하거나 편향 분석을 위해 예측 레이블을 선택하는 데 사용되는 0으로 시작하는 정수 인덱스 또는 JMESPath 표현식 문자열입니다. `probability`의 값은 다음과 같이 `accept_type`매개변수의 값에 따라 달라지게 됩니다.
+ 만약 `accept_type`이 **text/csv**라면, `probability`는 해당 모델 출력에 포함된 확률(점수)의 인덱스입니다. `probability`가 제공되지 않으면 전체 모델 출력이 확률(점수)인 것으로 간주됩니다.
+ 만약 `accept_type`이 JSON 데이터(**application/jsonlines** 또는 **application/json**)라면, `probability`는 해당 모델 출력으로부터 확률(점수)을 추출하는 데 사용되는 JMESPath 표현식이어야 합니다.
+ **time\$1series\$1predictor\$1config** – (선택 사항) 시계열 설명 가능성에만 사용됩니다. `dataset_uri`에서 S3 URI로 전달된 데이터에서 데이터를 올바르게 구문 분석하는 방법을 SageMaker Clarify 프로세서에 지시하는 데 사용됩니다.
+ **예측** - 예측 결과를 추출하는 데 사용되는 JMESPath 표현식입니다.
## 예제 분석 구성 파일
다음 섹션에는 CSV 형식이나 JSON Lines 형식으로 된 데이터 그리고 자연어 처리(NLP), 컴퓨터 비전(CV) 및 시계열(TS) 설명 가능성을 위한 예시 분석 구성 파일이 포함되어 있습니다.
### CSV 데이터세트를 위한 분석 구성
다음 예제는 CSV 포맷의 테이블 형식 데이터세트를 위해 편향 분석과 설명 가능성 분석을 구성하는 방법을 보여줍니다. 이 예제에서 수신되는 데이터세트에는 4개의 특징 열과 1개의 바이너리 레이블 열(`Target`)이 포함되어 있습니다. 데이터 세트의 내용은 다음과 같습니다. 레이블의 값이 `1`이면 긍정적인 결과임을 나타냅니다. 데이터세트는 `dataset`처리의 입력을 통해 SageMaker Clarify 작업에 제공됩니다.
```
"Target","Age","Gender","Income","Occupation"
0,25,0,2850,2
1,36,0,6585,0
1,22,1,1759,1
0,48,0,3446,1
...
```
다음 섹션은 훈련 전 및 훈련 후 편향 지표, SHAP 값, 그리고 CSV 포맷의 데이터세트에서의 특징 중요도를 표시해주는 부분 종속성 도표(PDP)를 계산하는 방법을 보여줍니다.
#### 모든 훈련 전 편향 지표의 계산
이 예제 구성은 이전 샘플 데이터세트가 **Gender**값이 `0`인 샘플에 대해 우호적으로 편향되어 있는지 여부를 측정하는 방법을 보여줍니다. 다음 분석 구성은 SageMaker Clalify 처리 작업으로 하여금 해당 데이터세트에 대한 모든 훈련 전 편향 지표를 계산하도록 지시합니다.
```
{
"dataset_type": "text/csv",
"label": "Target",
"label_values_or_threshold": [1],
"facet": [
{
"name_or_index": "Gender",
"value_or_threshold": [0]
}
],
"methods": {
"pre_training_bias": {
"methods": "all"
}
}
}
```
#### 모든 훈련 후 편향 지표의 계산
훈련 전에는 훈련 전 편향 지표를 계산할 수 있습니다. 하지만 훈련 후 편향 지표를 계산하려면 먼저 훈련된 모델이 준비되어야 합니다. 다음 예제는 데이터를 CSV 포맷으로 내보내는 바이너리 분류 모델이 출력한 결과입니다. 이 예제 출력에서는 각 행마다 2개의 열이 있습니다. 첫 번째 열에는 예측 레이블이 포함되고, 두 번째 열에는 해당 레이블에 대한 확률 값이 포함됩니다.
```
0,0.028986845165491
1,0.825382471084594
...
```
다음 구성 예제는 SageMaker Clarify 처리 작업으로 하여금 해당 데이터세트와 모델 출력의 예측을 사용하여 가능한 모든 편향 지표를 계산하도록 지시합니다. 이 예시에서는 모델이 SageMaker AI 엔드포인트인 `your_endpoint`에 배포되어 있습니다.
**참고**
다음 예제 코드에서는 매개변수 `content_type`과 `accept_type`이 설정되지 않았습니다. 따라서 이는 dataset\$1type 매개변수의 값에 해당하는 `text/csv`를 자동으로 사용하게 됩니다.
```
{
"dataset_type": "text/csv",
"label": "Target",
"label_values_or_threshold": [1],
"facet": [
{
"name_or_index": "Gender",
"value_or_threshold": [0]
}
],
"methods": {
"pre_training_bias": {
"methods": "all"
},
"post_training_bias": {
"methods": "all"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"label": 0
}
}
```
#### SHAP 값의 계산
다음 예제 분석 구성은 작업으로 하여금 `Target`열을 레이블로 지정하고 나머지 모든 열은 특징으로 지정하는 SHAP 값을 계산하도록 지시합니다.
```
{
"dataset_type": "text/csv",
"label": "Target",
"methods": {
"shap": {
"num_clusters": 1
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"probability": 1
}
}
```
이 예제에서는 SHAP `baseline`매개변수가 생략되어 있고 `num_clusters`매개변수의 값은 `1`입니다. 이를 통해 SageMaker Clarify 프로세서가 SHAP 기준 샘플 하나를 계산하도록 지시됩니다. 이 예제에서는 확률이 `1`로 설정되어 있습니다. 이를 통해 SageMaker Clarify 처리 작업이 해당 모델 출력의 두 번째 열에서 확률 점수를 추출하도록 (0으로 시작하는 인덱싱을 사용하여) 지시됩니다.
#### 부분 종속성 도표(PDP)의 계산
다음 예제는 PDP를 사용하여 분석 보고서에서 `Income`특징의 중요도를 표시하는 방법을 보여줍니다. 보고서 매개변수는 SageMaker Clarify 처리 작업으로 하여금 보고서를 생성하도록 지시합니다. 작업이 완료되면, 생성된 보고서가 `analysis_result`위치에 report.pdf 형식으로 저장됩니다. `grid_resolution` 매개변수는 해당 특징 값의 범위를 `10`개의 버킷으로 분할합니다. 다음 예제에서 지정된 매개변수들 모두는 SageMaker Clarify 처리 작업으로 하여금 x축에 `10`개의 세그먼트가 있는 `Income`PDP 그래프가 포함된 보고서를 생성하도록 지시합니다. y축은 `Income`이 예측에 미치는 한계 영향을 표시하게 됩니다.
```
{
"dataset_type": "text/csv",
"label": "Target",
"methods": {
"pdp": {
"features": ["Income"],
"grid_resolution": 10
},
"report": {
"name": "report"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"probability": 1
},
}
```
#### 편향 지표 및 특징 중요도 모두에 대한 계산
이전 구성 예제의 모든 메서드를 단일 분석 구성 파일로 결합하여 하나의 작업만으로 모든 계산을 수행하는 것이 가능합니다. 다음 예제는 모든 단계를 결합했을 때의 분석 구성을 보여줍니다.
이 예제에서 `probability`매개변수는 확률이 두 번째 열에 포함되어 있음을 나타내기 위해 (0으로 시작하는 인덱싱을 사용하여) `1`로 설정되어 있습니다. 그러나 편향 분석에는 예측 레이블이 필요하므로, 확률 점수를 바이너리 레이블로 변환할 수 있도록 `probability_threshold`매개변수가 `0.5`로 설정되었습니다. 이 예제에서는 부분 종속성 도표 `pdp`메서드의 `top_k_features`매개변수가 `2`로 설정되어 있습니다. 이를 통해 SageMaker Clarify 처리 작업이 가장 큰 전역 SHAP 값을 가진 상위 특징 `2`개를 대상으로 부분 종속성 도표(PDP)를 계산하도록 지시됩니다.
```
{
"dataset_type": "text/csv",
"label": "Target",
"probability_threshold": 0.5,
"label_values_or_threshold": [1],
"facet": [
{
"name_or_index": "Gender",
"value_or_threshold": [0]
}
],
"methods": {
"pre_training_bias": {
"methods": "all"
},
"post_training_bias": {
"methods": "all"
},
"shap": {
"num_clusters": 1
},
"pdp": {
"top_k_features": 2,
"grid_resolution": 10
},
"report": {
"name": "report"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"probability": 1
}
}
```
모델을 엔드포인트에 배포하지 않고 그 대신 `model_name` 파라미터를 사용하여 SageMaker Clarify 처리 작업에 해당 SageMaker AI 모델의 이름을 제공하는 것도 가능합니다. 다음 예제는 **your\$1model**이라는 이름의 모델을 지정하는 방법을 보여줍니다. SageMaker Clarify 처리 작업은 해당 구성을 사용하여 섀도우 엔드포인트를 생성하게 됩니다.
```
{
...
"predictor": {
"model_name": "your_model",
"initial_instance_count": 1,
"instance_type": "ml.m5.large",
"probability": 1
}
}
```
### JSON Lines 데이터세트를 위한 분석 구성
다음 예제는 JSON Lines 포맷의 테이블 형식 데이터세트를 위해 편향 분석과 설명 가능성 분석을 구성하는 방법을 보여줍니다. 이 예시에서 수신되는 데이터세트는 이전 섹션에서와 동일한 데이터이지만, 이번에는 SageMaker AI JSON Lines 조밀 형식으로 되어 있습니다. 각 라인은 유효한 JSON 객체입니다. “Features” 키는 특징 값의 배열을 가리키고, “Label” 키는 실측 레이블을 가리킵니다. 데이터세트는 "dataset" 처리의 입력을 통해 SageMaker Clarify 작업에 제공됩니다. JSON 라인에 관한 자세한 정보는 [JSONLINES 요청 형식](cdf-inference.md#cm-jsonlines) 항목을 참조하세요.
```
{"Features":[25,0,2850,2],"Label":0}
{"Features":[36,0,6585,0],"Label":1}
{"Features":[22,1,1759,1],"Label":1}
{"Features":[48,0,3446,1],"Label":0}
...
```
다음 섹션은 훈련 전 및 훈련 후 편향 지표, SHAP 값, 그리고 JSON Lines 포맷의 데이터세트에서의 특징 중요도를 표시해주는 부분 종속성 도표(PDP)를 계산하는 방법을 보여줍니다.
#### 훈련 전 편향 지표의 계산
`Gender` 값이 `0`인 대상에서 훈련 전 편향 지표를 측정하기 위한 레이블, 특징, 형식 및 방법을 지정합니다. 다음 예제에서는 `headers`매개변수가 특징 이름을 먼저 제공합니다. 레이블 이름은 마지막에 제공됩니다. 마지막 헤더는 통상적으로 레이블 헤더입니다.
SageMaker Clarify 처리 작업이 각 레코드에서 특징 배열을 추출할 수 있도록 `features`매개변수가 JMESPath 표현식 “Features”로 설정되었습니다. SageMaker Clarify 처리 작업이 각 레코드에서 실측 레이블을 추출할 수 있도록 `label`매개변수가 JMESPath 표현식 “Label”로 설정되었습니다. 다음과 같이 패싯 이름을 사용하여 민감한 속성을 지정합니다.
```
{
"dataset_type": "application/jsonlines",
"headers": ["Age","Gender","Income","Occupation","Target"],
"label": "Label",
"features": "Features",
"label_values_or_threshold": [1],
"facet": [
{
"name_or_index": "Gender",
"value_or_threshold": [0]
}
],
"methods": {
"pre_training_bias": {
"methods": "all"
}
}
}
```
#### 모든 편향 지표의 계산
훈련 후 편향 지표를 계산하려면 먼저 훈련된 모델이 준비되어야 합니다. 다음 예제는 JSON Lines 데이터를 해당 예제에서의 형식으로 내보내는 바이너리 분류 모델에서의 결과입니다. 모델 출력의 각 행은 유효한 JSON 객체입니다. `predicted_label` 키는 예측 레이블을 가리키고, `probability`키는 확률 값을 가리킵니다.
```
{"predicted_label":0,"probability":0.028986845165491}
{"predicted_label":1,"probability":0.825382471084594}
...
```
`your_endpoint`라는 SageMaker AI 엔드포인트에 모델을 배포할 수 있습니다. 다음 예제 분석 구성은 SageMaker Clalify 처리 작업으로 하여금 해당 데이터 세트와 모델 모두에서 가능한 모든 편향 지표를 계산하도록 지시합니다. 이 예제에서는 `content_type`및 `accept_type`매개변수가 설정되어 있지 않습니다. 따라서 이는 dataset\$1type 매개변수의 값에 해당하는 `application/jsonlines`를 사용하도록 자동으로 설정됩니다. SageMaker Clarify 처리 작업은 `content_template`매개변수를 사용하여 `$features`자리 표시자를 특징의 배열로 대체함으로써 모델 입력을 구성합니다.
```
{
"dataset_type": "application/jsonlines",
"headers": ["Age","Gender","Income","Occupation","Target"],
"label": "Label",
"features": "Features",
"label_values_or_threshold": [1],
"facet": [
{
"name_or_index": "Gender",
"value_or_threshold": [0]
}
],
"methods": {
"pre_training_bias": {
"methods": "all"
},
"post_training_bias": {
"methods": "all"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "{\"Features\":$features}",
"label": "predicted_label"
}
}
```
#### SHAP 값의 계산
SHAP 분석에는 실측 레이블이 필요하지 않으므로 `label`매개변수는 생략됩니다. 이 예제에서는 `headers`매개변수도 생략되었습니다. 따라서 SageMaker Calify 처리 작업에서는 자리 표시자를 생성할 때 특징 헤더에는 `column_0`또는 `column_1`을, 레이블 헤더에는 `label0`을 사용하는 등 일반적인 이름을 적용해야 합니다. 분석 결과의 가독성을 높이기 위해 `headers`및 `label`에 각각의 값을 지정할 수 있습니다. 확률 매개변수가 JMESPath 표현식 `probability`로 설정되었으므로, 해당 확률 값이 모델의 출력으로부터 추출됩니다. 다음은 SHAP 값을 계산하는 예제입니다.
```
{
"dataset_type": "application/jsonlines",
"features": "Features",
"methods": {
"shap": {
"num_clusters": 1
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "{\"Features\":$features}",
"probability": "probability"
}
}
```
#### 부분 종속성 도표(PDP)의 계산
다음 예제는 PDP에서 “Income”의 중요도를 표시하는 방법을 보여줍니다. 이 예제에서 특징 헤더는 제공되지 않습니다. 따라서 `pdp`메서드의 `features`매개변수는 해당 특징 열의 위치를 참조할 수 있도록 반드시 0으로 시작하는 인덱스를 사용해야 합니다. `grid_resolution` 매개변수는 해당 특징 값의 범위를 `10`개의 버킷으로 분할합니다. 이 예제에 나와 있는 매개변수들 모두는 SageMaker Clarify 처리 작업으로 하여금 x축에 `10`개의 세그먼트가 있는 `Income`PDP 그래프가 포함된 보고서를 생성하도록 지시합니다. y축은 `Income`이 예측에 미치는 한계 영향을 표시하게 됩니다.
```
{
"dataset_type": "application/jsonlines",
"features": "Features",
"methods": {
"pdp": {
"features": [2],
"grid_resolution": 10
},
"report": {
"name": "report"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "{\"Features\":$features}",
"probability": "probability"
}
}
```
#### 편향 지표 및 특징 중요도 모두에 대한 계산
이전의 모든 메서드를 단일 분석 구성 파일로 결합하여 하나의 작업만으로 모든 계산을 수행하는 것이 가능합니다. 다음 예제는 모든 단계를 결합했을 때의 분석 구성을 보여줍니다. 이 예제에서는 `probability`매개변수가 설정되어 있습니다. 그러나 편향 분석에는 예측 레이블이 필요하므로, 확률 점수를 바이너리 레이블로 변환할 수 있도록 `probability_threshold`매개변수가 `0.5`로 설정되었습니다. 이 예제에서는 `pdp`메서드의 `top_k_features`매개변수가 `2`로 설정되어 있습니다. 이를 통해 SageMaker Clarify 처리 작업이 가장 큰 전역 SHAP 값을 가진 상위 특징 `2`개를 대상으로 PDP를 계산하도록 지시됩니다.
```
{
"dataset_type": "application/jsonlines",
"headers": ["Age","Gender","Income","Occupation","Target"],
"label": "Label",
"features": "Features",
"probability_threshold": 0.5,
"label_values_or_threshold": [1],
"facet": [
{
"name_or_index": "Gender",
"value_or_threshold": [0]
}
],
"methods": {
"pre_training_bias": {
"methods": "all"
},
"post_training_bias": {
"methods": "all"
},
"shap": {
"num_clusters": 1
},
"pdp": {
"top_k_features": 2,
"grid_resolution": 10
},
"report": {
"name": "report"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "{\"Features\":$features}",
"probability": "probability"
}
}
```
### JSON 데이터세트를 위한 분석 구성
다음 예제는 JSON 포맷의 테이블 형식 데이터세트를 위해 편향 분석과 설명 가능성 분석을 구성하는 방법을 보여줍니다. 이 예시에서 수신되는 데이터세트는 이전 섹션에서와 동일한 데이터이지만, 이번에는 SageMaker AI JSON 조밀 형식으로 되어 있습니다. JSON 라인에 관한 자세한 정보는 [JSONLINES 요청 형식](cdf-inference.md#cm-jsonlines) 항목을 참조하세요.
전체 입력 요청이 유효한 JSON으로, 그 외부 구조는 목록이고 각 요소는 레코드의 데이터에 해당합니다. 각각의 레코드에서 `Features`키는 특징 값의 배열을 가리키고, `Label`키는 실측 레이블을 가리킵니다. 데이터세트는 `dataset`처리의 입력을 통해 SageMaker Clarify 작업에 제공됩니다.
```
[
{"Features":[25,0,2850,2],"Label":0},
{"Features":[36,0,6585,0],"Label":1},
{"Features":[22,1,1759,1],"Label":1},
{"Features":[48,0,3446,1],"Label":0},
...
]
```
다음 섹션은 훈련 전 및 훈련 후 편향 지표, SHAP 값, 그리고 JSON Lines 포맷의 데이터세트에서의 특징 중요도를 표시해주는 부분 종속성 도표(PDP)를 계산하는 방법을 보여줍니다.
#### 훈련 전 편향 지표의 계산
`Gender` 값이 `0`인 대상에서 훈련 전 편향 지표를 측정하기 위한 레이블, 특징, 형식 및 방법을 지정합니다. 다음 예제에서는 `headers`매개변수가 특징 이름을 먼저 제공합니다. 레이블 이름은 마지막에 제공됩니다. JSON 데이터세트의 경우, 마지막 헤더는 레이블 헤더입니다.
`features` 매개변수는 2D 배열 또는 행렬을 추출하는 JMESPath 표현식으로 설정되었습니다. 이 행렬의 각 행에는 각 레코드의 `Features`목록이 반드시 포함되어야 합니다. `label` 매개변수는 실측 레이블의 목록을 추출하는 JMESPath 표현식으로 설정되었습니다. 이 목록의 각 요소에는 레코드의 레이블이 반드시 포함되어야 합니다.
다음과 같이 패싯 이름을 사용하여 민감한 속성을 지정합니다.
```
{
"dataset_type": "application/json",
"headers": ["Age","Gender","Income","Occupation","Target"],
"label": "[*].Label",
"features": "[*].Features",
"label_values_or_threshold": [1],
"facet": [
{
"name_or_index": "Gender",
"value_or_threshold": [0]
}
],
"methods": {
"pre_training_bias": {
"methods": "all"
}
}
}
```
#### 모든 편향 지표의 계산
훈련 후 편향 지표를 계산하려면 먼저 훈련된 모델이 준비되어야 합니다. 다음 코드 예제는 JSON 데이터를 해당 예제에서의 형식으로 내보내는 바이너리 분류 모델에서의 결과입니다. 이 예제에서 `predictions`아래의 각 요소는 레코드의 예측 출력에 해당합니다. 예제 코드에 포함되어 있는 `predicted_label`키는 예측 레이블을 가리키고, `probability`키는 확률 값을 가리킵니다.
```
{
"predictions": [
{"predicted_label":0,"probability":0.028986845165491},
{"predicted_label":1,"probability":0.825382471084594},
...
]
}
```
`your_endpoint`라는 SageMaker AI 엔드포인트에 모델을 배포할 수 있습니다.
다음 예제에서는 매개변수 `content_type`과 `accept_type`이 설정되지 않았습니다. 따라서 `content_type`및 `accept_type`은 `dataset_type`매개변수의 값에 해당하는 `application/json`을 사용하도록 자동으로 설정됩니다. 그러면 SageMaker Clatify 처리 작업이 `content_template`매개변수를 사용하여 모델 입력을 구성하게 됩니다.
다음 예제에서는 `$records`자리 표시자를 레코드의 배열로 대체하여 모델 입력을 구성하고 있습니다. 그런 다음 `record_template`매개변수는 각 레코드의 JSON 구조를 구성하고 `$features`자리 표시자를 각 레코드의 특징 배열로 대체하게 됩니다.
다음 예제 분석 구성은 SageMaker Clalify 처리 작업으로 하여금 해당 데이터세트와 모델 모두에서 가능한 모든 편향 지표를 계산하도록 지시합니다.
```
{
"dataset_type": "application/json",
"headers": ["Age","Gender","Income","Occupation","Target"],
"label": "[*].Label",
"features": "[*].Features",
"label_values_or_threshold": [1],
"facet": [
{
"name_or_index": "Gender",
"value_or_threshold": [0]
}
],
"methods": {
"pre_training_bias": {
"methods": "all"
},
"post_training_bias": {
"methods": "all"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "$records",
"record_template": "{\"Features\":$features}",
"label": "predictions[*].predicted_label"
}
}
```
#### SHAP 값의 계산
SHAP 분석에 대한 레이블은 지정하지 않아도 됩니다. 다음 예제에서는 `headers`매개변수가 지정되지 않았습니다. 따라서 SageMaker Calify 처리 작업에서는 자리 표시자를 생성할 때 특징 헤더에는 `column_0`또는 `column_1`을, 레이블 헤더에는 `label0`을 사용하는 등 일반적인 이름을 적용하게 됩니다. 분석 결과의 가독성을 높이기 위해 `headers`및 `label`에 각각의 값을 지정할 수 있습니다.
다음 구성 예제에서 확률 매개변수는 각각의 예측에서 개별 레코드의 확률을 추출해내는 JMESPath 표현식으로 설정되어 있습니다. 다음은 SHAP 값을 계산하는 예제입니다.
```
{
"dataset_type": "application/json",
"features": "[*].Features",
"methods": {
"shap": {
"num_clusters": 1
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "$records",
"record_template": "{\"Features\":$features}",
"probability": "predictions[*].probability"
}
}
```
#### 부분 종속성 도표(PDP)의 계산
다음 예제는 PDP에서 특징 중요도를 표시하는 방법을 보여줍니다. 이 예제에서 특징 헤더는 제공되지 않습니다. 따라서 `pdp`메서드의 `features`매개변수는 해당 특징 열의 위치를 참조할 수 있도록 반드시 0으로 시작하는 인덱스를 사용해야 합니다. `grid_resolution` 매개변수는 해당 특징 값의 범위를 `10`개의 버킷으로 분할합니다.
다음 예제에 나와 있는 매개변수들 모두는 SageMaker Clarify 처리 작업으로 하여금 x축에 `10`개의 세그먼트가 있는 `Income`PDP 그래프가 포함된 보고서를 생성하도록 지시합니다. y축은 `Income`이 예측에 미치는 한계 영향을 보여주게 됩니다.
다음 구성 예제는 PDP에서 `Income`의 중요도를 표시하는 방법을 보여줍니다.
```
{
"dataset_type": "application/json",
"features": "[*].Features",
"methods": {
"pdp": {
"features": [2],
"grid_resolution": 10
},
"report": {
"name": "report"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "$records",
"record_template": "{\"Features\":$features}",
"probability": "predictions[*].probability"
}
}
```
#### 편향 지표 및 특징 중요도 모두에 대한 계산
이전의 모든 구성 메서드를 단일 분석 구성 파일로 결합하여 하나의 작업만으로 모든 계산을 수행하는 것이 가능합니다. 다음 예제는 모든 단계를 결합했을 때의 분석 구성을 보여줍니다.
이 예제에서는 `probability`매개변수가 설정되어 있습니다. 편향 분석에는 예측 레이블이 필요하므로 `probability_threshold`매개변수가 `0.5`로 설정되었고, 이는 확률 점수를 바이너리 레이블로 변환하는 데 사용됩니다. 이 예제에서는 `pdp`메서드의 `top_k_features`매개변수가 `2`로 설정되어 있습니다. 이를 통해 SageMaker Clarify 처리 작업이 가장 큰 전역 SHAP 값을 가진 상위 특징 `2`개를 대상으로 PDP를 계산하도록 지시됩니다.
```
{
"dataset_type": "application/json",
"headers": ["Age","Gender","Income","Occupation","Target"],
"label": "[*].Label",
"features": "[*].Features",
"probability_threshold": 0.5,
"label_values_or_threshold": [1],
"facet": [
{
"name_or_index": "Gender",
"value_or_threshold": [0]
}
],
"methods": {
"pre_training_bias": {
"methods": "all"
},
"post_training_bias": {
"methods": "all"
},
"shap": {
"num_clusters": 1
},
"pdp": {
"top_k_features": 2,
"grid_resolution": 10
},
"report": {
"name": "report"
}
},
"predictor": {
"endpoint_name": "your_endpoint",
"content_template": "$records",
"record_template": "{\"Features\":$features}",
"probability": "predictions[*].probability"
}
}
```
### 자연어 처리의 설명 가능성을 위한 분석 구성
다음 예제는 자연어 처리(NLP)에서의 특징 중요도를 계산하기 위한 분석 구성 파일을 보여줍니다. 이 예제에서 투입되는 데이터세트는 다음과 같이 1개의 바이너리 레이블 열과 2개의 특징 열로 구성된 CSV 포맷의 테이블 형식 데이터세트입니다. 데이터세트는 `dataset`처리의 입력 매개변수를 통해 SageMaker Clarify 작업에 제공됩니다.
```
0,2,"They taste gross"
1,3,"Flavor needs work"
1,5,"Taste is awful"
0,1,"The worst"
...
```
이 예제에서 바이너리 분류 모델은 이전 데이터세트에서 훈련되었습니다. 모델은 CSV 데이터를 받아들인 다음 `0`\$1`1`범위의 단일 점수를 다음과 같이 출력합니다.
```
0.491656005382537
0.569582343101501
...
```
이 모델은 'your\$1model'이라는 SageMaker AI 모델을 만드는 데 사용됩니다. 다음 분석 구성은 모델 및 데이터세트를 사용하여 토큰별 설명 가능성 분석을 실행하는 방법을 보여줍니다. `text_config` 매개변수는 NLP 설명 가능성 분석을 활성화합니다. `granularity` 매개변수는 분석 시 토큰을 해석해야 함을 나타냅니다.
영어에서 각 토큰은 하나의 단어입니다. 다음 예제는 평균 4의 “Rating”을 사용하여 현재 위치의 SHAP “baseline” 인스턴스를 제공하는 방법도 보여줍니다. 특수 마스크 토큰인 “[MASK]”는 “Comments”의 토큰(단어)을 대체하는 용도로 사용됩니다. 또한 이 예제에서는 GPU 엔드포인트 인스턴스 유형을 사용하여 추론의 속도를 높입니다.
```
{
"dataset_type": "text/csv",
"headers": ["Target","Rating","Comments"]
"label": "Target",
"methods": {
"shap": {
"text_config": {
"granularity": "token",
"language": "english"
}
"baseline": [[4,"[MASK]"]],
}
},
"predictor": {
"model_name": "your_nlp_model",
"initial_instance_count": 1,
"instance_type": "ml.g4dn.xlarge"
}
}
```
### 컴퓨터 비전의 설명 가능성을 위한 분석 구성
다음 예제는 컴퓨터 비전에서의 특징 중요도를 계산하는 분석 구성 파일을 보여줍니다. 이 예제에서 입력 데이터세트는 JPEG 이미지로 구성되어 있습니다. 데이터세트는 `dataset`처리의 입력 매개변수를 통해 SageMaker Clarify 작업에 제공됩니다. 이 예제는 SageMaker 이미지 분류 모델을 사용하여 설명 가능성 분석을 구성하는 방법을 보여줍니다. 이 예제에서 `your_cv_ic_model`이라는 이름의 모델은 입력된 JPEG 이미지에서 동물의 종류를 분류하도록 훈련되었습니다.
```
{
"dataset_type": "application/x-image",
"methods": {
"shap": {
"image_config": {
"model_type": "IMAGE_CLASSIFICATION",
"num_segments": 20,
"segment_compactness": 10
}
},
"report": {
"name": "report"
}
},
"predictor": {
"model_name": "your_cv_ic_model",
"initial_instance_count": 1,
"instance_type": "ml.p2.xlarge",
"label_headers": ["bird","cat","dog"]
}
}
```
이미지 분류에 대한 자세한 내용은 [이미지 분류 - MXNet](image-classification.md) 섹션을 참조하세요.
이 예시에서 [SageMaker AI 객체 감지 모델](https://docs.aws.amazon.com/sagemaker/latest/dg/object-detection.html)인 `your_cv_od_model`은 이미지의 동물을 식별하기 위해 동일한 JPEG 이미지로 훈련되었습니다. 다음 예제는 객체 감지 모델을 위한 설명 가능성 분석을 구성하는 방법을 보여줍니다.
```
{
"dataset_type": "application/x-image",
"probability_threshold": 0.5,
"methods": {
"shap": {
"image_config": {
"model_type": "OBJECT_DETECTION",
"max_objects": 3,
"context": 1.0,
"iou_threshold": 0.5,
"num_segments": 20,
"segment_compactness": 10
}
},
"report": {
"name": "report"
}
},
"predictor": {
"model_name": "your_cv_od_model",
"initial_instance_count": 1,
"instance_type": "ml.p2.xlarge",
"label_headers": ["bird","cat","dog"]
}
}
```
### 시계열 예측 모델 설명 가능성을 위한 분석 구성
다음 예시는 시계열(TS)에서의 특성 중요도를 계산하기 위한 분석 구성 파일을 보여줍니다. 이 예시에서 수신 데이터세트는 동적 및 정적 공변량 특성 집합이 있는 JSON 형식의 시계열 데이터세트입니다. 데이터세트는 데이터세트 처리 입력 파라미터 `dataset_uri`를 통해 SageMaker Clarify 작업에 제공됩니다.
```
[
{
"item_id": "item1",
"timestamp": "2019-09-11",
"target_value": 47650.3,
"dynamic_feature_1": 0.4576,
"dynamic_feature_2": 0.2164,
"dynamic_feature_3": 0.1906,
"static_feature_1": 3,
"static_feature_2": 4
},
{
"item_id": "item1",
"timestamp": "2019-09-12",
"target_value": 47380.3,
"dynamic_feature_1": 0.4839,
"dynamic_feature_2": 0.2274,
"dynamic_feature_3": 0.1889,
"static_feature_1": 3,
"static_feature_2": 4
},
{
"item_id": "item2",
"timestamp": "2020-04-23",
"target_value": 35601.4,
"dynamic_feature_1": 0.5264,
"dynamic_feature_2": 0.3838,
"dynamic_feature_3": 0.4604,
"static_feature_1": 1,
"static_feature_2": 2
},
]
```
다음 섹션에서는 JSON 데이터세트의 비대칭 Shapley 값 알고리즘을 사용하여 예측 모델의 특성 어트리뷰션을 계산하는 방법을 설명합니다.
#### 시계열 예측 모델에 대한 설명 계산
다음 예시 분석 구성은 시계열 예측 모델에 대한 설명을 계산하기 위해 작업에서 사용하는 옵션을 표시합니다.
```
{
'dataset_type': 'application/json',
'dataset_uri': 'DATASET_URI',
'methods': {
'asymmetric_shapley_value': {
'baseline': {
"related_time_series": "zero",
"static_covariates": {
"item1": [0, 0], "item2": [0, 0]
},
"target_time_series": "zero"
},
'direction': 'chronological',
'granularity': 'fine_grained',
'num_samples': 10
},
'report': {'name': 'report', 'title': 'Analysis Report'}
},
'predictor': {
'accept_type': 'application/json',
'content_template': '{"instances": $records}',
'endpoint_name': 'ENDPOINT_NAME',
'content_type': 'application/json',
'record_template': '{
"start": $start_time,
"target": $target_time_series,
"dynamic_feat": $related_time_series,
"cat": $static_covariates
}',
'time_series_predictor_config': {'forecast': 'predictions[*].mean[:2]'}
},
'time_series_data_config': {
'dataset_format': 'timestamp_records',
'item_id': '[].item_id',
'related_time_series': ['[].dynamic_feature_1', '[].dynamic_feature_2', '[].dynamic_feature_3'],
'static_covariates': ['[].static_feature_1', '[].static_feature_2'],
'target_time_series': '[].target_value',
'timestamp': '[].timestamp'
}
}
```
##### 시계열 설명 가능성 구성
앞의 예에서는 `methods`에서 `asymmetric_shapley_value`를 사용하여 기준, 방향, 세분화 및 샘플 수와 같은 시계열 설명 가능성 인수를 정의합니다. 기준 값은 관련 시계열, 정적 공변량 및 대상 시계열의 세 가지 데이터 유형에 대해 모두 설정됩니다. 이러한 필드는 SageMaker Clarify 프로세서에 한 번에 한 항목에 대한 특성 어트리뷰션을 계산하도록 지시합니다.
##### 예측기 구성
JMESPath 구문을 사용하여 SageMaker Clarify 프로세서가 전송하는 페이로드 구조를 완전히 제어할 수 있습니다. 이전 예시에서 `predictor` config는 Clarify에 레코드를 `'{"instances": $records}'`로 집계하도록 지시합니다. 여기서 각 레코드는 예시의 `record_template`에 지정된 인수로 정의됩니다. `$start_time`, `$target_time_series`, `$related_time_series` 및 `$static_covariates`는 데이터세트 값을 엔드포인트 요청 값에 매핑하는 데 사용되는 내부 토큰입니다.
마찬가지로 `time_series_predictor_config`의 속성 `forecast`는 엔드포인트 응답에서 모델 예측을 추출하는 데 사용됩니다. 예를 들어 엔드포인트 배치 응답은 다음과 같을 수 있습니다.
```
{
"predictions": [
{"mean": [13.4, 3.6, 1.0]},
{"mean": [23.0, 4.7, 3.0]},
{"mean": [3.4, 5.6, 2.0]}
]
}
```
다음 시계열 예측기 구성을 지정한다고 가정해 보겠습니다.
```
'time_series_predictor_config': {'forecast': 'predictions[*].mean[:2]'}
```
예측 값은 다음과 같이 구문 분석됩니다.
```
[
[13.4, 3.6],
[23.0, 4.7],
[3.4, 5.6]
]
```
##### 데이터 구성
`time_series_data_config` 속성을 사용하여 SageMaker Clarify 프로세서에 `dataset_uri`의 S3 URI로 전달된 데이터에서 데이터를 올바르게 구문 분석하도록 지시합니다.
# 데이터 형식 호환성 안내서
이 안내서는 SageMaker Clarify 처리 작업과 호환되는 데이터 형식의 유형을 설명합니다. 지원되는 데이터 형식 유형에는 파일 확장명, 데이터 구조, 그리고 테이블 형식, 이미지, 시계열 데이터세트와 관련한 구체적인 요구 사항 또는 제한 사항이 포함됩니다. 이 안내서에서는 데이터세트가 이러한 요구 사항을 준수하는지 확인하는 방법도 보여줍니다.
전체적으로 보면, SageMaker Clarify 처리 작업은 편향 지표와 특징 속성을 계산하는 데 있어 입력-처리-출력 모델을 따르게 됩니다. 세부 정보는 다음 예시를 참조하세요.
SageMaker Clarify 처리 작업에 대한 입력은 다음과 같이 구성됩니다.
+ 분석할 데이터세트
+ 해당 분석 구성 분석을 구성하는 방법에 대한 자세한 내용은 [분석 구성 파일](clarify-processing-job-configure-analysis.md) 섹션을 참조하세요.
처리 단계에서 SageMaker Clarify는 편향 지표와 특징 속성을 계산합니다. SageMaker Clarify 처리 작업은 백엔드에서 다음과 같은 단계들을 완료합니다.
+ SageMaker Clarify 처리 작업은 분석 구성을 파싱한 다음 해당 **데이터세트**를 로드합니다.
+ 작업이 훈련 후 편향 지표와 특징 속성을 계산할 수 있으려면 해당 모델이 수행한 예측이 필요합니다. SageMaker Clarify 처리 작업은 사용자의 데이터를 직렬화하여 이를 SageMaker AI 실시간 추론 **엔드포인트**에 배포된 상태인 해당 모델에 **요청**의 형태로 전송하게 됩니다. 그런 다음 SageMaker Clarify 처리 작업은 도착한 **응답**으로부터 예측을 추출합니다.
+ SageMaker Clarify 처리 작업은 편향 및 설명 가능성 분석을 수행한 다음 결과를 출력합니다.
자세한 정보는 [SageMaker Clarify 처리 작업의 작동 방식](clarify-configure-processing-jobs.md#clarify-processing-job-configure-how-it-works)을 참조하세요.
데이터 형식을 지정하는 데 사용하는 매개변수는 처리 흐름 상에서 데이터가 사용되는 위치에 따라 다음과 같이 달라지게 됩니다.
+ **입력 데이터세트**인 경우, `dataset_type`매개변수를 사용하여 해당 형식 또는 MIME 유형을 지정합니다.
+ 엔드포인트에 대한 **요청**인 경우, `content_type`매개변수를 사용하여 해당 형식을 지정합니다.
+ 엔드포인트에서의 **응답**인 경우, `accept_type`매개변수를 사용하여 해당 형식을 지정합니다.
입력 데이터세트, 요청, 그리고 엔드포인트와 주고 받는 응답의 형식은 반드시 동일하지 않아도 됩니다. 예를 들어 다음과 같은 조건에서는 Parquet 데이터세트를 CSV **요청** 페이로드 및 JSON Lines **응답** 페이로드와 함께 사용하는 것이 가능합니다.
+ 분석이 올바르게 구성되어 있음
+ 모델이 해당 요청 및 응답 형식을 지원함
**참고**
`content_type` 또는 `accept_type`이 제공되지 않은 경우, SageMaker Clarify 컨테이너는 `content_type`과 `accept_type`을 유추합니다.
**Topics**
+ [테이블 형식 데이터](clarify-processing-job-data-format-tabular.md)
+ [이미지 데이터 요구 사항](clarify-processing-job-data-format-image.md)
+ [시계열 데이터](clarify-processing-job-data-format-time-series.md)
# 테이블 형식 데이터
테이블 형식 데이터란 2차원의 데이터 프레임에 로드할 수 있는 데이터를 말합니다. 프레임에서 각 행은 레코드를 나타내며, 각 레코드에는 하나 이상의 열이 포함되어 있습니다. 데이터 프레임 셀 각각의 값은 숫자, 범주 또는 텍스트 데이터 유형일 수 있습니다.
## 테이블 형식 데이터세트의 전제 조건
데이터세트에는 분석에 앞서 필요한 사전 처리 단계들이 이미 적용되어 있어야 합니다. 여기에는 데이터 정리 또는 특징 엔지니어링이 포함됩니다.
데이터 세트는 하나 또는 여러 개 제공할 수 있습니다. 복수의 데이터세트를 제공하려는 경우, 다음을 참고하여 데이터세트가 SageMaker Clarify 처리 작업을 대상으로 식별되도록 하세요.
+ `dataset`로 이름이 지정된 [ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingInput.html) 또는 분석 구성 `dataset_uri`를 사용하여 기본 데이터세트를 지정합니다. `dataset_uri`에 대한 자세한 내용은 [분석 구성 파일](clarify-processing-job-configure-analysis.md)의 파라미터 목록을 참조하세요.
+ 분석 구성 파일에서 제공된 `baseline`매개변수를 사용합니다. SHAP 분석에는 기준 데이터세트가 필수입니다. 예시가 포함된 분석 구성 파일에 대한 자세한 내용은 [분석 구성 파일](clarify-processing-job-configure-analysis.md) 섹션을 참조하세요.
다음 표에는 지원되는 데이터 형식, 해당 파일 확장명 및 MIME 유형이 나열되어 있습니다.
| 데이터 형식 | 파일 확장명 | MIME 유형 |
| --- | --- | --- |
| CSV | csv | `text/csv` |
| JSON Lines | jsonl | `application/jsonlines` |
| JSON | json | `application/json` |
| PARQUET | parquet | "application/x-parquet" |
다음 섹션은 CSV, JSON Lines 및 Apache Parquet 포맷의 테이블 형식 데이터세트 예제를 보여줍니다.
### CSV 포맷 테이블 형식 데이터세트의 전제 조건
SageMaker Clarify 처리 작업은 CSV 데이터 파일을 [csv.excel](https://docs.python.org/3/library/csv.html#csv.excel) 언어로 로드하도록 설계되었습니다. 하지만 이는 `\n`및 `\r`을 비롯한 다른 라인 종결자도 유연하게 지원할 수 있습니다.
호환성을 위해 SageMaker Clarify 처리 작업에 제공되는 모든 CSV 데이터 파일은 UTF-8 형식으로 인코딩되어 있어야 합니다.
해당 데이터세트에 헤더 행이 없는 경우, 다음을 수행합니다.
+ 분석 구성 레이블을 index `0`으로 설정합니다. 이는 첫 번째 열이 실측 레이블임을 의미합니다.
+ 매개변수 `headers`가 설정된 경우, `label`을 레이블 열의 헤더로 설정하여 해당 레이블 열의 위치를 나타냅니다. 다른 모든 열은 특징으로 지정됩니다.
다음은 헤더 행을 포함하고 있지 않은 데이터세트의 예제입니다.
```
1,5,2.8,2.538,This is a good product
0,1,0.79,0.475,Bad shopping experience
...
```
데이터에 헤더 행이 포함되어 있다면, 매개변수 `label`을 index `0`으로 설정합니다. 레이블 열의 위치를 나타내려면 실측 레이블 헤더 `Label`을 사용하세요. 다른 모든 열은 특징으로 지정됩니다.
다음은 헤더 행을 포함하고 있는 데이터세트의 예제입니다.
```
Label,Rating,A12,A13,Comments
1,5,2.8,2.538,This is a good product
0,1,0.79,0.475,Bad shopping experience
...
```
### JSON 포맷 테이블 형식 데이터세트의 전제 조건
JSON은 모든 수준의 복잡성을 포함하는 구조화된 데이터를 표현하기 위해 사용되는 유연한 형식입니다. SageMaker Clalify의 JSON 관련 지원은 특정 형식에만 국한되지 않으므로, CSV 또는 JSON Lines 포맷의 데이터세트에 비해 더 유연한 방식으로 데이터 형식을 사용할 수 있습니다. 이 안내서는 JSON 포맷의 테이블 형식 데이터에 대한 분석 구성을 설정하는 방법을 보여줍니다.
**참고**
호환성을 보장하기 위해 SageMaker Clarify 처리 작업에 제공되는 모든 JSON 데이터 파일은 UTF-8 형식으로 인코딩되어 있어야 합니다.
다음은 상위 키, 특징 목록 및 레이블이 포함된 레코드가 있는 입력 데이터 예제입니다.
```
[
{"features":[1,5,2.8,2.538,"This is a good product"],"label":1},
{"features":[0,1,0.79,0.475,"Bad shopping experience"],"label":0},
...
]
```
이전 입력 예제 데이터 세트에 대한 구성 분석 예제에서는 다음 매개변수가 설정되어야 합니다.
+ `label` 매개변수는 [JMESPath](https://jmespath.org/) 표현식 `[*].label`을 사용하여 해당 데이터세트의 각 레코드에 대한 실측 레이블을 추출하게 됩니다. JMESPath 표현식은 i번째 레이블이 i번째 레코드와 일치하는 레이블 목록을 생성하게 됩니다.
+ `features` 매개변수는 JMESPath 표현식 `[*].features`를 사용하여 해당 데이터세트의 각 레코드에 대한 특징 배열을 추출하게 됩니다. JMESPath 표현식은 i번째 레코드와 일치하는 특징 값을 i번째 행이 포함하고 있는 2D 배열 또는 행렬을 생성하게 됩니다.
다음은 상위 키 그리고 특징 목록 및 각 레코드의 레이블을 포함하는 중첩 키가 포함된 입력 데이터의 예제입니다.
```
{
"data": [
{"features":[1,5,2.8,2.538,"This is a good product"],"label":1}},
{"features":[0,1,0.79,0.475,"Bad shopping experience"],"label":0}}
]
}
```
이전 입력 예제 데이터세트에 대한 구성 분석 예제에서는 다음 매개변수가 설정되어야 합니다.
+ `label` 매개변수는 [JMESPath](https://jmespath.org/) 표현식 `data[*].label`을 사용하여 해당 데이터세트의 각 레코드에 대한 실측 레이블을 추출합니다. JMESPath 표현식은 i번째 레이블이 i번째 레코드에 맞는 레이블 목록을 생성하게 됩니다.
+ `features` 파라미터는 JMESPath 표현식 `data[*].features`를 사용하여 해당 데이터세트의 각 레코드에 대한 특성 배열을 추출합니다. JMESPath 표현식은 i번째 레코드의 특징 값을 i번째 행이 포함하고 있는 2D 배열 또는 행렬을 생성하게 됩니다.
### JSON Lines 포맷 테이블 형식 데이터세트의 전제 조건
JSON Lines은 각 라인이 유효한 JSON 객체인 구조화된 데이터를 나타내기 위해 사용되는 텍스트 형식입니다. 현재 SageMaker Clarify 처리 작업은 SageMaker AI 조밀 형식 JSON Lines만 지원합니다. 요구되는 형식을 준수하려면 레코드의 모든 특징이 단일 JSON 배열에 나열되어 있어야 합니다. JSON 라인에 관한 자세한 정보는 [JSONLINES 요청 형식](cdf-inference.md#cm-jsonlines) 항목을 참조하세요.
**참고**
SageMaker Clarify 처리 작업에 제공되는 모든 JSON Lines 데이터 파일은 UTF-8 형식으로 인코딩하여 호환성이 보장되어야 합니다.
다음은 **상위 키**와 요소들의 **목록**을 포함하는 레코드에 대한 분석 구성을 설정하는 방법의 예제입니다.
```
{"features":[1,5,2.8,2.538,"This is a good product"],"label":1}
{"features":[0,1,0.79,0.475,"Bad shopping experience"],"label":0}
...
```
이전 데이터 세트 예제에 대한 구성 분석에서는 매개변수가 다음과 같이 설정되어야 합니다.
+ 실측 레이블의 위치를 나타내려면 매개변수 `label`이 JMESPath 표현식 `label`로 설정되어 있어야 합니다.
+ 특징 배열의 위치를 나타내려면 매개변수 `features`가 JMESPath 표현식 `features`로 설정되어 있어야 합니다.
다음은 **상위 키** 그리고 요소들의 **목록**이 있는 **중첩 키**를 포함하는 레코드에 대한 분석 구성을 설정하는 방법의 예제입니다.
```
{"data":{"features":[1,5,2.8,2.538,"This is a good product"],"label":1}}
{"data":{"features":[0,1,0.79,0.475,"Bad shopping experience"],"label":0}}
...
```
이전 데이터세트 예제에 대한 구성 분석에서는 매개변수가 다음과 같이 설정되어야 합니다.
+ 실측 레이블의 위치를 나타내려면 매개변수 `label`이 JMESPath 표현식 `data.label`로 설정되어 있어야 합니다.
+ 특징 배열의 위치를 나타내려면 매개변수 `features`가 JMESPath 표현식 `data.features`로 설정되어 있어야 합니다.
### Parquet 포맷 테이블 형식 데이터세트의 전제 조건
[Parquet](https://parquet.apache.org/)은 열 중심의 바이너리 데이터 형식입니다. 현재 SageMaker Clarify 처리 작업은 처리 인스턴스의 개수가 `1`인 경우에만 Parquet 데이터 파일의 로드를 지원합니다.
SageMaker Clarify 처리 작업은 Parquet 형식의 엔드포인트 요청 또는 엔드포인트 응답을 지원하지 않으므로, 사용자가 분석 구성 매개변수 `content_type`을 지원 가능한 형식으로 설정함으로써 해당 엔드포인트 요청의 데이터 형식을 직접 지정해야 합니다. 자세한 설명은 [분석 구성 파일](clarify-processing-job-configure-analysis.md)에서 `content_type` 섹션을 참조하세요.
Parquet 데이터에는 문자열 형식으로 되어 있는 열 이름이 반드시 있어야 합니다. 분석 구성 `label`매개변수를 사용하여 실측 레이블의 위치를 나타내는 레이블 열 이름을 설정합니다. 다른 모든 열은 특징으로 지정됩니다.
# 테이블 형식 데이터에 대한 엔드포인트 요청
SageMaker Clarify 처리 작업은 훈련 후 편향 분석 및 특징 중요도 분석을 위한 모델 예측을 얻기 위해 테이블 형식 데이터를 바이트로 직렬화한 다음 이를 추론 엔드포인트에 요청 페이로드로서 전송합니다. 이 테이블 형식 데이터는 입력 데이터세트에서 가져왔거나 생성된 데이터세트입니다. 데이터가 합성 데이터인 경우, 이는 설명자가 SHAP 분석 또는 PDP 분석을 위해 생성한 것입니다.
요청 페이로드의 데이터 형식은 분석 구성 매개변수 `content_type`을 통해 지정되어야 합니다. 매개변수가 제공되지 않은 경우, SageMaker Clalify 처리 작업은 `dataset_type`매개변수 값을 콘텐츠 유형으로 사용하게 됩니다. `content_type` 또는 `dataset_type`에 대한 자세한 내용은 [분석 구성 파일](clarify-processing-job-configure-analysis.md) 섹션을 참조하세요.
다음 섹션은 CSV 및 JSON Lines 포맷으로 된 엔드포인트 요청의 예제를 보여줍니다.
## CSV 포맷의 엔드포인트 요청
SageMaker Clarify 처리 작업은 데이터를 CSV 포맷(MIME 유형: `text/csv`)으로 직렬화할 수 있습니다. 다음 표는 직렬화된 요청 페이로드의 예제를 보여줍니다.
| 엔드포인트 요청 페이로드(문자열 표현식) | 설명 |
| --- | --- |
| '1,2,3,4' | 단일 레코드(숫자 특징 4개). |
| '1,2,3,4\$1n5,6,7,8' | 줄 바꿈 '\$1n'으로 구분된 2개의 레코드 |
| '"좋은 제품입니다”,5' | 단일 레코드(텍스트 특징 1개 및 숫자 특징 1개). |
| '"좋은 제품입니다”,5\$1n“나쁜 쇼핑 경험”,1' | 레코드 2개 |
## JSON Lines 형식의 엔드포인트 요청
SageMaker Clarify 처리 작업은 데이터를 SageMaker AI JSON Lines 조밀 형식(MIME 유형: `application/jsonlines`)으로 직렬화할 수 있습니다. JSON 라인에 관한 자세한 정보는 [JSONLINES 요청 형식](cdf-inference.md#cm-jsonlines) 항목을 참조하세요.
테이블 형식 데이터를 JSON 데이터로 변환하려면, 분석 구성 매개변수 `content_template`에 템플릿 문자열을 제공하세요. `content_template`에 대한 자세한 내용은 [분석 구성 파일](clarify-processing-job-configure-analysis.md) 섹션을 참조하세요. 다음 표는 직렬화된 JSON Lines 요청 페이로드의 예제를 보여줍니다.
| 엔드포인트 요청 페이로드(문자열 표현식) | 설명 |
| --- | --- |
| '\$1"data":\$1"features":[1,2,3,4]\$1\$1' | 단일 레코드. 이 경우 템플릿은 `'{"data":{"features":$features}}' `의 형태가 되며, `$features`는 특징의 목록인 `[1,2,3,4]`로 대체됩니다. |
| '\$1"data":\$1"features":[1,2,3,4]\$1\$1\$1n\$1"data":\$1"features":[5,6,7,8]\$1\$1' | 레코드 2개. |
| '\$1"features":["좋은 제품입니다",5]\$1' | 단일 레코드. 이 경우 템플릿은 `'{"features":$features}'`의 형태가 되며, \$1features는 특징의 목록인 `["This is a good product",5]`로 대체됩니다. |
| '\$1"features":["좋은 제품입니다",5]\$1\$1n\$1"features":["나쁜 쇼핑 경험",1]\$1' | 레코드 2개 |
## JSON 포맷의 엔드포인트 요청
SageMaker Clarify 처리 작업은 데이터를 임의의 JSON 구조(MIME 유형: `application/json`)로 직렬화할 수 있습니다. 이렇게 하려면 분석 구성 `content_template`매개변수에 템플릿 문자열을 제공해야 합니다. 이는 SageMaker Clarify 처리 작업에서 외부 JSON 구조를 구성하는 용도로 사용됩니다. 또한 각 레코드의 JSON 구조를 구성하는 데 사용되는 `record_template`에 대한 템플릿 문자열도 제공해야 합니다. `content_template` 및 `record_template`에 대한 자세한 내용은 [분석 구성 파일](clarify-processing-job-configure-analysis.md)섹션을 참조하세요.
**참고**
`content_template` 및 `record_template`은 문자열 매개변수이므로, JSON 직렬화 구조의 일부인 모든 큰 따옴표 문자(`"`)는 해당 구성 파일에서 이스케이프 처리된 문자로 표시되어야 합니다. 예를 들어, Python에서 큰 따옴표를 이스케이프 처리하려면 `content_template`에 대해 다음을 입력하면 됩니다.
```
"{\"data\":{\"features\":$record}}}"
```
다음 표에는 직렬화된 JSON 요청 페이로드의 예제와 이를 구성하는 데 필요한 해당 `content_template`및 `record_template`매개변수가 나와 있습니다.
| 엔드포인트 요청 페이로드(문자열 표현식) | 설명 | content\$1template | record\$1template |
| --- | --- | --- | --- |
| '\$1"data":\$1"features":[1,2,3,4]\$1\$1' | 한 번에 하나의 레코드. | '\$1"data":\$1"features":\$1record\$1\$1\$1' | “\$1features” |
| '\$1"instances":[[0, 1], [3, 4]], "feature-names": ["A", "B"]\$1' | 특징 이름이 있는 다중 레코드. | ‘\$1"instances":\$1records, "feature-names":\$1feature\$1names\$1' | “\$1features" |
| '[\$1"A": 0, "B": 1\$1, \$1"A": 3, "B": 4\$1]' | 다중 레코드 및 키-값 페어. | “\$1records" | “\$1features\$1kvp" |
| ‘\$1"A": 0, "B": 1\$1' | 한 번에 하나의 레코드 및 키-값 페어. | "\$1record" | "\$1features\$1kvp" |
| ‘\$1"A": 0, "nested": \$1"B": 1\$1\$1' | 혹은 임의의 구조에는 자세히 기술한 record\$1template을 사용해도 됩니다. | "\$1record" | '\$1"A": "\$1\$1A\$1", "nested": \$1"B": "\$1\$1B\$1"\$1\$1' |
# 테이블 형식 데이터에 대한 엔드포인트 응답
SageMaker Clarify 처리 작업은 추론 엔드포인트 호출의 응답을 수신할 경우 응답 페이로드를 역직렬화한 다음 이 페이로드에서 예측을 추출합니다. 응답 페이로드의 데이터 형식을 지정하기 위해 분석 구성 `accept_type`매개변수를 사용합니다. `accept_type`가 제공되지 않은 경우, SageMaker Clarify 처리 작업은 content\$1type 매개변수의 값을 모델 출력 형식으로 사용하게 됩니다. `accept_type`에 대한 자세한 정보는 [분석 구성 파일](clarify-processing-job-configure-analysis.md) 섹션을 참조하세요.
예측은 편향 분석을 위한 예측 레이블 또는 특징 중요도 분석을 위한 확률 값(점수)으로 구성될 수 있습니다. `predictor` 분석 구성에서는 다음 세 가지 매개변수가 예측을 추출하게 됩니다.
+ `probability` 매개변수는 엔드포인트의 응답에서 확률 값(점수)의 위치를 찾는 데 사용됩니다.
+ `label` 매개변수는 엔드포인트의 응답에서 예측된 레이블의 위치를 찾는 데 사용됩니다.
+ (선택사항) `label_headers`매개변수는 멀티클래스 모델에 대한 예측 레이블을 제공합니다.
다음은 CSV, JSON Lines 및 JSON 포맷으로 된 엔드포인트 응답과 관련한 지침입니다.
## 엔드포인트 응답이 CSV 포맷인 경우
응답 페이로드가 CSV 포맷(MIME 유형:`text/csv`)으로 되어 있다면, SageMaker Clarify 처리 작업은 각 행을 역직렬화합니다. 그런 다음에는 분석 구성에서 제공된 열 인덱스를 사용하여 역직렬화된 해당 데이터로부터 예측을 추출합니다. 응답 페이로드에 포함된 행은 요청 페이로드 상의 레코드와 일치해야 합니다.
다음 표에는 다양한 포맷으로 되어 있는 다양한 문제 유형을 위한 응답 데이터의 예제가 나와 있습니다. 해당 분석 구성에 따라 예측을 추출했을 때의 실제 데이터는 이러한 예제의 데이터와 다를 수 있습니다.
다음 섹션은 CSV 포맷으로 된 엔드포인트 응답의 예제를 보여줍니다.
### 엔드포인트 응답이 CSV 포맷이며 확률만 포함하고 있는 경우
다음 표는 회귀 문제와 바이너리 분류 문제에 대한 엔드포인트 응답의 예제입니다.
| 엔드포인트 요청 페이로드 | 엔드포인트 응답 페이로드(문자열 표현식) |
| --- | --- |
| 단일 레코드. | '0.6' |
| 레코드 2개(결과는 한 줄에 쉼표로 나누어 표시됨) | '0.6,0.3' |
| 레코드 2개(결과는 두 줄로 표시됨) | '0.6\$1n0.3' |
이전 예제에서의 경우, 엔드포인트는 예측 레이블의 단일 확률 값(점수)을 출력합니다. 인덱스를 사용하여 확률을 추출하고 이를 특징 중요도 분석에 사용하려면 분석 구성 매개변수 `probability`를 열 인덱스 `0`으로 설정하세요. 이러한 확률은 `probability_threshold`매개변수를 사용하여 바이너리 값으로 변환할 경우 편향 분석 용도로도 사용이 가능합니다. `probability_threshold`에 대한 자세한 정보는 [분석 구성 파일](clarify-processing-job-configure-analysis.md) 섹션을 참조하세요.
다음 표는 멀티클래스 문제에 대한 엔드포인트 응답의 예제입니다.
| 엔드포인트 요청 페이로드 | 엔드포인트 응답 페이로드(문자열 표현식) |
| --- | --- |
| 멀티클래스 모델의 단일 레코드(클래스 3개). | '0.1,0.6,0.3' |
| 멀티클래스 모델의 레코드 2개(클래스 3개). | '0.1,0.6,0.3\$1n0.2,0.5,0.3' |
이전 예제에서의 경우, 엔드포인트는 확률의 목록(점수)을 출력합니다. 인덱스가 제공되지 않은 경우 모든 값이 추출되어 특징 중요도 분석에 사용됩니다. 만약 분석 구성 매개변수 `label_headers`가 제공되었다면 SageMaker Clarify 처리 작업은 최대 확률의 레이블 헤더를 예측 레이블로 선택하여 이를 편향 분석 용도로 사용할 수 있게 됩니다. `label_headers`에 대한 자세한 정보는 [분석 구성 파일](clarify-processing-job-configure-analysis.md) 섹션을 참조하세요.
### 엔드포인트 응답이 CSV 포맷이며 예측 레이블만 포함하고 있는 경우
다음 표는 회귀 문제와 바이너리 분류 문제에 대한 엔드포인트 응답의 예제입니다.
| 엔드포인트 요청 페이로드 | 엔드포인트 응답 페이로드(문자열 표현식) |
| --- | --- |
| 단일 레코드 | '1' |
| 레코드 2개(결과는 한 줄에 쉼표로 나누어 표시됨) | '1,0' |
| 레코드 2개(결과는 두 줄로 표시됨) | '1\$1n0' |
이전 예제에서의 경우, 엔드포인트는 확률 대신에 예측 레이블을 출력합니다. 인덱스 `0`을 사용하여 예측 레이블을 추출하고 이를 편향 분석에 사용할 수 있도록`predictor` 구성의 `label`매개변수를 열 인덱스 0으로 설정합니다.
### 엔드포인트 응답이 CSV 포맷이며 예측 레이블과 확률을 포함하고 있는 경우
다음 표는 회귀 문제와 바이너리 분류 문제에 대한 엔드포인트 응답의 예제입니다.
| 엔드포인트 요청 페이로드 | 엔드포인트 응답 페이로드(문자열 표현식) |
| --- | --- |
| 단일 레코드 | '1,0.6' |
| 레코드 2개 | '1,0.6\$1n0,0.3' |
이전 예제에서의 경우, 엔드포인트는 예측 레이블과 해당 확률을 차례로 출력합니다. `predictor` 구성의 `label`매개변수를 열 인덱스 `0`으로 설정하고 `probability`를 열 인덱스 `1`로 설정하여 두 매개변수의 값을 모두 추출합니다.
### 엔드포인트 응답이 CSV 포맷이며 복수의 예측 레이블과 확률을 포함하고 있는 경우(멀티클래스)
Amazon SageMaker Autopilot으로 훈련된 멀티클래스 모델 컨테이너는 예측된 레이블 및 확률 목록의 문자열 표현을 출력하도록 구성할 수 있습니다. 다음 예제 표는 `predicted_label`, `probability`, `labels`, `probabilities`를 출력하도록 구성된 모델로부터의 엔드포인트 응답 예제를 보여줍니다.
| 엔드포인트 요청 페이로드 | 엔드포인트 응답 페이로드(문자열 표현식) |
| --- | --- |
| 단일 레코드 | '"dog",0.6,"[\$1'cat\$1', \$1'dog\$1', \$1'fish\$1']","[0.1, 0.6, 0.3]"' |
| 레코드 2개 | '"dog",0.6,"[\$1'cat\$1', \$1'dog\$1', \$1'fish\$1']","[0.1, 0.6, 0.3]"\$1n""cat",0.7,[\$1'cat\$1', \$1'dog\$1', \$1'fish\$1']","[0.7, 0.2, 0.1]"' |
이전 예제에서의 경우, SageMaker Clarify 처리 작업을 다음과 같은 방식으로 구성하여 예측을 추출할 수 있습니다.
편향 분석의 경우, 이전 예제를 다음 중 한 가지 방식으로 구성할 수 있습니다.
+ `predictor` 구성의 `label`매개변수를 `0`으로 설정하여 예측 레이블을 추출합니다.
+ 예측 레이블을 추출하려면 매개변수를 `2`로 설정하고, 해당 확률을 추출하려면 `probability`를 `3`으로 설정합니다. SageMaker Clalify 처리 작업은 확률 값이 가장 높은 레이블을 식별하여 예측 레이블을 자동으로 결정할 수 있습니다. 단일 레코드의 이전 예제를 참조하자면, 모델은 `cat`, `dog`, `fish`라는 세 가지 레이블을 해당하는 확률인 `0.1`, `0.6`, `0.3`으로 예측합니다. 이 확률을 기반으로 예측된 레이블은 확률 값이 `0.6`으로 가장 높게 나타난 `dog`입니다.
+ `probability`를 `3`으로 설정하여 확률을 추출합니다. `label_headers`가 제공된 경우, SageMaker Clalify 처리 작업은 확률 값이 가장 높은 레이블 헤더를 식별하여 예측 레이블을 자동으로 결정할 수 있습니다.
특징 중요도 분석에서의 경우, 이전 예제를 다음과 같이 구성할 수 있습니다.
+ `probability`를 `3`으로 설정하여 모든 예측 레이블의 확률을 추출합니다. 그러면 모든 레이블에 대한 특징 속성이 계산됩니다. 고객이 `label_headers`를 지정하지 않을 경우, 분석 보고서에서는 예측 레이블이 레이블 헤더로 사용됩니다.
## JSON Lines 형식의 엔드포인트 응답
응답 페이로드가 JSON Lines 포맷(MIME 유형:`application/jsonlines`)으로 되어 있다면, SageMaker Clarify 처리 작업은 각 라인을 JSON의 형태로 역직렬화합니다. 그런 다음에는 분석 구성에서 제공된 JMESPath 표현식을 사용하여 역직렬화된 해당 데이터로부터 예측을 추출합니다. 응답 페이로드에 포함된 라인은 요청 페이로드 상의 레코드와 일치해야 합니다. 다음 표에는 다양한 형식의 응답 데이터 예제가 나와 있습니다. 해당 분석 구성에 따라 예측을 추출했을 때의 실제 데이터는 이러한 예제의 데이터와 다를 수 있습니다.
다음 섹션은 JSON Lines 포맷으로 된 엔드포인트 응답의 예제를 보여줍니다.
### 엔드포인트 응답이 JSON Lines 포맷이며 확률만 포함되어 있는 경우
다음 표는 확률 값(점수)만을 출력하는 엔드포인트 응답의 예제입니다.
| 엔드포인트 요청 페이로드 | 엔드포인트 응답 페이로드(문자열 표현식) |
| --- | --- |
| 단일 레코드 | '\$1"score":0.6\$1' |
| 레코드 2개 | '\$1"score":0.6\$1\$1n\$1"score":0.3\$1' |
이전 예제에서의 경우, 분석 구성 매개변수 `probability`를 JMESPath 표현식 “score”로 설정하여 해당 값을 추출합니다.
### 엔드포인트 응답이 JSON Lines 포맷이며 예측 레이블만 포함하고 있는 경우
다음 표는 예측 레이블만을 출력하는 엔드포인트 응답의 예제입니다.
| 엔드포인트 요청 페이로드 | 엔드포인트 응답 페이로드(문자열 표현식) |
| --- | --- |
| 단일 레코드 | '\$1"prediction":1\$1' |
| 레코드 2개 | '\$1"prediction":1\$1\$1n\$1"prediction":0\$1' |
이전 예제에서의 경우, 예측자 구성의 `label`매개변수를 JMESPath 표현식 `prediction`으로 설정합니다. 그러면 SageMaker Clarify 처리 작업이 편향 분석을 위해 예측 레이블을 추출할 수 있게 됩니다. 자세한 내용은 [분석 구성 파일](clarify-processing-job-configure-analysis.md) 단원을 참조하십시오.
### 엔드포인트 응답이 JSON Lines 포맷이며 예측 레이블과 확률을 포함하고 있는 경우
다음 표는 예측 레이블과 그 점수를 출력하는 엔드포인트 응답의 예제입니다.
| 엔드포인트 요청 페이로드 | 엔드포인트 응답 페이로드(문자열 표현식) |
| --- | --- |
| 단일 레코드 | '\$1"prediction":1,"score":0.6\$1' |
| 레코드 2개 | '\$1"prediction":1,"score":0.6\$1\$1n\$1"prediction":0,"score":0.3\$1' |
이전 예제에서의 경우, `predictor`구성의 `label`매개변수를 JMESPath 표현식 "prediction"으로 설정하여 예측 레이블을 추출합니다. `probability`를 JMESPath 표현식 “score”로 설정하여 확률을 추출합니다. 자세한 내용은 [분석 구성 파일](clarify-processing-job-configure-analysis.md) 단원을 참조하십시오.
### 엔드포인트 응답이 JSON Lines 포맷이며 복수의 예측 레이블과 확률을 포함하고 있는 경우(멀티클래스)
다음 표는 멀티클래스 모델로부터 받은 엔드포인트 응답의 예제로, 이는 다음을 출력합니다.
+ 예측 레이블의 목록
+ 확률, 선택된 예측 레이블, 해당 확률
| 엔드포인트 요청 페이로드 | 엔드포인트 응답 페이로드(문자열 표현식) |
| --- | --- |
| 단일 레코드 | '\$1"predicted\$1label":"dog","probability":0.6,"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1' |
| 레코드 2개 | '\$1"predicted\$1label":"dog","probability":0.6,"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1\$1n\$1"predicted\$1label":"cat","probability":0.7,"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.7,0.2,0.1]\$1' |
이전 예제에서의 경우, SageMaker Clarify 처리 작업을 몇 가지 방식으로 구성하여 예측을 추출할 수 있습니다.
편향 분석의 경우, 이전 예제를 다음 중 **한 가지** 방식으로 구성할 수 있습니다.
+ `predictor` 구성의 `label`매개변수를 JMESPath 표현식 "predicted\$1label"로 설정하여 예측 레이블을 추출합니다.
+ 해당 매개변수를 JMESPath 표현식 "predicted\$1labels"로 설정하여 복수의 예측 레이블을 추출합니다. `probability`를 JMESPath 표현식 “probabilities”로 설정하여 해당 확률을 추출합니다. SageMaker Clalify 작업은 확률 값이 가장 높은 레이블을 식별하여 예측 레이블을 자동으로 결정합니다.
+ `probability`를 JMESPath 표현식 “probabilities”로 설정하여 해당 확률을 추출합니다. `label_headers`가 제공된 경우, SageMaker Clalify 처리 작업은 확률 값이 가장 높은 레이블을 식별하여 예측 레이블을 자동으로 결정할 수 있습니다.
특징 중요도 분석의 경우, 다음을 수행합니다.
+ `probability`를 JMESPath 표현식 “probabilities”로 설정하여 모든 예측 레이블의 해당 확률을 추출합니다. 그러면 모든 레이블에 대한 특징 속성이 계산됩니다.
## 엔드포인트 응답이 JSON 포맷인 경우
응답 페이로드가 JSON 포맷(MIME 유형:`application/json`)으로 되어 있다면, SageMaker Clarify 처리 작업은 전체 페이로드를 JSON의 형태로 역직렬화합니다. 그런 다음에는 분석 구성에서 제공된 JMESPath 표현식을 사용하여 역직렬화된 해당 데이터로부터 예측을 추출합니다. 응답 페이로드에 포함된 레코드는 요청 페이로드 상의 레코드와 일치해야 합니다.
다음 섹션은 JSON 포맷으로 된 엔드포인트 응답의 예제를 보여줍니다. 이 섹션에는 다양한 포맷으로 되어 있는 다양한 문제 유형을 위한 응답 데이터의 예제 표가 포함되어 있습니다. 해당 분석 구성에 따라 예측을 추출했을 때의 실제 데이터는 이러한 예제의 데이터와 다를 수 있습니다.
### 엔드포인트 응답이 JSON 포맷이며 확률만 포함되어 있는 경우
다음 표는 확률 값(점수)만을 출력하는 엔드포인트에서 받은 응답의 예제입니다.
| 엔드포인트 요청 페이로드 | 엔드포인트 응답 페이로드(문자열 표현식) |
| --- | --- |
| 단일 레코드 | '[0.6]' |
| 레코드 2개 | '[0.6,0.3]' |
이전 예제에서의 경우 응답 페이로드 본문에 줄 바꿈이 없습니다. 그 대신 단일 JSON 객체에는 해당 요청의 각 레코드당 하나씩 점수의 목록이 포함되어 있습니다. 분석 구성 매개변수 `probability`를 JMESPath 표현식 "[\$1]"로 설정하여 해당 값을 추출합니다.
### 엔드포인트 응답이 JSON 포맷이며 예측 레이블만 포함하고 있는 경우
다음 표는 예측 레이블만을 출력하는 엔드포인트에서 받은 응답의 예제입니다.
| 엔드포인트 요청 페이로드 | 엔드포인트 응답 페이로드(문자열 표현식) |
| --- | --- |
| 단일 레코드 | '\$1"predicted\$1labels":[1]\$1' |
| 레코드 2개 | '\$1"predicted\$1labels":[1,0]\$1' |
`predictor` 구성의 `label`매개변수를 JMESPath 표현식 “predicted\$1labels”로 설정하면 SageMaker Clarify 처리 작업이 편향 분석을 위해 예측 레이블을 추출할 수 있게 됩니다.
### 엔드포인트 응답이 JSON 포맷이며 예측 레이블과 확률을 포함하고 있는 경우
다음 표는 예측 레이블과 그 점수를 출력하는 엔드포인트에서 받은 응답의 예제입니다.
| 엔드포인트 요청 페이로드 | 엔드포인트 응답 페이로드(문자열 표현식) |
| --- | --- |
| 단일 레코드 | '\$1"predictions":[\$1"label":1,"score":0.6\$1' |
| 레코드 2개 | ‘\$1"predictions":[\$1"label":1,"score":0.6\$1,\$1"label":0,"score":0.3\$1]\$1' |
이전 예제에서의 경우, `predictor`구성의 `label`매개변수를 JMESPath 표현식 "predictions[\$1].label"로 설정하여 예측 레이블을 추출합니다. `probability`를 JMESPath 표현식 “predictions[\$1].score”로 설정하여 확률을 추출합니다.
### 엔드포인트 응답이 JSON 포맷이며 복수의 예측 레이블과 확률을 포함하고 있는 경우(멀티클래스)
다음 표는 멀티클래스 모델로부터 받은 엔드포인트 응답의 예제로, 이는 다음을 출력합니다.
+ 예측 레이블의 목록
+ 확률, 선택된 예측 레이블, 해당 확률
| 엔드포인트 요청 페이로드 | 엔드포인트 응답 페이로드(문자열 표현식) |
| --- | --- |
| 단일 레코드 | '[\$1"predicted\$1label":"dog","probability":0.6,"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1]' |
| 레코드 2개 | '[\$1"predicted\$1label":"dog","probability":0.6,"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]\$1,\$1"predicted\$1label":"cat","probability":0.7,"predicted\$1labels":["cat","dog","fish"],"probabilities":[0.7,0.2,0.1]\$1]' |
SageMaker Clarify 처리 작업을 몇 가지 방식으로 구성하여 예측을 추출할 수 있습니다.
편향 분석의 경우, 이전 예제를 다음 중 **한 가지** 방식으로 구성할 수 있습니다.
+ `predictor` 구성의 `label`매개변수를 JMESPath 표현식 "[\$1].predicted\$1label"로 설정하여 예측 레이블을 추출합니다.
+ 해당 매개변수를 JMESPath 표현식 "[\$1].predicted\$1labels"로 설정하여 복수의 예측 레이블을 추출합니다. `probability`를 JMESPath 표현식 “[\$1].probabilities”로 설정하여 해당 확률을 추출합니다. SageMaker Clalify 처리 작업은 근접성 값이 가장 높은 레이블을 식별하여 예측 레이블을 자동으로 결정할 수 있습니다.
+ `probability`를 JMESPath 표현식 “[\$1].probabilities”로 설정하여 해당 확률을 추출합니다. `label_headers`가 제공된 경우, SageMaker Clalify 처리 작업은 확률 값이 가장 높은 레이블을 식별하여 예측 레이블을 자동으로 결정할 수 있습니다.
특징 중요도 분석의 경우, `probability`를 JMESPath 표현식 “[\$1].probabilities”로 설정하여 모든 예측 레이블의 해당 확률을 추출합니다. 그러면 모든 레이블에 대한 특징 속성이 계산됩니다.
# 테이블 형식 데이터에 대한 엔드포인트 요청 및 응답의 사전 확인
먼저 SageMaker AI 실시간 추론 엔드포인트에 모델을 배포한 다음 해당 엔드포인트에 요청을 보내는 것을 권장합니다. 요청과 응답을 수동으로 검사하여 둘 다 [테이블 형식 데이터에 대한 엔드포인트 요청](clarify-processing-job-data-format-tabular-request.md)섹션과 [테이블 형식 데이터에 대한 엔드포인트 응답](clarify-processing-job-data-format-tabular-response.md)섹션에서의 요구 사항을 준수하고 있는지 확인하세요. 모델 컨테이너가 배치 요청을 지원하는 경우, 먼저 단일 레코드 요청으로 시작했다가 이후 2개 이상의 레코드로 시도해볼 수 있습니다.
다음 명령은 AWS CLI를 사용하여 응답을 요청하는 방법을 보여줍니다. AWS CLI 는 SageMaker Studio 및 SageMaker 노트북 인스턴스에 사전 설치되어 있습니다. 를 설치하려면이 [설치 가이드를](https://aws.amazon.com/cli/) AWS CLI따르세요.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name $ENDPOINT_NAME \
--content-type $CONTENT_TYPE \
--accept $ACCEPT_TYPE \
--body $REQUEST_DATA \
$CLI_BINARY_FORMAT \
/dev/stderr 1>/dev/null
```
매개변수는 다음과 같이 정의됩니다.
+ `$ENDPOINT NAME` - 엔드포인트의 이름입니다.
+ `$CONTENT_TYPE` – 요청의 MIME 유형(모델 컨테이너 입력)입니다.
+ `$ACCEPT_TYPE` – 응답의 MIME 유형(모델 컨테이너 출력)입니다.
+ `$REQUEST_DATA` – 요청된 페이로드 문자열입니다.
+ `$CLI_BINARY_FORMAT` – 명령줄 인터페이스(CLI) 매개변수의 형식입니다. AWS CLI v1의 경우이 파라미터는 비워 두어야 합니다. v2의 경우 이 파라미터를 `--cli-binary-format raw-in-base64-out`으로 설정해야 합니다.
**참고**
AWS CLI v2[는 기본적으로](https://docs.aws.amazon.com/cli/latest/userguide/cliv2-migration.html#cliv2-migration-binaryparam) 이진 파라미터를 base64로 인코딩된 문자열로 전달합니다.
# AWS CLI v1 예제
이전 섹션의 예제는 AWS CLI v2에 대한 것입니다. 엔드포인트와 주고 받는 요청 및 응답을 보여주는 다음 예제에서는 AWS CLI v1을 사용합니다.
## CSV 포맷의 엔드포인트 요청 및 응답
다음 코드 예제에서 요청은 단일 레코드로 구성되며, 응답은 레코드의 확률 값에 해당합니다.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-sagemaker-xgboost-model \
--content-type text/csv \
--accept text/csv \
--body '1,2,3,4' \
/dev/stderr 1>/dev/null
```
이전 코드 예제에서의 응답 출력은 다음과 같습니다.
```
0.6
```
다음 코드 예제에서 요청은 2개의 레코드로 구성되며, 응답은 그에 대한 확률 값에 해당하고, 이는 쉼표로 구분되어 있습니다.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-sagemaker-xgboost-model \
--content-type text/csv \
--accept text/csv \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
이전 코드 예제에서, `--body`에 포함된 `$'content'`표현식은 명령이 콘텐츠의 `'\n'`을 줄 바꿈으로 해석하도록 지시합니다. 응답 출력은 다음과 같습니다.
```
0.6,0.3
```
다음 코드 예제에서 요청은 2개의 레코드로 구성되며, 응답은 그에 대한 확률 값에 해당하고, 줄 바꿈으로 구분되어 있습니다.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-1 \
--content-type text/csv \
--accept text/csv \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
이전 코드 예제에서의 응답 출력은 다음과 같습니다.
```
0.6
0.3
```
다음 코드 예제에서 요청은 단일 레코드로 구성되며, 응답은 3개 클래스가 포함된 멀티클래스 모델에서의 확률 값에 해당합니다.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-1 \
--content-type text/csv \
--accept text/csv \
--body '1,2,3,4' \
/dev/stderr 1>/dev/null
```
이전 코드 예제에서의 응답 출력은 다음과 같습니다.
```
0.1,0.6,0.3
```
다음 코드 예제에서 요청은 2개 레코드로 구성되며, 그 응답에는 3개 클래스가 포함된 멀티클래스 모델에서의 확률 값이 포함됩니다.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-1 \
--content-type text/csv \
--accept text/csv \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
이전 코드 예제에서의 응답 출력은 다음과 같습니다.
```
0.1,0.6,0.3
0.2,0.5,0.3
```
다음 코드 예제에서 요청은 2개의 레코드로 구성되며, 응답에는 예측 레이블과 확률이 포함됩니다.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-2 \
--content-type text/csv \
--accept text/csv \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
이전 코드 예제에서의 응답 출력은 다음과 같습니다.
```
1,0.6
0,0.3
```
다음 코드 예제에서 요청은 2개의 레코드로 구성되며, 응답에는 레이블 헤더와 확률이 포함됩니다.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-3 \
--content-type text/csv \
--accept text/csv \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
이전 코드 예제에서의 응답 출력은 다음과 같습니다.
```
"['cat','dog','fish']","[0.1,0.6,0.3]"
"['cat','dog','fish']","[0.2,0.5,0.3]"
```
## JSON Lines 포맷의 엔드포인트 요청 및 응답
다음 코드 예제에서 요청은 단일 레코드로 구성되며, 응답은 레코드의 확률 값에 해당합니다.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-jsonlines \
--content-type application/jsonlines \
--accept application/jsonlines \
--body '{"features":["This is a good product",5]}' \
/dev/stderr 1>/dev/null
```
이전 코드 예제에서의 응답 출력은 다음과 같습니다.
```
{"score":0.6}
```
다음 코드 예제에서 요청은 2개의 레코드를 포함하며, 응답에는 예측 레이블과 확률이 포함됩니다.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-jsonlines-2 \
--content-type application/jsonlines \
--accept application/jsonlines \
--body $'{"features":[1,2,3,4]}\n{"features":[5,6,7,8]}' \
/dev/stderr 1>/dev/null
```
이전 코드 예제에서의 응답 출력은 다음과 같습니다.
```
{"predicted_label":1,"probability":0.6}
{"predicted_label":0,"probability":0.3}
```
다음 코드 예제에서 요청은 2개의 레코드를 포함하며, 응답에는 레이블 헤더와 확률이 포함됩니다.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-jsonlines-3 \
--content-type application/jsonlines \
--accept application/jsonlines \
--body $'{"data":{"features":[1,2,3,4]}}\n{"data":{"features":[5,6,7,8]}}' \
/dev/stderr 1>/dev/null
```
이전 코드 예제에서의 응답 출력은 다음과 같습니다.
```
{"predicted_labels":["cat","dog","fish"],"probabilities":[0.1,0.6,0.3]}
{"predicted_labels":["cat","dog","fish"],"probabilities":[0.2,0.5,0.3]}
```
## 혼합 형식의 엔드포인트 요청 및 응답
다음 코드 예제에서 요청은 CSV 형식으로 되어 있고, 응답은 JSON Lines 형식으로 되어 있습니다.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-in-jsonlines-out \
--content-type text/csv \
--accept application/jsonlines \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
이전 코드 예제에서의 응답 출력은 다음과 같습니다.
```
{"probability":0.6}
{"probability":0.3}
```
다음 코드 예제에서 요청은 JSON Lines 형식으로 되어 있고, 응답은 CSV 형식으로 되어 있습니다.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-jsonlines-in-csv-out \
--content-type application/jsonlines \
--accept text/csv \
--body $'{"features":[1,2,3,4]}\n{"features":[5,6,7,8]}' \
/dev/stderr 1>/dev/null
```
이전 코드 예제에서의 응답 출력은 다음과 같습니다.
```
0.6
0.3
```
다음 코드 예제에서 요청은 CSV 형식으로 되어 있고, 응답은 JSON 형식으로 되어 있습니다.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-csv-in-jsonlines-out \
--content-type text/csv \
--accept application/jsonlines \
--body $'1,2,3,4\n5,6,7,8' \
/dev/stderr 1>/dev/null
```
이전 코드 예제에서의 응답 출력은 다음과 같습니다.
```
{"predictions":[{"label":1,"score":0.6},{"label":0,"score":0.3}]}
```
# 이미지 데이터 요구 사항
SageMaker Clarify 처리 작업은 이미지 설명을 지원합니다. 이 주제에는 이미지 데이터에 대한 데이터 형식 요구 사항이 나와 있습니다. 이미지 데이터 처리에 대한 자세한 내용은 [컴퓨터 비전의 설명 가능성을 위한 이미지 데이터의 분석](clarify-processing-job-run.md#clarify-processing-job-run-cv) 섹션을 참조하세요.
이미지 데이터세트에는 하나 이상의 이미지 파일이 포함되어 있습니다. SageMaker Clarify 처리 작업에 대한 입력 데이터세트를 식별하려면, `dataset`로 이름이 지정된 [ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateProcessingJob.html#sagemaker-CreateProcessingJob-request-ProcessingInputs) 또는 분석 구성 `dataset_uri`매개변수를 해당 이미지 파일의 Amazon S3 URI 접두사로 설정하세요.
지원되는 이미지 파일 형식과 파일 확장자는 다음 표에 나열되어 있습니다.
| 이미지 형식 | 파일 확장명 |
| --- | --- |
| JPEG | jpg, jpeg |
| PNG | PNG |
분석 구성의 `dataset_type`매개변수를 **application/x-image**로 설정하세요. 유형이 특정 이미지 파일 형식이 아니므로, 이미지 파일 형식과 확장자를 결정하기 위해 `content_type`이 사용됩니다.
SageMaker Clalify 처리 작업은 추가적인 처리를 위해 각 이미지 파일을 3차원의 [NumPy 배열](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html)로 로드합니다. 3차원에는 각 픽셀의 높이, 너비 및 RGB 값이 포함됩니다.
## 엔드포인트 요청 형식
SageMaker Clarify 처리 작업은 이미지의 원시 RGB 데이터를 JPEG 등의 호환되는 이미지 형식으로 변환합니다. 이 작업은 예측을 위해 데이터를 엔드포인트로 보내기 전에 수행됩니다. 지원되는 이미지 형식은 다음과 같습니다.
| 데이터 형식 | MIME 유형 | 파일 확장명 |
| --- | --- | --- |
| JPEG | `image/jpeg` | jpg, jpeg |
| PNG | `image/png` | PNG |
| NPY | `application/x-npy` | 모두 해당 |
분석 구성 매개변수 `content_type`을 사용하여 요청 페이로드의 데이터 형식을 지정합니다. `content_type`이 제공되지 않은 경우, 데이터 형식은 기본값인 `image/jpeg`가 됩니다.
## 엔드포인트 응답 형식
SageMaker Clarify 처리 작업은 추론 엔드포인트 호출의 응답을 수신하면 응답 페이로드를 역직렬화한 다음 이 페이로드에서 예측을 추출합니다.
### 이미지 분류 문제
응답 페이로드의 데이터 형식은 분석 구성 매개변수 accept\$1type을 통해 지정되어야 합니다. `accept_type`이 제공되지 않은 경우, 데이터 형식은 기본값인 `application/json`가 됩니다. 지원되는 형식은 테이블 형식 데이터 섹션의 **Endpoint response for tabular data**에 나와 있는 형식과 동일합니다.
단일 이미지를 받아들인 각 클래스에 대해 확률 값(점수)으로 구성된 배열을 반환하는 SageMaker AI의 기본 제공 이미지 분류 알고리즘의 예시는 [이미지 분류 알고리즘을 이용한 추론](image-classification.md#IC-inference) 섹션을 참조하세요.
다음 표에서 볼 수 있듯이, `content_type`매개변수가 `application/jsonlines`로 설정된 경우 그 응답은 JSON 객체가 됩니다.
| 엔드포인트 요청 페이로드 | 엔드포인트 응답 페이로드(문자열 표현식) |
| --- | --- |
| 단일 이미지 | '\$1"prediction":[0.1,0.6,0.3]\$1' |
이전 예제에서는 `probability`매개변수를 JMESPath 표현식 “prediction”으로 설정하여 점수를 추출했습니다.
`content_type`이 `application/json`으로 설정된 경우, 그 응답은 다음 표에서 볼 수 있듯이 JSON 객체가 됩니다.
| 엔드포인트 요청 페이로드 | 엔드포인트 응답 페이로드(문자열 표현식) |
| --- | --- |
| 단일 이미지 | '[0.1,0.6,0.3]' |
이전 예제에서는 `probability`를 JMESPath 표현식 “[\$1]”로 설정하여 해당 배열의 모든 요소를 추출했습니다. 이전 예제에서는 [`0.1, 0.6, 0.3]`이 추출되었습니다. 또는 사용자가 `probability`구성 매개변수 설정을 건너뛸 경우 해당 배열의 모든 요소도 함께 추출되게 됩니다. 이는 전체 페이로드 자체가 예측으로서 역직렬화되기 때문입니다.
### 객체 감지 문제
분석 구성 `accept_type`의 기본값은 `application/json`이며, 지원 가능한 유일한 형식은 객체 감지 추론 형식입니다. 응답 형식에 대한 자세한 내용은 [응답 형식](object-detection-in-formats.md#object-detection-recordio) 섹션을 참조하세요.
다음 표는 배열을 출력하는 엔드포인트에서 받은 응답의 예제입니다. 이 배열을 이루는 각 요소는 클래스 인덱스, 신뢰도 점수, 그리고 검출된 객체의 경계 상자 좌표를 포함하고 있는 값의 배열입니다.
| 엔드포인트 요청 페이로드 | 엔드포인트 응답 페이로드(문자열 표현식) |
| --- | --- |
| 단일 이미지(객체 1개) | '[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244]]' |
| 단일 이미지(객체 2개) | '[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244],[0.0, 0.73376623392105103, 0.5714187026023865, 0.40427327156066895, 0.827075183391571, 0.9712159633636475]]' |
다음 표는 배열을 참조하는 키가 포한된 JSON 객체를 출력하는 엔드포인트에서 받은 응답의 예제입니다. 분석 구성의 `probability`를 “prediction” 키로 설정하여 값을 추출합니다.
| 엔드포인트 요청 페이로드 | 엔드포인트 응답 페이로드(문자열 표현식) |
| --- | --- |
| 단일 이미지(객체 1개) | '\$1"prediction":[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244]]\$1' |
| 단일 이미지(객체 2개) | '\$1"prediction":[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244],[0.0, 0.73376623392105103, 0.5714187026023865, 0.40427327156066895, 0.827075183391571, 0.9712159633636475]]\$1' |
## 이미지 데이터에 대한 엔드포인트 요청 및 응답의 사전 확인
먼저 SageMaker AI 실시간 추론 엔드포인트에 모델을 배포한 다음 해당 엔드포인트에 요청을 보내는 것을 권장합니다. 요청 및 응답을 수동으로 검토합니다. 둘 다 **이미지 데이터에 대한 엔드포인트 요청** 섹션과 **이미지 데이터에 대한 엔드포인트 응답** 섹션의 요구 사항을 준수하고 있는지 확인하세요.
다음은 요청을 보내고 이미지 분류 및 객체 감지 문제에 대한 응답을 검사하는 방법을 보여주는 두 가지 코드 예제입니다.
### 이미지 분류 문제
다음 예제 코드는 엔드포인트로 하여금 PNG 파일을 읽도록 지시한 다음 이를 분류합니다.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-sagemaker-image-classification \
--content-type "image/png" \
--accept "application/json" \
--body fileb://./test.png \
/dev/stderr 1>/dev/null
```
이전 코드 예제에서의 응답 출력은 다음과 같습니다.
```
[0.1,0.6,0.3]
```
### 객체 감지 문제
다음 예제 코드는 엔드포인트로 하여금 JPEG 파일을 읽도록 지시한 다음 그 안에 있는 객체를 감지합니다.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-sagemaker-object-detection \
--content-type "image/jpg" \
--accept "application/json" \
--body fileb://./test.jpg \
/dev/stderr 1>/dev/null
```
이전 코드 예제에서의 응답 출력은 다음과 같습니다.
```
{"prediction":[[4.0, 0.86419455409049988, 0.3088374733924866, 0.07030484080314636, 0.7110607028007507, 0.9345266819000244],[0.0, 0.73376623392105103, 0.5714187026023865, 0.40427327156066895, 0.827075183391571, 0.9712159633636475],[4.0, 0.32643985450267792, 0.3677481412887573, 0.034883320331573486, 0.6318609714508057, 0.5967587828636169],[8.0, 0.22552496790885925, 0.6152569651603699, 0.5722782611846924, 0.882301390171051, 0.8985623121261597],[3.0, 0.42260299175977707, 0.019305512309074402, 0.08386176824569702, 0.39093565940856934, 0.9574796557426453]]}
```
# 시계열 데이터
시계열 데이터란 3차원의 데이터 프레임에 로드할 수 있는 데이터를 말합니다. 프레임에서 타임스탬프마다 각 행은 대상 레코드를 나타내며, 각 대상 레코드에는 하나 이상의 관련 열이 포함되어 있습니다. 데이터 프레임 셀 각각의 값은 숫자, 범주 또는 텍스트 데이터 유형일 수 있습니다.
## 시계열 데이터세트 사전 조건
분석 전에 데이터 정리 또는 특성 엔지니어링과 같이 데이터를 준비하는 데 필요한 사전 처리 단계를 완료합니다. 데이터세트는 하나 또는 여러 개 제공할 수 있습니다. 여러 데이터세트를 제공하는 경우, 다음 방법 중 하나를 사용하여 SageMaker Clarify 처리 작업에 데이터세트를 제공하세요.
+ `dataset`로 이름이 지정된 [ProcessingInput](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ProcessingInput.html) 또는 분석 구성 `dataset_uri`를 사용하여 기본 데이터세트를 지정합니다. `dataset_uri`에 대한 자세한 내용은 [분석 구성 파일](clarify-processing-job-configure-analysis.md)의 파라미터 목록을 참조하세요.
+ 분석 구성 파일에서 제공된 `baseline`매개변수를 사용합니다. `static_covariates`가 있는 경우 기준 데이터세트가 필요합니다. 예시가 포함된 분석 구성 파일에 대한 자세한 내용은 [분석 구성 파일](clarify-processing-job-configure-analysis.md) 섹션을 참조하세요.
다음 표에는 지원되는 데이터 형식, 해당 파일 확장명 및 MIME 유형이 나열되어 있습니다.
| 데이터 형식 | 파일 확장명 | MIME 유형 |
| --- | --- | --- |
| `item_records` | json | `application/json` |
| `timestamp_records` | json | `application/json` |
| `columns` | json | `application/json` |
JSON은 정형 데이터에서 모든 수준의 복잡성을 표현할 수 있는 유연한 형식입니다. 표에 표시된 대로 SageMaker Clarify는 `item_records`, `timestamp_records`, `columns` 형식을 지원합니다.
## 시계열 데이터세트 구성 예시
이 섹션에서는 JSON 형식의 시계열 데이터에 `time_series_data_config`를 사용하여 분석 구성을 설정하는 방법을 보여줍니다. 다음과 같이 각각 타임스탬프(t), 대상 시계열(x), 관련 시계열(r) 2개, 정적 공변량(u) 2개가 각각 포함된 항목 2개로 구성된 데이터세트가 있다고 가정해 보겠습니다.
t1 = [0,1,2], t2 = [2,3]
x1 = [5,6,4], x2 = [0,4]
r1 = [0,1,0], r 21 = [1,1]
r 12 = [0,0,0], r 22 = [1,0]
u 11 = -1, u 21 = 0
u 12 = 1, u 22 = 2
`dataset_format`에 따라 세 가지 방법으로 `time_series_data_config`를 사용하여 데이터세트를 인코딩할 수 있습니다. 다음 섹션에서 각 방법에 대해 설명합니다.
### `dataset_format`이 `columns`인 경우 시계열 데이터 구성
다음 예시에서는 `dataset_format`에 `columns` 값을 사용합니다. 다음 JSON 파일은 이전 데이터세트를 나타냅니다.
```
{
"ids": [1, 1, 1, 2, 2],
"timestamps": [0, 1, 2, 2, 3], # t
"target_ts": [5, 6, 4, 0, 4], # x
"rts1": [0, 1, 0, 1, 1], # r1
"rts2": [0, 0, 0, 1, 0], # r2
"scv1": [-1, -1, -1, 0, 0], # u1
"scv2": [1, 1, 1, 2, 2], # u2
}
```
항목 ID는 `ids` 필드에서 반복됩니다. `time_series_data_config`의 올바른 구현은 다음과 같습니다.
```
"time_series_data_config": {
"item_id": "ids",
"timestamp": "timestamps",
"target_time_series": "target_ts",
"related_time_series": ["rts1", "rts2"],
"static_covariates": ["scv1", "scv2"],
"dataset_format": "columns"
}
```
### `dataset_format`이 `item_records`인 경우 시계열 데이터 구성
다음 예시에서는 `dataset_format`에 `item_records` 값을 사용합니다. 다음 JSON 파일은 데이터세트를 나타냅니다.
```
[
{
"id": 1,
"scv1": -1,
"scv2": 1,
"timeseries": [
{"timestamp": 0, "target_ts": 5, "rts1": 0, "rts2": 0},
{"timestamp": 1, "target_ts": 6, "rts1": 1, "rts2": 0},
{"timestamp": 2, "target_ts": 4, "rts1": 0, "rts2": 0}
]
},
{
"id": 2,
"scv1": 0,
"scv2": 2,
"timeseries": [
{"timestamp": 2, "target_ts": 0, "rts1": 1, "rts2": 1},
{"timestamp": 3, "target_ts": 4, "rts1": 1, "rts2": 0}
]
}
]
```
각 항목은 JSON에서 별도의 항목으로 표시됩니다. 다음 코드 조각은 해당 `time_series_data_config`를 보여줍니다(JMESPath 사용).
```
"time_series_data_config": {
"item_id": "[*].id",
"timestamp": "[*].timeseries[].timestamp",
"target_time_series": "[*].timeseries[].target_ts",
"related_time_series": ["[*].timeseries[].rts1", "[*].timeseries[].rts2"],
"static_covariates": ["[*].scv1", "[*].scv2"],
"dataset_format": "item_records"
}
```
### `dataset_format`이 `timestamp_record`인 경우 시계열 데이터 구성
다음 예시에서는 `dataset_format`에 `timestamp_record` 값을 사용합니다. 다음 JSON 파일은 이전 데이터세트를 나타냅니다.
```
[
{"id": 1, "timestamp": 0, "target_ts": 5, "rts1": 0, "rts2": 0, "svc1": -1, "svc2": 1},
{"id": 1, "timestamp": 1, "target_ts": 6, "rts1": 1, "rts2": 0, "svc1": -1, "svc2": 1},
{"id": 1, "timestamp": 2, "target_ts": 4, "rts1": 0, "rts2": 0, "svc1": -1, "svc2": 1},
{"id": 2, "timestamp": 2, "target_ts": 0, "rts1": 1, "rts2": 1, "svc1": 0, "svc2": 2},
{"id": 2, "timestamp": 3, "target_ts": 4, "rts1": 1, "rts2": 0, "svc1": 0, "svc2": 2},
]
```
JSON의 각 항목은 단일 타임스탬프를 나타내며 단일 항목에 해당합니다. 구현 `time_series_data_config`는 다음과 같이 표시됩니다.
```
{
"item_id": "[*].id",
"timestamp": "[*].timestamp",
"target_time_series": "[*].target_ts",
"related_time_series": ["[*].rts1"],
"static_covariates": ["[*].scv1"],
"dataset_format": "timestamp_records"
}
```
# 시계열 데이터에 대한 엔드포인트 요청
SageMaker Clarify 처리 작업은 데이터를 임의의 JSON 구조(MIME 유형: `application/json` 사용)로 직렬화합니다. 이렇게 하려면 분석 구성 `content_template`매개변수에 템플릿 문자열을 제공해야 합니다. 이는 SageMaker Clarify 처리 작업에서 모델에 제공된 JSON 쿼리를 구성하는 데 사용됩니다. `content_template`에는 데이터세트의 레코드 하나 또는 여러 개가 포함되어 있습니다. 또한 각 레코드의 JSON 구조를 구성하는 데 사용되는 `record_template`에 대한 템플릿 문자열도 제공해야 합니다. 그런 다음 이러한 레코드가 `content_template`에 삽입됩니다. `content_type` 또는 `dataset_type`에 대한 자세한 내용은 [분석 구성 파일](clarify-processing-job-configure-analysis.md) 섹션을 참조하세요.
**참고**
`content_template` 및 `record_template`은 문자열 파라미터이므로, JSON 직렬화 구조의 일부인 모든 큰 따옴표 문자(")는 해당 구성 파일에서 이스케이프 처리된 문자로 표시되어야 합니다. 예를 들어, Python에서 큰 따옴표를 이스케이프 처리하려면 `content_template`에 대해 다음 값을 입력하면 됩니다.
```
'$record'
```
다음 표에는 직렬화된 JSON 요청 페이로드의 예시와 이를 구성하는 데 필요한 해당 `content_template` 및 `record_template` 파라미터가 나와 있습니다.
| 사용 사례: | 엔드포인트 요청 페이로드(문자열 표현식) | content\$1template | record\$1template |
| --- | --- | --- | --- |
| 한 번에 하나의 레코드 | `{"target": [1, 2, 3],"start": "2024-01-01 01:00:00"}` | `'$record'` | `'{"start": $start_time, "target": $target_time_series}'` |
| `$related_time_series` 및 `$static_covariates`가 포함된 단일 레코드 | `{"target": [1, 2, 3],"start": "2024-01-01 01:00:00","dynamic_feat": [[1.0, 2.0, 3.0],[1.0, 2.0, 3.0],"cat": [0,1]}` | `'$record'` | `'{"start": $start_time, "target": $target_time_series, "dynamic_feat": $related_time_series, "cat": $static_covariates}'` |
| 다중 레코드 | `{"instances": [{"target": [1, 2, 3],"start": "2024-01-01 01:00:00"}, {"target": [1, 2, 3],"start": "2024-01-01 02:00:00"}]}` | `'{"instances": $records}'` | `'{"start": $start_time, "target": $target_time_series}'` |
| `$related_time_series` 및 `$static_covariates`가 포함된 다중 레코드 | `{"instances": [{"target": [1, 2, 3],"start": "2024-01-01 01:00:00","dynamic_feat": [[1.0, 2.0, 3.0],[1.0, 2.0, 3.0],"cat": [0,1]}, {"target": [1, 2, 3],"start": "2024-01-01 02:00:00","dynamic_feat": [[1.0, 2.0, 3.0],[1.0, 2.0, 3.0],"cat": [0,1]}]}` | `'{"instances": $records}'` | `''{"start": $start_time, "target": $target_time_series, "dynamic_feat": $related_time_series, "cat": $static_covariates}'` |
# 시계열 데이터에 대한 엔드포인트 응답
SageMaker Clarify 처리 작업은 전체 페이로드를 JSON으로 역직렬화합니다. 그런 다음에는 분석 구성에서 제공된 JMESPath 표현식을 사용하여 역직렬화된 해당 데이터로부터 예측을 추출합니다. 응답 페이로드에 포함된 레코드는 요청 페이로드 상의 레코드와 일치해야 합니다.
다음 표는 평균 예측 값만을 출력하는 엔드포인트에서 받은 응답의 예시입니다. [분석 구성](https://docs.aws.amazon.com/sagemaker/latest/dg/clarify-processing-job-configure-analysis.html#clarify-processing-job-configure-analysis-parameters)의 `predictor` 필드에 사용된 `forecast`의 값은 처리 작업에 대한 예측 결과를 찾기 위해 JMESPath 표현식으로 제공되어야 합니다.
| 엔드포인트 요청 페이로드 | 엔드포인트 응답 페이로드(문자열 표현식) | 분석 구성에서 예측을 위한 JMESPath 표현식 |
| --- | --- | --- |
| 단일 레코드 예시입니다. 예측을 제대로 추출하려면 구성이 `TimeSeriesModelConfig(forecast="prediction.mean")`여야 합니다. | `'{"prediction": {"mean": [1, 2, 3, 4, 5]}'` | `'prediction.mean'` |
| 다중 레코드입니다. An AWS deepAR 엔드포인트 응답. | `'{"predictions": [{"mean": [1, 2, 3, 4, 5]}, {"mean": [1, 2, 3, 4, 5]}]}'` | `'predictions[*].mean'` |
# 시계열 데이터에 대한 엔드포인트 요청 및 응답의 사전 확인
SageMaker AI 실시간 추론 엔드포인트에 모델을 배포한 다음 해당 엔드포인트에 요청을 보내는 것을 권장합니다. 요청과 응답을 수동으로 검사하여 둘 다 [시계열 데이터에 대한 엔드포인트 요청](clarify-processing-job-data-format-time-series-request-jsonlines.md) 섹션과 [시계열 데이터에 대한 엔드포인트 응답](clarify-processing-job-data-format-time-series-response-json.md) 섹션에 있는 요구 사항을 준수하고 있는지 확인하세요. 모델 컨테이너가 배치 요청을 지원하는 경우, 먼저 단일 레코드 요청으로 시작했다가 이후 2개 이상의 레코드로 시도해볼 수 있습니다.
다음 명령은 AWS CLI를 사용하여 응답을 요청하는 방법을 보여줍니다. AWS CLI 는 Studio 및 SageMaker 노트북 인스턴스에 사전 설치되어 있습니다. 를 설치하려면 [설치 안내서](https://aws.amazon.com//cli/)를 AWS CLI따릅니다.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name $ENDPOINT_NAME \
--content-type $CONTENT_TYPE \
--accept $ACCEPT_TYPE \
--body $REQUEST_DATA \
$CLI_BINARY_FORMAT \
/dev/stderr 1>/dev/null
```
파라미터는 다음과 같이 정의됩니다.
+ \$1ENDPOINT NAME - 엔드포인트의 이름입니다.
+ \$1CONTENT\$1TYPE - 요청의 MIME 유형(모델 컨테이너 입력)입니다.
+ \$1ACCEPT\$1TYPE - 응답의 MIME 유형(모델 컨테이너 출력)입니다.
+ \$1REQUEST\$1DATA - 요청된 페이로드 문자열입니다.
+ \$1CLI\$1BINARY\$1FORMAT – 명령줄 인터페이스(CLI) 파라미터의 형식입니다. AWS CLI v1의 경우이 파라미터는 비워 두어야 합니다. v2의 경우 이 파라미터를 `--cli-binary-format raw-in-base64-out`으로 설정해야 합니다.
**참고**
AWS CLI v2는 기본적으로 이진 파라미터를 base64로 인코딩된 문자열로 전달합니다. 엔드포인트에 대한 다음 요청 및 응답 예제는 AWS CLI v1을 사용합니다.
------
#### [ Example 1 ]
다음 코드 예시에서 요청은 단일 레코드로 구성됩니다.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-json \
--content-type application/json \
--accept application/json \
--body '{"target": [1, 2, 3, 4, 5],
"start": "2024-01-01 01:00:00"}' \
/dev/stderr 1>/dev/null
```
다음 코드 조각은 해당 응답 출력을 보여줍니다.
```
{'predictions': {'mean': [1, 2, 3, 4, 5]}
```
------
#### [ Example 2 ]
다음 코드 예시에서 요청은 두 개의 레코드를 포함합니다.
```
aws sagemaker-runtime invoke-endpoint \
--endpoint-name test-endpoint-json-2 \
--content-type application/json \
--accept application/json \
--body $'{"instances": [{"target":[1, 2, 3],
"start":"2024-01-01 01:00:00",
"dynamic_feat":[[1, 2, 3, 4, 5],
[1, 2, 3, 4, 5]]}], {"target":[1, 2, 3],
"start":"2024-01-02 01:00:00",
"dynamic_feat":[[1, 2, 3, 4, 5],
[1, 2, 3, 4, 5]]}]}' \
dev/stderr 1>/dev/null
```
응답 출력은 다음과 같습니다.
```
{'predictions': [{'mean': [1, 2, 3, 4, 5]}, {'mean': [1, 2, 3, 4, 5]}]}
```
------