Azure AI 검색에서 인덱스 업데이트 또는 다시 빌드

이 문서에서는 증분 인덱싱을 통해 스키마 변경 또는 콘텐츠 변경으로 Azure AI Search의 기존 인덱스를 업데이트하는 방법을 설명합니다. 다시 빌드가 필요한 상황을 설명하고 진행 중인 쿼리 요청에 대한 다시 빌드의 영향을 완화하기 위한 권장 사항을 제공합니다.

인덱스 디자인을 반복할 때 개발 중에 인덱스를 삭제한 후 다시 빌드하는 것이 일반적입니다. 대부분의 개발자는 다시 인덱싱 속도를 높이기 위해 데이터의 작은 대표 샘플을 사용하여 작업합니다.

이미 프로덕션에 있는 애플리케이션에 대한 스키마 변경의 경우 기존 인덱스와 나란히 실행되는 새 인덱스를 만들고 테스트하는 것이 좋습니다. 인덱스 별칭을 사용하여 애플리케이션 코드를 변경하지 않고 새 인덱스를 교환합니다.

콘텐츠 업데이트

원본 데이터의 변경 내용에 대해 인덱스를 증분 인덱싱 및 동기화하는 것은 대부분의 검색 애플리케이션에서 기본 사항입니다. 이 섹션에서는 검색 인덱스의 필드 콘텐츠를 업데이트하는 워크플로에 대해 설명합니다.

1. 문서를 로드하는 데 동일한 기술인 문서 - 인덱스(REST) 또는 Azure SDK에 해당하는 API를 사용합니다. 인덱싱 기술에 대한 자세한 내용은 문서 로드를 참조하세요.

2. @search.action 매개 변수를 설정하여 기존 문서에 미치는 영향을 확인합니다.

   작업	효과
   delete	인덱스에서 전체 문서를 제거합니다. 개별 필드를 제거하려는 경우에는 대신 merge를 사용하여 해당 필드를 null로 설정합니다. 삭제된 문서 및 필드는 인덱스의 공간을 즉시 확보하지 않습니다. 몇 분마다 백그라운드 프로세스는 물리적 삭제를 수행합니다. 포털 또는 API를 사용하여 인덱스 통계를 반환하든 삭제가 포털 및 API를 통해 반영되기 전에 약간의 지연이 예상될 수 있습니다.
   merge	이미 존재하는 문서를 업데이트하고 찾을 수 없는 문서는 실패합니다. 병합은 기존 값을 대체합니다. 이러한 이유로 형식 Collection(Edm.String)의 필드와 같이 여러 값이 포함된 컬렉션 필드를 확인해야 합니다. 예를 들어 값이 tags 필드가 ["budget"] 값으로 시작하고 ["economy", "pool"]과 병합을 실행하면 tags 필드의 최종 값은 ["economy", "pool"]입니다. ["budget", "economy", "pool"]이 아닙니다.
   mergeOrUpload	문서가 존재하는 경우 병합처럼 작동하고 문서가 새 문서인 경우 업로드합니다. 이는 증분 업데이트에 대한 가장 일반적인 작업입니다.
   upload	문서가 새 문서인 경우 삽입되고, 존재하는 경우 업데이트되거나 바뀌는 "upsert"와 유사합니다. 인덱스에 필요한 값이 문서에 없으면 문서 필드의 값이 null로 설정됩니다.

3. 업데이트를 게시합니다.

쿼리는 계속 실행되지만 기존 필드를 업데이트하거나 제거하는 경우 혼합된 결과와 더 높은 제한 발생률을 기대할 수 있습니다.

증분 인덱싱 팁

• 인덱서는 증분 인덱싱을 자동화합니다. 인덱서가 사용 가능하고 데이터 원본이 변경 내용 추적을 지원하는 경우 반복 일정에 따라 인덱서를 실행하여 외부 데이터와 동기화되도록 검색 가능한 콘텐츠를 추가, 업데이트 또는 덮어쓸 수 있습니다.

• 푸시 API를 통해 직접 인덱스 호출을 만드는 경우 검색 작업으로 mergeOrUpload을(를) 사용합니다.

