AWS Bedrock Knowledge Base에 CSV 메타데이터 쉽게 등록하기

AWS Bedrock Knowledge Base(KB)에 장비 목록이 등록된 대용량 CSV 파일을 연결하려는데, 모든 행(row)을 개별 파일로 쪼개지 않고 메타데이터를 등록할 수 있는 방법을 소개합니다.

AWS User Guide: "Include metadata in a data source to improve knowledge base query"

 

🎯 목표

수천 개의 행(row)을 갖고 있는 CSV 파일 1개를 업로드하고, '본문 검색(Semantic Search)'과 '메타데이터 필터링(Filtering)'을 모두 사용해 검색 결과의 정확도를 높이는 것이 목표입니다.

 

🚀 JSON 설정 파일 분석

CSV 파일 업로드 시 필요한 JSON 설정의 핵심은 documentStructureConfiguration 객체입니다.

{
  "documentStructureConfiguration": {
    "type": "RECORD_BASED_STRUCTURE_METADATA",
    "recordBasedStructureMetadata": {
      "contentFields": [ ... ],
      "metadataFieldsSpecification": { ... }
    }
  }
}

 

각 항목을 자세히 살펴보겠습니다.

1. RECORD_BASED_STRUCTURE_METADATA

이것은 Bedrock에게 "이 파일은 행(Record) 기반으로 구성되어 있고, 메타데이터 규칙은 JSON 구조(Structure)"라고 알려주는 선언입니다.

2. contentFields

• 역할: 사용자가 자연어(질문)로 검색할 때, Bedrock이 의미를 분석하고 검색할 대상이 됩니다.
• 처리: 이 열의 텍스트는 '벡터 임베딩'이라는 과정을 거쳐 검색 가능한 상태가 됩니다.
• 제약사항: Bedrock KB는 현재 contentFields로 단 하나의 열(column)만 지원합니다.
• 예시: 메모 필드와 같이 자연어가 포함된 열을 지정하는 것이 좋습니다.

      "contentFields": [
        {
          "fieldName": "Comments"
        }
      ],

3. metadataFieldsSpecification

• 역할: 검색 결과를 좁힐 때 사용할 '태그(Tag)' 역할을 합니다.
• 처리: 이 열의 값들은 필터 조건(예: Role = 'Wireless' 또는 Site = 'BRANCH')으로만 사용되며, '메모' 필드는 해당되지 않습니다.
• fieldsToInclude: 여기에 배열( [] ) 형식으로 필터로 사용하고 싶은 '모든 열 이름'을 나열하면 됩니다.

      "metadataFieldsSpecification": {
        "fieldsToInclude": [
          { "fieldName": "Name" },
          { "fieldName": "Status" },
          { "fieldName": "Site" },
          { "fieldName": "Role" },
          { "fieldName": "Manufacturer" }
          /* ...필터로 사용할 다른 모든 열... */
        ],
        "fieldsToExclude": []
      }

 

⚠️ metadataAttributes 는 언제 쓸까?

AWS 사용자 가이드(https://docs.aws.amazon.com/bedrock/latest/userguide/kb-metadata.html)의 JSON 예시를 보면 metadataAttributes: { "key": "value" } 같은 형식을 볼 수 있습니다. 이것은 단일 CSV 파일일에서 각 열의 필드를 설명할 때는 필요로 하지 않습니다. 

• fieldsToInclude 형식: CSV 파일 1개를 업로드할 때, 특정열(column)을 필터로 쓰라고 알려줄 때 사용하는 방법
• metadataAttributes 형식: CSV 내의 모든 행(row)을 개별 파일로 쪼개서 업로드할 때. 즉, 수백 또는 수천 개의 콘텐츠/메타데이터 파일 쌍을 보유할때 사용하는 방법

 

✅ 최종 예시

Comments 열을 '자연어' 검색을 할 수 있게 선언하고, 나머지 25개의 열을 '필터'로 사용하는 최종 JSON 설정 예시입니다.

{
  "documentStructureConfiguration": {
    "type": "RECORD_BASED_STRUCTURE_METADATA",
    "recordBasedStructureMetadata": {
      
      "contentFields": [
        {
          "fieldName": "Comments"
        }
      ],

      "metadataFieldsSpecification": {
        "fieldsToInclude": [
          { "fieldName": "Name" },
          { "fieldName": "Status" },
          { "fieldName": "Tenant" },
          { "fieldName": "Site" },
          { "fieldName": "Location" },
          { "fieldName": "Rack" },
          { "fieldName": "Role" },
          { "fieldName": "Manufacturer" }
        ],
        
        "fieldsToExclude": []
      }
    }
  }
}