기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 데이터 소스에 메타데이터를 포함하여 지식 기반 쿼리 개선
<a name="kb-metadata"></a>

CSV(쉼표로 구분된 값) 파일을 수집할 때 지식 기반이 특정 열을 콘텐츠 필드와 메타데이터 필드로 취급하도록 할 수 있습니다. 이제 수백 또는 수천 개의 콘텐츠/메타데이터 파일 페어를 처리하는 대신 단일 CSV 파일과 해당 metadata.json 파일을 사용해 CSV 내의 각 열을 처리하는 방법에 대한 지식 기반 힌트를 제공할 수 있습니다.

청크당 문서 메타데이터 필드/속성에는 한도가 있습니다. [지식 기반 할당량](https://docs.aws.amazon.com/bedrock/latest/userguide/quotas.html)을 참조하세요

CSV 파일을 수집하기 전에 다음을 확인합니다.
+ CSV가 RFC4180 형식이며 UTF-8로 인코딩되어 있습니다.
+ CSV의 첫 번째 행에 헤더 정보가 포함되어 있습니다.
+ metadata.json 파일에 제공된 메타데이터 필드가 CSV에 열로 표시됩니다.
+ 다음 형식의 fileName.csv.metadata.json 파일을 제공해야 합니다.

  ```
  {
      "metadataAttributes": {
          "${attribute1}": "${value1}",
          "${attribute2}": "${value2}",
          ...
      },
      "documentStructureConfiguration": {
          "type": "RECORD_BASED_STRUCTURE_METADATA",
          "recordBasedStructureMetadata": {
              "contentFields": [
                  {
                      "fieldName": "string"
                  }
              ],
              "metadataFieldsSpecification": {
                  "fieldsToInclude": [
                      {
                          "fieldName": "string"
                      }
                  ],
                  "fieldsToExclude": [
                      {
                          "fieldName": "string"
                      }
                  ]
              }
          }
      }
  }
  ```

CSV 파일은 한 번에 한 행씩 구문 분석되고 청킹 전략과 벡터 임베딩이 콘텐츠 필드에 적용됩니다. Amazon Bedrock Knowledge Bases는 현재 하나의 콘텐츠 필드를 지원합니다. 콘텐츠 필드는 청크로 분할되고 각 청크와 연결된 메타데이터 필드(열)는 문자열 값으로 처리됩니다.

예를 들어 'Description' 열과 'Creation\_Date' 열이 있는 CSV가 있다고 가정해 보겠습니다. 설명 필드는 콘텐츠 필드이고 생성 날짜는 연결된 메타데이터 필드입니다. 설명 텍스트는 청크로 분할되고 CSV의 각 행에 대해 벡터 임베딩으로 변환됩니다. 생성 날짜 값은 날짜를 문자열로 표현한 것으로 취급되며 설명의 각 청크와 연결됩니다.

포함/제외 필드가 제공되지 않으면 콘텐츠 열을 제외한 모든 열이 메타데이터 열로 처리됩니다. 포함 필드만 제공된 경우 제공된 열만 메타데이터로 처리됩니다. 제외 필드만 제공된 경우 제외 열을 제외한 모든 열이 메타데이터로 처리됩니다. `fieldsToInclude` 및 `fieldsToExclude` 모두에서 동일한 `fieldName`을 제공하는 경우 Amazon Bedrock은 검증 예외를 발생시킵니다. 포함과 제외 사이에 충돌이 있는 경우 실패로 이어집니다.

CSV 내에서 발견된 빈 행은 무시되거나 건너뜁니다.

## 예: 메타데이터가 있는 다중 행 CSV
<a name="kb-metadata-csv-example"></a>

다음 예제에서는 전체 CSV 파일과 해당 메타데이터 JSON 파일을 보여줍니다.

**예제 CSV 파일(`properties.csv`)**

```
description,city,price,bedrooms
"Spacious 3-bedroom home with updated kitchen and large backyard.",Seattle,450000,3
"Modern downtown condo with floor-to-ceiling windows and city views.",Portland,325000,2
"Charming craftsman bungalow with original hardwood floors.",Austin,275000,2
```

**해당 메타데이터 파일(`properties.csv.metadata.json`)**

```
{
    "metadataAttributes": {
        "source": "property_listings_2024"
    },
    "documentStructureConfiguration": {
        "type": "RECORD_BASED_STRUCTURE_METADATA",
        "recordBasedStructureMetadata": {
            "contentFields": [
                {
                    "fieldName": "description"
                }
            ],
            "metadataFieldsSpecification": {
                "fieldsToInclude": [
                    {
                        "fieldName": "city"
                    },
                    {
                        "fieldName": "price"
                    }
                ]
            }
        }
    }
}
```

이 예시는 다음과 같이 설정되어 있습니다.
+ `contentFields` - 한 열(`description`)을 청크 및 임베드할 콘텐츠로 지정합니다. 하나의 콘텐츠 필드만 지원됩니다.
+ `fieldsToInclude` - 필터링 가능한 메타데이터로 처리할 열(`city` 및 `price`)을 지정합니다. `bedrooms` 열은 나열되지 않으므로 제외됩니다.
+ `metadataAttributes` -이 CSV의 모든 청크에 적용되는 문서 수준 메타데이터를 지정합니다. 이 예제에서는 모든 행에 적용되는 정적 속성`source`입니다.

각 행은 청크 하나를 생성합니다. 첫 번째 행의 경우 청크 텍스트는 설명이고 메타데이터는 `city: "Seattle"`, `price: "450000"`및 입니다`source: "property_listings_2024"`. CSV 열의 모든 메타데이터 값은 문자열로 저장됩니다.

## 지원되는 메타데이터 데이터 형식
<a name="kb-metadata-data-types"></a>

메타데이터 속성에는 다음 데이터 유형이 지원됩니다.
+ `STRING` - 텍스트 값입니다.
+ `NUMBER` - 숫자 값입니다. 이 페이지에 설명된 CSV 기반 메타데이터 구성을 사용하는 경우 숫자 값은 문자열로 저장됩니다.
+ `BOOLEAN` - true 또는 false 값입니다.
+ `STRING_LIST` - 문자열 값 목록입니다.

쿼리 필터링에 사용되는 전체 메타데이터 속성 스키마는 API 참조의 [MetadataAttributeSchema](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_MetadataAttributeSchema.html)를 참조하세요.

## 관련 메타데이터 구성 옵션
<a name="kb-metadata-related"></a>

이 페이지에 설명된 CSV 기반 메타데이터 구성 외에도 Amazon S3 데이터 소스의 모든 문서 유형에 대해 사이드카 `.metadata.json` 파일을 사용하여 메타데이터를 구성할 수도 있습니다. 이 메서드는 전체 데이터 유형 세트와 `includeForEmbedding` 옵션을 지원합니다. 자세한 내용은 [문서 메타데이터 필드](s3-data-source-connector.md#ds-s3-metadata-fields) 단원을 참조하십시오.

메타데이터를 사용하여 쿼리 결과를 필터링하는 방법을 알아보려면의 **지식 기반 프롬프트 템플릿** 섹션을 참조하세요[쿼리와 응답 생성 구성 및 사용자 지정](kb-test-config.md).