Azure.Search.Documents 11.6.0

Azure AI Search 客户端库，适用于 .NET

Azure AI Search（之前称为“Azure 智能搜索”）是一个 AI 驱动的信息检索平台，帮助开发者构建丰富的搜索体验和结合大型语言模型与企业数据的生成式 AI 应用。

Azure AI Search 服务非常适合以下应用场景

• 将各种内容类型合并到单个可搜索索引中。要填充索引，您可以推送包含内容 JSON 文档，或者如果数据已经在 Azure 中，则创建索引器以自动拉入数据。
• 将技能集附加到索引器，以从图片和无结构文档中创建可搜索内容。技能集利用 Azure AI 服务的 API，包括内置的 OCR、实体识别、关键词提取、语言检测、文本翻译和情感分析。您还可以添加自定义技能，以在数据摄取期间集成外部处理您的内容的处理。
• 在搜索客户端应用程序中实现类似于商业网络搜索引擎和聊天应用程序的查询逻辑和用户体验。

使用 Azure.Search.Documents 客户端库来

• 通过向量、关键字和混合查询形式提交查询。
• 实现针对元数据、地理空间搜索、分面导航或基于筛选条件的查询。
• 创建和管理搜索索引。
• 上传和更新搜索索引中的文档。
• 创建和管理索引器，从 Azure 中提取数据到索引。
• 创建和管理用于数据摄取中添加人工智能增强的技能集。
• 创建和管理用于高级文本分析或多语言内容的分析器。
• 通过语义排名和评分配置文件优化结果，以考虑业务逻辑或新鲜度。

源代码 | 包（NuGet） | API 参考文档 | REST API 文档 | 产品文档 | 示例

入门

安装包

使用 NuGet 安装 Azure AI Search 客户端库。

dotnet add package Azure.Search.Documents

先决条件

您需要一个 Azure 订阅 和一个 搜索服务 才能使用此包。

要创建新的搜索服务，您可以使用 Azure 门户、Azure PowerShell 或 Azure CLI。以下是一个使用 Azure CLI 创建免费实例以入门的示例

az search service create --name <mysearch> --resource-group <mysearch-rg> --sku free --location westus

有关更多选择，请参阅 选择定价层。

认证客户端

要与搜索服务交互，您需要创建合适的客户端类的实例：用于搜索已索引文档的 SearchClient、用于管理索引的 SearchIndexClient 或用于爬取数据源并将搜索文档加载到索引中的 SearchIndexerClient。要实例化客户端对象，您需要一个 端点、Azure 角色或 API 密钥。有关与搜索服务相关的 支持的身份验证方法 的更多信息，请参阅文档。

获取 API 密钥

API 密钥是一个更容易入门的方法，因为它不需要预先存在的角色分配。

您可以从 Azure 门户 获取搜索服务的 端点 和 API 密钥。请参阅 文档 了解获取 API 密钥的说明。

或者，您可以使用以下 Azure CLI 命令从搜索服务检索 API 密钥

az search admin-key show --service-name <mysearch> --resource-group <mysearch-rg>

用于访问您的搜索服务的密钥有两种类型：管理员 （读/写）和 查询 （只读）密钥。限制客户端应用程序的访问和操作对于保护您服务上的搜索资产至关重要。请始终使用查询密钥而不是管理员密钥进行任何来自客户端应用程序的查询。

注意：上面示例中的 Azure CLI 策略检索管理员密钥，这样可以更容易地探索 API，但应谨慎管理。

创建 SearchClient

要实例化 SearchClient，您需要一个 端点、API 密钥 和 索引名称

string indexName = "nycjobs";

// Get the service endpoint and API key from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");

// Create a client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchClient client = new SearchClient(endpoint, indexName, credential);

创建使用Microsoft Entra ID身份验证的客户端

您还可以使用Microsoft Entra ID身份验证创建 SearchClient、SearchIndexClient 或 SearchIndexerClient。您的用户或服务主体必须被分配“搜索索引数据读取器”角色。使用 DefaultAzureCredential，您可以使用托管标识或服务主体对服务进行身份验证，以开发人员身份对应用程序进行身份验证，以及其他所有操作，而无需更改代码。请参考文档中有关如何使用Azure基于角色的访问控制（Azure RBAC）连接到Azure AI Search的说明。

在您可以使用 DefaultAzureCredential 或 Azure.Identity 中的任何凭证类型之前，您首先需要安装Azure.Identity软件包。

