Azure Blob Storage의 데이터 인덱싱

이 문서에서는 Azure Blob Storage에서 콘텐츠를 가져오고 Azure AI Search에서 검색할 수 있도록 만드는 인덱서를 구성하는 방법에 대해 알아봅니다. 인덱서에 대한 입력은 단일 컨테이너에 있는 Blob입니다. 출력은 개별 필드에 저장된 검색 가능한 콘텐츠 및 메타데이터가 포함된 검색 인덱스입니다.

인덱서 구성 및 실행하려면 다음을 사용할 수 있습니다.

• Search Service REST API, 모든 버전.
• Azure SDK 패키지, 모든 버전.
• Azure Portal에서 데이터 가져오기 마법사
• Azure Portal에서 데이터 가져오기 및 벡터화 마법사

이 문서에서는 REST API를 사용하여 각 단계를 설명합니다.

필수 조건

• Azure Blob Storage, 표준 성능(범용 v2)

• 액세스 계층은 핫, 쿨, 콜드, 보관을 포함합니다. 인덱서는 핫, 쿨, 콜드 액세스 계층에서 Blob를 검색할 수 있습니다.

• 텍스트 콘텐츠 및 메타데이터를 제공하는 Blob. Blob에 이진 콘텐츠 또는 구조화되지 않은 텍스트가 포함된 경우 이미지 및 자연어 처리를 위한 AI 보강을 추가하는 것이 좋습니다. Blob 콘텐츠는 검색 서비스 계층의 인덱스기 한도를 초과할 수 없습니다.

• 지원되는 네트워크 구성 및 데이터 액세스. 최소한 Azure Storage에 대한 읽기 권한이 필요합니다. 액세스 키가 포함된 스토리지 연결 문자열은 스토리지 콘텐츠에 대한 읽기 권한을 제공합니다. 대신 Microsoft Entra 로그인 및 역할을 사용하는 경우 검색 서비스의 관리 ID에 Storage Blob 데이터 읽기 권한자 권한이 있는지 확인합니다.

  기본적으로 검색 및 스토리지는 모두 공용 IP 주소의 요청을 수락합니다. 네트워크 보안이 즉각적인 문제가 아닌 경우 연결 문자열 및 읽기 권한만 사용하여 Blob 데이터를 인덱싱할 수 있습니다. 네트워크 보호를 추가할 준비가 되면 Azure 네트워크 보안 기능으로 보호되는 콘텐츠에 대한 인덱서 액세스에서 데이터 액세스에 대한 참고 자료를 참조하세요.

• 이 문서에 표시된 것과 유사한 REST 호출을 작성하려면 REST 클라이언트를 사용합니다.

지원되는 작업

이 인덱서는 다음 작업에 사용할 수 있습니다.

• 데이터 인덱싱 및 증분 인덱싱: 인덱서는 Blob 컨테이너 및 폴더에서 파일 및 관련 메타데이터를 인덱싱할 수 있습니다. 기본 제공 변경 검색을 통해 새 파일 및 업데이트된 파일 및 메타데이터를 검색합니다. 일정 또는 요청 시 데이터 새로 고침을 구성할 수 있습니다.
• 삭제 검색: 인덱서는 네이티브 일시 삭제 또는 사용자 지정 메타데이터를 통해 삭제를 검색할 수 있습니다.
• 기술 세트를 통한 적용된 AI: 기술 세트 는 인덱서에서 완전히 지원됩니다. 여기에는 데이터 청크 및 포함 단계를 추가하는 통합 벡터화와 같은 주요 기능이 포함됩니다.
• 구문 분석 모드: JSON 배열 또는 줄을 개별 검색 문서로 구문 분석하려는 경우 JSON 구문 분석 모드를 지원합니다. Markdown 구문 분석 모드도 지원합니다.
• 다른 기능과의 호환성: 인덱서는 디버그 세션, 증분 보강을 위한 인덱서 캐시 및 지식 저장소와 같은 다른 인덱서 기능과 원활하게 작동하도록 설계되었습니다.

지원되는 문서 형식

BLOB 인덱서는 다음과 같은 문서 형식에서 텍스트를 추출할 수 있습니다.

• CSV(CSV Blob 인덱싱 참조)
• EML
• EPUB
• GZ
• HTML
• JSON(JSON BLOB 인덱싱 참조)
• KML(지리적 표현을 위한 XML)
• Microsoft Office 형식: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG(Outlook 메일), XML(2003 및 2006 WORD XML 모두)
• 오픈 문서 형식: ODT, ODS, ODP
• PDF
• 일반 텍스트 파일(일반 텍스트 인덱싱도 참조)
• RTF
• XML
• ZIP