• 페이로드에는 추가, 업데이트 또는 삭제하려는 모든 문서의 키 또는 식별자가 포함되어야 합니다.

• 인덱스가 벡터 필드를 포함하고 stored 속성을 false로 설정하는 경우 값이 변경되지 않더라도 부분 문서 업데이트에 벡터를 제공해야 합니다. stored을(를) false로 설정하는 부작용은 다시 인덱싱 작업에서 벡터가 삭제된다는 것입니다. 문서 페이로드에 벡터를 제공하면 이러한 일이 발생하지 않습니다.

• 단순 필드 및 하위 필드의 내용을 복합 형식으로 업데이트하려면 변경하려는 필드만 나열합니다. 예를 들어 설명 필드만 업데이트해야 하는 경우 페이로드는 문서 키와 수정된 설명으로 구성되어야 합니다. 다른 필드를 생략하면 기존 값이 유지됩니다.

• 인라인 변경 내용을 문자열 컬렉션에 병합하려면 전체 값을 제공합니다. 이전 섹션의 tags 필드 예제를 기억하세요. 새 값은 전체 필드의 이전 값을 덮어쓰며 필드 콘텐츠 내에서는 병합되지 않습니다.

다음은 이러한 팁을 보여주는 REST API 예제 입니다.

### Get Stay-Kay City Hotel by ID
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

### Change the description, city, and tags for Stay-Kay City Hotel
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search.index?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "value": [
            {
            "@search.action": "mergeOrUpload",
            "HotelId": "1",
            "Description": "I'm overwriting the description for Stay-Kay City Hotel.",
            "Tags": ["my old item", "my new item"],
            "Address": {
                "City": "Gotham City"
                }
            }
        ]
    }
       
### Retrieve the same document, confirm the overwrites and retention of all other values
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

인덱스 스키마 변경

인덱스 스키마는 검색 서비스에서 만든 물리적 데이터 구조를 정의하므로 전체 다시 빌드를 수행하지 않고 수행할 수 있는 스키마 변경은 많지 않습니다. 다음 목록에서는 기존 인덱스에 원활하게 도입할 수 있는 스키마 변경 내용을 열거합니다. 일반적으로 목록에는 쿼리 실행 중에 사용되는 새 필드와 기능이 포함됩니다.

• 새 필드 추가
• 기존 필드에 retrievable 특성 설정
• 기존 indexAnalyzer이(가) 있는 필드에 대한 searchAnalyzer 업데이트
• 인덱스에 새 분석기 정의 추가(새 필드에 적용할 수 있음)
• 점수 매기기 프로필 추가, 업데이트 또는 삭제
• CORS 설정 추가, 업데이트 또는 삭제
• synonymMaps 추가, 업데이트 또는 삭제
• 의미 체계 구성 추가, 업데이트 또는 삭제

작업 순서:

1. 인덱스 정의 정보를 가져옵니다.

2. 이전 목록의 업데이트로 스키마를 수정합니다.

3. 검색 서비스에서 인덱스 스키마를 업데이트합니다.

4. 새 필드를 추가한 경우 수정된 스키마와 일치하도록 인덱스 콘텐츠를 업데이트합니다. 다른 모든 변경 내용의 경우 기존에 인덱싱된 콘텐츠가 그대로 사용됩니다.

새 필드를 포함하도록 인덱스 스키마를 업데이트하면 인덱스의 기존 문서에 해당 필드에 대한 null 값이 제공됩니다. 다음 인덱싱 작업에서는 외부 원본 데이터의 값이 Azure AI 검색에서 추가한 null을 바꿉니다.

업데이트 중에는 쿼리 중단이 없어야 하지만 업데이트가 적용되면 쿼리 결과가 달라집니다.

인덱스 삭제 및 다시 빌드

일부 수정에는 인덱스 삭제 및 다시 빌드가 필요하며 현재 인덱스를 새 인덱스로 바꿉니다.

