在查詢中設定自動完成和建議的建議工具

在 Azure AI 搜尋服務中，會透過使用建議工具來啟用預先輸入或「在輸入期間進行搜尋」功能。 建議工具是索引中的組態，其會指定應該使用哪些欄位來填入自動完成和建議的相符項。 這些欄位會額外進行 Token 化，產生前置詞序列以支援部分字詞比對功能。 例如，包含值為 city 的 欄位的建議工具具有 sea、seat、seatt 和 seattl 的前置詞組合，以支援預先輸入功能。

部分字詞比對可以是自動完成的查詢或建議的相符項目。 一個建議工具同時支援這兩種體驗。

預先輸入體驗

Azure AI 搜尋服務中的「預先輸入」功能可以是自動完成 (用於完成整個字詞查詢的部分輸入)，也可以是建議 (用於邀請使用者點擊查看特定的相符項)。 自動完成會產生查詢。 建議會產生相符文件。

以下螢幕擷取畫面說明這兩者。 自動完成功能會預測一個可能的字詞，並用 in 補完 tw。 建議功能是迷你搜尋結果，其中像 hotel name 這樣的欄位代表索引中符合的旅館搜尋文件。 若使用建議功能，您可以呈現任何提供描述性資訊的欄位。

您可以單獨或一起使用這些功能。 為了在 Azure AI 搜尋服務中實作這些行為，需有索引和查詢元件。

• 將建議工具新增至搜尋索引定義。 本文的其餘部分著重於說明如何建立建議工具。

• 使用使用建議工具中列出的其中一個 API，以建議要求或自動完成要求的形式呼叫啟用建議工具的查詢。

針對字串欄位，根據每個欄位啟用在輸入期間進行搜尋。 如果您想要類似螢幕擷取畫面中所指出的體驗，可以在同一個搜尋解決方案內實作這兩種預先輸入行為。 這兩種要求都會以特定索引的文件集合為目標，並在使用者至少提供三個字元的輸入字串之後傳回回應。

如何建立建議工具

若要建立建議工具，請將建議工具新增至索引定義。 建議工具會採用一個名稱和一個欄位集合，以此為基礎啟用預先輸入體驗。 當您也定義了使用建議工具的欄位時，是建立建議工具的最佳時機。

• 僅限使用字串欄位。