인덱싱할 Blob 결정

인덱싱을 설정하기 전에 원본 데이터를 검토하여 미리 변경해야 하는지 여부를 결정합니다. 인덱서는 한 번에 한 컨테이너의 콘텐츠를 인덱싱할 수 있습니다. 기본적으로 컨테이너의 모든 Blob이 처리됩니다. 보다 선택적 처리를 위한 몇 가지 옵션이 있습니다.

• Blob을 가상 폴더에 배치합니다. 인덱서 데이터 원본 정의에는 가상 폴더를 사용할 수 있는 "쿼리" 매개 변수가 포함되어 있습니다. 가상 폴더를 지정하면 폴더에 있는 Blob만 인덱싱됩니다.

• 파일 형식별로 Blob을 포함하거나 제외합니다. 지원되는 문서 형식 목록은 제외할 blob을 결정하는 데 도움이 될 수 있습니다. 예를 들어, 검색 가능한 텍스트를 제공하지 않는 이미지 또는 오디오 파일을 제외할 수 있습니다. 이 기능은 인덱서의 구성 설정을 통해 제어됩니다.

• 임의의 Blob을 포함하거나 제외합니다. 어떤 이유로든 특정 Blob을 건너뛰려는 경우 다음 메타데이터 속성 및 값을 Blob Storage의 Blob에 추가할 수 있습니다. 인덱서가 이 속성을 발견하면 인덱싱 실행에서 Blob 또는 해당 콘텐츠를 건너뜁니다.

  Property name	속성 값	설명
  "AzureSearch_Skip"	"true"	BLOB 인덱서가 BLOB을 완전히 건너뛰도록 지시합니다. 메타데이터와 콘텐츠 추출이 모두 시도되지 않습니다. 특정 BLOB이 반복적으로 실패하고 인덱싱 프로세스가 중단되는 경우에 유용합니다.
  "AzureSearch_SkipContent"	"true"	콘텐츠를 건너뛰고 메타데이터만 추출합니다. 이는 구성 설정에 설명된 "dataToExtract" : "allMetadata" 설정과 동일하며 특정 Blob으로 범위가 지정되었습니다.

포함 또는 제외 기준을 설정하지 않으면 인덱서는 부적합 Blob을 오류로 보고하고 계속 진행합니다. 충분한 오류가 발생하면 처리가 중지될 수 있습니다. 인덱서 구성 설정에서 오류 허용 범위를 지정할 수 있습니다.

인덱서는 일반적으로 Blob당 하나의 검색 문서를 만들며 여기서 텍스트 콘텐츠 및 메타데이터는 인덱스에서 검색 가능한 필드로 캡처됩니다. Blob이 전체 파일인 경우 잠재적으로 여러 검색 문서로 구문 분석할 수 있습니다. 예를 들어, CSV 파일의 행을 구문 분석하여 행당 하나의 검색 문서를 만들 수 있습니다.

복합 또는 포함된 문서(예: ZIP 보관 파일, 첨부 파일이 있는 Outlook 메일이 포함된 Word 문서 또는 첨부 파일이 포함된 .MSG 파일)도 단일 문서로 인덱싱됩니다. 예를 들어 .MSG 첨부 파일에서 추출한 모든 이미지는 normalized_images 필드에 반환됩니다. 이미지가 있는 경우 AI 보강을 추가하여 해당 콘텐츠에서 더 많은 검색 유틸리티를 가져올 수 있습니다.

문서의 텍스트 콘텐츠는 “content”라는 문자열 필드로 추출됩니다. 표준 및 사용자 정의 메타데이터를 추출할 수도 있습니다.

Blob 메타데이터 인덱싱

Blob 메타데이터도 인덱싱할 수 있으며, 이는 표준 또는 사용자 지정 메타데이터 속성이 필터 및 쿼리에 유용하다고 생각하는 경우에 유용합니다.

사용자 지정 메타데이터 속성은 그대로 추출됩니다. 값을 받으려면 Blob의 메타데이터 키와 이름이 같은 Edm.String 형식의 검색 인덱스에 필드를 정의해야 합니다. 예를 들어, Blob의 메타데이터 키 Sensitivity의 값이 High인 경우 검색 인덱스에 Sensitivity라는 필드를 정의하면 High 값으로 채워집니다.

