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

Azure 认知搜索 Python 客户端库 - 版本 11.4.0

Azure 认知搜索是一种搜索即服务云解决方案，它为开发人员提供 API 和工具，以便基于 Web、移动和企业应用程序中的专用异类内容添加丰富的搜索体验。

Azure 认知搜索服务非常适合以下应用程序方案：

• 将各种内容类型合并到单个可搜索索引中。 若要填充索引，可以推送包含内容的 JSON 文档，或者，如果数据已在 Azure 中，请创建索引器以自动拉取数据。
• 将技能集附加到索引器，以从图像和大型文本文档创建可搜索的内容。 技能组利用认知服务中的 AI 进行内置的 OCR、实体识别、关键短语提取、语言检测、文本翻译和情绪分析。 还可以添加自定义技能，以在数据引入期间集成对内容的外部处理。
• 在搜索客户端应用程序中，实现类似于商业 Web 搜索引擎的查询逻辑和用户体验。

使用 Azure.Search.Documents 客户端库可以：

• 提交包含模糊搜索、通配符搜索和正则表达式的简单和高级查询表单的查询。
• 实现分面导航、地理空间搜索或基于筛选条件缩小结果的筛选查询。
• 创建和管理搜索索引。
• 上传和更新搜索索引中的文档。
• 创建和管理从 Azure 将数据拉取到索引中的索引器。
• 创建和管理向数据引入添加 AI 扩充的技能集。
• 为高级文本分析或多语言内容创建和管理分析器。
• 通过评分配置文件优化结果，以将业务逻辑或新鲜度考虑在内。

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

入门

安装包

使用 pip 安装适用于 Python 的 Azure 认知搜索 客户端库：

pip install azure-search-documents

先决条件

• 使用此包需要 Python 3.7 或更高版本。
• 需要 Azure 订阅和Azure 认知搜索服务才能使用此包。

若要创建新的搜索服务，可以使用 Azure 门户、Azure PowerShell 或 Azure CLI。

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

有关可用选项的详细信息 ，请参阅选择定价层 。

验证客户端

若要与搜索服务交互，需要创建相应的客户端类的实例：SearchClient用于搜索索引文档、SearchIndexClient管理索引或SearchIndexerClient对数据源进行爬网以及将搜索文档加载到索引中。 若要实例化客户端对象，需要 终结点 和 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))

使用 Azure Active Directory 身份验证创建客户端

还可以使用 Azure Active Directory (AAD) 身份验证创建 SearchClientSearchIndexClient、 或 SearchIndexerClient 。 必须为用户或服务主体分配“搜索索引数据读取者”角色。 使用 DefaultAzureCredential ，可以使用托管标识或服务主体对服务进行身份验证、以开发人员身份处理应用程序等方式进行身份验证，而无需更改代码。 有关如何使用 Azure 基于角色的访问控制 (Azure RBAC) 连接到Azure 认知搜索的说明，请参阅文档。

首先需要安装 Azure.Identity 包，DefaultAzureCredential然后才能使用 或 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 认知搜索服务包含一个或多个索引，这些索引以 JSON 文档的形式提供可搜索数据的持久存储。 (如果不熟悉搜索，可以在索引和数据库表之间进行非常粗略的类比。) Azure.Search.Documents 客户端库通过两种main客户端类型公开对这些资源执行的操作。

• SearchClient 帮助：

  • 使用丰富的查询和强大的数据整形来搜索索引文档
  • 基于索引中的文档自动完成部分键入的搜索词
  • 建议 文档中最可能匹配的文本作为用户类型
  • 从索引中添加、更新或删除文档文档

• 使用 SearchIndexClient，你可以：

  • 创建、删除、更新或配置搜索索引
  • 声明自定义同义词映射以展开或重写查询
  • 当前 SearchServiceClient 预览版中尚未提供大部分功能

• 使用 SearchIndexerClient，你可以：

  • 启动索引器以自动对数据源进行爬网
  • 定义 AI 支持的技能组以转换和扩充数据

Azure 认知搜索提供了两个强大的功能：语义搜索和矢量搜索。

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

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

若要详细了解语义搜索，请参阅 文档。

矢量搜索是一种信息检索技术，可克服传统基于关键字 (keyword) 搜索的限制。 矢量搜索利用机器学习模型来捕获单词和短语的上下文含义，而不是仅依赖于词法分析和匹配的各个查询词。 它将文档和查询表示为称为嵌入的高维空间中的向量。 通过了解查询背后的意图，矢量搜索可以提供更相关的结果，这些结果符合用户的要求，即使文档中没有确切的术语。 此外，矢量搜索可以应用于各种类型的内容，包括图像和视频，而不仅仅是文本。

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

此外，有关矢量搜索的更全面信息，包括其概念和用法，可以参考 文档。 本文档提供有关在 Azure 认知搜索 中利用矢量搜索功能的详细解释和指导。

Azure.Search.Documents (v1) 客户端库是一项全新的产品/服务，适用于想要在其应用程序中使用搜索技术的 Python 开发人员。 (v10) 有一个功能齐全的 Microsoft.Azure.Search 较旧的客户端库，其中包含许多外观相似的 API，因此在浏览联机资源时请小心避免混淆。

示例

以下示例都使用一个简单的 Hotel 数据集，可以从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)

将文档添加到索引

可以在UploadMerge单个批处理请求中从索引、、 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
• 在 audience 、 SearchIndexClient或 中SearchClient设置SearchIndexerClient

# 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 认知搜索客户端将引发 Azure Core 中定义的异常。

日志记录

此库使用标准 日志记录 库进行日志记录。 有关 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/azure-search-documents_11.4.0/sdk/search/azure-search-documents/samples
• 观看 演示或深入探讨视频
• 详细了解Azure 认知搜索服务

贡献

有关构建、测试和参与此库的详细信息，请参阅 我们的搜索 CONTRIBUTING.md 。

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

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与 联系。

相关项目

• 适用于 Python 的 Microsoft Azure SDK