在 Azure AI 搜尋服務中使用語意排序器重寫查詢（預覽）

註

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

Important

標記（預覽）的功能、能力或屬性不受服務等級協議涵蓋，也不建議用於生產工作負載，且在正式上架前可能會有所變動或受限。 Azure AI 搜尋服務預覽條款適用於所有預覽功能，無論是獨立功能還是正式推出功能的一部分。

查詢重寫（預覽）是將使用者的查詢轉化為更有效率的過程，新增更多詞彙並精煉搜尋結果。搜尋服務會將搜尋查詢（或其變體）傳送給生成模型，該模型會產生替代查詢。

查詢重寫透過修正使用者查詢中的錯字或拼字錯誤，以及擴充帶有同義詞的查詢，來提升語意排名的結果。

搜尋與查詢重寫的運作方式如下：

使用者查詢是透過 search 請求中的屬性傳送的。
搜尋服務會將搜尋查詢（或其變體）傳送給生成模型，該模型會產生替代查詢。
搜尋服務會使用原始查詢與重寫的查詢來取得搜尋結果。

查詢重寫是可選功能。搜尋服務無需重寫查詢，僅使用原始查詢來取得搜尋結果。

註

重寫的查詢可能不包含原始查詢中所有相同的詞彙。若查詢非常具體且需精確匹配唯一識別碼或產品代碼，這可能會影響搜尋結果。

先決條件

提供查詢重寫的任何區域中的 Azure AI 搜尋服務。
一個具有語意配置與富文本內容的現有搜尋索引。本指南中的範例使用 hotels-sample index 來示範查詢重寫。
要依照本文說明操作，你需要一個支援 REST API 請求的網頁客戶端。本文中的範例是用 Visual Studio Code 以及 REST Client 擴充功能進行測試的。

提示

包含說明或定義的內容最適合語意排序。

使用查詢重寫提出搜尋要求

在這個 REST API 範例中，請使用 Search Documents（預覽）來表達請求。

將以下請求貼入網頁客戶端作為範本。
```
POST https://[search-service-name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-08-01-preview
{
    "search": "newer hotel near the water with a great restaurant",
    "semanticConfiguration":"en-semantic-config",
    "queryType":"semantic",
    "queryRewrites":"generative|count-5",
    "queryLanguage":"en-US",
    "debug":"queryRewrites",
    "top": 1
}
```
- 請用你的搜尋服務名稱來取代 search-service-name 。
- 如果你的索引名稱不同，請將 hotels-sample 替換為你的索引名稱。
- 將「search」設為全文搜尋查詢。搜尋屬性是查詢重寫所必需的，除非你指定向量查詢。如果你指定向量查詢，那麼「搜尋」文字必須與 "text" 物件的 "vectorQueries" 屬性相符。你的搜尋字串可以支援簡單語法或完整的 Lucene 語法。
- 將「semanticConfiguration」設為嵌入索引中的預設語意配置。
- 將「queryType」設為「semantic」。你需要將「queryType」設為「semantic」，或在請求中加入非空的「semanticQuery」屬性。進行重寫查詢時需要語意排名。
- 將「queryRewrites」設為「generative|count-5」，最多可獲得五次查詢重寫。你可以把計數設定在1到10之間的任何數值。
- 既然你是透過設定「queryRewrites」屬性來請求查詢重寫，你必須將「queryLanguage」設為搜尋文字語言。搜尋服務在查詢重寫時使用相同的語言。在這個例子中，你使用了「en-US」。支援的語系包括：en-AU, en-CA, en-GB, en-IN, en-US, ar-EG, ar-JO, ar-KW, ar-MA, ar-SA, bg-BG, bn-IN, ca-ES, cs-CZ, da-DK, de-DE, el-GR, es-ES, es-MX, et-EE, eu-ES, fa-AE, fi-FI, fr-CA, fr-FR, ga-IE, gl-ES, gu-IN, he-IL, hi-IN, hr-BA, hr-HR, hu-HU, hy-AM, id-ID, is-IS, it-IT, ja-JP, kn-IN, ko-KR, lt-LT, lv-LV, ml-IN, mr-IN, ms-BN, ms-MY, nb-NO, nl-BE, nl-NL, no-NO, pa-IN, pl-PL, pt-BR, pt-PT, ro-RO, ru-RU, sk-SK, sl-SL, sr-BA, sr-ME, sr-RS, sv-SE, ta-IN, te-IN, th-TH, tr-TR, uk-UA, ur-PK, vi-VN, zh-CN, zh-TW。
- 將「debug」設為「queryRewrites」，即可在回應內容中取得查詢重寫。
  
  提示
  
  只設 "debug": "queryRewrites" 為測試用途。為了提升效能，不要在生產環境中使用 debug。
- 將「top」設為 1，只回傳最熱門的搜尋結果。
發送請求執行查詢並回傳結果。

接著，你要評估透過查詢重寫後的搜尋結果。

評估回應

這裡有一個包含查詢重寫的回應範例：

