技能介绍

要解决什么问题

在 Python 服务或脚本里接入 Azure AI Vision 4.0 图像分析 时，你需要统一调用说明生成、内容标签、带框物体/人物检测、OCR 以及缩略图裁剪建议，而不是为每种能力各自拼 REST 请求和处理响应格式。本技能围绕官方 azure-ai-vision-imageanalysis 客户端库，把从鉴权、选特征到同步/异步调用的常见路径整理成可复用指引。

核心能力与关键步骤

分析入口通常是 URL 或 本地文件；一次请求通过 visual_features 选择所需能力，避免为不需要的结果付延迟与费用：

CAPTION / DENSE_CAPTIONS：整图或分区域的文字说明
TAGS：场景、物体、动作类标签
OBJECTS / PEOPLE：带边界框的检测
READ：OCR 文本提取
SMART_CROPS：按宽高比给出裁剪区域

鉴权上，新代码应优先 DefaultAzureCredential（本地 Azure CLI / VS Code，云端托管标识），仅在尚未迁移 Entra 的旧密钥部署里才用 AzureKeyCredential。生产代码应把 ImageAnalysisClient 包在 with / async with 里；异步路径还需对 azure.identity.aio 的凭据使用 async with，以便释放连接与令牌缓存。高吞吐场景选 异步客户端，并在同一条调用链里不要混用 sync 与 aio 模块。

适用边界与注意点

图像需满足服务限制：JPEG、PNG、GIF、BMP、WEBP 等，单张 ≤20 MB，边长 50×50～16000×16000。无效图像或鉴权失败会表现为 HttpResponseError，调用方应显式处理。说明文案可通过 gender_neutral_caption、语言参数做本地化与包容性调整；同一图像多次分析时建议 缓存结果。更完整的非核心场景与生产检查项见技能内 references/ 文档。