Azure 内容理解 Python 技能
用 Python 从文档、图像、音频和视频中提取结构化内容。
文档推荐DefaultAzureCredential、避免密钥，并说明端点和凭据环境变量，体现了较好的凭据安全意识；但通过URL把文档、图像、音频和视频交给外部Azure服务，未说明数据流、敏感内容处理、用户确认、权限最小化或结果保护，也未提供删除/回滚流程，因此扣分。
核心异步分析流程、同步/异步客户端生命周期和长任务提示较清楚；但主文档的create_analyzer字典示例与参考文件的begin_create_analyzer模型示例不一致，结果访问方式也分别写成result.fields和content.fields，且缺少异常、超时、重试、分页和空结果处理。静态证据不足，按上限保守评分。
触发词、Python SDK受众、文档/图像/音频/视频及自定义分析场景明确，并覆盖同步和异步用法；但未声明服务区域、网络可达性、输入限制、隐私边界和不适用场景，也未提供中文使用指导，因此扣分。
结构包含安装、环境变量、认证、核心流程、示例、最佳实践和参考文件，且有MIT许可证、作者与1.0.0版本；但缺少变更日志、维护责任和更新路径，参考内容与主文档存在API命名和模型继承不一致，故未满分。
预构建分析器和端到端示例可帮助用户完成基本多模态提取，输出markdown、转录和关键帧具有直接用途；但自定义分析示例存在相互矛盾的API和结果字段访问，缺少错误处理、输入验证、成本/延迟及本地替代方案，结果仍可能需要较多人工修正。
源文件提供了具体代码、包名、环境变量和仓库CI/测试基础设施，具备一定审计性；但未提供该技能关键路径的专属测试、实际执行结果或第三方交叉验证，且文件内部API表述冲突，因此只能给有限分数。
- 使用URL输入前确认数据已获授权，并评估敏感信息是否允许发送到Azure及其所在区域。
- 不要直接照搬自定义分析器示例；先以当前官方SDK API核对创建方法、模型类型和结果字段访问方式。
- 为生产代码补充异常、超时、重试、空结果、输入大小/类型、成本和长任务取消处理。
- 确认目标环境可以访问Azure端点；技能未说明中国大陆网络、区域可用性或服务数据驻留。
它能做什么 & 适用场景
该技能为 Azure AI Content Understanding Python SDK 提供编码指导。它覆盖文档、图像、音频和视频的多模态分析，并可输出 Markdown、转录文本、时间信息、关键帧及自定义字段。技能说明了同步与异步客户端、DefaultAzureCredential、长时间运行分析以及分析器管理。适合构建 RAG 和自动化工作流，但需要 Azure 内容理解终结点和相应运行环境。
指导安装 azure-ai-contentunderstanding，配置 CONTENTUNDERSTANDING_ENDPOINT，并使用 ContentUnderstandingClient 调用 Azure AI Content Understanding。它通过预置分析器提取文档 Markdown、图像内容、音频转录、视频转录与关键帧，也展示如何创建带字段架构的自定义分析器、查询和删除分析器，并从 AnalyzeResult.contents 或自定义字段读取结果。
- 需要将 PDF 或 Office 文档转换为 Markdown 以支持 RAG 的 Python 开发者。
- 需要从图片中提取可检索内容的应用开发者。
- 需要获得带时间戳音频转录的自动化工作流开发者。
- 需要从视频中提取转录、摘要相关内容和关键帧的团队。
- 需要从发票中提取供应商、金额和行项目等领域字段的开发者。
优缺点一览
- 覆盖文档、图像、音频和视频四类内容。
- 提供预置分析器和自定义字段架构。
- 同时说明同步、异步和分析器管理流程。
- 强调 DefaultAzureCredential 与上下文管理器等身份和生命周期实践。
- 必须配置 Azure 内容理解终结点，并依赖 Azure 服务网络访问。
- 音频和视频分析可能需要数分钟，调用方需要处理长时间运行操作。
- 源材料未提供该单项技能的独立测试结果、费用信息或权限清单。
- 技能主要给出 URL 输入示例，未详细说明本地文件上传流程。
如何安装
在终端运行 pip install azure-ai-contentunderstanding。使用集合时，可运行 npx skills add microsoft/skills，再从安装向导中选择该技能；也可复制 .github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py 到目标 Agent 的技能目录。具体目标目录取决于所用 Agent。
如何使用
配置 CONTENTUNDERSTANDING_ENDPOINT=https://<resource>.cognitiveservices.azure.com/。让编码 Agent 处理例如：“使用 azure-ai-contentunderstanding 分析这个 PDF URL，并返回文档 Markdown。”生产代码应优先使用 DefaultAzureCredential，使用 begin_analyze() 启动分析，并通过 poller.result() 获取结果。异步场景使用 aio 客户端和 azure.identity.aio 凭据。