在 Azure AI 搜尋服務中新增同義字

Note

Azure AI 搜尋服務 可透過 Azure 入口網站、REST API 及 Azure SDK 取得。 它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。

在搜尋服務中，同義字對應可將對等詞彙相互關聯，從而擴展查詢範圍，使用者無需實際提供該詞彙即可執行搜尋。 例如，假設 dog、canine 與 puppy 被設定為對應的同義字，則針對 canine 的查詢也會匹配到包含 dog 的文件。 您可以為不同語言 (例如英文版與法文版) 或語彙建立多個同義字對應，特別是當您的內容包含技術用語、俚語或晦澀術語。

有關同義字對應的一些重點：

  • 同義字對應是最上層資源，建立一次後即可供許多索引使用。
  • 同義字對應會套用至字串欄位。
  • 您可以隨時建立並指派同義字對應，無需中斷索引編製或查詢。
  • 您的服務層級會設定您可以建立的同義字對應數量上限。
  • 搜尋服務可以有多個同義字對應，但在索引內，欄位定義只能有一個同義字對應指派。

建立同義字對應

同義映射由名稱、格式及作為同義映射條目運作的規則組成。 唯一支援的格式是 solr，而該 solr 格式決定規則的構造。

若要建立同義字對應，請以程式設計方式執行。 Azure 入口網站不支援同義地圖定義。

使用建立同義字對應 (REST API) 來建立同義字對應。

POST /synonymmaps?api-version=2026-04-01
{
    "name": "geo-synonyms",
    "format": "solr",
    "synonyms": "
        USA, United States, United States of America\n
        Washington, Wash., WA => WA\n"
}

定義規則

對應規則遵守 Apache Solr 的開放原始碼同義字篩選規格，如本文件所述：SynonymGraphFilter。 solr 格式支援兩種規則：

  • 對等關係 (即詞彙在查詢中為完全對等的替代項)

  • 明確對應 (其中的詞彙已對應至一個明確詞彙)

每條規則由換行字元（\n）界定。 在免費服務中，每個同義字對應最多可定義 5,000 條規則，而其他服務層級中，每個對應則最多可定義 20,000 條規則。 每個規則最多可以有 20 個擴展，或規則中的項目。 如需詳細資訊，請參閱同義字限制。

查詢剖析器會自動將大寫或混合大小寫的詞彙轉換為小寫。 若需在字串中保留特殊字元 (如逗號或破折號)，請在建立同義字對應時新增適當的逸出字元。

對等規則

對等詞彙的規則在同一條規則內以逗號分隔。 在第一個例子中，查詢 USA 會擴展為 USA 或「美國」或「美國 of America」。如果你想在片語上匹配，查詢本身必須是引號包的短語查詢。

在對等案例中，針對 dog 的查詢會擴展為同時包含 puppy 和 canine。

{
"format": "solr",
"synonyms": "
    USA, United States, United States of America\n
    dog, puppy, canine\n
    coffee, latte, cup of joe, java\n"
}

明確對應

明確對應的規則會以箭號 => 表示。 當指定此規則後，若搜尋查詢中的詞彙序列符合 => 左側內容，系統將在查詢階段將其替換為右側的對應選項。

在明確情況下，查詢 Washington、Wash. 或 WA 會被重寫為 WA，且查詢引擎只會尋找 WA 這個詞彙的匹配項。 明確對應僅適用於指定的方向，在此案例中不會將查詢 WA 重寫為 Washington。

{
"format": "solr",
"synonyms": "
    Washington, Wash., WA => WA\n
    California, Calif., CA => CA\n"
}

逸出特殊字元

同義字在查詢處理期間會像其他查詢詞彙一樣被分析，這表示保留字元和特殊字元的規則同樣適用於您的同義字對應中的詞彙。 需要逸出的字元清單會因簡單語法和完整語法而異：

若要保留預設分析器捨棄的字元，請替換為能保留這些字元的分析器。 部分選項包含 Microsoft 自然語言分析器，可保留連字號組成的字詞，或用於更複雜模式的自訂分析器。 如需詳細資訊，請參閱部分詞彙、模式與特殊字元。

