不區分大小寫的篩選、Facet 和排序的文字正規化

發行項
09/03/2024

重要

此功能在補充使用規定下處於公開預覽狀態。預覽 REST API 支援此功能。

在 Azure AI 搜尋服務中，正規化程式是一種可預先處理文字的元件，會針對標示為「可篩選」、「可面向化」或「可排序」的欄位比對關鍵字。相較於與文字分析器搭配使用的全文「可搜尋」欄位，針對篩選 -Facet- 排序作業所建立的內容不會經過分析或 Token 化。若缺少文字分析，在遇到大小寫和字元差異時會產生非預期的結果，這便是為何需要正規化程式來將內容中的差異同質化。

藉由套用正規化程式，您可以達成輕度文字轉換，進而改善結果：

一致的大小寫 (例如所有文字皆為小寫或大寫)
將重音和變音符號正規化，例如 ö 或 ê 以及 ASCII 對等字元「o」和「e」
將 - 字元和空白字元對應至使用者指定的字元

正規化程式的優點

從搜尋索引搜尋和擷取文件需要比對查詢輸入與文件的內容。叫用「搜尋」時比對權杖化內容，而當要求是篩選、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"，即使目的是要將相同的城市排在一起 (不論大小寫為何)。

在編製索引和查詢執行期間叫用的正規化程式，會在篩選、Facet 和排序案例的文字中進行輕度轉換，以消除文字中的些微差異。在先前的範例中，會根據您選取的正規化程式來處理 "Las Vegas" 的變體 (例如，所有文字都是小寫)，以取得更統一的結果。

如何指定正規化程式

正規化程式是以每個欄位為基礎，根據索引定義在文字欄位 (Edm.String 和Collection(Edm.String)) 中指定，而「可篩選」、「可排序」或「可 Facet」中至少有一個屬性需設定為 true。設定正規化程式是選用設定，預設為 Null。建議您先評估預先定義的正規化程式，再設定自訂正規化程式。

正規化程式只能在您將新欄位新增至索引時指定，因此可能的話，請試著預先評估正規化的需要，並在卸除和重建索引為例行工作時，於開發的初始階段指派正規化程式。

在索引中建立欄位定義時，請將 "normalizer" 屬性設定為下列其中一個值：預先定義的正規化程式如 "lowercase"，或自訂正規化程式 (在相同的索引結構描述中定義)。
```
"fields": [
 {
   "name": "Description",
   "type": "Edm.String",
   "retrievable": true,
   "searchable": true,
   "filterable": true,
   "analyzer": "en.microsoft",
   "normalizer": "lowercase"
   ...
 }
]
```
自訂正規化程式會先在索引的 "normalizers" 區段中定義，然後指派給欄位定義，如上一個步驟所示。如需詳細資訊，請參閱建立索引以及新增自訂正規化程式。
```
"fields": [
 {
   "name": "Description",
   "type": "Edm.String",
   "retrievable": true,
   "searchable": true,
   "analyzer": null,
   "normalizer": "my_custom_normalizer"
 },
```

注意

若要變更現有欄位的正規化程式，請重建整個索引 (您無法重建個別欄位)。

當重建索引成本很高，理想的產生索引替代方案會是建立與舊索引相同的新欄位，但使用新的正規化程式，並用以取代舊的欄位。使用更新索引來合併新欄位，以及使用 mergeOrUpload 來填入資料。稍後，您可以清除索引以移除過時的欄位，當作規劃索引服務的一部分。

預先定義和自訂正規化程式

Azure AI 搜尋服務提供一般使用案例的內建正規化程式，以及視需要自訂的功能。

類別	描述
預先定義的正規化程式	以立即可用的形式提供，而且不需要任何設定即可使用。
自訂正規化程式 ¹	適用於進階案例。需要現有元素組合的使用者定義設定，其中包含 Char 和 Token 篩選條件。

⁽¹⁾ 自訂正規化程式不會指定權杖化工具，因為正規化程式一律會產生單一權杖。

正規化程式參考

預先定義的正規化程式

名稱	說明和選項
standard	小寫文字後面接著 asciifolding。
小寫	將字元轉換成小寫。
uppercase	將字元轉換成大寫。
asciifolding	將不在基本拉丁 Unicode 區塊中的字元轉換為 ASCII 對等字元 (如存在)。例如，將 `à` 變更為 `a`。
elision	移除權杖開頭的省略。

支援的 Char 篩選條件

正規化程式支援兩個與自訂分析器字元篩選條件中對應項目相同的字元篩選條件：

支援的權杖篩選條件

下列清單顯示正規化程式支援的權杖篩選條件，而且是自訂分析器中使用的整體權杖篩選條件子集。

新增自訂正規化程式

自訂正規化程式會在索引結構描述內定義。定義包含名稱、類型、一或多個字元篩選條件和權杖篩選條件。字元篩選條件和權杖篩選條件是自訂正規化程式的建置組塊，負責處理文字。這些篩選條件會以由左到右的順序套用。

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",
      ...
   }
]

您可以在建立索引期間，或稍後藉由更新現有的正規化程式來新增自訂正規化程式。將自訂正規化程式新增至現有的索引，需要更新索引中指定的 "allowIndexDowntime" 旗標，而且會導致索引在幾秒鐘內無法使用。

自訂正規化程式範例

下列範例說明具有對應字元篩選條件和權杖篩選條件的自訂正規化程式定義。字元篩選和權杖篩選條件會個別指定為具名的建構，然後在正規化程式定義中加以參考，如下圖所示。

名為 "my_custom_normalizer" 的自訂正規化程式，如索引定義的「正規化程式」區段中所定義。
正規化程式是由兩個字元篩選條件和三個權杖篩選條件所組成：省略、小寫和自訂 asciifolding 篩選條件 “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
        }
     ]
  }

共用方式為