在 Azure AI 搜尋中將語意排名新增至查詢

發行項
12/10/2024

如果您的搜尋文件包含字串欄位，且向量查詢在搜尋文件具有文字表示法，您可將語意排名套用至文字查詢、混合式查詢和向量查詢。

本文說明如何在查詢上叫語意排名工具。它假設您使用的是最新的穩定或預覽 API。如需舊版的說明，請參閱移轉語意排名程序代碼。

必要條件

使用啟用語意排名工具的搜尋服務、基本階層或更高層級。
具有語意設定和 RTF 內容的現有搜尋索引。
如果您需要功能簡介，請檢閱語意排名。

注意

會從搜尋文件中的文字擷取標題和答案。語意子系統會使用機器閱讀理解來識別具有標題或答案特性的內容，但其不會撰寫新的句子或片語。因此，包含說明或定義的內容最適用於語意排名。如果您要與產生的回應進行聊天樣式互動，請參閱擷取擴增生成 (RAG)。

選擇用戶端

您可以使用下列任何工具和 SDK 來建置使用語意排名的查詢：

避免會略過相關性評分的功能

一些查詢功能會略過相關性評分，這使得其與語意排名不相容。如果您的查詢邏輯包含下列功能，則無法對結果進行語意排名：

具有 search=* 或空白搜尋字串的查詢 (例如純篩選查詢) 將無法運作，因為沒有任何內容可供測量語意相關性，所以搜尋分數為零。查詢必須提供可在處理期間評估的字詞或片語。
針對特定欄位排序 (orderBy 子句) 會覆寫搜尋分數和語意分數。有鑑於語意分數應該會提供排名，若您將語意排名套用至已排序的結果，則新增 orderby 子句會導致 HTTP 400 錯誤。

設定查詢

根據預設，查詢不會使用語意排名。若要使用語意排名，可以使用兩個不同的參數。每個參數都支援一組不同的案例。

語意查詢，無論是透過 search 加號 queryType或透過 semanticQuery指定，都必須是純文本，而且不能是空的。空白查詢不會將語意排名套用至結果。

語意排名器參數	純文本搜尋	簡單文字搜尋語法	全文搜索語法	向量搜尋	混合式搜尋	語意答案和標題
`queryType-semantic`¹	✅	❌	❌	❌	✅	✅
`semanticQuery="<your plain text query>"`²	✅	✅	✅	✅	✅	✅

¹ queryType=semantic 無法支援明確 simple 或 full 值， queryType 因為參數正用於 semantic。有效的查詢行為是簡單剖析器的預設。

² 參數 semanticQuery 可用於所有查詢類型。不過，Azure 入口網站搜尋總管中不支援它。

不論選擇的參數為何，索引都應該包含具有豐富語意內容和語意組態的文字欄位。

搜尋總管包含語意排名選項。回想一下，您無法在 Azure 入口網站中設定 semanticQuery 參數。

登入 Azure 入口網站。
開啟搜尋索引，然後選取 [搜尋總管]。
選取 [查詢選項]。如果您已定義語意設定，則系統預設會選取此設定。如果您還未設定，請為索引建立語意設定。
輸入查詢，例如「提供美食且歷史悠久的酒店」，然後選取 [搜尋]。

或者，選取 [JSON 檢視 ]，並將定義貼到查詢編輯器中。 Azure 入口網站不支援使用 semanticQuery，因此需要將設定queryType為"semantic"：

將查詢類型設定為語意的 JSON 範例，您可以貼到檢視中：

{
  "search": "funky or interesting hotel with good food on site",
  "count": true,
  "queryType": "semantic",
  "semanticConfiguration": "my-semantic-config",
  "captions": "extractive|highlight-true",
  "answers": "extractive|count-3",
  "highlightPreTag": "<strong>",
  "highlightPostTag": "</strong>",
  "select": "HotelId,HotelName,Description,Category"
}

使用搜尋文件來制定要求。

回應會自動包含 @search.rerankerScore。如果您想要回應中的標題或答案，請藉由設定queryTypesemantic或設定和新增標題和答案來啟用semanticQuery語意排名。

本節中的下列範例會使用 hotels-sample-index 來示範語意答案和標題的語意排名。

使用 queryType=semantic

如果您想要將設定 queryType 為 semantic，請將下列要求貼到 Web 用戶端作為範本。以您的搜尋服務名稱取代 search-service-name ，如果您有不同的索引名稱，請取代 hotels-sample-index 。

POST https://[search-service-name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
      "search": "interesting hotel with restaurant on site and cozy lobby or shared area",
      "count": true,
      "queryType": "semantic",
      "semanticConfiguration": "semantic-config",
      "captions": "extractive|highlight-true",
      "answers": "extractive|count-3",
      "highlightPreTag": "<strong>",
      "highlightPostTag": "</strong>",
      "select": "HotelId,HotelName,Description,Category"
}