下列範例示範如何使用反斜線逸出字元：

{
    "format": "solr",
    "synonyms": "WA\, USA, WA, Washington\n"
}

由於反斜線本身在 JSON 和 C# 等其他語言中也是特殊字元，您可能需要將其逸出兩次。 此處是 JSON 的範例：

{
    "format":"solr",
    "synonyms": "WA\\, USA, WA, Washington"
}

管理同義字對應

您可以在不中斷查詢和索引編製工作負載的情況下，更新同義字對應。 不過，當您將同義字對應新增至欄位之後，如果您刪除同義字對應，任何包含有問題欄位的查詢就會失敗，並出現 404 錯誤。

建立、更新和刪除同義字對應，始終是整份文件的作業。 您無法以累加方式更新或刪除部分的同義字對應。 即便只是更新一個規則也需要重新載入。

將同義字指派給欄位

建立同義字對應之後，請將其指派給索引中的欄位。 若要指派同義字對應，請以程式設計方式執行。 Azure 入口網站不支援同義地圖欄位關聯。

  • 欄位的類型必須是 Edm.String 或 Collection(Edm.String)
  • 欄位必須具備 "searchable":true
  • 一個欄位只能有一個同義字對應

如果同義字對應存在於搜尋服務中，則會在下一個查詢中使用，無需重新編製索引或重建。

使用建立或更新索引 (REST API) 來修改欄位定義。

PUT /indexes?api-version=2026-04-01
{
    "name":"hotels-sample",
    "fields":[
        {
            "name":"description",
            "type":"Edm.String",
            "searchable":true,
            "synonymMaps":[
            "en-synonyms"
            ]
        },
        {
            "name":"description_fr",
            "type":"Edm.String",
            "searchable":true,
            "analyzer":"fr.microsoft",
            "synonymMaps":[
            "fr-synonyms"
            ]
        }
    ]
}

查詢對等或對應的欄位

同義字欄位指派不會變更您撰寫查詢的方式。 在同義字對應指派之後，唯一的差異在於，如果同義字對應中有查詢詞彙，搜尋引擎會根據規則來擴充或重寫詞彙或片語。

查詢執行期間如何使用同義字

同義字是一種查詢擴充技術，可透過對等詞彙補充索引的內容，但僅適用於具有同義字指派的欄位。 如果欄位範圍查詢排除已啟用同義字的欄位，您就不會看到同義字對應中的相符項目。

針對已啟用同義字的欄位，同義字受限於與相關聯欄位相同的文字分析。 例如，如果系統使用標準 Lucene 分析器來分析欄位，同義字詞彙也會在查詢時受限於標準 Lucene 分析器。 如果您想要在同義字詞彙中保留標點符號，例如句點或虛線，請在該欄位上套用內容保留分析器。

在內部，同義字功能會使用 OR 運算子，以同義字重寫原始查詢。 基於此原因，搜尋結果醒目提示與評分設定檔會將原始詞彙與同義字視為對等處理。

同義字僅適用於自由格式的文字查詢，且不支援篩選、Facet、自動完成或建議。 自動完成和建議僅根據原始詞彙提供，同義字比對結果不會出現在回應中。

如果您在開發 (非生產) 環境中有現有索引，可使用小型同義詞表進行測試，觀察新增同義字如何改變搜尋體驗，包括對評分設定檔、搜尋結果醒目提示和搜尋建議的影響。

萬用字元搜尋

同義字擴充不適用於萬用字元搜尋詞彙；也不會擴充前置詞、模糊與 RegEx 詞彙。

如果您需要執行適用同義字展開和萬用字元、regex 或模糊搜尋的單一查詢，您可以使用 OR 語法結合查詢。 例如，若要針對簡單查詢語法結合同義字與萬用字元，該詞彙可以是 <query> | <query>*。

後續步驟

建立同義字對應 (REST API)

  • Last updated on