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

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

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

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

콘텐츠 업데이트

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

요청 본문에는 인덱싱할 문서가 하나 이상 포함되어 있습니다. 문서는 고유한 대/소문자를 구분하는 키로 식별됩니다. 각 문서는 "upload", "delete", "merge" 또는 "mergeOrUpload" 작업과 연결됩니다. 업로드 요청은 키/값 쌍 집합으로 문서 데이터를 포함해야 합니다.

{  
  "value": [  
    {  
      "@search.action": "upload (default) | merge | mergeOrUpload | delete",  
      "key_field_name": "unique_key_of_document", (key/value pair for key field from index schema)  
      "field_name": field_value (key/value pairs matching index schema)  
        ...  
    },  
    ...  
  ]  
}

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

• 대규모 업데이트의 경우 일괄 처리(일괄 처리당 최대 1,000개 문서 또는 일괄 처리당 약 16MB,어느 제한이 먼저 오는지)를 권장하며 인덱싱 성능을 크게 향상시킵니다.

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

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

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

응답

성공적인 응답을 위해 상태 코드 200이 반환됩니다. 즉, 모든 항목이 지속적으로 저장되고 인덱싱되기 시작합니다. 인덱싱은 백그라운드에서 실행되며 인덱싱 작업이 완료된 후 몇 초 후에 새 문서(즉, 쿼리 가능하고 검색 가능)를 사용할 수 있습니다. 특정 지연은 서비스의 부하에 따라 달라집니다.

성공적인 인덱싱은 모든 항목에 대해 true로 설정되는 상태 속성뿐만 statusCode 아니라 새로 업로드된 문서의 경우 201 또는 200(병합되거나 삭제된 문서의 경우)으로 설정되는 속성으로 표시됩니다.

{
  "value": [
    {
      "key": "unique_key_of_new_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 201
    },
    {
      "key": "unique_key_of_merged_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    },
    {
      "key": "unique_key_of_deleted_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    }
  ]
}

하나 이상의 항목이 성공적으로 인덱싱되지 않은 경우 상태 코드 207이 반환됩니다. 인덱싱되지 않은 항목에는 상태 필드가 false로 설정됩니다. 및 statusCode 속성은 errorMessage 인덱싱 오류의 원인을 나타냅니다.

{
  "value": [
    {
      "key": "unique_key_of_document_1",
      "status": false,
      "errorMessage": "The search service is too busy to process this document. Please try again later.",
      "statusCode": 503
    },
    {
      "key": "unique_key_of_document_2",
      "status": false,
      "errorMessage": "Document not found.",
      "statusCode": 404
    },
    {
      "key": "unique_key_of_document_3",
      "status": false,
      "errorMessage": "Index is temporarily unavailable because it was updated with the 'allowIndexDowntime' flag set to 'true'. Please try again later.",
      "statusCode": 422
    }
  ]
}  

이 속성은 errorMessage 가능한 경우 인덱싱 오류의 원인을 나타냅니다.

다음 표에서는 응답에서 반환할 수 있는 다양한 문서별 상태 코드를 설명합니다. 일부 상태 코드는 요청 자체의 문제를 나타내고 다른 코드는 임시 오류 조건을 나타냅니다. 후자는 지연 후 다시 시도해야 합니다.

클라이언트 코드에서 207 응답이 자주 발생하는 경우 한 가지 가능한 이유는 시스템이 로드 중이기 때문입니다. statusCode 속성을 503으로 확인하여 확인할 수 있습니다. statusCode가 503인 경우 인덱싱 요청을 제한하는 것이 좋습니다. 인덱싱 트래픽이 감소하지 않는 경우에는 시스템에서 모든 요청을 거부하며 503 오류가 발생할 수 있습니다.

상태 코드 429는 인덱스당 문서 수에 대한 할당량을 초과했음을 나타냅니다. 더 높은 용량 제한을 위해 새 인덱스를 만들거나 업그레이드해야 합니다.

증분 인덱싱 팁

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

• 푸시 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 업데이트
• 인덱스(새 필드에 적용할 수 있는)에 새 분석기 정의 추가
• 점수 매기기 프로필 추가, 업데이트 또는 삭제
• synonymMaps 추가, 업데이트 또는 삭제
• 의미 체계 구성 추가, 업데이트 또는 삭제
• CORS 설정 추가, 업데이트 또는 삭제

작업 순서:

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

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

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

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

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

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

다시 빌드가 필요한 업데이트

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

작업 순서:

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

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

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

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

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

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

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

애플리케이션 코드 중단을 최소화하려면 인덱스 별칭을 만드는 것이 좋습니다. 애플리케이션 코드는 별칭을 참조하지만 별칭이 가리키는 인덱스의 이름을 업데이트할 수 있습니다.

워크로드 분산

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

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

업데이트 확인

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

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

필드를 추가하거나 이름을 바꾼 경우 select를 사용하여 해당 필드를 반환합니다.

"search": "*",
"select": "document-id, my-new-field, some-old-field",
"count": true

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

연결 없는 문서 삭제

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

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

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

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 Portal에서 인덱싱
• Azure SQL Database 인덱서
• Azure Cosmos DB for NoSQL 인덱서
• Azure Blob 인덱서
• Azure 테이블 인덱서
• Azure AI Search의 보안