azure-ai-contentunderstanding-py

Python 用 Azure AI Content Understanding SDK

RAG と自動化されたワークフロー向けに、ドキュメント、動画、音声、画像ファイルから意味内容を抽出するマルチモーダル AI サービスです。

インストール

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)

基本的なワークフロー

Content Understanding の操作は、非同期の長時間実行操作です。

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()
)

# Analyze document from URL
poller = client.begin_analyze(
    analyzer_id="prebuilt-documentSearch",
    inputs=[AnalyzeInput(url="https://example.com/document.pdf")]
)

result = poller.result()

# Access markdown content (contents is a list)
content = result.contents[0]
print(content.markdown)

ドキュメントコンテンツの詳細へのアクセス

from azure.ai.contentunderstanding.models import MediaContentKind, DocumentContent

content = result.contents[0]
if content.kind == MediaContentKind.DOCUMENT:
    document_content: DocumentContent = content  # type: ignore
    print(document_content.start_page_number)

画像の分析

from azure.ai.contentunderstanding.models import AnalyzeInput

poller = client.begin_analyze(
    analyzer_id="prebuilt-imageSearch",
    inputs=[AnalyzeInput(url="https://example.com/image.jpg")]
)
result = poller.result()
content = result.contents[0]
print(content.markdown)

動画の分析

from azure.ai.contentunderstanding.models import AnalyzeInput

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

result = poller.result()

# Access video content (AudioVisualContent)
content = result.contents[0]

# Get transcript phrases with timing
for phrase in content.transcript_phrases:
    print(f"[{phrase.start_time} - {phrase.end_time}]: {phrase.text}")

# Get key frames (for video)
for frame in content.key_frames:
    print(f"Frame at {frame.time}: {frame.description}")

音声の分析

from azure.ai.contentunderstanding.models import AnalyzeInput

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

result = poller.result()

# Access audio transcript
content = result.contents[0]
for phrase in content.transcript_phrases:
    print(f"[{phrase.start_time}] {phrase.text}")

カスタムアナライザー

特殊な抽出向けに、フィールドスキーマを使用してカスタムアナライザーを作成します。

# Create custom analyzer
analyzer = client.create_analyzer(
    analyzer_id="my-invoice-analyzer",
    analyzer={
        "description": "Custom invoice analyzer",
        "base_analyzer_id": "prebuilt-documentSearch",
        "field_schema": {
            "fields": {
                "vendor_name": {"type": "string"},
                "invoice_total": {"type": "number"},
                "line_items": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "description": {"type": "string"},
                            "amount": {"type": "number"}
                        }
                    }
                }
            }
        }
    }
)

# Use custom analyzer
from azure.ai.contentunderstanding.models import AnalyzeInput

poller = client.begin_analyze(
    analyzer_id="my-invoice-analyzer",
    inputs=[AnalyzeInput(url="https://example.com/invoice.pdf")]
)

result = poller.result()

# Access extracted fields
for content in result.contents or []:
    fields = content.fields or {}
    print(fields.get("vendor_name"))
    print(fields.get("invoice_total"))

アナライザーの管理

# List all analyzers
analyzers = client.list_analyzers()
for analyzer in analyzers:
    print(f"{analyzer.analyzer_id}: {analyzer.description}")

# Get specific analyzer
analyzer = client.get_analyzer("prebuilt-documentSearch")

# Delete custom analyzer
client.delete_analyzer("my-custom-analyzer")

非同期クライアント

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

async def analyze_document():
    endpoint = os.environ["CONTENTUNDERSTANDING_ENDPOINT"]
    credential = DefaultAzureCredential()
    
    async with ContentUnderstandingClient(
        endpoint=endpoint,
        credential=credential
    ) as client:
        poller = await client.begin_analyze(
            analyzer_id="prebuilt-documentSearch",
            inputs=[AnalyzeInput(url="https://example.com/doc.pdf")]
        )
        result = await poller.result()
        content = result.contents[0]
        return content.markdown

asyncio.run(analyze_document())

コンテンツタイプ

クラス	対象	提供内容
DocumentContent	PDF、画像、Office ドキュメント	ページ、表、図、段落
AudioVisualContent	音声、動画ファイル	トランスクリプトのフレーズ、タイミング情報、キーフレーム

どちらも MediaContent を継承しており、基本情報と Markdown 表現を提供します。

モデルのインポート

from azure.ai.contentunderstanding.models import (
    AnalyzeInput,
    AnalyzeResult,
    MediaContentKind,
    DocumentContent,
    AudioVisualContent,
)

クライアントの種類

クライアント	用途
ContentUnderstandingClient	すべての操作に対応する同期クライアント
ContentUnderstandingClient (aio)	すべての操作に対応する非同期クライアント

ベストプラクティス

1. AnalyzeInput と begin_analyze を使用します — これが正しいメソッドシグネチャです
2. result.contents[0] から結果にアクセスします — 結果はリストとして返されます
3. 一般的なシナリオでは事前構築済みアナライザーを使用します（ドキュメント／画像／音声／動画の検索）
4. カスタムアナライザーは、ドメイン固有のフィールド抽出に限って作成します
5. 高スループットのシナリオでは、azure.identity.aio の認証情報とともに非同期クライアントを使用します
6. 長時間実行操作を適切に処理します — 動画や音声の分析には数分かかることがあります
7. 可能な場合は URL ソースを使用して、アップロードのオーバーヘッドを回避します

使用する場面

このスキルは、概要に記載されたワークフローまたはアクションを実行する場合に適用できます。

制限事項

• このスキルは、タスクが上記の範囲に明確に合致する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、成功基準が不足している場合は、作業を中止して確認を求めてください。

SDK／サービスのバージョンによって動作が異なります。固定されたパッケージのバージョンに基づいてアナライザースキーマと結果フィールドを確認してください。インデックスアクセスの前に contents が空でないことを確認し、使用前に抽出フィールドが欠落していないか確認してください。これらは断片的な例であり、アナライザーのライフサイクル全体を示すものではありません。非同期クライアントと認証情報はコンテキストマネージャーで閉じ、ポーリングに上限を設けて、失敗を報告してください。ドキュメント、音声、動画はローカル環境の外部に送信されます。機密情報の転送を承認し、抽出フィールドをマスキングして、財務・法務上の判断に使用する前に出力を検証してください。公式 SDK ガイドを参照してください。