"@search.debug": {
  "semantic": null,
  "queryRewrites": {
    "text": {
      "inputQuery": "newer hotel near the water with a great restaurant",
      "rewrites": [
        "new waterfront hotels with top-rated eateries",
        "new waterfront hotels with top-rated restaurants",
        "new waterfront hotels with excellent dining",
        "new waterfront hotels with top-rated dining",
        "new water-side hotels with top-rated restaurants"
      ]
    },
    "vectors": []
  }
},
"value": [
  {
    "@search.score": 58.992092,
    "@search.rerankerScore": 2.815633535385132,
    "HotelId": "18",
    "HotelName": "Ocean Water Resort & Spa",
    "Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
    "Description_fr": "Nouvel h\u00f4tel de luxe pour des vacances inoubliables. Vue sur la baie depuis chaque chambre, emplacement pr\u00e8s de la jet\u00e9e, piscine sur le toit, restaurant au bord de l'eau et plus encore.",
    "Category": "Luxury",
    "Tags": [
      "view",
      "pool",
      "restaurant"
    ],
    "ParkingIncluded": true,
    "LastRenovationDate": "2020-11-14T00:00:00Z",
    "Rating": 4.2,
    "Location": {
      "type": "Point",
      "coordinates": [
        -82.537735,
        27.943701
      ],
      "crs": {
        "type": "name",
        "properties": {
          "name": "EPSG:4326"
        }
      }
    },
    //... more properties redacted for brevity
  }
]

以下是一些重點需要注意：

因為你把「debug」屬性設為「queryRewrites」來測試，回應會包含 @search.debug 一個包含文字輸入查詢和查詢重寫的物件。
因為你把「queryRewrites」屬性設為「generative|count-5」，回應最多包含五次查詢重寫。
"inputQuery" 值是傳送至生成式模型以進行查詢重寫的查詢。輸入查詢不一定和使用者的 "search" 查詢相同。

這裡有一個沒有查詢重寫的回應範例。

"@search.debug": {
  "semantic": null,
  "queryRewrites": {
    "text": {
      "inputQuery": "",
      "rewrites": []
    },
    "vectors": []
  }
},
"value": [
  {
    "@search.score": 7.774868,
    "@search.rerankerScore": 2.815633535385132,
    "HotelId": "18",
    "HotelName": "Ocean Water Resort & Spa",
    "Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
    "Description_fr": "Nouvel h\u00f4tel de luxe pour des vacances inoubliables. Vue sur la baie depuis chaque chambre, emplacement pr\u00e8s de la jet\u00e9e, piscine sur le toit, restaurant au bord de l'eau et plus encore.",
    "Category": "Luxury",
    "Tags": [
      "view",
      "pool",
      "restaurant"
    ],
    "ParkingIncluded": true,
    "LastRenovationDate": "2020-11-14T00:00:00Z",
    "Rating": 4.2,
    "Location": {
      "type": "Point",
      "coordinates": [
        -82.537735,
        27.943701
      ],
      "crs": {
        "type": "name",
        "properties": {
          "name": "EPSG:4326"
        }
      }
    },
    //... more properties redacted for brevity
  }
]

使用查詢重寫的向量查詢

你可以在搜尋請求中加入向量查詢，將關鍵字搜尋與向量搜尋結合成單一請求與統一回應。

這裡有一個包含向量查詢並進行查詢重寫的查詢範例。修改先前的範例，加入向量查詢。

在請求中加入一個「vectorQueries」物件。此物件包含一個向量查詢，並將「kind」設為「text」。
「文字」值和「搜尋」值是一樣的。這些值必須相同，查詢重寫才能有效。

POST https://[search-service-name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2026-08-01-preview
{
    "search": "newer hotel near the water with a great restaurant",
    "vectorQueries": [
        {
            "kind": "text",
            "text": "newer hotel near the water with a great restaurant",
            "k": 50,
            "fields": "Description",
            "queryRewrites": "generative|count-3"
        }
    ],
    "semanticConfiguration":"en-semantic-config",
    "queryType":"semantic",
    "queryRewrites":"generative|count-5",
    "queryLanguage":"en-US",
    "top": 1
}

回應包含文字查詢與向量查詢的重寫。

使用除錯功能測試查詢重寫

你應該測試你的查詢重寫，確保它們如預期般運作。在查詢要求中設定 "debug": "queryRewrites" 屬性，以在回應中取得查詢重寫。為測試目的，設定 "debug" 是可選的。為了提升效能，不要在生產環境中設置此屬性。

部分反應原因

你可能會注意到，除錯（測試）回應中，text.rewrites 和 vectors 屬性包含一個空陣列。

{
  "@odata.context": "https://demo-search-svc.search.windows.net/indexes('hotels-sample')/$metadata#docs(*)",
  "@search.debug": {
    "semantic": null,
    "queryRewrites": {
      "text": {
        "rewrites": []
      },
      "vectors": []
    }
  },
  "@search.semanticPartialResponseReason": "Transient",
  "@search.semanticQueryRewriteResultType": "OriginalQueryOnly",
  //... more properties redacted for brevity
}

在前述例子中：

回應包含 @search.semanticPartialResponseReason 一個屬性，值為「暫時性」。此訊息表示至少有一個查詢未完成。
回應中也包含 @search.semanticQueryRewriteResultType 一個屬性，值為「OriginalQueryOnly」。此訊息表示查詢重寫不可用。只有原始查詢會用來取得搜尋結果。

下一步

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

混合查詢與語意排序

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-17