Azure Image Analysis客户端库用于Python

图像分析服务提供用于处理图像并返回其内容的AI算法。在一个服务调用中，您可以同时从图像中提取一个或多个视觉特征，包括获取图像的标题、提取图像中显示的文本（OCR）和检测对象。有关服务和支持的视觉功能的更多信息，请参阅图像分析概述和概念页面。

使用图像分析客户端库

• 验证服务
• 设置要提取的功能
• 上传图像进行分析，或发送图像URL
• 获取分析结果

产品文档 | 示例 | 视觉工作室 | API参考文档 | 包（Pypi） | SDK源代码

入门

先决条件

• 安装Python 3.8或更高版本，包括pip。
• 一个Azure订阅。
• 在您的Azure订阅中创建一个 计算机视觉资源。
  • 您需要从这个资源中获取密钥和端点来验证服务。
  • 注意，为了使用CAPTION或DENSE_CAPTIONS功能运行图像分析，Azure资源必须来自支持GPU的区域。有关支持区域列表的说明，请参阅此处。

安装图像分析包

pip install azure-ai-vision-imageanalysis

创建和验证客户端

使用API密钥

要使用API密钥验证ImageAnalysisClient，您需要从Azure门户中的Azure计算机视觉资源获取端点和API密钥。以下代码示例假设这些值存储在环境变量中。

• 将环境变量VISION_ENDPOINT设置为端点URL。它具有以下形式：https://your-resource-name.cognitiveservices.azure.com，其中your-resource-name是您的唯一Azure计算机视觉资源名称。

• 将环境变量VISION_KEY设置为密钥。密钥是一个32位的十六进制数。

注意：客户端库在运行时不会直接读取这些环境变量。端点和密钥必须提供给您的代码中ImageAnalysisClient构造函数。以下代码示例通过读取环境变量来推广不要在源代码中硬编码秘密的做法。

一旦定义了环境变量，以下Python代码将使用密钥创建并验证一个同步的ImageAnalysisClient。

import os
from azure.ai.vision.imageanalysis import ImageAnalysisClient
from azure.ai.vision.imageanalysis.models import VisualFeatures
from azure.core.credentials import AzureKeyCredential

# Set the values of your computer vision endpoint and computer vision key
# as environment variables:
try:
    endpoint = os.environ["VISION_ENDPOINT"]
    key = os.environ["VISION_KEY"]
except KeyError:
    print("Missing environment variable 'VISION_ENDPOINT' or 'VISION_KEY'")
    print("Set them before running this sample.")
    exit()

# Create an Image Analysis client for synchronous operations,
# using API key authentication
client = ImageAnalysisClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(key)
)

使用Entra ID

您还可以使用Entra ID和Azure Identity库验证ImageAnalysisClient。要使用以下示例中所示的DefaultAzureCredential提供程序或其他提供程序，请安装azure-identity包。

pip install azure.identity

假设您已定义上述提到的环境变量VISION_ENDPOINT，以下Python代码将使用Entra ID创建并验证一个同步的ImageAnalysisClient。

import os
from azure.ai.vision.imageanalysis import ImageAnalysisClient
from azure.ai.vision.imageanalysis.models import VisualFeatures
from azure.identity import DefaultAzureCredential

# Set the value of your computer vision endpoint as environment variable:
try:
    endpoint = os.environ["VISION_ENDPOINT"]
except KeyError:
    print("Missing environment variable 'VISION_ENDPOINT'.")
    print("Set it before running this sample.")
    exit()

# Create an Image Analysis client for synchronous operations,
# using Entra ID authentication
client = ImageAnalysisClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential(exclude_interactive_browser_credential=False),
)

创建异步客户端

同步客户端支持同步分析方法，这意味着它们将阻塞直到服务响应分析结果。以下代码示例都使用了同步方法，因为它更适合入门指南。SDK提供等效的异步API，通常更受欢迎。要创建异步客户端，请执行以下操作：

• 安装额外的包aiohttp

  pip install aiohttp
  

• 更新上述代码以从azure.ai.vision.imageanalysis.aio导入ImageAnalysisClient。

  from azure.ai.vision.imageanalysis.aio import ImageAnalysisClient
  

• 如果您使用DefaultAzureCredential进行Entra ID身份验证，请更新上述代码以从azure.identity.aio导入DefaultAzureCredential。

  from azure.identity.aio import DefaultAzureCredential
  

关键概念

视觉特征

一旦初始化了ImageAnalysisClient，您需要选择一个或多个视觉特征进行分析。这些选项由枚举类VisualFeatures指定。以下功能受支持：

