你当前正在访问 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 门户中的智能体使用的、可复用且具备权限感知能力的知识库。

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

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

先决条件

Azure AI 搜索在任何提供语义排名的地区。
具有语义配置和丰富文本内容的现有搜索索引。
熟悉语义排名。

注意

标题和答案是从搜索文档中的文本逐字提取的。语义子系统使用机器阅读理解来识别具有题注或答案特征的内容，但除查询重写（预览）外，不会生成新的句子或短语。因此，包含解释或定义的内容最适合语义排名。如果要与生成的响应进行聊天式交互，请参阅代理检索或检索扩充生成（RAG）。

选择客户端

可以使用以下任何工具和 SDK 来生成使用语义排名的查询：

Azure门户，使用索引设计器添加语义配置。
Visual Studio Code REST 客户端
适用于 .NET 的 Azure SDK
Python 的 Azure SDK
Azure SDK for Java
适用于 JavaScript 的 Azure 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。如果想要响应中的标题或答案，请通过设置queryTypesemantic或设置semanticQuery和添加对请求的字幕和答案来启用语义排名。

本节中的以下示例使用 hotels-sample 索引演示语义排名，并结合语义答案和说明。

使用 queryType=semantic

如果要设置为queryTypesemantic，请将以下请求粘贴到 Web 客户端中作为模板。 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. 这通过使用在必应语料库上训练的排名模型（以自然语言表示的查询而不是关键字）重新调整前 50 个匹配项，从而提高搜索结果的精度。如果将查询类型设置为语义，则还必须设置 semanticConfiguration。您可以选择设置答案，以便在查询输入采用自然语言（如“什么是...”）时，还返回前 3 个答案。此外，您可以选择设置标题，从排名最高的文档中提取关键段落。
将 search 设置为简单的纯文本查询。由于 queryType 已设置为 semantic，因此不支持简单语法或完整 Lucene 语法。提供*或空字符串不会对查询应用语义排名。
将 semanticConfiguration 设置为嵌入在你的索引中的预定义语义配置。
设置为 answers 指定是否在结果中包含语义答案。此参数 extractive 的有效值为和 none。仅当查询类型为“semantic”时，此参数才有效。当设置为“提取”时，查询从语义排名最高的文档中的关键段落生成并返回答案。默认值为一个答案，但可以通过添加计数来指定最多 10 个答案。例如， "answers": "extractive|count-3" 返回三个答案。若要返回答案，目标字段中必须存在类似于答案的逐字内容。用于答案的语言模型经过训练以识别答案，而不是生成答案。此外，查询本身必须看起来像一个问题。
设置为 captions 指定是否在结果中包含语义标题。有效值为“none”和“extractive”。默认值为“none”。仅当查询类型为“semantic”时，此参数才有效。设置为“提取”时，查询将返回从排名最高的文档中的关键段落中提取的标题。

当字幕设置为“提取”时，默认情况下会启用突出显示，并且可以通过添加管道字符“|”后接选项 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