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

将语义排名添加到 Azure AI 搜索中的查询

项目
12/10/2024

如果搜索文档包含字符串字段，并且搜索文档中的矢量查询具有文本表示形式，可以将语义排序应用于文本查询、混合查询和矢量查询。

本文介绍了如何对查询调用语义排序器。它假定你使用的是最新的稳定 API 或预览 API。有关较旧版本的帮助，请参阅“迁移语义排名代码”。

先决条件

一项搜索服务，位于基本层或更高层级，且已启用语义排序器。
具有语义配置的现有搜索索引和富文本内容。
如果需要该功能的简介，请查看语义排名。

注意

标题和答案会从搜索文档的文本中逐字提取。语义子系统使用计算机阅读理解来识别具有标题或答案特征的内容，但不会撰写新句子或短语。出于此原因，包含解释或定义的内容最适用于语义排名。如果希望与生成的响应进行聊天式交互，请参阅检索增强生成 (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 门户中设置 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 并添加对请求的标题和答案来启用语义排名。

本部分中的以下示例使用 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 个。默认值为 1。此示例显示了三个答案的计数：extractive|count-3。

不能保证每个请求都能得到答案。要获取答案，查询必须类似于问题，并且内容必须包含类似于答案的文本。
设置 captions 以指定结果中是否包含语义标题。目前，此参数唯一的有效值为 extractive。标题可配置为在带或不带突出显示效果的情况下返回结果。默认设置是返回突出显示效果。此示例返回不带突出显示效果的标题：extractive|highlight-false。

标题和答案的基础是“semanticConfiguration”中引用的字段。这些字段处于一个组合限制之下：不得超出 2000 个标记或大约 20000 个字符。如果预计标记计数超过此限制，请考虑执行一个使用文本拆分技能的数据分块步骤。此方法引入了对 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}");

若要使用 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

如果预计一致的吞吐量要求接近、达到或高于此级别，请提交支持票证，以便我们可以为工作负荷预配。

后续步骤

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

使用语义排序器的混合查询

通过