通过

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

快速入门：使用 .NET 或 Python 进行语义排名

  • 项目

在 Azure AI 搜索中，语义排名是查询端功能，它使用 Microsoft 的计算机读取理解对搜索结果进行重新评分，将与语义上最相关的匹配项提升到列表顶部。 根据内容和查询，语义排名可以显著改进搜索相关性，且开发人员的工作最少。

本快速入门将引导你完成调用语义排序器的索引和查询修改。

注意

有关使用 ChatGPT 交互的 Azure AI 搜索解决方案示例，请参阅此演示或此加速器。

先决条件

  • 具有活动订阅的 Azure 帐户。 你可以免费创建一个帐户。

  • Azure AI 搜索资源，位于基本层或更高层级，且已启用语义排序器。

  • API 密钥和搜索服务终结点。 登录到 Azure 门户并查找你的搜索服务。

    在“概述”中，复制 URL 并将其保存，以供后续步骤使用。 示例终结点可能类似于 https://mydemo.search.windows.net。

    在“密钥”中，复制并保存管理密钥，以获取创建和删除对象的完整权限。 有两个可互换的主要密钥和辅助密钥。 选择其中一个。

    显示搜索服务的 HTTP 终结点和访问密钥的位置的屏幕截图。

添加语义排名

要使用语义排序器，请将语义配置添加到搜索索引，并将参数添加到查询。 如果有现有索引，可以进行这些更改，无需重新编制内容索引，因为不会影响可搜索内容的结构。

  • 语义配置为提供在语义重新排名中使用的标题、关键字和内容的字段设置优先级顺序。 字段优先级允许更快的处理。

  • 调用语义排序器的查询包括查询类型以及是否返回字幕和答案的参数。 可以将这些参数添加到现有的查询逻辑。 与其他参数没有冲突。

通过使用 Azure.Search.Documents 客户端库生成控制台应用程序，从而将语义排名添加到现有搜索索引。

或者，可以下载源代码以从完成的项目开始。

设置你的环境

  1. 启动 Visual Studio 并为控制台应用创建新项目。

  2. 在“工具”>“NuGet 包管理器”中，选择“管理解决方案的 NuGet 包...”。

  3. 选择“浏览”。

  4. 搜索 Azure.Search.Documents 包，然后选择最新的稳定版本。

  5. 选择安装”，将该程序集添加到你的项目和解决方案。

创建搜索客户端

  1. 在Program.cs中，添加以下using个指令。

    using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;

  2. 创建两个客户端：SearchIndexClient 创建索引，SearchClient 加载并查询现有索引。

    两个客户端都需要服务终结点和管理员 API 密钥才能使用创建/删除权限进行身份验证。 但是，代码会为你生成 URI，因此请仅指定 serviceName 属性的搜索服务名称。 不要包括 https:// 或 .search.windows.net。

     static void Main(string[] args)
 {
     string serviceName = "<YOUR-SEARCH-SERVICE-NAME>";
     string apiKey = "<YOUR-SEARCH-ADMIN-API-KEY>";
     string indexName = "hotels-quickstart";


     // Create a SearchIndexClient to send create/delete index commands
     Uri serviceEndpoint = new Uri($"https://{serviceName}.search.windows.net/");
     AzureKeyCredential credential = new AzureKeyCredential(apiKey);
     SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, credential);

     // Create a SearchClient to load and query documents
     SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, credential);
     . . . 
 }

创建索引

创建或更新索引架构以包含 SemanticConfiguration。 如果要更新现有索引，此修改无需重新编制索引，因为文档的结构保持不变。

// Create hotels-quickstart index
private static void CreateIndex(string indexName, SearchIndexClient adminClient)
{

    FieldBuilder fieldBuilder = new FieldBuilder();
    var searchFields = fieldBuilder.Build(typeof(Hotel));

    var definition = new SearchIndex(indexName, searchFields);
    var suggester = new SearchSuggester("sg", new[] { "HotelName", "Category", "Address/City", "Address/StateProvince" });
    definition.Suggesters.Add(suggester);
    definition.SemanticSearch = new SemanticSearch
    {
        Configurations =
        {
            new SemanticConfiguration("my-semantic-config", new()
            {
                TitleField = new SemanticField("HotelName"),
                ContentFields =
                {
                    new SemanticField("Description"),
                    new SemanticField("Description_fr")
                },
                KeywordsFields =
                {
                    new SemanticField("Tags"),
                    new SemanticField("Category")
                }
            })
        }
    };

    adminClient.CreateOrUpdateIndex(definition);
}

以下代码在搜索服务上创建索引：

// Create index
Console.WriteLine("{0}", "Creating index...\n");
CreateIndex(indexName, adminClient);

SearchClient ingesterClient = adminClient.GetSearchClient(indexName);

加载文档

Azure AI 搜索对存储在服务中的内容进行搜索。 用于上传文档的代码与全文搜索的 C# 快速入门 相同，因此我们无需在此处复制它。 你应该有四家酒店，其中包含名称、地址和说明。 解决方案应具有“酒店”和“地址”类型。

搜索索引

下面是调用语义排序器的查询，其中包含用于指定参数的搜索选项：

Console.WriteLine("Example of a semantic query.");

options = new SearchOptions()
{
    QueryType = Azure.Search.Documents.Models.SearchQueryType.Semantic,
    SemanticSearch = new()
    {
        SemanticConfigurationName = "my-semantic-config",
        QueryCaption = new(QueryCaptionType.Extractive)
    }
};
options.Select.Add("HotelName");
options.Select.Add("Category");
options.Select.Add("Description");

// response = srchclient.Search<Hotel>("*", options);
response = srchclient.Search<Hotel>("what hotel has a good restaurant on site", options);
WriteDocuments(response);

为了进行比较，下面是基于字词频率和邻近度使用默认 BM25 排名的查询的结果。 给定查询“哪家酒店现场有不错的餐厅”，BM25 排名算法会按以下屏幕截图所示的顺序返回匹配项：

匹配项（按 BM25 排名）的屏幕截图。

相比之下，当语义排名应用于同一查询（“哪家酒店现场有不错的餐厅”）时，结果会根据与查询的语义相关性重新排名。 这一次，最优结果是具有相应餐厅的酒店，这更符合用户期望。

屏幕截图显示按语义排名而排列的匹配项。

运行程序

按 F5 可重新生成应用并完整运行该程序。

输出包含 Console.WriteLine 中的消息，并添加了查询信息和结果。

清理资源

在自己的订阅中操作时，最好在项目结束时确定是否仍需要已创建的资源。 持续运行资源可能会产生费用。 可以逐个删除资源，也可以删除资源组以删除整个资源集。

可以使用左侧导航窗格中的“所有资源”或“资源组”链接 ，在门户中查找和管理资源。

后续步骤

在本快速入门中，你学习了如何对现有索引调用语义排名。 下一步，建议尝试对自己的索引进行语义排名。 但是，如果要继续查看演示，请访问以下链接。

教程：向 Web 应用添加搜索