인덱서, 기술 또는 문서 실행 또는 초기화

  • 아티클

Azure AI Search에는 인덱서를 실행하는 여러 가지 방법이 있습니다.

이 문서에서는 초기화를 사용하거나 사용하지 않고 요청 시 인덱서를 실행하는 방법을 설명합니다. 또한 인덱서 실행, 기간 및 동시성에 대해서도 설명합니다.

인덱서가 Azure 리소스에 연결되는 방법

인덱서는 다른 Azure 리소스에 대해 아웃바운드 호출을 수행하는 몇 안 되는 하위 시스템 중 하나입니다. Azure 역할의 관점에서 인덱서에는 별도의 ID가 없습니다. 검색 엔진에서 다른 Azure 리소스로의 연결은 검색 서비스의 시스템 또는 사용자 할당 관리 ID를 사용하여 이루어집니다. 인덱서가 가상 네트워크의 Azure 리소스에 연결되는 경우 해당 연결에 대한 공유 프라이빗 링크를 만들어야 합니다. 안전한 연결에 대한 자세한 내용은 Azure AI 검색의 보안을 참조하세요.

인덱서 실행

검색 서비스는 검색 단위당 하나의 인덱서 작업을 실행합니다. 모든 검색 서비스는 하나의 검색 단위로 시작하지만 새 파티션 또는 복제본마다 서비스의 검색 단위가 증가합니다. 포털의 개요 페이지에 있는 Essential 섹션에서 검색 단위 수를 확인할 수 있습니다. 동시 처리가 필요한 경우 충분한 복제본이 있는지 확인합니다. 인덱서는 백그라운드에서 실행되지 않으므로 서비스가 압력을 받고 있는 경우 평소보다 더 많은 쿼리 제한을 감지할 수 있습니다.

다음 스크린샷은 한 번에 실행할 수 있는 인덱서 수를 결정하는 검색 단위 수를 보여 줍니다.

검색 단위를 보여 주는 개요 페이지의 Essentials 섹션에 대한 스크린샷.

인덱서 실행이 시작되면 일시 중지하거나 중지할 수 없습니다. 로드하거나 새로 고칠 문서가 더 이상 없거나 최대 실행 시간 제한에 도달하면 인덱서 실행이 중지됩니다.

용량이 충분하다고 가정할 때 한 번에 여러 인덱서를 실행할 수 있지만 각 인덱서 자체는 단일 인스턴스입니다. 인덱서가 이미 실행 중인 동안 새 인스턴스를 시작하면 다음 오류가 발생합니다. "Failed to run indexer "<indexer name>" error: "Another indexer invocation is currently in progress; concurrent invocations are not allowed."

인덱서 작업은 관리되는 실행 환경에서 실행됩니다. 현재 두 가지 환경이 있습니다. 사용되는 환경을 제어하거나 구성할 수 없습니다. Azure AI Search는 작업 구성 및 인덱서 작업을 콘텐츠 프로세서로 이동하는 서비스 기능을 기반으로 환경을 결정합니다(일부 보안 기능은 다중 테넌트 환경을 차단함).

인덱서 실행 환경에는 다음이 포함됩니다.

  • 검색 서비스와 관련된 콘텐츠 프로세서에서 실행되는 프라이빗 실행 환경입니다.

  • 추가 비용 없이 Microsoft에서 관리하고 보호하는 콘텐츠 프로세서가 있는 다중 테넌트 환경입니다. 이 환경은 계산 집약적 처리를 없애는 데 사용되며 서비스별 리소스는 일상적인 작업에 사용할 수 있게 남아 있습니다. 가능하면 대부분의 인덱서 작업은 다중 테넌트 환경에서 실행됩니다.

인덱서 제한은 환경마다 다릅니다.

작업 부하 최대 기간 최대 작업 실행 환경
프라이빗 실행 24시간 검색 단위당 하나의 인덱서 작업 1. 인덱싱은 백그라운드에서 실행되지 않습니다. 대신 검색 서비스는 진행 중인 쿼리 및 개체 관리 작업(예: 인덱스 만들기 또는 업데이트)에 대해 모든 인덱싱 작업의 균형을 맞춥니다. 인덱서를 실행할 때 인덱싱 볼륨이 크면 일부 쿼리 대기 시간이 발생할 것으로 예상해야 합니다.
다중 테넌트 2시간 2 확정되지 않은 3 콘텐츠 처리 클러스터는 다중 테넌트이므로 수요를 충족하기 위해 콘텐츠 프로세서가 추가됩니다. 주문형 또는 예약된 실행이 지연되는 경우 시스템에서 프로세서를 추가하거나 프로세서를 사용할 수 있길 기다리고 있기 때문일 수 있습니다.