표준 Blob 메타데이터 속성은 아래에 나열된 것과 같이 유사한 이름과 형식의 필드로 추출할 수 있습니다. Blob 인덱서는 이러한 Blob 메타데이터 속성에 대한 내부 필드 매핑을 자동으로 만들어 하이픈으로 연결된 원래 이름("metadata-storage-name")을 밑줄이 있는 해당 이름("metadata_storage_name")으로 변환합니다.

여전히 밑줄이 있는 필드를 인덱스 정의에 추가해야 하지만 인덱서가 자동으로 연결을 만들기 때문에 필드 매핑을 생략할 수 있습니다.

• metadata_storage_name(Edm.String) - Blob의 파일 이름입니다. 예를 들어 blob /my-container/my-folder/subfolder/resume.pdf를 포함하는 경우 이 필드의 값은 resume.pdf입니다.

• metadata_storage_path(Edm.String) - 스토리지 계정을 포함하는 Blob의 전체 URI입니다. 예를 들어 https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf

• metadata_storage_content_type(Edm.String) - Blob을 업로드하기 위해 사용한 코드에 지정된 콘텐츠 형식입니다. 예: application/octet-stream.

• metadata_storage_last_modified(Edm.DateTimeOffset) - Blob에 대해 마지막으로 수정된 타임스탬프입니다. Azure AI Search는 이 타임스탬프로 변경된 Blob을 식별하여 초기 인덱싱 후 모든 항목을 다시 인덱싱하는 것을 방지합니다.

• metadata_storage_size(Edm.Int64) - Blob 크기(바이트)입니다.

• metadata_storage_content_md5(Edm.String) - Blob 콘텐츠의 MD5 해시(사용 가능한 경우)입니다.

• metadata_storage_sas_token(Edm.String) - 사용자 지정 기술이 Blob에 액세스하는 데 사용할 수 있는 임시 SAS 토큰입니다. 이 토큰은 만료될 수 있으므로 나중에 사용하기 위해 저장하면 안 됩니다.

마지막으로 인덱싱 중인 Blob의 문서 형식과 관련된 모든 메타데이터 속성을 인덱스 스키마에 표시할 수도 있습니다. 콘텐츠 관련 메타데이터에 대한 자세한 내용은 콘텐츠 메타데이터 속성을 참조하세요.

검색 인덱스에서 위의 모든 속성에 대한 필드를 정의하지 않아도 되는 경우 애플리케이션에 필요한 속성만 캡처하는 것이 중요합니다.

현재 인덱싱 Blob 인덱스 태그는 이 인덱서에서 지원되지 않습니다.

데이터 원본 정의

데이터 원본 정의는 인덱싱할 데이터, 자격 증명 및 데이터 변경 내용을 식별하기 위한 정책을 지정합니다. 데이터 원본은 여러 인덱서에서 사용할 수 있도록 독립적인 리소스로 정의됩니다.

1. 데이터 원본을 만들거나 업데이트하여 정의를 설정합니다.

   {
       "name" : "my-blob-datasource",
       "type" : "azureblob",
       "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
       "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" }
   }
   

2. "type"을 "azureblob"(필수)으로 설정합니다.

3. “credentials”를 Azure Storage 연결 문자열로 설정합니다. 다음 섹션에서는 지원되는 형식에 대해 설명합니다.

4. "container"를 Blob 컨테이너로 설정하고 "query"를 사용하여 하위 폴더를 지정합니다.

원본 문서가 삭제 플래그가 지정되었을 때 인덱서가 검색 문서를 삭제하도록 하려면 데이터 원본 정의에 일시 삭제 정책도 포함될 수 있습니다.

지원되는 자격 증명 및 연결 문자열

인덱서는 다음 연결을 사용하여 Blob 컨테이너에 연결할 수 있습니다.

인덱스에 검색 필드 추가

검색 인덱스에서 Azure blob의 콘텐츠 및 메타데이터를 허용하는 필드를 추가합니다.