1. VisualFeatures.CAPTION（示例 | 样本）：生成一个描述图像内容的可读句子。
2. VisualFeatures.READ （示例 | 示例代码）：也称为光学字符识别（OCR）。从图像中提取印刷或手写文本。 注意：要从PDF、Office和HTML文档以及文档图像中提取文本，请使用带有读取模型的文档智能服务。此模型针对文本密集型的数字和扫描文档进行了优化，具有异步REST API，使其易于支持智能文档处理场景。此服务与图像分析服务分开，并有自己的SDK。
3. VisualFeatures.DENSE_CAPTIONS （示例代码）：密集描述提供了更多细节，通过为图像中的最多10个不同区域生成一句话的描述，包括整个图像。
4. VisualFeatures.TAGS （示例代码）：提取图像中数千个可识别对象、生物、风景和动作的内容标签。
5. VisualFeatures.OBJECTS （示例代码）：对象检测。这与标签类似，但专注于检测图像中的物理对象并返回其位置。
6. VisualFeatures.SMART_CROPS （示例代码）：用于查找图像的代表性子区域以生成缩略图，优先考虑包括面部。
7. VisualFeatures.PEOPLE （示例代码）：检测图像中的人并返回其位置。

有关这些功能的更多信息，请参阅图像分析概述和概念页面。

从图像缓冲区或URL进行分析

ImageAnalysisClient为analyze方法提供两种重载。

• 从输入字节对象分析图像。客户端将图像作为REST请求的一部分上传到服务。
• 从公开可访问的URL分析图像。客户端将图像URL发送到服务。服务将获取图像。

下面的示例显示了如何执行这两种操作。从输入bytes对象分析图像的示例通过从磁盘上的文件加载图像来填充bytes对象。

支持的图像格式

图像分析适用于满足以下要求的图像

• 图像必须是JPEG、PNG、GIF、BMP、WEBP、ICO、TIFF或MPO格式
• 图像的文件大小必须小于20兆字节（MB）
• 图像的尺寸必须大于50 x 50像素且小于16,000 x 16,000像素

示例

以下部分提供了涵盖这些常见图像分析场景的代码片段

• 为图像文件生成图像描述
• 为图像URL生成图像描述
• 从图像文件提取文本（OCR）
• 从图像URL提取文本（OCR）

这些片段使用来自创建和验证客户端的同步client。

有关所有视觉功能（包括异步客户端）的完整工作示例，请参阅示例文件夹。

为图像文件生成图像描述

本例演示了如何使用ImageAnalysisClient为图像文件sample.jpg生成一句话描述。同步（阻塞）的analyze方法调用返回一个包含caption属性的ImageAnalysisResult对象，该属性的数据类型为CaptionResult。它包含生成的描述和其在[0, 1]范围内的置信度分数。默认情况下，描述可能包含性别术语，例如“男人”、“女人”或“男孩”、“女孩”。您可以在调用analyze时设置gender_neutral_caption = True来请求中性性别术语，如“人”或“孩子”。

注意

• 描述仅在部分Azure区域中可用。请参阅先决条件。
• 目前仅支持英文描述。

# Load image to analyze into a 'bytes' object
with open("sample.jpg", "rb") as f:
    image_data = f.read()

# Get a caption for the image. This will be a synchronously (blocking) call.
result = client.analyze(
    image_data=image_data,
    visual_features=[VisualFeatures.CAPTION],
    gender_neutral_caption=True,  # Optional (default is False)
)

# Print caption results to the console
print("Image analysis results:")
print(" Caption:")
if result.caption is not None:
    print(f"   '{result.caption.text}', Confidence {result.caption.confidence:.4f}")

要为其他图像生成描述，只需多次调用analyze即可。您可以使用相同的ImageAnalysisClient进行多次分析调用。

为图像URL生成图像描述

此示例与上述示例类似，但它调用analyze方法并提供一个公开可访问的图像URL，而不是文件名。

# Get a caption for the image. This will be a synchronously (blocking) call.
result = client.analyze_from_url(
    image_url="https://aka.ms/azsdk/image-analysis/sample.jpg",
    visual_features=[VisualFeatures.CAPTION],
    gender_neutral_caption=True,  # Optional (default is False)
)

# Print caption results to the console
print("Image analysis results:")
print(" Caption:")
if result.caption is not None:
    print(f"   '{result.caption.text}', Confidence {result.caption.confidence:.4f}")

从图像文件中提取文本

本例演示了如何使用ImageAnalysisClient从图像文件sample.jpg中提取打印或手写的文本。同步（阻塞）的analyze方法调用返回一个包含read属性的ImageAnalysisResult对象，该属性的数据类型为ReadResult。它包含文本行列表以及围绕每行文本的边界多边形。对于每一行，它还返回文本行中的单词列表以及围绕每个单词的边界多边形。

