Azure AI 검색에서 증분 보강을 위해 캐싱을 사용하도록 설정

아티클
03/05/2024

Important

이 기능은 추가 사용 약관에 따라 공개 미리 보기로 제공됩니다. 미리 보기 REST API는 이 기능을 지원합니다.

이 문서에서는 매번 전체를 다시 빌드하지 않고도 다운스트림 보강 단계를 수정할 수 있도록 보강 파이프라인에 캐싱을 추가하는 방법을 설명합니다. 기본적으로 기술 세트는 상태 비저장이며 해당 컴포지션의 어떤 부분이든 변경하려면 인덱서 전체를 다시 실행해야 합니다. 보강 캐시를 사용하면 인덱서가 기술 세트 또는 인덱서 정의에서 검색된 변경 내용을 기준으로 새로 고쳐야 하는 문서 트리 부분을 확인할 수 있습니다. 처리된 기존 출력은 유지되고 가능한 모든 곳에서 재사용됩니다.

캐시된 콘텐츠는 제공된 계정 정보를 사용하여 Azure Storage에 보관됩니다. 인덱서를 실행하면 ms-az-search-indexercache-<alpha-numerc-string>이라는 컨테이너가 생성됩니다. 이 컨테이너는 검색 서비스에서 관리하는 내부 구성 요소로 간주해야 하며 수정할 수 없습니다.

필수 조건

캐시된 보강을 저장하기 위한 Azure Storage 입니다. 스토리지 계정은 범용 v2여야 합니다.
Blob 인덱싱의 경우에만 데이터 원본에서 Blob을 삭제할 때 캐시와 인덱스 모두에서 동기화된 문서 제거가 필요한 경우 인덱서에서 삭제 정책을 사용하도록 설정합니다. 이 정책이 없으면 캐시에서 문서 삭제가 지원되지 않습니다.

인덱서 설정에 대해 잘 알고 있어야 합니다. 인덱서 개요로 시작한 다음, 기술 세트를 계속 진행하여 보강 파이프라인에 대해 알아봅니다. 주요 개념에 대한 자세한 배경 정보는 증분 보강을 참조하세요.

주의

SharePoint Online 인덱서(미리 보기)를 사용하는 경우 증분 보강을 피해야 합니다. 특정 상황에서 캐시를 다시 로드하도록 선택하면 캐시가 유효하지 않으므로 인덱서가 다시 설정되고 실행해야 합니다.

새 인덱서에서 사용

인덱서에서 보강 캐시를 사용하도록 설정하려면 Azure Portal, 미리 보기 API 또는 베타 Azure SDK를 사용할 수 있습니다.

Azure Portal
REST

왼쪽에서 인덱서를 선택한 다음 인덱서 추가를 선택합니다.
인덱서 이름 및 기존 인덱스, 데이터 원본 및 기술 세트를 제공합니다.
증분 캐싱을 사용하도록 설정하고 Azure Storage 계정을 설정합니다.

새 인덱서에서 인덱서 만들기 또는 업데이트(2021-04-30-Preview)를 호출할 때 인덱서 정의 페이로드에 "캐시" 속성을 추가합니다. 이전 미리 보기 API 버전인 2020-06-30-Preview를 사용할 수도 있습니다.