1. 인덱스를 만들거나 업데이트하여 Blob 콘텐츠와 메타데이터를 저장할 검색 필드를 정의합니다.

   POST https://[service name].search.windows.net/indexes?api-version=2024-07-01
   {
       "name" : "my-search-index",
       "fields": [
           { "name": "ID", "type": "Edm.String", "key": true, "searchable": false },
           { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false },
           { "name": "metadata_storage_name", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true  },
           { "name": "metadata_storage_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
           { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true },        
       ]
   }
   

2. 문서 키 필드("key": true)를 만듭니다. Blob 콘텐츠의 경우 가장 적합한 후보는 메타데이터 속성입니다.

   • metadata_storage_path(기본값) 개체 또는 파일의 전체 경로입니다. 키 필드(이 예에서는 "ID")는 기본값이기 때문에 metadata_storage_path의 값으로 채워집니다.

   • metadata_storage_name, 이름이 고유한 경우에만 사용할 수 있습니다. 이 필드를 키로 사용하려면 "key": true를 이 필드 정의로 이동합니다.

   • Blob에 추가하는 사용자 지정 메타데이터 속성입니다. 이 옵션에는 해당 메타데이터 속성을 모든 BLOB에 추가하는 BLOB 업로드 프로세스가 필요합니다. 키는 필수 속성이므로 값이 누락된 Blob은 인덱싱되지 않습니다. 사용자 지정 메타데이터 속성을 키로 사용하는 경우 해당 속성을 변경하지 마세요. 키 속성이 변경되면 인덱서는 동일한 Blob에 대해 중복 문서를 추가합니다.

   메타데이터 속성에는 문서 키에 유효하지 않은 / 및 -와 같은 문자가 포함되는 경우가 많습니다. 그러나 인덱서는 구성이나 필드 매핑이 필요하지 않고 키 메타데이터 속성을 자동으로 인코딩합니다.

3. Blob 의 “content” 속성을 통해 각 파일에서 추출된 텍스트를 저장하는 “content” 필드를 추가합니다. 이 이름을 반드시 사용해야 하는 것은 아니지만 이렇게 하면 암시적 필드 매핑을 활용할 수 있습니다.

4. 표준 메타데이터 속성에 대한 필드를 추가합니다. 인덱서는 사용자 지정 메타데이터 속성, 표준 메타데이터 속성 및 콘텐츠 관련 메타데이터 속성을 읽을 수 있습니다.

Blob 인덱서 구성 및 실행

인덱스와 데이터 원본이 만들어지면 인덱서를 만들 준비가 된 것입니다. 인덱서 구성은 런타임 동작을 제어하는 입력, 매개 변수 및 속성을 지정합니다. 인덱싱할 Blob 부분을 지정할 수도 있습니다.

1. 이름을 지정하고 데이터 원본 및 대상 인덱스를 참조하여 인덱서를 만들거나 업데이트합니다.

   POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
   {
     "name" : "my-blob-indexer",
     "dataSourceName" : "my-blob-datasource",
     "targetIndexName" : "my-search-index",
     "parameters": {
         "batchSize": null,
         "maxFailedItems": null,
         "maxFailedItemsPerBatch": null,
         "configuration": {
             "indexedFileNameExtensions" : ".pdf,.docx",
             "excludedFileNameExtensions" : ".png,.jpeg",
             "dataToExtract": "contentAndMetadata",
             "parsingMode": "default"
         }
     },
     "schedule" : { },
     "fieldMappings" : [ ]
   }
   

2. 기본값(문서 10개)이 사용 가능한 리소스를 충분히 활용하지 못하거나 초과하는 경우 batchSize를 설정합니다. 기본 일괄 처리 크기는 데이터 원본에 따라 다릅니다. Blob 인덱싱은 더 큰 평균 문서 크기를 인식하여 일괄 처리 크기를 10개 문서로 설정합니다.

3. "구성"에서 파일 형식에 따라 인덱싱되는 Blob을 제어하거나 모든 Blob을 검색하려면 지정하지 않은 상태로 둡니다.

   "indexedFileNameExtensions"의 경우 쉼표로 구분된 파일 확장명 목록(선행 점이 있음)을 제공합니다. "excludedFileNameExtensions"에 대해 동일한 작업을 수행하여 건너뛰어야 하는 확장을 나타냅니다. 동일한 확장자가 두 목록에 있으면 인덱싱에서 제외됩니다.

4. "configuration"에서 "dataToExtract"를 설정하여 인덱싱되는 Blob 부분을 제어합니다.

   • "contentAndMetadata"는 Blob에서 추출된 모든 메타데이터 및 텍스트 콘텐츠가 인덱싱되도록 지정합니다. 기본값입니다.

   • "storageMetadata"는 표준 blob 속성 및 사용자 지정 메타데이터만 인덱싱되도록 지정합니다.

   • "allMetadata"는 표준 Blob 속성 및 찾은 콘텐츠 형식에 대한 메타데이터를 Blob 콘텐츠에서 추출하고 인덱싱하도록 지정합니다.

5. "구성"에서 "parsingMode"를 설정합니다. 기본 구문 분석 모드는 Blob당 하나의 검색 문서입니다. Blob이 일반 텍스트인 경우 일반 텍스트 구문 분석으로 전환하여 성능을 높일 수 있습니다. Blob을 여러 검색 문서에 매핑하는 보다 세분화된 구문 분석이 필요한 경우 다른 모드를 지정합니다. 다음으로 구성된 Blob에 대해 일대다 구문 분석이 지원됩니다.

   • JSON 문서
   • CSV 파일

6. 필드 이름 또는 형식이 다르거나 검색 인덱스에서 여러 버전의 원본 필드가 필요한 경우 필드 매핑을 지정합니다.

   Blob 인덱싱에서는 인덱서가 "content" 및 메타데이터 속성을 인덱스의 유사한 이름 및 형식 필드에 매핑하는 기능을 기본 제공하므로 필드 매핑을 종종 생략할 수 있습니다. 메타데이터 속성의 경우 인덱서는 검색 인덱스에서 하이픈 -을 밑줄로 자동으로 바꿉니다.

7. 다른 속성에 대한 자세한 내용은 인덱서 만들기를 참조하세요. 매개 변수 설명의 전체 목록은 REST API를 참조하세요.

인덱서가 만들어지면 자동으로 실행됩니다. 이는 "disabled"를 true로 설정하여 방지할 수 있습니다. 인덱서 실행을 제어하려면 요청 시 인덱서를 실행하거나 일정에 배치합니다.

여러 Azure Blob 컨테이너의 데이터를 단일 인덱스로 인덱싱

인덱서는 단일 컨테이너의 데이터만 인덱싱할 수 있다는 점에 유의해야 합니다. 여러 컨테이너의 데이터를 인덱싱하고 이를 단일 AI 검색 인덱스로 통합해야 하는 경우 모두 동일한 인덱스로 연결되는 여러 인덱서를 구성하여 이를 달성할 수 있습니다. SKU당 사용할 수 있는 최대 인덱서 수에 유의하세요.

설명을 위해 my-blob-datasource1 및 my-blob-datasource2라는 두 개의 서로 다른 데이터 원본에서 데이터를 끌어오는 두 개의 인덱서의 예를 살펴보겠습니다. 각 데이터 원본은 별도의 Azure Blob 컨테이너를 가리키지만 둘 다 my-search-index라는 동일한 인덱스를 가리킵니다.

첫 번째 인덱서 정의 예:

POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
{
  "name" : "my-blob-indexer1",
  "dataSourceName" : "my-blob-datasource1",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

병렬로 실행되는 두 번째 인덱서 정의 예:

POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
{
  "name" : "my-blob-indexer2",
  "dataSourceName" : "my-blob-datasource2",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

인덱서 상태 확인

인덱서 상태 및 실행 기록을 모니터링하려면 인덱서 상태 가져오기 요청을 보냅니다.

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-07-01
  Content-Type: application/json  
  api-key: [admin key]

응답에는 상태 및 처리된 항목 수가 포함됩니다. 다음 예와 유사해야 합니다.

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

실행 기록에는 최대 50개의 가장 최근에 완료된 실행이 포함되며, 가장 최근의 실행이 먼저 나오도록 시간 역순으로 정렬됩니다.

오류 처리

인덱싱 중에 일반적으로 발생하는 오류에는 지원되지 않는 콘텐츠 형식, 누락된 콘텐츠 또는 크기가 너무 큰 Blob이 포함됩니다.

기본적으로 Blob 인덱서는 지원되지 않는 콘텐츠 형식(예: 오디오 파일)을 포함하는 Blob을 발견하는 즉시 중지됩니다. "excludedFileNameExtensions" 매개 변수를 사용하여 특정 콘텐츠 형식을 건너뛸 수 있습니다. 그러나 오류가 발생한 경우에도 인덱싱을 진행하고, 나중에 개별 문서를 디버그하려고 할 수 있습니다. 인덱서 오류에 관한 자세한 내용은 인덱서 문제 해결 지침과 인덱서 오류 및 경고를 참조하세요.

오류가 발생할 때 인덱서의 응답을 제어하는 다섯 가지 인덱서 속성이 있습니다.

PUT /indexers/[indexer name]?api-version=2024-07-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
      }
    }
}

참고 항목

• 변경 감지 및 삭제 감지
• 큰 데이터 세트 인덱싱
• Azure 네트워크 보안 기능으로 보호되는 콘텐츠에 대한 인덱서 액세스