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

在搜索结果中配置语义排名器并返回标题

注意

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

重要

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

语义排名循环访问初始结果集，应用 L2 排名方法，该方法将最语义上相关的结果提升到堆栈顶部。还可以获取语义标题，其中突出显示了最相关的术语和短语以及语义答案。

本文介绍如何配置搜索索引进行语义重新调整。

注意

如果现有代码调用预览版或以前的 API 版本，请参阅 Migrate 语义排名代码，获取有关修改代码的帮助。

先决条件

在任何提供语义排名的区域中使用Azure AI 搜索。
包含富文本内容的现有搜索索引。语义排名适用于字符串（非函数）字段，最适合信息性或描述性内容。
在Azure AI 搜索上创建和使用对象的权限。我们建议使用基于角色的访问，但如果角色分配不可行，则可以使用 API 密钥。有关详细信息，请参阅 “连接到搜索服务”。
搜索服务 REST API 的 2026-08-01-preview 版本。

选择客户端

可以使用以下任何工具和软件开发工具包（SDK）在新的索引或现有索引上指定语义配置，以添加语义配置：

Azure门户，使用索引设计器添加语义配置。
Visual Studio Code REST 客户端和创建或更新索引（REST）API。
适用于 .NET 的 Azure SDK
Python 的 Azure SDK
Azure SDK for Java
适用于 JavaScript 的 Azure SDK

添加语义配置

某些工作负荷会自动创建语义配置。如果你使用智能体检索和在 Azure AI 搜索上进行索引的知识源，那么生成的索引已经具有适合内容的语义配置。

Tip

从 2026-05-01-preview API 版本开始，支持的代理检索知识库流不需要显式语义配置。此异常不适用于经典语义排名查询或较旧的 API 版本。有关详细信息，请参阅创建搜索索引知识源。

对于其他工作负荷，可以自行设置语义配置。 语义配置是索引中的一个部分，用于建立用于语义排名的字段输入。可以随时添加或更新语义配置，无需重新生成。如果创建多个配置，可以指定默认值。在查询时，在查询请求上指定语义配置，或将其留空以使用默认值。

最多可以在单个索引中创建 100 个语义配置。

语义配置具有名称和以下属性：

财产	特征
标题字段	理想情况下，短字符串应该少于 25 个单词。此字段可以是文档的标题、产品的名称或唯一标识符。如果没有合适的字段，请将其留空。
内容字段	采用自然语言形式的较长文本区块，受机器学习模型的最大令牌输入限制的约束。常见示例包括文档正文、产品说明或其他自由格式文本。
关键字字段	关键字列表（如文档上的标记）或描述性术语（如项的类别）。

只能指定一个标题字段，但可以具有任意数量的内容和关键字字段。对于内容和关键字字段，按优先级顺序列出字段，因为优先级较低的字段可能会截断。

在所有语义配置属性中，分配的字段必须是：

被标记为 searchable 和 retrievable
是 Edm.String 或 Collection(Edm.String) 类型的字符串。Edm.ComplexType 的字符串子字段

在 Azure 门户中转到你的搜索服务。
在左侧导航窗格的 “索引 ”中，选择一个索引。
选择 语义配置 ，然后选择 “添加语义配置”。

显示了在 Azure portal 中添加语义配置选项的截图。
在 “新建语义配置 ”页上，输入语义配置名称，然后选择在语义配置中使用的字段。只有可搜索和可检索的字符串字段才符合条件。请确保按优先级顺序列出内容字段和关键字字段。

展示如何在 Azure 门户中创建语义配置的屏幕截图。
选择 “保存” 以保存配置设置。
在索引页上再次选择“ 保存 ”，以在索引中保存语义配置。

制定创建或更新索引请求。

将语义配置添加到索引定义，或许在scoringProfiles或suggesters之后。如果有多个配置，则指定默认值是可选的，但很有用。

"semantic": {
    "defaultConfiguration": "my-semantic-config-default",
    "configurations": [
        {
            "name": "my-semantic-config-default",
            "prioritizedFields": {
                "titleField": {
                    "fieldName": "HotelName"
                },
                "prioritizedContentFields": [
                    {
                        "fieldName": "Description"
                    }
                ],
                "prioritizedKeywordsFields": [
                    {
                        "fieldName": "Tags"
                    }
                ]
            }
        },
                    {
            "name": "my-semantic-config-desc-only",
            "prioritizedFields": {
                "prioritizedContentFields": [
                    {
                        "fieldName": "Description"
                    }
                ]
            }
        }
    ]
}

在 Azure .NET SDK 中使用 SemanticConfiguration 类。

以下示例来自Azure SDK团队创作的 semantic 排名示例。

string indexName = "hotel";
SearchIndex searchIndex = new(indexName)
{
    Fields =
    {
        new SimpleField("HotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true, IsFacetable = true },
        new SearchableField("HotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("Description") { IsFilterable = true },
        new SearchableField("Category") { IsFilterable = true, IsSortable = true, IsFacetable = true },
    },
    SemanticSearch = new()
    {
        Configurations =
        {
            new SemanticConfiguration("my-semantic-config", new()
            {
                TitleField = new SemanticField("HotelName"),
                ContentFields =
                {
                    new SemanticField("Description")
                },
                KeywordsFields =
                {
                    new SemanticField("Category")
                }
            })
        }
    }
};

选择启用预发布语义排序模型（预览版）

使用支持该属性的预览版 REST API和预览版 Azure SDK，如果你的区域已部署预发布语义排序模型，则可以选择将索引配置为使用该模型。没有机制可以知道预发行版是否可用，或者它是否用于特定查询。出于此原因，我们建议在测试环境中使用此属性，并且仅当你有兴趣尝试最新的语义排名模型时。

配置属性是在 "flightingOptIn": true索引的语义配置部分中设置的。默认情况下，该属性为 null 或 false。你可以随时在创建或更新请求上设置它，并且它会影响向前移动的语义查询，前提是查询规定包含该属性的语义配置。

PUT https://myservice.search.windows.net/indexes('hotels')?allowIndexDowntime=False&api-version=2026-08-01-preview

{
  "name": "hotels",
  "fields": [ ],
  "scoringProfiles": [ ],
  "defaultScoringProfile": "geo",
  "suggesters": [ ],
  "analyzers": [ ],
  "corsOptions": { },
  "encryptionKey": { },
  "similarity": { },
  "semantic": {
    "configurations": [
      {
        "name": "semanticHotels",
        "prioritizedFields": {
          "titleField": {
            "fieldName": "hotelName"
          },
        "prioritizedContentFields": [
            {
              "fieldName": "description"
            },
            {
              "fieldName": "description_fr"
            }
          ],
        "prioritizedKeywordsFields": [
            {
              "fieldName": "tags"
            },
            {
              "fieldName": "category"
            }
          ],
        "flightingOptIn": true
        }
      }
    ]
  },
  "vectorSearch": {  }
}

后续步骤

通过运行语义查询来测试语义配置。

创建语义查询

反馈

此页面是否有帮助？

Last updated on 2026-09-17