1 검색 단위는 파티션과 복제본의 유연한 조합일 수 있지만 인덱서 작업은 둘 중 하나에 연결되어 있지 않습니다. 즉, 12개의 장치가 있는 경우 검색 장치가 배포되는 방식에 관계없이 프라이빗 실행에서 동시에 실행되는 12개의 인덱서 작업을 가질 수 있습니다.

2 모든 데이터를 처리하는 데 2시간 이상이 필요한 경우 변경 검색을 사용하도록 설정하고 2시간 간격으로 실행되도록 인덱서를 예약합니다. 자세한 전략은 큰 데이터 세트 인덱싱을 참조하세요.

3 '미확정'은 한도가 작업 수로 정량화되지 않음을 의미합니다. 기술 세트 처리와 같은 일부 워크로드는 병렬로 실행될 수 있으므로 하나의 인덱서만 관련된 경우에도 많은 작업이 발생할 수 있습니다. 환경에 제약 조건이 없지만 검색 서비스에 대한 인덱서 제한이 계속 적용됩니다.

초기화 없이 실행

인덱서 실행 작업은 검색 인덱스를 기본 데이터 원본의 변경 내용과 동기화하는 데 필요한 항목만 검색하고 처리합니다. 증분 인덱싱은 마지막으로 업데이트된 검색 문서를 찾기 위해 내부 상위 워터 마크 표시를 찾는 것으로 시작합니다. 이 검색 문서는 데이터 원본의 새 문서 및 업데이트된 문서에 대한 인덱서 실행의 시작점이 됩니다.

변경 검색은 데이터 원본에서 새롭거나 업데이트된 항목을 결정하는 데 필수적입니다. 인덱서는 기본 데이터 원본의 변경 검색 기능을 사용하여 데이터 원본에서 새 항목 또는 업데이트된 항목을 확인합니다.

  • Azure Storage에는 LastModified 속성을 통한 변경 검색 기능이 기본 제공되어 있습니다.

  • Azure SQL 또는 Azure Cosmos DB와 같은 다른 데이터 원본은 인덱서가 새 행과 업데이트된 행을 읽을 수 있기 전에 변경 검색을 위해 구성되어야 합니다.

기본 콘텐츠가 변경되지 않으면 실행 작업이 적용되지 않습니다. 이 경우 인덱서 실행 기록은 처리된 0\0 문서를 나타냅니다.

전체를 다시 처리하려면 다음 섹션에 설명된 대로 인덱서를 초기화해야 합니다.

인덱서 초기화

초기 실행 후, 인덱서는 내부의 상위 워터 마크를 통해 어떤 검색 문서를 인덱스하였는지 추적합니다. 마커는 노출되지 않지만 내부적으로 인덱서는 마커가 마지막으로 중지된 위치를 알고 있습니다.

인덱스 전체 또는 일부를 다시 빌드해야 하는 경우 초기화를 통해 인덱서의 상위 워터 마크 표시를 지울 수 있습니다. 다시 설정 API는 다음의 개체 계층 구조에서 감소 수준으로 사용할 수 있습니다.

초기화 후 실행 명령을 따라 새 문서와 기존 문서를 다시 처리합니다. 데이터 원본에 대응 항목이 없는 분리된 검색 문서는 초기화/실행을 통해 제거할 수 없습니다. 문서를 삭제해야 하는 경우 대신 문서 - 인덱스를 참조하세요.

인덱서를 초기화하고 실행하는 방법

초기화는 상위 워터 마크 표시를 지웁니다. 검색 인덱스의 모든 문서는 인라인 업데이트나 기존 콘텐츠에 병합하지 않고 전체 덮어쓰기 플래그가 지정됩니다. 기술 집합 및 보강 캐싱이 있는 인덱서의 경우 인덱스를 초기화하면 기술 집합도 암시적으로 초기화됩니다.

실제 작업은 실행 명령으로 초기화를 따를 때 발생합니다.

  • 기본 원본에서 찾은 모든 새 문서가 검색 인덱스에 추가됩니다.
  • 데이터 원본과 검색 인덱스에 모두 존재하는 모든 문서는 검색 인덱스에서 덮어씁니다.
  • 기술 집합에서 만들어진 보강된 콘텐츠는 모두 재구성됩니다. 보강 캐시가 사용하도록 설정된 경우 새로 고쳐집니다.