要使用具有客户端ID和密钥的 DefaultAzureCredential，您需要设置环境变量 AZURE_TENANT_ID、AZURE_CLIENT_ID 和 AZURE_CLIENT_SECRET；或者，您可以将这些值传递给 Azure.Identity 中的 ClientSecretCredential。

请确保在源文件顶部使用正确的命名空间 DefaultAzureCredential

using Azure.Identity;

然后，您可以创建一个 DefaultAzureCredential 的实例并将其传递给客户端的新实例

string indexName = "nycjobs";

// Get the service endpoint from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
DefaultAzureCredential credential = new DefaultAzureCredential();

// Create a client
SearchClient client = new SearchClient(endpoint, indexName, credential);

ASP.NET Core

要在ASP.NET Core应用程序中将 SearchClient 注入为依赖项，首先安装软件包 Microsoft.Extensions.Azure。然后在 Startup.ConfigureServices 方法中注册客户端

public void ConfigureServices(IServiceCollection services)
{
    services.AddAzureClients(builder =>
    {
        builder.AddSearchClient(Configuration.GetSection("SearchClient"));
    });

    services.AddControllers();
}

要使用前面的代码，请将以下内容添加到配置中

{
    "SearchClient": {
      "endpoint": "https://<resource-name>.search.windows.net",
      "indexname": "nycjobs"
    }
}

您还需要提供资源密钥以对客户端进行身份验证，但您不应该将此信息放在配置中。相反，在开发时，请使用用户密钥。将以下内容添加到 secrets.json

{
    "SearchClient": {
      "credential": { "key": "<you resource key>" }
    }
}

在生产环境中运行时，建议使用环境变量

SEARCH__CREDENTIAL__KEY="..."

或使用其他安全的秘密存储方式，如Azure密钥保管库。

有关ASP.NET Core应用程序中的依赖注入的更多详细信息，请参阅使用Azure SDK for .NET进行依赖注入。

关键概念

Azure AI Search服务包含一个或多个索引，这些索引以JSON文档的形式提供可搜索数据的持久存储。（如果您对搜索尚不熟悉，可以将索引与数据库表进行非常粗略的比较。）Azure.Search.Documents客户端库通过三种主要的客户端类型公开这些资源的操作。

• SearchClient 帮助

  • 使用 向量查询、关键字查询 和 混合查询 来搜索索引文档
  • 向量查询过滤器 和 文本查询过滤器
  • 语义排序 和 评分配置文件 以增强相关性
  • 自动完成 部分输入的搜索词，根据索引中的文档进行匹配
  • 建议 用户输入时最可能的匹配文本
  • 添加、更新或删除文档 从索引中

• SearchIndexClient 允许您

  • 创建、删除、更新或配置搜索索引
  • 声明自定义同义词映射以扩展或重写查询

• SearchIndexerClient 允许您

  • 创建索引器来自动爬取数据源
  • 定义人工智能Skillsets以转换和丰富您的数据

Azure AI Search 提供两个强大功能

语义排名

语义排名可提高文本查询的搜索结果质量。通过在您的搜索服务上启用语义排名，您可以以两种方式提高搜索结果的相关性：

• 它将对初始结果集应用次要排序，将语义相关性最强的结果提升到顶部。
• 它将提取并返回响应中的标题和答案，这可以在搜索页面上显示，以增强用户搜索体验。

要了解更多关于语义搜索的信息，您可以参考示例。

此外，为了获取更多关于语义搜索的全面信息（包括其概念和用法），您可以参考文档。该文档提供了深入的解释和指导，如何利用Azure认知搜索中的语义搜索功能。

向量搜索

向量搜索是一种信息检索技术，它使用可搜索文档和查询字符串的数字表示。通过搜索与数字查询最相似的内容的数字表示，向量搜索可以在查询的精确项不包含在索引中时找到相关匹配。此外，向量搜索可以应用于各种类型的内容，包括图像、视频和翻译文本，而不仅仅是同一语言文本。

要了解如何索引向量字段和执行向量搜索，您可以参考示例。这个示例提供了详细的指导，如何索引向量字段，并演示了如何执行向量搜索。

此外，要获取更多关于向量搜索的全面信息（包括其概念和用法），您可以参考文档。该文档提供了深入的说明和指导，如何利用Azure AI Search中的向量搜索功能。

Azure.Search.Documents 客户端库（v11）为数据平面操作提供API。之前的Microsoft.Azure.Search客户端库（v10）现已停用。它有许多类似外观的API，所以当您在在线资源中探索时，请务必注意以避免混淆。一个好的做法是当您查找API参考时检查命名空间using Azure.Search.Documents;。

