在 Azure AI 搜尋服務中為查詢加入語意排名

註

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

如果你的搜尋文件包含字串欄位，且向量查詢在搜尋文件中有文字表示，你可以對文字查詢、混合查詢和向量查詢套用語意排序。

本文說明如何在查詢中調用語意排序器。它假設你使用的是最新的穩定或預覽 API。如需舊版本的協助，請參見「遷移語意排名程式碼」。

先決條件

任何提供語意排序的地區均適用Azure AI 搜尋服務。
一個具有語意配置與富文本內容的現有搜尋索引。
熟悉語意排名。

註

標題與答案皆從搜尋文件中的文字逐字擷取。語意子系統利用機器閱讀理解來辨識具有標題或答案特徵的內容，但除了查詢重寫（預覽）時，不會生成新的句子或片語。因此，包含說明或定義的內容最適合語意排序。如果你想要以聊天方式進行互動並產生回應，請參考Agentic 檢索或檢索增強生成（RAG，檢索輔助生成）。

選擇客戶

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

避免使用繞過相關性評分的功能

部分查詢功能繞過相關性評分，使其與語意排名不相容。如果你的查詢邏輯包含以下特徵，你就無法語意上對結果進行排名：

帶有 search=* 搜尋字串或空的查詢，例如純篩選的查詢，無法運作，因為沒有語意相關性可依據，搜尋分數為零。查詢必須提供可在處理過程中評估的術語或片語，並產生經過相關性評分的搜尋文件。評分結果是語意排序器的輸入。
特定欄位上的排序 (orderBy 子句) 會覆寫搜尋分數和語意分數。既然語意分數應該提供排名，若在有序結果上套用語意排序，加入 orderby 子句會導致 HTTP 400 錯誤。

設定查詢

預設情況下，查詢不使用語意排序。使用語意排序時，可以使用兩種不同的參數。每個參數支援不同的查詢格式。

所有語意查詢，不論是透過 search 加 queryType號或透過 semanticQuery，都必須是純文字，且不能是空的。如你從下表所見，該 queryType-semantic 參數支援部分查詢格式。

參數	純文字搜尋	簡單文字搜尋語法	全文搜尋語法	向量搜尋	混合搜尋	語義回答與字幕
`queryType-semantic` ¹	✅	❌	❌	❌	✅	✅
`semanticQuery="<your plain text query>"` ²	✅	✅	✅	✅	✅	✅

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

² 參數 semanticQuery 可用於所有查詢類型。不過，Azure入口網站Search Explorer 並不支援此功能。

無論選擇哪種參數，索引都應包含具有豐富語意內容及語意配置的文字欄位。

搜尋總管包含語意排序選項。請記得你無法在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。如果你想在回應中新增說明或答案，請透過將 queryType 設定為 semantic 或設定 semanticQuery 並將說明和答案加入到請求中來啟用語意排名。

本節以下範例使用飯店樣本索引，展示語意排名，並附有語意答案與說明。

使用 queryType=semantic

如果你想設定 queryType 為 semantic，將以下請求貼上到網頁客戶端作為範本。用你的搜尋服務名稱替換 search-service-name ，如果有不同的索引名稱就替換 hotels-sample 。

POST https://[search-service-name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-04-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。這透過使用以 Bing 語料庫訓練的排名模型，重新排序前 50 個匹配項，以提升搜尋結果的精確度，這是針對以自然語言表達的查詢進行排序，而不是關鍵字。如果你把查詢類型設為 semantic，也必須設定 semanticConfiguration。如果查詢輸入是使用自然語言（例如「什麼是......」），你可以選擇設定答案以回傳前三名的答案。此外，你也可以選擇設定標題，以便從排名最高的文件中擷取關鍵段落。
設定 search 為一個簡單的純文字查詢。由於queryType被設定為semantic，因此不支援簡單語法或完整 Lucene 語法。提供 * 或空字串則不會對查詢套用語意排序。
設定 semanticConfiguration 為嵌入索引中的預設語意配置。
設定 answers 以指定結果中是否包含語意答案。此參數的有效值為 extractive 和 none。此參數僅在查詢類型為「語意」時有效。當設定為「擷取」時，查詢會從語意排名最高的文件中的關鍵段落中提出並回傳答案。預設是一個答案，但你也可以透過增加計數來指定最多 10 個。例如，"answers": "extractive|count-3" 會返回三個答案。要回傳答案，目標欄位必須有看起來像答案的逐字內容。用於回答的語言模型是訓練來辨識答案，而非生成答案。此外，查詢本身也必須看起來像是一個問題。
設定 captions 為指定結果是否包含語意說明。有效值為「none」和「extractive」。預設為「無」。此參數僅在查詢類型為「語意」時有效。當設定為「擷取」時，查詢會回傳從排名最高文件中關鍵段落擷取的說明文字。

當字幕設定為「擷取式」時，預設會啟用高亮，並可透過加上管道字元 '|' 後接 highlight-<true/false> 選項來設定，例如 extractive|highlight-true。此範例回傳無重點的說明： 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/docs/search?api-version=2026-04-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}");

若要使用 semanticQuery，而不是將 queryType 設為 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"）。提供字幕是由於設定了「captions」屬性，包括純文字版本和帶有標示的版本。如果無法確定答案，則會從回答中省略。為了簡潔起見，此範例僅展示三個答案及三個最高分的查詢結果。

{
  "@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

如果您預期吞吐量需求會接近、達到或高於此水準，請提交支援工單，以便我們為您的工作負載進行配置。

下一步

語意排名可用於結合關鍵字搜尋與向量搜尋的混合查詢，形成單一請求與統一回應。

混合查詢與語意排序

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-07-03