작업	설명
필드 삭제	필드의 모든 추적을 실제로 제거하려면 인덱스를 다시 작성해야 합니다. 즉시 다시 빌드하는 것이 실용적이지 않은 경우 애플리케이션 코드를 수정하여 더 이상 사용되지 않는 필드에서 액세스를 리디렉션하거나 searchFields를 사용하고 쿼리 매개 변수를 선택하여 검색하고 반환할 필드를 선택할 수 있습니다. 실제로 필드 정의와 콘텐츠는 다음 번에 의심스러운 필드를 생략하는 스키마를 적용할 때 다시 작성이 수행될 때까지 인덱스에 남아 있습니다.
필드 정의 변경	필드 이름, 데이터 형식 또는 특정 인덱싱 특성(검색 가능, 필터링 가능, 정렬 가능, 패싯 가능)을 수정하려면 전체적으로 다시 빌드해야 합니다.
필드에 분석기 할당	분석기는 인덱스에 정의되어 필드에 할당된 다음, 인덱싱 중에 호출되어 토큰 생성 방법을 알려줍니다. 언제든지 새 분석기 정의를 인덱스에 추가할 수 있지만, 분석기 할당은 필드를 만들 때만 가능합니다. 분석기와 indexAnalyzer 둘 다 그렇습니다. searchAnalyzer 속성은 예외입니다(이 속성을 기존 필드에 할당 가능).
인덱스의 분석기 정의 업데이트 또는 삭제	전체 인덱스를 다시 작성하지 않는 한 인덱스의 기존 분석기 구성(분석기, 토크나이저, 토큰 필터 또는 char 필터)을 삭제 또는 변경할 수 없습니다.
제안기에 필드 추가	필드가 이미 존재하고 이를 Suggesters 구문에 추가하려면 인덱스를 다시 빌드합니다.
계층 전환	현재 위치 업그레이드는 지원되지 않습니다. 더 많은 용량이 필요한 경우 새 서비스를 만들고 인덱스를 처음부터 다시 빌드합니다. 이 프로세스를 자동화하는 데 도움이 되도록 이 Azure AI 검색 .NET 샘플 리포지토리의 index-backup-restore 샘플 코드를 사용할 수 있습니다. 이 앱은 일련의 JSON 파일에 인덱스를 백업한 다음 지정하는 검색 서비스에서 인덱스를 다시 만듭니다.

작업 순서:

1. 나중에 참조하거나 새 버전의 기초로 사용하기 위해 필요한 경우 인덱스 정의를 가져옵니다.

2. 백업 및 복원 솔루션을 사용하여 인덱스 콘텐츠의 복사본을 유지하는 것이 좋습니다. C# 및 Python에는 솔루션이 있습니다. 최신 상태이므로 Python 버전을 사용하는 것이 좋습니다.

   검색 서비스에 용량이 있는 경우 새 인덱스를 만들고 테스트하는 동안 기존 인덱스를 유지합니다.

3. 기존 인덱스를 삭제합니다. 해당 인덱스를 대상으로 하는 모든 쿼리는 즉시 삭제됩니다. 인덱스 삭제는 되돌릴 수 없으며, 필드 컬렉션 및 기타 구성에 대한 실제 스토리지가 제거됩니다.

4. 요청 본문에는 변경되거나 수정된 필드 정의 및 구성이 포함된 수정된 인덱스를 게시합니다.

5. 외부 원본의 문서를 사용하는 인덱스를 로드합니다. 문서는 새 스키마의 필드 정의 및 구성을 사용하여 인덱싱됩니다.

인덱스를 만들 때 실제 스토리지는 인덱스 스키마의 각 필드에 할당되며, 검색 가능한 각 필드에 대해 반전된 인덱스가 생성되고 각 벡터 필드에 대해 벡터 인덱스가 생성됩니다. 검색할 수 없는 필드는 필터 또는 식에 사용할 수 있지만, 반전된 인덱스를 갖고 있지 않으며 전체 텍스트 또는 유사 항목 검색이 불가능합니다. 인덱스를 다시 작성할 때 이러한 반전된 인덱스와 벡터 인덱스는 사용자가 제공하는 인덱스 스키마에 따라 삭제되고 다시 만들어집니다.

워크로드 분산

