Azure AI Search客户端库，用于Python

Azure AI Search（以前称为“Azure认知搜索”）是一个基于AI的信息检索平台，帮助开发者构建丰富的搜索体验和将大型语言模型与企业数据相结合的生成式AI应用程序。

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

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

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

• 使用矢量、关键词和混合查询形式提交查询。
• 实现针对元数据、地理空间搜索、分类导航或根据筛选条件缩小结果范围的筛选查询。
• 创建和管理搜索索引。
• 上传和更新搜索索引中的文档。
• 创建和管理索引器，用于从 Azure 拉取数据到索引。
• 创建和管理技能集，为数据摄入添加 AI 丰富功能。
• 创建和管理用于高级文本分析或多语言内容的分析器。
• 通过语义排名和评分配置文件优化结果，以考虑业务逻辑或新鲜度。

源代码 | 包 (PyPI) | 包 (Conda) | API 参考文档 | 产品文档 | 示例

入门

安装包

使用 pip 安装 Azure AI Search Python 客户端库

pip install azure-search-documents

先决条件

• 使用此包需要 Python 3.8 或更高版本。
• 您需要一个 Azure 订阅 和一个 Azure AI Search 服务。

要创建新的搜索服务，您可以使用 Azure 门户、Azure PowerShell 或 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 密钥 和 索引名称

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

service_endpoint = os.environ["AZURE_SEARCH_SERVICE_ENDPOINT"]
index_name = os.environ["AZURE_SEARCH_INDEX_NAME"]
key = os.environ["AZURE_SEARCH_API_KEY"]

search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

使用 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。

from azure.identity import DefaultAzureCredential
from azure.search.documents import SearchClient

service_endpoint = os.getenv("AZURE_SEARCH_SERVICE_ENDPOINT")
index_name = os.getenv("AZURE_SEARCH_INDEX_NAME")
credential = DefaultAzureCredential()

search_client = SearchClient(service_endpoint, index_name, credential)

关键概念

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

• SearchClient 帮助

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

• SearchIndexClient 允许您

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

• SearchIndexerClient 允许您
  • 启动索引器以自动爬取数据源。
  • 定义 AI 驱动的技能集以转换和丰富您的数据。

Azure AI Search 提供两个强大的功能：语义排名 和 向量搜索。

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

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

要了解更多关于语义排名的信息，请参阅 文档。

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

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

此外，有关向量搜索的更全面信息，包括其概念和用法，您可以参考文档。该文档提供了对利用Azure AI搜索中向量搜索功能的深入解释和指导。

Azure.Search.Documents客户端库（v1）提供数据平面操作的API。之前的Microsoft.Azure.Search客户端库（v10）现已退役。它有许多类似外观的API，所以在探索在线资源时请小心，避免混淆。一个很好的经验法则是查找命名空间Azure.Search.Documents;，当您查找API引用时。

示例

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

• 查询
• 创建索引
• 将文档添加到您的索引中
• 从您的索引中检索特定文档
• 异步API

查询

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

import os
from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

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

index_name = "hotels"
# Get the service endpoint and API key from the environment
endpoint = os.environ["SEARCH_ENDPOINT"]
key = os.environ["SEARCH_API_KEY"]

# Create a client
credential = AzureKeyCredential(key)
client = SearchClient(endpoint=endpoint,
                      index_name=index_name,
                      credential=credential)

让我们搜索一家“豪华”酒店。

results = client.search(search_text="luxury")

for result in results:
    print("{}: {})".format(result["hotelId"], result["hotelName"]))

创建索引

您可以使用SearchIndexClient来创建搜索索引。字段可以使用方便的SimpleField、SearchableField或ComplexField模型定义。索引还可以定义建议器、词法分析器等。

client = SearchIndexClient(service_endpoint, AzureKeyCredential(key))
name = "hotels"
fields = [
    SimpleField(name="hotelId", type=SearchFieldDataType.String, key=True),
    SimpleField(name="baseRate", type=SearchFieldDataType.Double),
    SearchableField(name="description", type=SearchFieldDataType.String, collection=True),
    ComplexField(
        name="address",
        fields=[
            SimpleField(name="streetAddress", type=SearchFieldDataType.String),
            SimpleField(name="city", type=SearchFieldDataType.String),
        ],
        collection=True,
    ),
]
cors_options = CorsOptions(allowed_origins=["*"], max_age_in_seconds=60)
scoring_profiles: List[ScoringProfile] = []
index = SearchIndex(name=name, fields=fields, scoring_profiles=scoring_profiles, cors_options=cors_options)

result = client.create_index(index)

将文档添加到您的索引中

您可以在单个批量请求中Upload、Merge、MergeOrUpload和Delete索引中的多个文档。请注意，合并有一些特殊的规则。

DOCUMENT = {
    "category": "Hotel",
    "hotelId": "1000",
    "rating": 4.0,
    "rooms": [],
    "hotelName": "Azure Inn",
}

result = search_client.upload_documents(documents=[DOCUMENT])

print("Upload of new document succeeded: {}".format(result[0].succeeded))

国家云身份验证

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

• 在凭证选项中设置AuthorityHost或通过AZURE_AUTHORITY_HOST环境变量
• 在SearchClient、SearchIndexClient或SearchIndexerClient中设置audience

# Create a SearchClient that will authenticate through AAD in the China national cloud.
import os
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts
from azure.search.documents import SearchClient

index_name = "hotels"
endpoint = os.environ["SEARCH_ENDPOINT"]
key = os.environ["SEARCH_API_KEY"]
credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_CHINA)

search_client = SearchClient(endpoint, index_name, credential=credential, audience="https://search.azure.cn")

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

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

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

result = search_client.get_document(key="23")

print("Details for hotel '23' are:")
print("        Name: {}".format(result["hotelName"]))
print("      Rating: {}".format(result["rating"]))
print("    Category: {}".format(result["category"]))

异步API

此库包含一个完整的异步API。要使用它，您必须首先安装异步传输，例如aiohttp。有关更多信息，请参阅azure-core文档。

from azure.core.credentials import AzureKeyCredential
from azure.search.documents.aio import SearchClient

search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

async with search_client:
    results = await search_client.search(search_text="spa")

    print("Hotels containing 'spa' in the name (or other fields):")
    async for result in results:
        print("    Name: {} (rating {})".format(result["hotelName"], result["rating"]))

故障排除

通用

Azure AI搜索客户端将引发在Azure Core中定义的异常。

日志记录

此库使用标准的logging库进行日志记录。HTTP会话的基本信息（URL、标题等）以INFO级别记录。

详细调试级别的日志记录，包括请求/响应体和未删除的头部信息，可以通过客户端的logging_enable关键字参数来启用

import sys
import logging
from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = SearchClient("<service endpoint>", "<index_name>", AzureKeyCredential("<api key>"), logging_enable=True)

同样，logging_enable也可以为单个操作启用详细日志记录，即使客户端没有启用

result =  client.search(search_text="spa", logging_enable=True)

下一步

• 深入了解Azure.Search.Documents和我们的https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/search/azure-search-documents/samples
• 了解更多关于Azure AI Search服务的信息

贡献

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

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

此项目采用了Microsoft开源行为准则。有关更多信息，请参阅行为准则常见问题解答或通过opencode@microsoft.com联系以获得任何额外的问题或评论。

相关项目

• Microsoft Azure SDK for Python