將 queryType 設定為 semantic。
設定 search 為簡單的純文本查詢。 queryType由於設定為 semantic，因此不支援簡單語法或完整的 Lucene 語法。 *提供或空字串會導致未將語意排名套用至查詢。
設定 semanticConfiguration 為內嵌在索引中的預先定義語意組態。
設定 answers 以指定結果中是否包含語意答案。此參數目前唯一有效的值是 extractive。答案可以設定為傳回最多 10 個項目。預設值為一個。此範例顯示三個答案的計數：extractive|count-3。

無法保證每個要求都會有答案。若要取得答案，查詢必須看似像問題，內容也必須包含看似像答案的文字。
設定 captions 以指定結果中是否包含語意標題。此參數目前唯一有效的值是 extractive。標題可以設定為傳回具有或不含反白顯示的結果。預設值是傳回反白顯示。此範例會傳回不含反白顯示的標題：extractive|highlight-false。

標題和答案的基礎是 "semanticConfiguration" 中所參考的欄位。這些欄位的組合限制為 2,000 個語彙基元或大約 20,000 個字元。如果您預期語彙基元計數會超過此限制，請考慮使用文字分割技能執行資料區塊化步驟。這種方法帶來對 AI 擴充管線和索引子的相依性。
設定 highlightPreTag ， highlightPostTag 如果您想要覆寫套用至標題的預設醒目提示格式設定。

標題會將白顯示格式套用至文件中摘要回應的主要段落。預設值為 <em>。如果您想要指定格式設定的類型 (例如黃色背景)，您可以設定 highlightPreTag 和 highlightPostTag。
設定 select 以指定回應中傳回哪些欄位，而「count」則會傳回索引中的相符項目數目。這些參數可改善要求的品質，以及回應的可讀性。
傳送要求以執行查詢並傳回結果。

使用 semanticQuery

藉由使用 semanticQuery，您可以明確套用簡單文字語法或全文檢索語法，這表示您現在可以進行欄位搜尋、詞彙提升和鄰近搜尋。您也可以指定純向量查詢，而不只是混合式查詢。

將要求調整為下列 JSON 以使用 semanticQuery。

POST https://[search-service-name].search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "Description:breakfast",
    "semanticQuery": "interesting hotel with restaurant on site and cozy lobby or shared area",
    "count": true,
    "queryType": "full",
    "semanticConfiguration": "semantic-config",
    "captions": "extractive|highlight-true",
    "answers": "extractive|count-3",
    "highlightPreTag": "<strong>",
    "highlightPostTag": "</strong>",
    "select": "HotelId,HotelName,Description,Category"
}

設定 queryType 為您使用的搜尋語法，可以是簡單或完整。
設定 semanticQuery 為您想要用於語意排名的簡單純文本查詢。不支援空白查詢。請避免字串本身內的運算符或任何查詢語法。

使用 QueryType 或 SemanticQuery 針對語意查詢叫用語意排名工具。下列範例來自 Azure SDK 小組。

SearchResults<Hotel> response = await searchClient.SearchAsync<Hotel>(
    "interesting hotel with restaurant on site and cozy lobby or shared area",
    new SearchOptions
    {
        SemanticSearch = new()
        {
            SemanticConfigurationName = "my-semantic-config",
            QueryCaption = new(QueryCaptionType.Extractive),
            QueryAnswer = new(QueryAnswerType.Extractive)
        },
        QueryType = SearchQueryType.Semantic
    });

int count = 0;
Console.WriteLine($"Semantic Search Results:");

Console.WriteLine($"\nQuery Answer:");
foreach (QueryAnswerResult result in response.SemanticSearch.Answers)
{
    Console.WriteLine($"Answer Highlights: {result.Highlights}");
    Console.WriteLine($"Answer Text: {result.Text}");
}

await foreach (SearchResult<Hotel> result in response.GetResultsAsync())
{
    count++;
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.HotelId}: {doc.HotelName}");

    if (result.SemanticSearch.Captions != null)
    {
        var caption = result.SemanticSearch.Captions.FirstOrDefault();
        if (caption.Highlights != null && caption.Highlights != "")
        {
            Console.WriteLine($"Caption Highlights: {caption.Highlights}");
        }
        else
        {
            Console.WriteLine($"Caption Text: {caption.Text}");
        }
    }
}
Console.WriteLine($"Total number of search results:{count}");

若要使用，而不是將設定semanticQueryqueryType為 semantic，搜尋代碼段可以取代為下列代碼段：

SearchResults<Hotel> response = await searchClient.SearchAsync<Hotel>(
    "Luxury hotel",
    new SearchOptions
    {
        SemanticSearch = new()
        {
            SemanticConfigurationName = "my-semantic-config",
            QueryCaption = new(QueryCaptionType.Extractive),
            QueryAnswer = new(QueryAnswerType.Extractive),
            SemanticQuery = "Is there any hotel located on the main commercial artery of the city in the heart of New York?"
        }
    });

評估回應

