대/소문자를 구분하지 않는 필터링, 패싯 및 정렬을 위한 텍스트 정규화

참고

Azure AI 검색 Azure 포털, REST API 및 Azure SDK 통해 사용할 수 있습니다. 또한 엔터프라이즈 콘텐츠를 Microsoft Foundry 포털의 에이전트에 대해 재사용 가능한 사용 권한 인식 기술 자료로 변환하는 관리되는 기술 계층인 Foundry IQ를 뒷받침합니다.

Azure AI 검색 normalizer는 "filterable", "facetable" 또는 "sortable"로 표시된 필드에 대한 키워드 일치를 위해 텍스트를 미리 처리하는 구성 요소입니다. 텍스트 분석기와 쌍을 이루는 전체 텍스트 "검색 가능" 필드와 달리 필터 패싯 정렬 작업을 위해 만들어진 콘텐츠는 분석 또는 토큰화를 거치지 않습니다. 텍스트 분석을 생략하면 대/소문자와 문자 차이가 표시될 때 예기치 않은 결과가 발생할 수 있으므로 콘텐츠의 변형을 균질화하기 위해 정규화기가 필요합니다.

normalizer를 적용하면 밝은 텍스트 변환을 수행하여 결과를 향상시킬 수 있습니다.

일관된 글자 형식(예: 모든 소문자 또는 대문자)
ö 또는 ê와 같은 악센트 및 발음을 ASCII 등가 문자 "o" 및 "e"로 정규화합니다.
문자 - 및 공백을 사용자 지정 문자로 매핑합니다.

normalizer의 이점

검색 인덱스에서 문서를 검색하고 검색하려면 쿼리 입력을 문서의 내용과 일치해야 합니다. 일치는 "search"을 호출할 때 토큰화된 콘텐츠에 대해 수행되거나, 요청이 filter, facet 또는 orderby 작업인 경우에는 토큰화되지 않은 콘텐츠에 대해 수행됩니다.

토큰화되지 않은 콘텐츠도 분석되지 않으므로 콘텐츠의 작은 차이는 분명히 다른 값으로 평가됩니다. 다음 예제를 고려하세요.

$filter=City eq 'Las Vegas'는 정확한 텍스트 "Las Vegas"가 포함된 문서만 반환하고, "LAS VEGAS"와 "las vegas"가 포함된 문서는 제외합니다. 대/소문자 구분과 관계없이 모든 문서가 필요한 사용 사례에서는 이러한 방식이 부적절합니다.
search=*&facet=City,count:5는 동일한 도시임에도 불구하고 고유한 값으로 반환 "Las Vegas""LAS VEGAS""las vegas" 됩니다.
search=usa&$orderby=City는 경우에 관계없이 동일한 도시를 함께 주문하려는 의도가 있더라도 어휘 순서"Las Vegas""Seattle""las vegas"로 도시를 반환합니다.

인덱싱 및 쿼리 실행 중에 호출되는 normalizer는 필터, 패싯 및 정렬 시나리오에 대한 텍스트의 사소한 차이를 부드럽게 하는 밝은 변환을 추가합니다. 이전 예제에서는 보다 균일한 결과를 위해 선택한 표준 변환기(예: 모든 텍스트가 소문자)에 따라 변형 "Las Vegas" 이 처리됩니다.

normalizer를 지정하는 방법

Normalizer는 "filterable", "sortable" 또는 "facetable" 속성 중 하나 이상이 true로 설정된 텍스트 필드(Edm.String 및 Collection(Edm.String))에서 필드별로 인덱스 정의에 지정됩니다. normalizer 설정은 선택 사항이며 기본적으로 null입니다. 사용자 지정 정규화를 구성하기 전에 미리 정의된 정규화를 평가하는 것이 좋습니다.

Normalizer는 인덱스에 새 필드를 추가할 때만 지정할 수 있으므로 가능한 경우 정규화 요구 사항을 미리 평가하고 인덱스를 삭제하고 다시 만들 때 개발 초기 단계에서 normalizer를 할당합니다.