线程安全

我们保证所有客户端实例方法都是线程安全的，并相互独立（指南）。这确保了即使跨线程，重用客户端实例的建议始终是安全的。

其他概念

客户端选项 | 访问响应 | 长运行操作 | 处理失败 | 诊断 | 模拟 | 客户端生命周期

例子

以下的所有例子都使用了一个简单的 酒店数据集，您可以从 Azure 门户将其导入到您自己的索引中。
这些只是基础知识的一部分，请查阅我们的示例以获取更多信息。

• 查询
  • 使用 C# 类型作为搜索结果
  • 将 SearchDocument 当作字典来使用搜索结果
  • 搜索选项
• 创建索引
• 向您的索引中添加文档
• 从您的索引中检索特定文档
• 异步 API

高级认证

• 创建一个可以在国家云中进行认证的客户端

查询

让我们首先导入我们的命名空间。

using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Core.GeoJson;

然后我们创建一个 SearchClient 来访问我们的酒店搜索索引。

// Get the service endpoint and API key from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");
string indexName = "hotels";

// Create a client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchClient client = new SearchClient(endpoint, indexName, credential);

与搜索查询返回的数据交互有两种方式。让我们使用搜索“豪华”酒店来探索它们。

使用 C# 类型作为搜索结果

我们可以用来自 System.Text.Json 的 属性 装饰自己的 C# 类型

public class Hotel
{
    [JsonPropertyName("HotelId")]
    [SimpleField(IsKey = true, IsFilterable = true, IsSortable = true)]
    public string Id { get; set; }

    [JsonPropertyName("HotelName")]
    [SearchableField(IsFilterable = true, IsSortable = true)]
    public string Name { get; set; }

    [SimpleField(IsFilterable = true, IsSortable = true)]
    public GeoPoint GeoLocation { get; set; }

    // Complex fields are included automatically in an index if not ignored.
    public HotelAddress Address { get; set; }
}

public class HotelAddress
{
    public string StreetAddress { get; set; }

