共用方式為

快速入門：使用 .NET 或 Python 進行語意排名

  • 發行項

在 Azure AI 搜尋服務中，語意排名為一項查詢端功能，依據 Microsoft 機器閱讀理解將搜尋結果重新評分，將語意相關性更高的結果移至清單頂端。 依據內容和查詢，語意排名可顯著改善搜尋相關性，且開發人員不需要投入大量心力。

本快速入門會逐步引導您如何修改索引和查詢來叫用語意排名工具。

注意

如需搭配 ChatGPT 互動的 Azure AI 搜尋解決方案範例，請參閱 此示範 或 此加速器。

必要條件

  • 具有有效訂用帳戶的 Azure 帳戶。 您可以免費建立帳戶。

  • 基本層或更高層級的 Azure AI 搜尋資源，已啟用 語意排名器。

  • API 金鑰和搜尋服務端點。 登入 Azure 入口網站，然後尋找您的搜尋服務。

    在 [ 概觀] 中，複製 URL 並加以儲存，以供後續步驟使用。 範例端點看起來會像是 https://mydemo.search.windows.net。

    在 [金鑰] 中，複製並儲存系統管理金鑰，以取得建立和刪除物件的完整權限。 共有兩個可交換的主要和次要金鑰。 選擇任一個。

    顯示搜尋服務 HTTP 端點和存取金鑰位置的螢幕快照。

新增語意排名

若要使用語意排名工具，請將語意設定新增至搜尋索引，然後在查詢中增加參數。 如果已有現有索引，您可進行這些變更，無須針對內容重新編製索引，因為不會影響可搜尋內容的結構。

  • 語意設定會設定欄位的優先順序，包括語意重新排名會使用的標題、關鍵字和內容。 欄位優先順序有助加速處理作業。

  • 叫用語意排名工具的查詢中，參數包括查詢類型以及是否傳回標題和答案。 您可將這些參數增加到現有的查詢邏輯。 不會與其他參數產生衝突。

使用 Azure.Search.Documents 用戶端連結庫建置主控台應用程式，以將語意排名新增至現有的搜尋索引。

或者，您可以 下載原始程式碼 ，以從完成的項目開始。

設定您的環境

  1. 啟動 Visual Studio 並建立主控台應用程式的新專案。

  2. 在 [工具]>[NuGet 套件管理員] 中，選取 [管理解決方案的 NuGet 套件] 中。

  3. 選取瀏覽。

  4. 搜尋 Azure.Search.Documents 套件 ，然後選取最新的穩定版本。

  5. 選取 [安裝] 以將組件新增到您的專案與解決方案。

建立搜尋用戶端

  1. 在 Program.cs 中，新增下列 using 指示詞。

    using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;

  2. 建立兩個用戶端：SearchIndexClient 會建立索引，而 SearchClient 會載入並查詢現有索引。

    這兩個用戶端都需要服務端點和系統管理 API 金鑰，才能使用建立/刪除許可權進行驗證。 不過，程式代碼會為您建置 URI，因此只指定 屬性的 serviceName 搜尋服務名稱。 請勿包含 https:// 或 .search.windows.net。

     static void Main(string[] args)
 {
     string serviceName = "<YOUR-SEARCH-SERVICE-NAME>";
     string apiKey = "<YOUR-SEARCH-ADMIN-API-KEY>";
     string indexName = "hotels-quickstart";


     // Create a SearchIndexClient to send create/delete index commands
     Uri serviceEndpoint = new Uri($"https://{serviceName}.search.windows.net/");
     AzureKeyCredential credential = new AzureKeyCredential(apiKey);
     SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, credential);

     // Create a SearchClient to load and query documents
     SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, credential);
     . . . 
 }

建立索引

建立或更新索引結構描述以納入 SemanticConfiguration。 如果您要更新現有索引，此修改動作不需要重新編製索引，因為文件的結構不會改變。

// Create hotels-quickstart index
private static void CreateIndex(string indexName, SearchIndexClient adminClient)
{

    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);
    definition.SemanticSearch = new SemanticSearch
    {
        Configurations =
        {
            new SemanticConfiguration("my-semantic-config", new()
            {
                TitleField = new SemanticField("HotelName"),
                ContentFields =
                {
                    new SemanticField("Description"),
                    new SemanticField("Description_fr")
                },
                KeywordsFields =
                {
                    new SemanticField("Tags"),
                    new SemanticField("Category")
                }
            })
        }
    };

    adminClient.CreateOrUpdateIndex(definition);
}

下列程式碼會針對您的搜尋服務建立索引：

// Create index
Console.WriteLine("{0}", "Creating index...\n");
CreateIndex(indexName, adminClient);

SearchClient ingesterClient = adminClient.GetSearchClient(indexName);

載入文件

Azure AI 搜尋服務會搜尋服務中儲存的內容。 上傳文件的程式碼與全文檢索搜尋的 C# 快速入門相同，因此不在此重複。 您應備妥四個飯店及其名稱、地址和說明。 您的解決方案應包含飯店類型和地址。

搜尋索引

此查詢會叫用語意排名工具，包括可指定參數的搜尋選項：

Console.WriteLine("Example of a semantic query.");

options = new SearchOptions()
{
    QueryType = Azure.Search.Documents.Models.SearchQueryType.Semantic,
    SemanticSearch = new()
    {
        SemanticConfigurationName = "my-semantic-config",
        QueryCaption = new(QueryCaptionType.Extractive)
    }
};
options.Select.Add("HotelName");
options.Select.Add("Category");
options.Select.Add("Description");

// response = srchclient.Search<Hotel>("*", options);
response = srchclient.Search<Hotel>("what hotel has a good restaurant on site", options);
WriteDocuments(response);

在此比較使用預設 BM25 排名查詢的結果，其以字詞頻率和鄰近性為基礎。 以此查詢 "what hotel has a good restaurant on site" 為例，BM25 排名演算法傳回的相符項目順序如以下螢幕擷取畫面所示：

顯示依 BM25 排名相符項目的螢幕擷取畫面。

相對而言，若相同查詢 ("what hotel has a good restaurant on site") 套用語意排名，則結果會依據查詢的語意相關性重新排名。 在此，第一項結果正是設有餐廳的飯店，更為符合使用者的期望。

顯示根據語意排名排序之相符項目的螢幕擷取畫面。

執行程式

按下 F5 以重建應用程式並完整執行程式。

輸出中包含來自 Console.WriteLine 的訊息，並且會加上查詢資訊和結果。

清除資源

如果您是在自己的訂用帳戶中進行，建議您在專案結束時判斷自己是否仍需要先前所建立的資源。 資源若繼續執行，將需付費。 您可以個別刪除資源，或刪除資源群組以刪除整組資源。

您可以使用左側瀏覽窗格中的 [所有資源] 或 [資源群組] 連結，在 Azure 入口網站 中找到和管理資源。

下一步

本快速入門說明如何針對現有索引叫用語意排名。 下一步，建議您針對自己的索引嘗試語意排名。 若您想繼續觀看其他示範，請造訪下列連結。

教學課程：將搜尋新增至 Web 應用程式