인덱스에서 필드 정의를 만들 때 "normalizer" 속성을 "소문자"와 같은 미리 정의된 정규화기 또는 사용자 지정 정규화기(동일한 인덱스 스키마에 정의됨) 값 중 하나로 설정합니다.
```
"fields": [
 {
   "name": "Description",
   "type": "Edm.String",
   "retrievable": true,
   "searchable": true,
   "filterable": true,
   "analyzer": "en.microsoft",
   "normalizer": "lowercase"
   ...
 }
]
```
사용자 지정 normalizer는 먼저 인덱스의 "normalizers" 섹션에서 정의한 다음, 이전 단계에서와 같이 필드 정의에 할당됩니다. 자세한 내용은 인덱스 만들기 및 사용자 지정 표준 변환기 추가를 참조하세요.
```
"fields": [
 {
   "name": "Description",
   "type": "Edm.String",
   "retrievable": true,
   "searchable": true,
   "analyzer": null,
   "normalizer": "my_custom_normalizer"
 },
```

참고

기존 필드의 normalizer를 변경하려면 인덱스 전체를 다시 작성합니다(개별 필드를 다시 작성할 수 없음).

인덱스를 다시 빌드하는 데 비용이 많이 드는 프로덕션 인덱스에 대한 좋은 해결 방법은 이전 필드와 동일하지만 새 정규화기를 사용하여 새 필드를 만들고 이전 필드 대신 사용하는 것입니다. 업데이트 인덱스를 사용하여 새 필드와 mergeOrUpload를 통합하여 채웁다. 나중에 계획된 인덱스 서비스의 일부로 인덱스를 정리하여 사용되지 않는 필드를 제거할 수 있습니다.

미리 정의된 표준 변환기 및 사용자 지정 표준 변환기

Azure AI 검색 필요에 따라 사용자 지정하는 기능과 함께 일반적인 사용 사례에 대한 기본 제공 정규화를 제공합니다.

범주	설명
미리 정의된 정규화기	기본 제공되며 구성 없이 사용할 수 있습니다.
사용자 지정 정규화기¹	고급 시나리오의 경우. char 및 토큰 필터로 구성된 기존 요소의 조합에 대한 사용자 정의 구성이 필요합니다.

⁽¹⁾ Normalizer는 항상 단일 토큰을 생성하기 때문에 사용자 정의 정규화기는 토큰 변환기를 지정하지 않습니다.

normalizer 시험하기

REST(Test Analyzer)를 사용하여 정규화기가 입력을 처리하는 방법을 확인할 수 있습니다.

요청

  POST https://[search service name].search.windows.net/indexes/[index name]/analyze?api-version=[api-version]
    Content-Type: application/json
    api-key: [admin key]

  {
     "normalizer":"asciifolding",
     "text": "Vis-à-vis means Opposite"
  }

응답

HTTP/1.1 200 OK

{
  "tokens": [
    {
      "token": "Vis-a-vis means Opposite",
      "startOffset": 0,
      "endOffset": 24,
      "position": 0
    }
  ]
}

Normalizers 자료 참조

미리 정의된 정규화기

이름	설명 및 옵션
표준	텍스트를 소문자로 변환한 다음 아스키 폴딩을 적용합니다.
소문자	문자를 소문자로 변환합니다.
대문자	문자를 대문자로 변환합니다.
asciifolding (아스키폴딩)	기본 라틴어 유니코드 블록에 없는 문자를 해당하는 ASCII(있는 경우)로 변환합니다. 예를 들어 `à`를 `a`로 변경하는 경우.
elision	토큰의 시작 부분에서 엘리션을 제거합니다.

지원되는 문자 필터

Normalizer는 사용자 지정 분석기 문자 필터에서와 마찬가지로 동일한 두 개의 문자 필터를 지원합니다.

지원되는 토큰 필터

아래 목록에서는 normalizer에 대해 지원되는 토큰 필터를 보여 줍니다. 이는 사용자 지정 분석기에서 사용되는 전체 토큰 필터의 하위 집합입니다.