    [SimpleField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
    public string City { get; set; }

    [SimpleField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
    public string StateProvince { get; set; }

    [SimpleField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
    public string Country { get; set; }

    [SimpleField(IsFilterable = true, IsSortable = true, IsFacetable = true)]
    public string PostalCode { get; set; }
}

然后我们在查询时使用它们作为类型参数以返回强类型的搜索结果

SearchResults<Hotel> response = client.Search<Hotel>("luxury");
foreach (SearchResult<Hotel> result in response.GetResults())
{
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.Id}: {doc.Name}");
}

如果您正在处理搜索索引并且知道其模式，建议创建 C# 类型。

将 SearchDocument 当作字典来使用搜索结果

如果您没有自己的搜索结果类型，可以使用 SearchDocument。在这里，我们执行搜索，枚举结果，并使用 SearchDocument 的字典索引器提取数据。

SearchResults<SearchDocument> response = client.Search<SearchDocument>("luxury");
foreach (SearchResult<SearchDocument> result in response.GetResults())
{
    SearchDocument doc = result.Document;
    string id = (string)doc["HotelId"];
    string name = (string)doc["HotelName"];
    Console.WriteLine($"{id}: {name}");
}

搜索选项

SearchOptions 提供了对我们的查询行为的强大控制。让我们搜索评分良好的前五家豪华酒店。

int stars = 4;
SearchOptions options = new SearchOptions
{
    // Filter to only Rating greater than or equal our preference
    Filter = SearchFilter.Create($"Rating ge {stars}"),
    Size = 5, // Take only 5 results
    OrderBy = { "Rating desc" } // Sort by Rating from high to low
};
SearchResults<Hotel> response = client.Search<Hotel>("luxury", options);
// ...

创建索引

您可以使用 SearchIndexClient 来创建搜索索引。可以从模型类使用 FieldBuilder 定义字段。索引还可以定义建议器、词法分析器等。

使用上面定义了简单和复杂字段的 Hotel 示例

Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");

// Create a service client
AzureKeyCredential credential = new AzureKeyCredential(key);
SearchIndexClient client = new SearchIndexClient(endpoint, credential);

// Create the index using FieldBuilder.
SearchIndex index = new SearchIndex("hotels")
{
    Fields = new FieldBuilder().Build(typeof(Hotel)),
    Suggesters =
    {
        // Suggest query terms from the HotelName field.
        new SearchSuggester("sg", "HotelName")
    }
};

client.CreateIndex(index);

在模型未知或无法修改的情况下，您还可以使用便捷的 SimpleField、SearchableField 或 ComplexField 类显式创建字段

// Create the index using field definitions.
SearchIndex index = new SearchIndex("hotels")
{
    Fields =
    {
        new SimpleField("HotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true },
        new SearchableField("HotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("Description") { AnalyzerName = LexicalAnalyzerName.EnLucene },
        new SearchableField("Tags", collection: true) { IsFilterable = true, IsFacetable = true },
        new ComplexField("Address")
        {
            Fields =
            {
                new SearchableField("StreetAddress"),
                new SearchableField("City") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("StateProvince") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("Country") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("PostalCode") { IsFilterable = true, IsSortable = true, IsFacetable = true }
            }
        }
    },
    Suggesters =
    {
        // Suggest query terms from the hotelName field.
        new SearchSuggester("sg", "HotelName")
    }
};

client.CreateIndex(index);

向您的索引中添加文档

您可以选择批量请求来从索引中一次上传、合并、合并或上传以及删除多个文档。合并有一些特殊规则 需要注意。

IndexDocumentsBatch<Hotel> batch = IndexDocumentsBatch.Create(
    IndexDocumentsAction.Upload(new Hotel { Id = "783", Name = "Upload Inn" }),
    IndexDocumentsAction.Merge(new Hotel { Id = "12", Name = "Renovated Ranch" }));

IndexDocumentsOptions options = new IndexDocumentsOptions { ThrowOnAnyError = true };
client.IndexDocuments(batch, options);

即使在个别操作失败的情况下，请求仍会成功并返回一个 IndexDocumentsResult 以供检查。还有一个 ThrowOnAnyError 选项，如果您只关心整个批次的成功或失败。

从您的索引中检索特定文档

除了使用关键词和可选过滤器查询文档外，如果您知道密钥，还可以从索引中检索特定文档。例如，您可以从查询中获取密钥，显示有关该文档的更多信息或将客户导航到该文档。

Hotel doc = client.GetDocument<Hotel>("1");
Console.WriteLine($"{doc.Id}: {doc.Name}");

异步 API

到目前为止所有的示例都使用了同步API，但我们同样提供了对异步API的全支持。你通常只需要在方法名后面添加Async后缀，并使用await。

SearchResults<Hotel> searchResponse = await client.SearchAsync<Hotel>("luxury");
await foreach (SearchResult<Hotel> result in searchResponse.GetResultsAsync())
{
    Hotel doc = result.Document;
    Console.WriteLine($"{doc.Id}: {doc.Name}");
}

在国家级云中进行身份验证

要在国家级云中进行身份验证，您需要在客户端配置中添加以下内容

• 在凭证选项或通过AZURE_AUTHORITY_HOST环境变量设置AuthorityHost
• 在SearchClientOptions中设置Audience

// Create a SearchClient that will authenticate through AAD in the China national cloud
string indexName = "nycjobs";
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
SearchClient client = new SearchClient(endpoint, indexName,
    new DefaultAzureCredential(
        new DefaultAzureCredentialOptions()
        {
            AuthorityHost = AzureAuthorityHosts.AzureChina
        }),
    new SearchClientOptions()
    {
        Audience = SearchAudience.AzureChina
    });

故障排除

任何失败的Azure.Search.Documents操作将抛出一个包含有用的RequestFailedException，并提供相关的状态码。其中许多错误是可以恢复的。

try
{
    return client.GetDocument<Hotel>("12345");
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
    Console.WriteLine("We couldn't find the hotel you are looking for!");
    Console.WriteLine("Please try selecting another.");
    return null;
}

如果您想深入了解针对服务发出的请求，可以轻松启用控制台日志记录。

有关如何诊断各种故障场景的详细信息，请参阅我们的故障排除指南。

下一步操作

• 深入了解Azure.Search.Documents和我们的示例
• 了解更多关于Azure AI Search服务的信息

贡献

有关构建、测试和为此库做贡献的详细信息，请参阅我们的Search CONTRIBUTING.md。

此项目欢迎贡献和建议。大多数贡献需要您同意贡献者许可协议（CLA），声明您有权并且实际上授予我们使用您贡献的权利。有关详细信息，请访问cla.microsoft.com。

此项目已采取Microsoft开源行为准则。有关更多信息，请参阅行为准则FAQ，或通过[email protected]联系以获取任何额外的疑问或评论。