• 如果字串欄位是複合類型的一部分 (例如地址中的城市欄位)，則請將父層包含在欄位路徑中："Address/City" (REST、C# 和 Python) 或 ["Address"]["City"] (JavaScript)。

• 對欄位使用預設標準 Lucene 分析器 ("analyzer": null) 或語言分析器 (例如 "analyzer": "fr.microsoft")。

如果您嘗試使用預先存在的欄位來建立建議工具，API 將不允許這麼做。 前置詞會在編製索引期間產生，兩個或多個字元組合中的部分字詞會與整個詞彙一起 Token 化。 假設現有的欄位已經 Token 化，如果您想將這些欄位新增至建議工具，則必須重建索引。 如需詳細資訊，請參閱在 Azure AI 搜尋服務中更新或重建索引。

選擇欄位

雖然建議工具有多項屬性，但主要是您啟用在輸入期間進行搜尋體驗的字串欄位集合。 每個索引都有一個建議工具，因此建議工具清單必須包含組成建議和自動完成內容的所有欄位。

若有較大欄位集區可提取內容，自動完成的成效會提高，因為額外的內容會帶來較高的字詞完成可能性。

另一方面，若您的欄位可供選擇，建議會產生更好的結果。 請記得，建議是搜尋文件的 Proxy，因此挑選最能代表單一結果的欄位。 能區分多個相符項目的名稱、標題或其他唯一欄位最為適合。 如果欄位是由重複的值所組成，建議便會包含相同的結果，讓使用者不知道要選擇哪一個結果。

若要滿足這兩種在輸入期間進行搜尋的體驗，請新增自動完成功能所需的所有欄位，然後使用 select、top、filter 和 searchFields 來控制建議的結果。

選擇分析器

您選擇的分析器會決定欄位如何權杖化和加上前置詞。 例如，對於像 context-sensitive 這樣的連字號的字串，使用語言分析器時會產生以下的語彙基元組合：context、sensitive、context-sensitive。 如果您使用標準 Lucene 分析器，連字號字串就不會存在。

評估分析器時，可考慮使用分析文字 API 來深入瞭解字詞的處理方式。 建置索引之後，您可以對字串嘗試各種分析器來檢視 Token 輸出。

為防止產生不良的結果，會明確禁止使用自訂分析器或內建分析器 (標準 Lucene 除外) 的欄位。

附註

如果您需要分析器條件約束的因應措施 (例如若您需要特定查詢案例的關鍵字或 ngram 分析器)，您應針對相同的內容使用兩個不同的欄位。 這樣可以讓其中一個欄位擁有建議工具，而另一個欄位可以使用自訂分析器組態進行設定。 如果您使用索引子，則可以將來源欄位對應到兩個不同的索引欄位以支援多種組態。

使用 Azure 入口網站建立

在 Azure 入口網站中，您可以在選取 [ 新增索引] 時指定建議器。

1. 選取 [ 新增索引 ]，然後新增字串欄位。
2. 將欄位歸屬設定為「可搜尋」。
3. 選取分析器。
4. 定義欄位後，選取 自動完成設定。
5. 選取您要啟用自動完成體驗的可搜尋字串欄位。

使用 REST 建立

在 REST API 中，使用 [建立索引] 來新增建議器。

{
  "name": "hotels-sample-index",
  "fields": [
    . . .
        {
            "name": "HotelName",
            "type": "Edm.String",
            "facetable": false,
            "filterable": false,
            "key": false,
            "retrievable": true,
            "searchable": true,
            "sortable": false,
            "analyzer": "en.microsoft",
            "indexAnalyzer": null,
            "searchAnalyzer": null,
            "synonymMaps": [],
            "fields": []
        },
  ],
  "suggesters": [
    {
      "name": "sg",
      "searchMode": "analyzingInfixMatching",
      "sourceFields": ["HotelName"]
    }
  ],
  "scoringProfiles": [
    . . .
  ]
}

使用 .NET 建立

使用 C# 定義 SearchSuggester 物件。 Suggesters 是 SearchIndex 物件的集合，但只能接受一個項目。 將建議工具新增至索引定義。

private static void CreateIndex(string indexName, SearchIndexClient indexClient)
{
    FieldBuilder fieldBuilder = new FieldBuilder();
    var searchFields = fieldBuilder.Build(typeof(Hotel));

    var definition = new SearchIndex(indexName, searchFields);

    var suggester = new SearchSuggester("sg", new[] { "HotelName", "Category", "Address/City", "Address/StateProvince" });
    definition.Suggesters.Add(suggester);

    indexClient.CreateOrUpdateIndex(definition);
}

屬性參考

屬性	描述
NAME	在建議工具定義中指定，但也會對自動完成或建議要求呼叫。
sourceFields	在建議工具定義中指定。 索引 (建議內容的來源) 中一或多個欄位的清單。 欄位的類型必須是 Edm.String。 如果在欄位上指定了分析器，則它必須是 LexicalAnalyzerName Struct 上列出的具名語彙分析器 (而非自訂分析器)。 最佳做法是，僅指定那些能夠產生預期且適當回應的欄位，無論是搜尋列中的已完成字串還是下拉式清單。 旅館名稱是一個不錯的選擇，因為它具有精確度。 描述和註解等詳細資訊欄位則太過密集。 同樣地，重複的欄位效果較差，例如類別和標籤。 在範例中，為了示範您可以包含多個欄位，我們仍納入類別。
searchMode	僅限 REST 參數，但也會顯示在 Azure 入口網站中。 此參數無法用於 .NET SDK。 指出用來搜尋候選片語的策略。 目前唯一支援的模式是 analyzingInfixMatching，目前會比對字詞的開頭內容。

使用建議工具

建議工具用於查詢中。 建立建議工具之後，請呼叫下列其中一個 API，以獲得在輸入期間進行搜尋體驗：

• 建議 REST API
• 自動完成 REST API
• SuggestAsync 方法
• AutocompleteAsync 方法

在搜尋應用程式中，用戶端程式碼應使用 jQuery UI Autocomplete 之類的程式庫來收集部分查詢並提供相符項目。 如需這項工作的詳細資訊，請參閱將自動完成或建議結果新增至用戶端程式碼。

下列對自動完成 REST API 發出的呼叫說明了 API 使用方式。 此範例有兩個重點。 首先，如同所有查詢，這項作業是針對索引的文件集合執行，且查詢中包含 search 參數，在此情況下會提供部分查詢。 其次，您必須將 suggesterName 新增至要求中。 如果沒有在索引中定義建議工具，對自動完成或建議的呼叫會失敗。

POST /indexes/myxboxgames/docs/autocomplete?search&api-version=2025-09-01
{
  "search": "minecraf",
  "suggesterName": "sg"
}

範例程式碼

若要了解如何使用開放原始碼的建議套件以在用戶端應用程式中完成部分字詞，請參閱探索 .NET 搜尋程式碼。

後續步驟

深入了解要求的構成方式。

在用戶端應用程式中新增自動完成和搜尋建議 (部分機器翻譯)