사용자 지정 표준 변환기 추가

사용자 지정 normalizer는 인덱스 스키마 내에서 정의됩니다. 정의에는 이름, 형식, 하나 이상의 문자 필터 및 토큰 필터가 포함됩니다. 문자 필터 및 토큰 필터는 사용자 지정 정규화기의 구성 요소이며 텍스트 처리를 담당합니다. 이러한 필터는 왼쪽에서 오른쪽으로 적용됩니다.

토큰 token_filter_name_1 필터의 이름이며 char_filter_name_1char_filter_name_2 문자 필터의 이름입니다(유효한 값은 아래 의 지원되는 토큰 필터 및 지원되는 char 필터테이블 참조).

"normalizers":(optional)[
   {
      "name":"name of normalizer",
      "@odata.type":"#Microsoft.Azure.Search.CustomNormalizer",
      "charFilters":[
         "char_filter_name_1",
         "char_filter_name_2"
      ],
      "tokenFilters":[
         "token_filter_name_1"
      ]
   }
],
"charFilters":(optional)[
   {
      "name":"char_filter_name_1",
      "@odata.type":"#char_filter_type",
      "option1": "value1",
      "option2": "value2",
      ...
   }
],
"tokenFilters":(optional)[
   {
      "name":"token_filter_name_1",
      "@odata.type":"#token_filter_type",
      "option1": "value1",
      "option2": "value2",
      ...
   }
]

인덱스를 만드는 동안 또는 나중에 기존 정규화를 업데이트하여 사용자 지정 정규화를 추가할 수 있습니다. 기존 인덱스에 사용자 지정 normalizer를 추가하려면 업데이트 인덱 스에 "allowIndexDowntime" 플래그를 지정해야 하며 몇 초 동안 인덱스를 사용할 수 없게 됩니다.

사용자 지정 normalizer 예제

아래 예제에서는 해당 문자 필터 및 토큰 필터를 사용하는 사용자 지정 정규화기 정의를 보여 줍니다. 문자 필터 및 토큰 필터에 대한 사용자 지정 옵션은 명명된 구문으로 별도로 지정된 다음 아래 그림과 같이 normalizer 정의에서 참조됩니다.

"my_custom_normalizer"라는 사용자 지정 normalizer는 인덱스 정의의 "normalizers" 섹션에 정의됩니다.
normalizer는 두 개의 문자 필터와 3개의 토큰 필터인 엘리전, 소문자 및 사용자 지정된 비시폴딩 필터 "my_asciifolding"로 구성됩니다.
첫 번째 문자 필터 "map_dash"는 모든 대시를 밑줄로 바꾸고 두 번째 문자 필터 "remove_whitespace"는 모든 공백을 제거합니다.

  {
     "name":"myindex",
     "fields":[
        {
           "name":"id",
           "type":"Edm.String",
           "key":true,
           "searchable":false,
        },
        {
           "name":"city",
           "type":"Edm.String",
           "filterable": true,
           "facetable": true,
           "normalizer": "my_custom_normalizer"
        }
     ],
     "normalizers":[
        {
           "name":"my_custom_normalizer",
           "@odata.type":"#Microsoft.Azure.Search.CustomNormalizer",
           "charFilters":[
              "map_dash",
              "remove_whitespace"
           ],
           "tokenFilters":[              
              "my_asciifolding",
              "elision",
              "lowercase",
           ]
        }
     ],
     "charFilters":[
        {
           "name":"map_dash",
           "@odata.type":"#Microsoft.Azure.Search.MappingCharFilter",
           "mappings":["-=>_"]
        },
        {
           "name":"remove_whitespace",
           "@odata.type":"#Microsoft.Azure.Search.MappingCharFilter",
           "mappings":["\\u0020=>"]
        }
     ],
     "tokenFilters":[
        {
           "name":"my_asciifolding",
           "@odata.type":"#Microsoft.Azure.Search.AsciiFoldingTokenFilter",
           "preserveOriginal":true
        }
     ]
  }

다음 항목 참고하기

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-07-03