앞에서 설명한 것처럼 초기화는 수동 작업입니다. 인덱스를 다시 빌드하려면 실행 요청을 따라야 합니다.

초기화/실행 작업은 검색 인덱스 또는 지식 저장소, 특정 문서 또는 프로젝션, 초기화에 명시적 또는 암시적으로 기술이 포함된 경우 캐시된 보강에 적용됩니다.

초기화는 만들기 및 업데이트 작업에도 적용됩니다. 검색 인덱스에서 고립된 문서의 삭제 또는 정리를 트리거하지 않습니다. 문서 삭제에 대한 자세한 내용은 문서 - 인덱스를 참조하세요.

인덱서를 초기화한 후에는 작업을 실행 취소할 수 없습니다.

  1. Azure Portal에 로그인하고 검색 서비스 페이지를 엽니다.

  2. 개요 페이지에서 인덱서 탭을 선택합니다.

  3. 인덱서를 선택합니다.

  4. 초기화 명령을 선택한 다음 예를 선택하여 작업을 확인합니다.

  5. 페이지를 새로 고쳐 상태를 표시합니다. 항목을 선택하여 세부 정보를 볼 수 있습니다.

  6. 실행을 선택하여 인덱서 처리를 시작하거나 예약된 다음 실행을 기다립니다.

    초기화 명령이 강조 표시된 인덱서 실행 포털 페이지의 스크린샷.

기술 초기화 방법(미리 보기)

기술 집합이 있는 인덱서의 경우 개별 기술을 초기화하여 해당 기술과 해당 출력에 의존하는 모든 다운스트림 기술만 강제로 처리할 수 있습니다. 사용하도록 설정한 경우 보강 캐시도 새로 고쳐집니다.

기술 초기화는 현재 REST 전용이며 2020-06-30-preview 이상을 통해 사용할 수 있습니다. 최신 미리 보기 API를 사용하는 것이 좋습니다.

POST /skillsets/[skillset name]/resetskills?api-version=2024-05-01-preview
{
    "skillNames" : [
        "#1",
        "#5",
        "#6"
    ]
}

위 예시에 나온 것처럼 개별 기술을 지정할 수 있지만, 해당 기술 가운데 하나라도 목록에 없는 기술(2~4)의 출력이 필요한 경우, 캐시가 필요한 정보를 제공할 수 있는 경우가 아니라면 목록에 없는 기술이 실행됩니다. 이러한 경우를 true로 설정하려면 기술 2~4에 대한 캐시 강화는 기술 1에 대한 종속성이 없어야 합니다(다시 설정을 위해 나열됨).

기술을 지정하지 않은 경우에는 전체 기술 세트가 실행되며 캐싱이 설정되었다면 해당 캐시도 새로 고쳐집니다.

인덱서 실행을 사용하여 실제 처리를 호출해야 합니다.

문서를 초기화하는 방법(미리 보기)

인덱서 - 문서 초기화는 특정 문서를 새로 고칠 수 있도록 문서 키 목록을 허용합니다. 지정된 경우, 다시 설정된 매개 변수는 기본 데이터의 기타 변경 사항과 상관없이 처리 대상의 유일한 결정자가 됩니다. 예를 들어, 마지막 인덱서 실행 이후 20개의 Blob이 추가되거나 업데이트되었지만 하나의 문서만 초기화한 경우 해당 문서만 처리됩니다.

문서별로 해당 검색 문서의 모든 필드가 데이터 원본 값으로 새로 고쳐집니다. 새로 고칠 필드를 골라 선택할 수 없습니다.

문서가 기술 세트를 통해 강화되었으며 캐시된 데이터가 있는 경우, 해당 기술 세트는 지정된 문서만을 위해 호출되고 캐시는 재처리한 문서를 위해 업데이트됩니다.

