技能介绍

要解决什么问题

在 RAG、合规归档或业务自动化里，原始素材往往不是纯文本：PDF/Office、扫描件、录音、监控视频和图片混在一起。手工转写或拆页面成本高，且很难得到带结构的语义结果（表格、段落、时间轴、关键帧）。Azure AI Content Understanding 提供统一的多模态分析入口；本技能对应其 Python SDK 的使用方式与约定，帮助你在代码里稳定跑通「提交 → 等待 → 取结果」这条链路。

核心能力与关键步骤

Content Understanding 的分析是异步长任务，典型流程有三步：

用 begin_analyze() 启动分析，得到可轮询的操作对象
通过 .result() 等待完成（SDK 负责轮询）
从 AnalyzeResult.contents 读取结构化输出；常见访问方式是 result.contents[0]

预构建分析器覆盖常见场景，例如：prebuilt-documentSearch（文档 → Markdown，便于 RAG）、prebuilt-imageSearch、prebuilt-audioSearch（转写与时间信息）、prebuilt-videoSearch（帧、转录、摘要）、prebuilt-invoice（发票字段）。需要领域字段时，可用字段模式创建自定义分析器并做分析器管理。

结果侧有两类内容模型：DocumentContent（PDF、图片、Office 等，含页面、表格、段落等）与 AudioVisualContent（音视频，含转录短语、时间戳、关键帧）；二者继承 MediaContent，可拿到基础信息与 Markdown 表示。客户端分同步 ContentUnderstandingClient 与异步 ContentUnderstandingClient (aio)，高吞吐场景应整条路径统一选一种模式。

认证与资源释放上，技能强调两条生产向规则：优先 DefaultAzureCredential（本地 Azure CLI/VS Code 与云上托管身份同一套写法；生产可用 AZURE_TOKEN_CREDENTIALS 收紧凭据链），以及客户端与异步凭据都放进上下文管理器（with / async with），避免 HTTP 连接与令牌缓存泄漏。

适用边界与注意点

视频/音频分析可能耗时数分钟，调用方需要按长任务设计超时与重试，而不是当作即时 API。
同一调用链不要混用同步与 azure.ai.contentunderstanding.aio 异步客户端。
大文件场景优先用 URL 源，减少上传开销；begin_analyze 应配合正确的 AnalyzeInput 入参。
预构建分析器已够用时不必自建分析器；自定义分析器留给专业字段提取。
更细的能力清单与次要场景见技能内 references/capabilities.md、references/non-hero-scenarios.md。