# 데이터 세트 관리
<a name="datasets-manage"></a>

이 주제에서는 데이터 세트 생성, 검색, 나열, 업데이트 및 삭제를 다룹니다.

## 데이터 세트 생성
<a name="datasets-create"></a>

`CreateDataset` API는 새 평가 데이터 세트를 생성합니다. 이는 비동기 작업(HTTP 202)으로, 수집이 완료되면 데이터 세트가에서 `ACTIVE` `CREATING`로 전환됩니다.

 **필수 파라미터:** `datasetName` (영숫자 및 밑줄만, `^[a-zA-Z][a-zA-Z0-9_]{0,47}$`), `schemaType`및 `source` (인라인 예제 또는 S3 URI).

 **선택적 파라미터:** `description`, `kmsKeyArn` (고객 관리형 암호화 키, 생성 후 변경할 수 없음 - [데이터 세트 암호화](datasets-encryption.md) 참조), `tags`.

다음 예제에서는 데이터 세트를 생성하는 방법을 보여줍니다.

**Example**  

1. 

   ```
   # Add a dataset to your project
   agentcore add dataset --name my_eval_dataset \
       --schema-type AGENTCORE_EVALUATION_PREDEFINED_V1
   
   # Edit the generated JSONL file with your scenarios
   # File location: agentcore/datasets/my_eval_dataset.jsonl
   
   # Deploy to create the dataset in your AWS account
   agentcore deploy
   ```

   이렇게 하면 로컬 JSONL 파일이 생성되고 프로젝트 구성에 데이터 세트가 등록됩니다. 를 실행`agentcore deploy`하여 데이터 세트 리소스를 생성하고 예제를 서비스에 동기화합니다.
**참고**  
AgentCore 프로젝트 디렉터리(로 생성됨) 내에서이 작업을 실행합니다`agentcore create`.

1. 

   ```
   from bedrock_agentcore.evaluation import DatasetClient
   
   client = DatasetClient(region_name="us-west-2")
   
   # Create with inline examples (polls until ACTIVE)
   ds = client.create_dataset_and_wait(
       datasetName="customer_support_scenarios",
       schemaType="AGENTCORE_EVALUATION_PREDEFINED_V1",
       source={
           "inlineExamples": {
               "examples": [
                   {
                       "scenario_id": "TC-01",
                       "turns": [{"input": "What is my balance?", "expected_response": "Your balance is $50."}],
                       "assertions": ["Response includes a dollar amount"],
                   }
               ]
           }
       },
   )
   print(f"Dataset ID: {ds['datasetId']}, Status: {ds['status']}")
   
   # Create with S3 source
   ds = client.create_dataset_and_wait(
       datasetName="my_s3_dataset",
       schemaType="AGENTCORE_EVALUATION_PREDEFINED_V1",
       source={"s3Source": {"s3Uri": "s3://my-bucket/scenarios.jsonl"}},
   )
   ```
**참고**  
S3 수집의 경우 JSONL 파일의 각 줄에는 `exampleId` 필드가 포함되어야 합니다. S3 버킷은 호출자의 자격 증명을 사용하여 액세스할 수 있어야 합니다.

1. 

   ```
   import boto3
   import time
   
   client = boto3.client('bedrock-agentcore-control')
   
   response = client.create_dataset(
       datasetName='customer_support_scenarios',
       schemaType='AGENTCORE_EVALUATION_PREDEFINED_V1',
       source={
           'inlineExamples': {
               'examples': [
                   {
                       'scenario_id': 'TC-01',
                       'turns': [{'input': 'What is my balance?', 'expected_response': 'Your balance is $50.'}],
                       'assertions': ['Response includes a dollar amount'],
                   }
               ]
           }
       }
   )
   dataset_id = response['datasetId']
   
   # Create with S3 source
   response = client.create_dataset(
       datasetName='my_s3_dataset',
       schemaType='AGENTCORE_EVALUATION_PREDEFINED_V1',
       source={
           's3Source': {'s3Uri': 's3://my-bucket/scenarios.jsonl'}
       }
   )
   
   # Poll until ACTIVE
   while True:
       ds = client.get_dataset(datasetId=dataset_id)
       if ds['status'] in ('ACTIVE', 'CREATE_FAILED'):
           break
       time.sleep(2)
   ```