이 API를 처음으로 테스트하는 경우 다음 API를 사용하여 동작의 유효성을 검사하고 테스트할 수 있습니다. 미리 보기 API 버전 2020-06-30-preview 이상을 사용할 수 있습니다. 최신 미리 보기 API를 사용하는 것이 좋습니다.

  1. 초기화 상태와 실행 상태를 확인하려면 미리 보기 API 버전으로 인덱서 - 상태 가져오기를 호출합니다. 해당 상태 응답의 마지막에서 다시 설정 요청에 대한 정보를 찾을 수 있습니다.

  2. 처리할 문서를 지정하려면 미리 보기 API 버전으로 인덱서 - 문서 초기화를 호출합니다.

    POST https://[service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2024-05-01-preview
{
    "documentKeys" : [
        "1001",
        "4452"
    ]
}

    • 요청을 통해 제공된 문서 키는 검색 인덱스의 값으로, 데이터 원본에서 대응되는 필드와는 다를 수 있습니다. 키 값을 잘 모르는 경우 쿼리를 보내 값을 반환합니다. select을(를) 사용하여 문서 키 필드만 반환할 수 있습니다.

    • 여러 검색 문서로 구문 분석되는 Blob의 경우(parsingMode가 jsonLines 또는 jsonArrays 또는 delimitedText로 설정됨) 문서 키는 인덱서에서 생성되며 사용자에게 알려지지 않을 수 있습니다. 이 시나리오에서 문서 키에 대한 쿼리는 올바른 값을 반환합니다.

  3. 인덱서 실행(모든 API 버전)을 호출하여 지정한 문서를 처리합니다. 해당 특정 문서만 인덱싱됩니다.

  4. 인덱서 실행을 두 번째로 호출하여 마지막 상위 워터 마크 표시부터 처리합니다.

  5. 문서 검색을 호출하여 업데이트된 값을 확인하고 값이 확실하지 않은 경우 문서 키를 반환합니다. 응답으로 표시되는 필드를 제한하려는 경우에는 "select": "<field names>"를 사용합니다.

문서 키 목록 덮어쓰기

서로 다른 키를 사용하여 문서 초기화 API를 여러 번 호출하면 문서 키 초기화 목록에 새 키가 추가됩니다. overwrite 매개 변수를 true로 설정하여 API를 호출하면 현재 목록을 새 목록으로 덮어씁니다.

POST https://[service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2020-06-30-Preview
{
    "documentKeys" : [
        "200",
        "630"
    ],
    "overwrite": true
}

초기화 상태 "currentState" 확인

초기화 상태를 확인하고 처리를 위해 대기 중인 문서 키를 확인하려면 다음 단계를 따릅니다.

  1. 미리 보기 API를 사용하여 인덱서 상태 가져오기를 호출합니다.

    미리 보기 API는 응답 끝에 있는 currentState 섹션을 반환합니다.

    "currentState": {
    "mode": "indexingResetDocs",
    "allDocsInitialTrackingState": "{\"LastFullEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"LastAttemptedEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"NameHighWaterMark\":null}",
    "allDocsFinalTrackingState": "{\"LastFullEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"LastAttemptedEnumerationStartTime\":\"2021-02-06T19:02:07.0323764+00:00\",\"NameHighWaterMark\":null}",
    "resetDocsInitialTrackingState": null,
    "resetDocsFinalTrackingState": null,
    "resetDocumentKeys": [
        "200",
        "630"
    ]
}

  2. "모드"를 확인합니다.

    기술 초기화의 경우 "모드"를 indexingAllDocs로 설정해야 합니다(AI 보강을 통해 채워진 필드 측면에서 잠재적으로 모든 문서가 영향을 받기 때문).

    문서 초기화의 경우 "모드"를 indexingResetDocs로 설정해야 합니다. 인덱서는 문서 초기화 호출에서 제공된 모든 문서 키가 처리될 때까지 이 상태를 유지합니다. 이 시간 동안에는 작업이 진행되는 동안 다른 인덱서 작업이 실행되지 않습니다. 문서 키 목록의 모든 문서를 찾기 위해서는 각 문서의 위치를 찾고 키와 일치하도록 이를 해독할 필요가 있으며 데이터 세트의 규모가 큰 경우 시간이 오래 걸릴 수 있습니다. Blob 컨테이너에 수백 개의 Blob이 포함되어 있고 다시 설정하려는 문서가 마지막에 있는 경우, 인덱서는 다른 모든 항목을 먼저 확인할 때까지 일치하는 Blob을 찾지 못합니다.

  3. 문서가 다시 처리된 후 인덱서 상태 가져오기를 다시 실행합니다. 인덱서는 indexingAllDocs 모드로 돌아가고 다음에 실행할 때 새 문서나 업데이트된 문서를 처리합니다.

다음 단계

다시 설정 API는 다음 인덱서 실행의 범위를 알리는 데 사용됩니다. 실제 처리를 위해서는 주문형 인덱서 실행을 호출하거나 작업 완료를 위해 예약된 작업을 허용하도록 해야 합니다. 실행을 완료하면 인덱서는 예약을 통해 처리하든 주문형으로 처리하든 상관없이 정상 처리로 돌아갑니다.

인덱서 작업을 초기화하고 다시 실행한 후 검색 서비스에서 상태를 모니터링하거나 리소스 로깅을 통해 자세한 정보를 가져올 수 있습니다.