POST https://[service name].search.windows.net/indexers?api-version=2021-04-30-Preview
    {
        "name": "<YOUR-INDEXER-NAME>",
        "targetIndexName": "<YOUR-INDEX-NAME>",
        "dataSourceName": "<YOUR-DATASOURCE-NAME>",
        "skillsetName": "<YOUR-SKILLSET-NAME>",
        "cache" : {
            "storageConnectionString" : "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        },
    "fieldMappings" : [],
    "outputFieldMappings": [],
    "parameters": []
    }

기존 인덱서에서 사용

기술 세트가 이미 있는 기존 인덱서의 경우 다음 단계에서 캐싱을 추가합니다. 일회용 작업으로 전체 인덱서를 초기화하고 다시 실행하여 캐시를 로드합니다.

1단계: 인덱서 정의 가져오기

데이터 원본, 기술 세트, 인덱스와 같은 구성 요소가 있는 유효한 작업 인덱서로 시작합니다. API 클라이언트를 사용하여 GET Indexer 요청을 보내서 인덱서를 검색합니다. 미리 보기 API 버전을 사용하여 인덱서를 GET하면 null로 설정된 "캐시" 속성 집합이 정의에 자동으로 추가됩니다.

GET https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2021-04-30-Preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

2단계: 캐시 속성 설정

인덱스 정의에서 다음 필수 및 선택적 속성을 포함하도록 "cache"를 수정합니다.

(필수) storageConnectionString은 Azure Storage 연결 문자열로 설정되어야 합니다.
(선택 사항) enableReprocessing 부울 속성(기본적으로 true)은 증분 보강이 사용하도록 설정되었음을 나타냅니다. 새 문서 인덱싱과 같은 다른 리소스 집약적 작업이 진행되는 동안 증분 처리를 일시 중지하고 나중에 true로 다시 전환하려는 경우 false로 설정합니다.

POST https://[service name].search.windows.net/indexers?api-version=2021-04-30-Preview
    {
        "name": "<YOUR-INDEXER-NAME>",
        "targetIndexName": "<YOUR-INDEX-NAME>",
        "dataSourceName": "<YOUR-DATASOURCE-NAME>",
        "skillsetName": "<YOUR-SKILLSET-NAME>",
        "cache" : {
            "storageConnectionString" : "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        },
        "fieldMappings" : [],
        "outputFieldMappings": [],
        "parameters": []
    }

3단계: 인덱서 다시 설정

모든 문서를 일관된 상태로 유지하려면 기존 인덱서에 대해 증분 보강을 설정할 때 인덱서를 다시 설정해야 합니다. 이 작업에 포털 또는 API 클라이언트를 사용할 수 있습니다.

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/reset?api-version=2021-04-30-Preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]

4단계: 인덱서 저장

요청 본문에 "캐시"가 포함된 PUT 요청으로 인덱서(2021-04-30-Preview)를 업데이트합니다.

PUT https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2021-04-30-Preview
    Content-Type: application/json
    api-key: [YOUR-ADMIN-KEY]
    {
        "name" : "<YOUR-INDEXER-NAME>",
        ...
        "cache": {
            "storageConnectionString": "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
            "enableReprocessing": true
        }
    }

이제 인덱서에서 다른 GET 요청을 실행하면 서비스의 응답에 캐시 개체의 속성이 포함됩니다 ID . 캐시된 모든 결과와 이 인덱서에서 처리된 각 문서의 중간 상태를 포함하는 컨테이너의 이름 뒤에 영숫자 문자열이 추가됩니다. ID는 Blob Storage의 캐시 이름을 고유하게 지정하는 데 사용됩니다.

    "cache": {
        "ID": "<ALPHA-NUMERIC STRING>",
        "enableReprocessing": true,
        "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-STORAGE-ACCOUNT>;AccountKey=<YOUR-STORAGE-KEY>;EndpointSuffix=core.windows.net"
    }

5단계: 인덱서 실행

인덱서를 실행하려면 포털 또는 API를 사용할 수 있습니다. 포털의 인덱서 목록에서 인덱서를 선택하고 실행을 선택합니다. 포털을 사용하는 경우의 장점 중 하나는 인덱서 상태, 작업 기간, 처리된 문서 수를 모니터링할 수 있다는 것입니다. 포털 페이지는 몇 분마다 새로 고쳐집니다.

또는 REST를 사용하여 인덱서를 실행할 수 있습니다.

POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/run?api-version=2020-06-30-Preview
Content-Type: application/json
api-key: [YOUR-ADMIN-KEY]

참고 항목

인덱서를 다시 설정한 후 다시 실행하면 콘텐츠를 캐시할 수 있도록 인덱서 전체가 다시 빌드됩니다. 모든 문서에서 모든 인식 보강이 다시 실행됩니다. 캐시에서 보강된 콘텐츠 재사용은 캐시가 로드된 후 시작됩니다.

캐시된 출력 확인

Blob 컨테이너 아래의 Azure Storage에서 캐시를 찾습니다. 컨테이너 이름은 ms-az-search-indexercache-<some-alphanumeric-string>입니다.

캐시는 인덱서에서 만들어지고 사용됩니다. 그 콘텐츠는 사람이 읽을 수 없습니다.

캐시가 작동하는지 확인하려면 기술 세트를 수정하고 인덱서를 실행한 다음 실행 시간 및 문서 수에 대한 전후 메트릭을 비교합니다.

검사한 문서의 이미지 분석 및 OCR(광학 인식)을 포함하는 기술 세트는 좋은 테스트 사례가 됩니다. 다운스트림 텍스트 기술 또는 이미지와 관련이 없는 기술을 수정하는 경우 인덱서는 이전에 처리한 모든 이미지 및 OCR 콘텐츠를 캐시에서 검색하여 편집으로 표시된 텍스트 관련 변경 내용만 업데이트하고 처리할 수 있습니다. 인덱서 실행 문서 수의 감소, 실행 시간 단축, 청구서 요금 감소를 기대할 수 있습니다.

cog-search-demo 자습서에 사용된 파일 집합는 JPG, PNG, HTML, DOCX, PPTX 및 기타 형식의 다양한 형식의 14개 파일을 포함하므로 유용한 테스트 사례입니다. 증분 보강의 개념 증명 테스트를 위해 텍스트 번역 기술에서 en을 es 또는 다른 언어로 변경합니다.

일반 오류

요청 시 미리 보기 API 버전을 지정하지 않은 경우 다음 오류가 발생합니다.

"The request is invalid. Details: indexer : A resource without a type name was found, but no expected type was specified. To allow entries without type information, the expected type must also be specified when the model is specified."

인덱서 요구 사항이 누락된 경우에도 400 잘못된 요청 오류가 발생합니다. 오류 메시지는 누락된 종속성을 지정합니다.

다음 단계

증분 보강은 기술 세트가 포함된 인덱서에 적용할 수 있으며 인덱스와 지식 저장소 모두에 대해 재사용 가능한 콘텐츠를 제공합니다. 다음 링크는 캐싱 및 기술 세트에 대한 자세한 정보를 제공합니다.