只有來自初始結果的前 50 個相符項目可以以語意方式設定優先順位。如同所有查詢項目，回應是由標示為可擷取的所有欄位所組成，或只包含 select 參數中列出的欄位。回應包含原始相關性分數，也可能包含計數或批次結果，視您制定要求的方式而定。

在語意排名中，回應具有更多元素：新的語意排名相關性分數、純文字中的選擇性標題、醒目提示，以及選擇性答案。如果您的結果未包含這些額外的元素，則您的查詢可能設定不正確。第一個步驟是針對問題進行疑難排解，請檢查語意設定，以確保在索引定義和查詢中都有指定該語意設定。

在用戶端應用程式中，您可以建構搜尋分頁，包含標題作為相符項目的說明，而不是特定欄位的整個內容。當個別欄位對搜尋結果分頁而言太密集時，此方法很有用。

上述範例查詢的回應（“現場有餐廳的有趣酒店和舒適的大廳或共用區域”）會傳回三個答案（"answers": "extractive|count-e"）。系統會傳回標題，因為已設定「標題」屬性，且具有純文字和反白顯示的版本。如果無法判斷答案，則會從回應中省略。為了簡潔起見，此範例只會顯示查詢中的三個答案和三個最高評分結果。

{
  "@odata.count": 29,
  "@search.answers": [
    {
      "key": "24",
      "text": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
      "highlights": "Chic hotel near the city. <strong>High-rise hotel in downtown, </strong>within<strong> walking distance to </strong>theaters, art<strong> galleries, restaurants and shops.</strong> Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
      "score": 0.9340000152587891
    },
    {
      "key": "40",
      "text": "Only 8 miles from Downtown. On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, All non-smoking hotel. Only 15 miles from airport.",
      "highlights": "Only 8 miles from Downtown. <strong>On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, </strong>All non-smoking<strong> hotel.</strong> Only 15 miles from airport.",
      "score": 0.9210000038146973
    },
    {
      "key": "38",
      "text": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "highlights": "Nature is Home on the beach. Explore the shore by day, and then come home to our<strong> shared living space </strong>to relax around a stone fireplace, sip something warm, and explore the library by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "score": 0.9200000166893005
    }
  ],
  "value": [
    {
      "@search.score": 3.2328331,
      "@search.rerankerScore": 2.575303316116333,
      "@search.captions": [
        {
          "text": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a complimentary continental breakfast in the lobby, and free Wi-Fi throughout the hotel.",
          "highlights": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our<strong> penthouse </strong>suites offer views for miles and the rooftop<strong> plaza </strong>is open to all guests from sunset to 10 p.m. Enjoy a<strong> complimentary continental breakfast in the lobby, </strong>and free Wi-Fi<strong> throughout </strong>the hotel."
        }
      ],
      "HotelId": "50",
      "HotelName": "Head Wind Resort",
      "Description": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a complimentary continental breakfast in the lobby, and free Wi-Fi throughout the hotel.",
      "Category": "Suite"
    },
    {
      "@search.score": 0.632956,
      "@search.rerankerScore": 2.5425150394439697,
      "@search.captions": [
        {
          "text": "Every stay starts with a warm cookie. Amenities like the Counting Sheep sleep experience, our Wake-up glorious breakfast buffet and spacious workout facilities await.",
          "highlights": "Every stay starts with a warm cookie. Amenities like the<strong> Counting Sheep sleep experience, </strong>our<strong> Wake-up glorious breakfast buffet and spacious workout facilities </strong>await."
        }
      ],
      "HotelId": "34",
      "HotelName": "Lakefront Captain Inn",
      "Description": "Every stay starts with a warm cookie. Amenities like the Counting Sheep sleep experience, our Wake-up glorious breakfast buffet and spacious workout facilities await.",
      "Category": "Budget"
    },
    {
      "@search.score": 3.7076726,
      "@search.rerankerScore": 2.4554927349090576,
      "@search.captions": [
        {
          "text": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
          "highlights": "Chic hotel near the city. <strong>High-rise hotel in downtown, </strong>within<strong> walking distance to </strong>theaters, art<strong> galleries, restaurants and shops.</strong> Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
        }
      ],
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel",
      "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
      "Category": "Suite"
    },
   . . .
  ]
}

預期的工作負載

針對語意排名，您應該預期搜尋服務支援每個複本最多 10 個同時查詢。

如果磁碟區太高，服務會節流語意排名要求。包含這些片語的錯誤訊息表示服務具有語意排名的容量：

Error in search query: Operation returned an invalid status 'Partial Content'`
@search.semanticPartialResponseReason`
CapacityOverloaded

如果您預期輸送量需求接近、位於或高於此層級，請提出支援票證，以便我們可以為您的工作負載佈建。

下一步

語意排名可用於混合式查詢，將關鍵詞搜尋和向量搜尋合併為單一要求和統一回應。

使用語意排名工具的混合式查詢

共用方式為