1. 

   ```
   # Create with inline examples
   aws bedrock-agentcore-control create-dataset \
       --dataset-name "customer_support_scenarios" \
       --schema-type AGENTCORE_EVALUATION_PREDEFINED_V1 \
       --source '{"inlineExamples": {"examples": [{"scenario_id": "TC-01", "turns": [{"input": "What is my balance?", "expected_response": "Your balance is $50."}], "assertions": ["Response includes a dollar amount"]}]}}'
   
   # Create with S3 source
   aws bedrock-agentcore-control create-dataset \
       --dataset-name "my_s3_dataset" \
       --schema-type AGENTCORE_EVALUATION_PREDEFINED_V1 \
       --source '{"s3Source": {"s3Uri": "s3://my-bucket/scenarios.jsonl"}}'
   
   # Poll until ACTIVE
   aws bedrock-agentcore-control get-dataset \
       --dataset-id my-dataset-id
   ```

## 데이터 세트 가져오기
<a name="datasets-get"></a>

`GetDataset` API는 데이터 세트 메타데이터, 상태, 예제 수 및 데이터 세트 콘텐츠에 대해 미리 서명된 다운로드 URL을 검색합니다. 기본적으로 초안을 읽고 게시된 버전에 `datasetVersion` 대해를 지정합니다.

`downloadUrl`는 전체 `dataset.jsonl` 파일에 대해 미리 서명된 S3 URL입니다. 인증 헤더 없이 일반 HTTP GET 요청으로 다운로드할 수 있습니다.

다음 예제에서는 데이터 세트를 가져오는 방법을 보여줍니다.

**Example**  

1. 

   ```
   # Show dataset deployment status and metadata
   agentcore status --type dataset
   
   # Download dataset content to your local JSONL file (default: Draft)
   agentcore dataset download --name my_eval_dataset
   
   # Download a specific published version
   agentcore dataset download --name my_eval_dataset --version 1
   ```

1. 

   ```
   from bedrock_agentcore.evaluation import DatasetClient
   
   client = DatasetClient(region_name="us-west-2")
   
   # Get dataset (default: Draft)
   ds = client.get_dataset(datasetId="my-dataset-id")
   print(f"Status: {ds['status']}, Examples: {ds['exampleCount']}")
   print(f"Download URL: {ds['downloadUrl']}")
   
   # Get a specific published version
   ds_v1 = client.get_dataset(datasetId="my-dataset-id", datasetVersion="1")
   ```

1. 

   ```
   import boto3
   
   client = boto3.client('bedrock-agentcore-control')
   
   response = client.get_dataset(datasetId='my-dataset-id')
   print(f"Status: {response['status']}, Examples: {response['exampleCount']}")
   
   # Download the dataset content via presigned URL
   if 'downloadUrl' in response:
       import requests
       data = requests.get(response['downloadUrl'])
       print(data.text)
   
   # Get a specific published version
   response = client.get_dataset(datasetId='my-dataset-id', datasetVersion='1')
   ```

1. 

   ```
   # Get dataset (default: Draft)
   aws bedrock-agentcore-control get-dataset \
       --dataset-id my-dataset-id
   
   # Get a specific published version
   aws bedrock-agentcore-control get-dataset \
       --dataset-id my-dataset-id \
       --dataset-version 1
   ```

## 데이터 세트 나열
<a name="datasets-list"></a>

`ListDatasets` API는 계정 및 리전에 있는 데이터 세트의 페이지 매김 목록을 반환합니다.

다음 예제에서는 데이터 세트를 나열하는 방법을 보여줍니다.

**Example**  

1. 

   ```
   agentcore status --type dataset
   ```

1. 

   ```
   from bedrock_agentcore.evaluation import DatasetClient
   
   client = DatasetClient(region_name="us-west-2")
   
   response = client.list_datasets()
   for dataset in response["datasets"]:
       print(f"  {dataset['datasetName']} ({dataset['status']})")
   ```

