Important
标记为“预览”的特性、功能或属性不受服务级别协议 (SLA) 保障,不建议用于生产工作负载,并且在正式发布之前可能会更改或受到限制。 Azure AI 搜索预览条款适用于所有预览功能,无论是独立功能还是正式版功能的一部分。
语义排序循环访问初始结果集,应用 L2 排序方法,该方法将语义上最相关的结果提升到堆栈顶部。 还可以获取语义标题,其中突出显示了最相关的术语和短语,以及语义答案。
本文介绍如何配置搜索索引进行语义重新调整。
注释
如果现有代码调用预览版或以前的 API 版本,请参阅迁移语义排名代码,获取有关修改代码的帮助。
先决条件
在提供语义排名的任何区域中使用 Azure AI 搜索。
包含富文本内容的现有搜索索引。 语义排名适用于字符串(非函数)字段,最适合信息性或描述性内容。
在Azure AI 搜索上创建和使用对象的权限。 我们建议 使用基于角色的访问,但如果角色分配不可行,则可以使用 API 密钥 。 有关详细信息,请参阅 “连接到搜索服务”。
搜索服务 REST API 的 2026-08-01-preview 版本。
选择客户端
可以使用以下任何工具和软件开发工具包 (SDK) 添加语义配置,在新索引或现有索引上指定语义配置:
- Azure门户,使用索引设计器添加语义配置。
- Visual Studio CodeREST 客户端和创建或更新索引(REST)API。
- 适用于 .NET 的 Azure SDK
- 适用于 Python 的 Azure SDK
- 适用于 Java 的 Azure SDK
- 适用于 JavaScript 的 Azure SDK
添加语义配置
某些工作负荷会自动创建语义配置。 如果您使用agentic 检索和在Azure AI 搜索中对内容进行索引的knowledge 源,则生成的索引已经拥有适用于您的内容的语义配置。
对于其他工作负荷,可以自行设置语义配置。 语义配置是索引中的一个部分,用于建立用于语义排名的字段输入。 可以随时添加或更新语义配置,而无需重新生成。 如果创建多个配置,可以指定一个默认值。 查询时,在查询请求上指定语义配置,或将其留空以使用默认值。
最多可以在单个索引中创建 100 个语义配置。
语义配置具有一个名称和以下属性:
| 资产 | 特征 |
|---|---|
| “标题”字段 | 一个短字符串,理想情况下少于 25 个单词。 此字段可以是文档的标题、产品名称或唯一标识符。 如果你没有合适的字段,请将其留空。 |
| 内容字段 | 自然语言形式的较长文本块,受机器学习模型的最大标记输入限制的约束。 常见的示例包括文档正文、产品说明或其他自由格式文本。 |
| 关键字字段 | 关键字(例如文档上的标记)的列表,或者项的类别等描述性词语。 |
只能指定一个标题字段,但可以拥有所需任意数量的内容和关键字字段。 对于内容和关键字字段,请按优先级顺序列出字段,因为优先级较低的字段可能会被截断。
在所有语义配置属性中,你分配的字段必须:
- 标记为
searchable和retrievable - 类型为
Edm.String、Collection(Edm.String)的字符串,以及Edm.ComplexType的字符串子字段
请在 Azure 门户中打开您的搜索服务。
从左侧导航窗格中的“索引”中选择一个索引。
选择“语义配置”,然后选择“添加语义配置”。
显示在 Azure 门户中添加语义配置选项的屏幕截图。 在“新建语义配置”页上,输入语义配置名称并选择在语义配置中使用的字段。 只有可搜索和可检索的字符串字段才符合条件。 请确保按优先级顺序列出内容字段和关键字字段。
此截图展示了如何在 Azure 门户中创建语义配置。 选择“保存”,保存配置设置。
在索引页上再次选择保存,以在索引中保存语义配置。
选择启用预发布语义排序模型(预览版)
使用支持该属性的预览版 REST API和预览版 Azure SDK,如果你的区域已部署预发布语义排序模型,则可以选择将索引配置为使用该模型。 没有机制可以知道预发行版是否可用,或者它是否用于特定查询。 出于此原因,我们建议在测试环境中使用此属性,并且仅当你有兴趣尝试最新的语义排名模型时。
配置属性是在 "flightingOptIn": true索引的语义配置部分中设置的。 默认情况下,该属性为 null 或 false。 你可以随时在创建或更新请求上设置它,并且它会影响向前移动的语义查询,前提是查询规定包含该属性的语义配置。
PUT https://myservice.search.azure.cn/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": { }
}
后续步骤
通过运行语义查询来测试语义配置。