인덱싱이 백그라운드에서 실행되지는 않지만, 검색 서비스가 모든 인덱싱 작업과 진행 중인 쿼리의 균형을 맞춥니다. 인덱싱 중에 포털에서 쿼리 요청을 모니터링하여 쿼리가 적시에 완료되도록 할 수 있습니다.

인덱싱 워크로드로 인해 허용할 수 없는 수준의 쿼리 대기 시간이 발생하는 경우, 성능을 분석하고 이러한 성능 팁을 검토하여 완화할 수 있습니다.

업데이트 확인

첫 번째 문서를 로드하는 즉시 인덱스 쿼리를 시작할 수 있습니다. 문서 ID를 알고 있는 경우 문서 조회 REST API가 특정 문서를 반환합니다. 보다 광범위한 테스트를 위해서는 인덱스가 완전히 로드될 때까지 기다린 다음, 쿼리를 사용하여 보려는 컨텍스트를 확인합니다.

검색 탐색기 또는 REST 클라이언트를 사용하여 업데이트된 콘텐츠를 확인할 수 있습니다.

필드를 추가하거나 이름을 변경한 경우 $select를 사용하여 해당 필드를 반환합니다. search=*&$select=document-id,my-new-field,some-old-field&$count=true

Azure Portal은 인덱스 크기 및 벡터 인덱스 크기를 제공합니다. 인덱스 업데이트 후 이러한 값을 확인할 수 있지만, 서비스에서 변경 내용을 처리하고 포털 새로 고침 속도를 고려할 때 약간의 지연이 예상되며 몇 분 정도가 될 수 있습니다.

연결 없는 문서 삭제

Azure AI Search는 격리된 특정 문서를 조회, 업데이트 및 삭제할 수 있도록 문서 수준 작업을 지원합니다. 다음 예제에서는 문서를 삭제하는 방법을 보여 줍니다.

문서를 삭제해도 인덱스의 공간이 즉시 확보되지는 않습니다. 몇 분마다 백그라운드 프로세스는 물리적 삭제를 수행합니다. 포털 또는 API를 사용하여 인덱스 통계를 반환하든 삭제가 포털 및 API 메트릭에 반영되기 전에 약간의 지연을 예상할 수 있습니다.

1. 문서 키인 필드를 식별합니다. 포털에서 각 인덱스의 필드를 볼 수 있습니다. 문서 키는 문자열 필드이며 더 쉽게 발견할 수 있도록 키 아이콘으로 표시됩니다.

2. 문서 키 필드 search=*&$select=HotelId의 값을 확인합니다. 간단한 문자열은 간단하지만 인덱스에서 base-64로 인코딩된 필드를 사용하거나 parsingMode 설정에서 검색 문서를 생성한 경우 익숙하지 않은 값으로 작업할 수 있습니다.

3. 문서를 조회하여 문서 ID의 값을 확인하고 문서를 삭제하기 전에 해당 콘텐츠를 검토합니다. 요청에서 키 또는 문서 ID를 지정합니다. 다음 예제에서는 Hotels 샘플 인덱스에 대한 간단한 문자열과 cog-search-demo 인덱스의 metadata_storage_path 키에 대한 base-64로 인코딩된 문자열을 보여 줍니다.

   GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2024-07-01
   

   GET https://[service name].search.windows.net/indexes/cog-search-demo/docs/aHR0cHM6Ly9oZWlkaWJsb2JzdG9yYWdlMi5ibG9iLmNvcmUud2luZG93cy5uZXQvY29nLXNlYXJjaC1kZW1vL2d1dGhyaWUuanBn0?api-version=2024-07-01
   

4. @search.action 삭제를 사용하여 문서를 삭제하여 검색 인덱스에서 제거합니다.

   POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/index?api-version=2024-07-01
   Content-Type: application/json   
   api-key: [admin key] 
   {  
     "value": [  
       {  
         "@search.action": "delete",  
         "id": "1111"  
       }  
     ]  
   }
   

참고 항목

• 인덱서 개요
• 대규모 데이터 집합 인덱싱
• 포털의 인덱싱
• Azure SQL Database 인덱서
• Azure Cosmos DB for NoSQL 인덱서
• Azure Blob 인덱서
• Azure 테이블 인덱서
• Azure AI Search의 보안