1. 

   ```
   import boto3
   
   client = boto3.client('bedrock-agentcore-control')
   
   response = client.list_datasets()
   for dataset in response['datasets']:
       print(f"  {dataset['datasetName']} ({dataset['status']})")
   ```

1. 

   ```
   aws bedrock-agentcore-control list-datasets
   ```

## 데이터 세트 업데이트
<a name="datasets-update"></a>

`UpdateDataset` API는 데이터 세트 메타데이터를 업데이트합니다. 이는 동기식 작업(HTTP 200)입니다. `description` 및 만 업데이트할 수 `tags` 있습니다. `datasetName`, `schemaType`및 `kmsKeyArn`는 생성 후 변경할 수 없습니다.

데이터 세트는 `ACTIVE`, `UPDATE_FAILED`또는 `CREATE_FAILED` 상태여야 합니다.

다음 예제에서는 데이터 세트 메타데이터를 업데이트하는 방법을 보여줍니다.

**Example**  

1. AgentCore CLI를 사용하여 데이터 세트를 업데이트하려면 `agentcore.json` 파일에서 데이터 세트 구성을 직접 편집한 다음 재배포합니다.

   ```
   agentcore deploy
   ```

   를 열고 `datasets` 배열에서 데이터 세트를 `agentcore.json`찾은 다음를 수정한 `description`다음를 실행합니다`agentcore deploy`. 변경 사항은 배포 후 적용됩니다.
**참고**  
AgentCore 프로젝트 디렉터리(로 생성됨) 내에서이 작업을 실행합니다`agentcore create`.

1. 

   ```
   from bedrock_agentcore.evaluation import DatasetClient
   
   client = DatasetClient(region_name="us-west-2")
   
   client.update_dataset(datasetId="my-dataset-id", description="Updated description")
   ```

1. 

   ```
   import boto3
   
   client = boto3.client('bedrock-agentcore-control')
   
   client.update_dataset(datasetId='my-dataset-id', description='Updated description')
   ```

1. 

   ```
   aws bedrock-agentcore-control update-dataset \
       --dataset-id my-dataset-id \
       --description "Updated description"
   ```

## 데이터 세트 삭제
<a name="datasets-delete"></a>

`DeleteDataset` API는 데이터 세트를 삭제합니다. 이는 비동기 작업(HTTP 202)입니다.
+  **전체 삭제**( 생략`datasetVersion`): 모든 버전, 초안 및 데이터 세트 레코드를 삭제합니다.
+  **버전별 삭제**(정수`datasetVersion`로 지정): 게시된 버전만 삭제합니다.

데이터 세트는 `ACTIVE`, `CREATE_FAILED``UPDATE_FAILED`, 또는 `DELETE_FAILED` 상태여야 합니다.

**참고**  
버전별 삭제에는 정수 버전 번호만 허용됩니다.

다음 예제에서는 데이터 세트를 삭제하는 방법을 보여줍니다.

**Example**  

1. 

   ```
   # Delete a specific published version
   agentcore dataset remove-version 1 --name my_eval_dataset
   
   # Delete entire dataset
   agentcore remove dataset --name my_eval_dataset
   agentcore deploy
   ```

1. 

   ```
   from bedrock_agentcore.evaluation import DatasetClient
   
   client = DatasetClient(region_name="us-west-2")
   
   # Delete a specific published version
   client.delete_dataset_and_wait(datasetId="my-dataset-id", datasetVersion="1")
   
   # Delete entire dataset (polls until complete)
   client.delete_dataset_and_wait(datasetId="my-dataset-id")
   ```

1. 

   ```
   import boto3
   
   client = boto3.client('bedrock-agentcore-control')
   
   # Delete a specific published version
   client.delete_dataset(datasetId='my-dataset-id', datasetVersion='1')
   
   # Delete entire dataset
   client.delete_dataset(datasetId='my-dataset-id')
   ```

1. 

   ```
   # Delete a specific published version
   aws bedrock-agentcore-control delete-dataset \
       --dataset-id my-dataset-id \
       --dataset-version 1
   
   # Delete entire dataset
   aws bedrock-agentcore-control delete-dataset \
       --dataset-id my-dataset-id
   ```