你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

在 Azure AI 搜索中使用语义排名器重写查询（预览版）

注意

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。它也是 Foundry IQ 的基础；Foundry IQ 是一个托管式知识层，可将企业内容转化为供 Microsoft Foundry 门户中的智能体使用的、可复用且具备权限感知能力的知识库。

重要

标记为“预览”的特性、功能或属性不受服务级别协议 (SLA) 保障，不建议用于生产工作负载，并且在正式发布之前可能会更改或受到限制。 Azure AI 搜索预览条款适用于所有预览功能，无论是独立功能还是正式版功能的一部分。

查询重写（预览版）是将用户的查询转换为更有效的查询的过程，添加更多字词并优化搜索结果。搜索服务将搜索查询（或它的变体）发送到生成替代查询的生成模型。

查询重写通过纠正用户查询中的拼写错误和扩展同义词来优化语义排名的结果。

使用查询重写进行搜索的工作原理如下：

用户查询通过 search 请求中的属性发送。
搜索服务将搜索查询（或它的变体）发送到生成替代查询的生成模型。
搜索服务使用原始查询和重写的查询来检索搜索结果。

查询重写是一项可选功能。如果不重写查询，搜索服务只需使用原始查询来检索搜索结果。

注意

重写的查询可能不包含原始查询拥有的所有确切术语。如果查询非常具体并且需要与唯一标识符或产品代码完全匹配，可能会影响搜索结果。

先决条件

Azure AI 搜索在任何提供查询重写的区域中。
具有语义配置和丰富文本内容的现有搜索索引。本指南中的示例使用 hotels-sample 索引来演示查询重写。
若要按照本文中的说明操作，需要支持 REST API 请求的 Web 客户端。本文中的示例已使用 Visual Studio Code 和 REST Client 扩展进行测试。

提示

包含解释或定义的内容最适合语义排名。

使用查询重写发出搜索请求

在此 REST API 示例中，使用搜索文档（预览版）来表述请求。

将以下请求粘贴到 Web 客户端中作为模板。
```
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”设置为全文搜索查询。除非指定矢量查询，否则查询重写需要搜索属性。如果指定矢量查询，则“search”文本必须与对象的属性"text"匹配"vectorQueries"。搜索字符串可以支持简单语法或完整的 Lucene 语法。
- 将“semanticConfiguration”设置为索引中嵌入的预定义语义配置。
- 将“queryType”设置为“semantic”。您需要将“queryType”设置为“semantic”，或者在请求中包含一个不为空的“semanticQuery”属性。语义排名是实现查询重写所必需的。
- 将“queryRewrites”设置为“generative|count-5”，以获取最多 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"用于测试目的。" 为了提高性能，请勿在生产环境中进行调试。
- 将“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”。
“text”值与“search”值相同。若要使查询重写正常工作，这些值必须相同。

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" 是可选的，用于测试目的。为了获得更好的性能，请勿在生产环境中设置此属性。

部分响应原因

你可能会发现调试（test）响应的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 值为“Transient”的属性。此消息表示至少有一个查询无法完成。
响应还包括 @search.semanticQueryRewriteResultType 值为“OriginalQueryOnly”的属性。此消息表示查询重写不可用。仅使用原始查询来检索搜索结果。

后续步骤

语义排名可用于将关键字搜索和矢量搜索合并到单个请求和统一响应的混合查询中。

具有语义排名器的混合查询

反馈

此页面是否有帮助？

Last updated on 2026-09-17