# Load image to analyze into a 'bytes' object
with open("sample.jpg", "rb") as f:
    image_data = f.read()

# Extract text (OCR) from an image stream. This will be a synchronously (blocking) call.
result = client.analyze(
    image_data=image_data,
    visual_features=[VisualFeatures.READ]
)

# Print text (OCR) analysis results to the console
print("Image analysis results:")
print(" Read:")
if result.read is not None:
    for line in result.read.blocks[0].lines:
        print(f"   Line: '{line.text}', Bounding box {line.bounding_polygon}")
        for word in line.words:
            print(f"     Word: '{word.text}', Bounding polygon {word.bounding_polygon}, Confidence {word.confidence:.4f}")

要为其他图像提取文本，只需多次调用analyze即可。您可以使用相同的ImageAnalysisClient进行多次分析调用。

注意：要从PDF、Office和HTML文档及其图像中提取文本，请使用带有Read模型的文档智能服务。此模型针对文本密集型数字和扫描文档进行了优化，具有异步REST API，可以轻松实现智能文档处理场景。此服务与图像分析服务分开，并有自己的SDK。

从图像URL中提取文本

此示例与上述示例类似，但它调用analyze方法并提供一个公开可访问的图像URL，而不是文件名。

# Extract text (OCR) from an image stream. This will be a synchronously (blocking) call.
result = client.analyze_from_url(
    image_url="https://aka.ms/azsdk/image-analysis/sample.jpg",
    visual_features=[VisualFeatures.READ]
)

# Print text (OCR) analysis results to the console
print("Image analysis results:")
print(" Read:")
if result.read is not None:
    for line in result.read.blocks[0].lines:
        print(f"   Line: '{line.text}', Bounding box {line.bounding_polygon}")
        for word in line.words:
            print(f"     Word: '{word.text}', Bounding polygon {word.bounding_polygon}, Confidence {word.confidence:.4f}")

故障排除

异常

当服务返回非成功的HTTP状态码时，analyze方法会引发一个HttpResponseError异常。异常的status_code将是HTTP响应状态码。异常的error.message包含一个详细的消息，可帮助您诊断问题

try:
    result = client.analyze( ... )
except HttpResponseError as e:
    print(f"Status code: {e.status_code}")
    print(f"Reason: {e.reason}")
    print(f"Message: {e.error.message}")

例如，当您提供错误的认证密钥时

Status code: 401
Reason: PermissionDenied
Message: Access denied due to invalid subscription key or wrong API endpoint. Make sure to provide a valid key for an active subscription and use a correct regional API endpoint for your resource.

或者当您提供的图像URL不存在或不可访问时

Status code: 400
Reason: Bad Request
Message: The provided image url is not accessible.

日志记录

客户端使用标准的Python日志库。SDK记录HTTP请求和响应的详细信息，这可能有助于故障排除。要记录到stdout，请添加以下内容

import sys
import logging

# Acquire the logger for this client library. Use 'azure' to affect both
# 'azure.core` and `azure.ai.vision.imageanalysis' libraries.
logger = logging.getLogger("azure")

# Set the desired logging level. logging.INFO or logging.DEBUG are good options.
logger.setLevel(logging.INFO)

# Direct logging output to stdout (the default):
handler = logging.StreamHandler(stream=sys.stdout)
# Or direct logging output to a file:
# handler = logging.FileHandler(filename = 'sample.log')
logger.addHandler(handler)

# Optional: change the default logging format. Here we add a timestamp.
formatter = logging.Formatter("%(asctime)s:%(levelname)s:%(name)s:%(message)s")
handler.setFormatter(formatter)

默认情况下，日志会去除URL查询字符串的值、某些HTTP请求和响应头（包括包含密钥的Ocp-Apim-Subscription-Key）以及请求和响应的有效负载。要创建不带删除的日志，请在创建ImageAnalysisClient时或在调用客户端上的analyze时设置方法参数logging_enable = True。

# Create an Image Analysis client with none redacted log
client = ImageAnalysisClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(key),
    logging_enable=True
)

仅当日志级别为logging.DEBUG时才会生成不带删除的日志。请确保保护不带删除的日志，以避免损害安全性。更多信息请参阅配置Python Azure库中的日志记录

下一步

• 查看包含用于图像分析（所有视觉功能、同步和异步客户端、从图像文件或URL）的完整可运行的Python代码的示例文件夹。

贡献

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

当您提交拉取请求时，CLA机器人会自动判断您是否需要提供CLA，并相应地装饰PR（例如，标签，注释）。只需遵循机器人提供的说明。您只需在整个使用我们的CLA的仓库中这样做一次。

本项目已采用Microsoft开源行为准则。有关更多信息，请参阅行为准则FAQ或通过opencode@microsoft.com联系以提出任何额外的问题或评论。