---

name: azure-ai-contentunderstanding-py description: Azure AI 内容理解 Python SDK。用于从文档、图片、音频和视频中进行多模态内容提取。 risk: unknown source: community date_added: '2026-02-27'

Azure AI 内容理解 Python SDK

多模态 AI 服务，从文档、视频、音频和图像文件中提取语义内容，用于 RAG 和自动化工作流。

安装

pip install azure-ai-contentunderstanding

环境变量

CONTENTUNDERSTANDING_ENDPOINT=https://<resource>.cognitiveservices.azure.com/

认证

import os
from azure.ai.contentunderstanding import ContentUnderstandingClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["CONTENTUNDERSTANDING_ENDPOINT"]
credential = DefaultAzureCredential()
client = ContentUnderstandingClient(endpoint=endpoint, credential=credential)

核心工作流

内容理解操作是异步长时间运行的操作：

1. 开始分析 — 使用 begin_analyze() 启动分析操作（返回轮询器）
2. 轮询结果 — 轮询直到分析完成（SDK 通过 .result() 处理）
3. 处理结果 — 从 AnalyzeResult.contents 中提取结构化结果

预构建分析器

| 分析器 | 内容类型 | 用途 | |--------|----------|------| | prebuilt-documentSearch | 文档 | 为 RAG 应用提取 markdown | | prebuilt-imageSearch | 图片 | 从图片中提取内容 | | prebuilt-audioSearch | 音频 | 带时间戳的音频转录 | | prebuilt-videoSearch | 视频 | 提取帧、转录、摘要 | | prebuilt-invoice | 文档 | 提取发票字段 |

分析文档

import os
from azure.ai.contentunderstanding import ContentUnderstandingClient
from azure.ai.contentunderstanding.models import AnalyzeInput
from azure.identity import DefaultAzureCredential

endpoint = os.environ["CONTENTUNDERSTANDING_ENDPOINT"]
client = ContentUnderstandingClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential()
)

# 从 URL 分析文档
poller = client.begin_analyze(
    analyzer_id="prebuilt-documentSearch",
    inputs=[AnalyzeInput(url="https://example.com/document.pdf")]
)

result = poller.result()

# 访问 markdown 内容（contents 是列表）
content = result.contents[0]
print(content.markdown)

访问文档内容详情

from azure.ai.contentunderstanding.models import AnalyzeInput

poller = client.begin_analyze(
    analyzer_id="prebuilt-documentSearch",
    inputs=[AnalyzeInput(url="https://example.com/report.pdf")]
)
result = poller.result()

for content in result.contents:
    print(f"Markdown 长度: {len(content.markdown)}")
    if content.fields:
        for field_name, field_value in content.fields.items():
            print(f"  {field_name}: {field_value}")

分析视频

poller = client.begin_analyze(
    analyzer_id="prebuilt-videoSearch",
    inputs=[AnalyzeInput(url="https://example.com/video.mp4")]
)
result = poller.result()

for content in result.contents:
    print(content.markdown)

分析音频

poller = client.begin_analyze(
    analyzer_id="prebuilt-audioSearch",
    inputs=[AnalyzeInput(url="https://example.com/audio.wav")]
)
result = poller.result()

for content in result.contents:
    print(content.markdown)

自定义分析器

from azure.ai.contentunderstanding.models import (
    AnalyzerDefinition,
    FieldDefinition,
    FieldType,
)

# 创建自定义分析器
analyzer = AnalyzerDefinition(
    description="自定义发票分析器",
    scenario="document",
    field_definitions=[
        FieldDefinition(name="vendor_name", type=FieldType.STRING),
        FieldDefinition(name="total_amount", type=FieldType.NUMBER),
        FieldDefinition(name="invoice_date", type=FieldType.DATE),
    ],
)

client.create_analyzer(analyzer_id="custom-invoice", body=analyzer)

限制

• 仅在任务明确匹配上述范围时使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少所需的输入、权限、安全边界或成功标准，请停下来要求澄清。