Azure AI Content Understanding SDK for Python 1.1.0で最初に確認すべき変更点は、分析処理のポーラーからusageを取得できるようになったことです。これにより、REST APIが返す課金・トークン消費の詳細をPython SDK側でも扱いやすくなりました。既存の抽出ロジック自体を大きく書き換える更新というより、コスト可視化、利用量監視、分析ジョブごとのメトリクス管理を強化するための更新と見るのが実務的です。(GitHub)
特に、請求書・契約書・社内文書・音声・動画などを大量に処理しているチームは、アップデート後にusageをログや監視基盤へ取り込めるかを早めに検証してください。一方で、単発のPoCや抽出結果だけを確認している段階なら、まずはステージング環境でバージョン固定、スモークテスト、usage is Noneへの対策を確認すれば十分です。
Azure AI Content Understanding Python SDK 1.1.0 is released の要点
Azure AI Content Understanding SDK for Python 1.1.0は、2026年4月20日付けのリリースとして公開されています。PyPI上でもazure-ai-contentunderstanding 1.1.0が最新バージョンとして表示され、Python 3.9以上が要件として示されています。(PyPI)
今回の更新で押さえるべきポイントは次の通りです。
| 確認項目 | 内容 | 実務での見方 |
|---|---|---|
| 対象パッケージ | azure-ai-contentunderstanding | Azure AI Content UnderstandingをPythonから利用している環境が対象 |
| バージョン | 1.1.0 | 既存の1.0.0、1.0.1利用者は更新候補 |
| 主な変更 | AnalyzeLROPollerとAnalyzeAsyncLROPollerにusageプロパティを追加 | 分析完了後に課金・トークン消費関連の情報を参照しやすくなる |
| 対象処理 | begin_analyzeなどの分析系の長時間実行処理 | ドキュメント処理、RAG用抽出、音声・動画分析の利用量把握に有効 |
| まず見るべき箇所 | 分析後のポーラー処理、ログ、監視、請求分析 | resultではなくpoller.usageを確認する設計にする |
公式リリースノート上、1.1.0の項目には「Features Added」としてusageプロパティの追加が記載されています。破壊的変更が明記されたリリースではありませんが、本番適用前には依存関係、型チェック、既存の分析フローを必ず検証してください。(GitHub)
何が変わったのか：usageで利用量をSDK側から確認できる
これまでの課題は、REST APIが返す利用量情報と、Python SDKで扱える結果オブジェクトの間に差が出るケースがあったことです。GitHub Issueでも、azure-ai-contentunderstanding==1.0.1ではREST APIレスポンスに含まれるusageがSDKのpoller.result()やAnalysisResultから見えない、という報告がありました。(GitHub)
1.1.0では、分析処理のポーラーであるAnalyzeLROPollerとAnalyzeAsyncLROPollerにusageプロパティが追加されました。Microsoft LearnのAPIリファレンスでは、usageは分析処理が正常に完了した後に利用でき、ドキュメントページ数、コンテキスト化トークン、LLMトークンの内訳など、分析で消費されたリソース情報を返すと説明されています。(Microsoft Learn)
UsageDetailsで確認できる主な情報
UsageDetailsには、次のような利用量情報が含まれます。
| 項目 | 意味 | 活用例 |
|---|---|---|
document_pages_minimal | minimalレベルで処理されたドキュメントページ数 | 軽量なドキュメント処理の量を把握する |
document_pages_basic | basicレベルで処理されたドキュメントページ数 | OCRや構造抽出の処理量を監視する |
document_pages_standard | standardレベルで処理されたドキュメントページ数 | 高度な分析処理のボリュームを確認する |
audio_hours | 処理された音声時間 | コールセンター音声や会議録処理の利用量を集計する |
video_hours | 処理された動画時間 | 動画分析ジョブごとの処理量を比較する |
contextualization_tokens | コンテキスト化、信頼度、ソースグラウンディング、出力整形などに使われたトークン数 | RAG向け前処理や構造化出力の負荷を見る |
tokens | LLMや埋め込みモデルのトークン消費をモデル・種類別にまとめた情報 | モデル別の利用傾向やコスト増加要因を調査する |
Microsoft LearnのUsageDetailsリファレンスでは、ページ数、音声・動画時間、コンテキスト化トークン、モデル別・種類別トークン消費などの変数が示されています。テキストやHTMLのように明示的なページを持たないドキュメントでは、3,000 UTF-16文字ごとに1ページとして数える説明もあります。(Microsoft Learn)
実務で影響を受けやすい利用シーン
大量ドキュメント処理のコスト管理
請求書、領収書、契約書、本人確認書類などを毎日大量に処理している場合、1ジョブあたりの利用量を把握できるかどうかは重要です。usageをログに残せば、次のような分析がしやすくなります。
- どの
analyzer_idで利用量が増えているか - 特定の顧客、部署、ワークフローだけページ数やトークン数が増えていないか
- PDFのページ数増加、画像混入、長文HTML化などが処理コストに影響していないか
- RAG用インデックス作成時に、想定以上のトークンを消費していないか
ここで大切なのは、usageを「請求金額そのもの」として扱わないことです。SDKが返すのは利用量の詳細であり、最終的な請求額や通貨、割引、契約条件はAzure側の課金情報と照合して確認する必要があります。
RAG・検索基盤の前処理
Azure AI Content Understandingは、ドキュメント、画像、音声、動画から構造化されたコンテンツを抽出し、RAGや自動化ワークフロー向けの機械可読データに変換するサービスとして説明されています。Python SDKのREADMEでも、ドキュメント抽出、音声分析、動画分析、事前構築済みアナライザー、カスタムアナライザーなどの用途が示されています。(Microsoft Learn)
RAG用途では、検索品質だけでなく、前処理にかかるコストや処理時間も設計上の重要な指標です。たとえば、社内ナレッジベースを毎晩再処理する場合、次のような観点でusageを確認できます。
| 観点 | 見るべき情報 | 判断例 |
|---|---|---|
| ドキュメント量 | document_pages_* | 夜間バッチで処理対象が急増していないか |
| トークン消費 | contextualization_tokens、tokens | インデックス更新のたびに過剰なトークンを使っていないか |
| モダリティ別負荷 | audio_hours、video_hours | 音声・動画分析が想定以上に増えていないか |
| 顧客別・部署別配賦 | ジョブID、アナライザーID、usage | 利用量ベースで内部配賦できるか |
AIエンジニアのモデル利用分析
UsageDetails.tokensは、LLMや埋め込みモデルのトークン消費をモデルや種類別にまとめる情報として説明されています。これにより、分析結果の品質だけでなく、モデル利用量の観点からアナライザー設計を比較しやすくなります。(Microsoft Learn)
たとえば、同じ契約書処理でも、汎用のドキュメント検索向けアナライザーと、特定フィールド抽出用のカスタムアナライザーでは、消費するページ数やトークンの傾向が変わる可能性があります。精度改善のために抽出スキーマや対象ファイルを広げた結果、利用量が急増していないかを追跡できるようになります。
アップデート前に確認すべきチェックリスト
本番環境でAzure AI Content Understanding SDK for Pythonを利用している場合は、いきなり本番更新せず、次の順番で確認してください。
| 手順 | 確認内容 | 具体的な作業 |
|---|---|---|
| 1 | 現在のバージョンを確認 | pip show azure-ai-contentunderstanding、requirements.txt、pyproject.toml、ロックファイルを確認 |
| 2 | 1.1.0をステージングに導入 | python -m pip install --upgrade azure-ai-contentunderstanding==1.1.0を検証環境で実行 |
| 3 | 代表的な分析処理を実行 | ドキュメント、画像、音声、動画など自社で使う入力形式を試す |
| 4 | poller.usageを確認 | 分析完了後にusageが取得できるか、Noneの場合に落ちないかを見る |
| 5 | 既存の結果処理を確認 | result.contents、フィールド抽出、Markdown生成などが従来通り動くか確認 |
| 6 | ログ設計を見直す | 利用量メタデータだけを保存し、本文や機密情報を不要に出力しない |
| 7 | 請求・監視と照合 | Azureの課金情報、社内メトリクス、ジョブ単位の利用量を突き合わせる |
SDKのREADMEでは、1.1.0、1.0.1、1.0.0はいずれも対応するAPI service versionとして2025-11-01が示されています。ただし、SDK側の取得可能プロパティや型情報はバージョンで変わるため、APIバージョンが同じでもアプリケーション側の検証は省略しないでください。(GitHub)
既存コードで追加するならこの形が安全
usageはAnalysisResultではなく、分析処理を開始したときに返るポーラー側で確認します。Microsoft LearnのAnalyzeLROPollerリファレンスでも、usageはポーラーの属性として説明されています。(Microsoft Learn)
同期処理では、次のようにpoller.result()の後で確認すると安全です。
from azure.ai.contentunderstanding import ContentUnderstandingClient
from azure.ai.contentunderstanding.models import AnalysisInput
from azure.core.credentials import AzureKeyCredential
client = ContentUnderstandingClient(
endpoint=endpoint,
credential=AzureKeyCredential(api_key),
)
poller = client.begin_analyze(
analyzer_id="prebuilt-documentSearch",
inputs=[AnalysisInput(url=file_url)],
)
result = poller.result()
usage = getattr(poller, "usage", None)
if usage is not None:
usage_dict = usage.as_dict()
print(usage_dict)
else:
print("Usage details are not available for this operation.")非同期処理では、await poller.result()の後で同じように扱います。
from azure.ai.contentunderstanding.aio import ContentUnderstandingClient
from azure.ai.contentunderstanding.models import AnalysisInput
from azure.core.credentials import AzureKeyCredential
async with ContentUnderstandingClient(
endpoint=endpoint,
credential=AzureKeyCredential(api_key),
) as client:
poller = await client.begin_analyze(
analyzer_id="prebuilt-documentSearch",
inputs=[AnalysisInput(url=file_url)],
)
result = await poller.result()
usage = getattr(poller, "usage", None)
if usage is not None:
usage_dict = usage.as_dict()
print(usage_dict)usageは、処理が正常に完了した後に利用できる情報です。未完了、失敗、またはサービス側で利用量情報が返らないケースではNoneになり得るため、監視コードでは必ずNoneを許容してください。(Microsoft Learn)
ログに残すなら、本文ではなく利用量メタデータを保存する
実務では、usage.as_dict()をそのまま標準出力に出すだけでは不十分です。ジョブ単位で後から集計できるように、最低限次の情報を一緒に保存します。
| ログ項目 | 例 | 目的 |
|---|---|---|
timestamp | 2026-04-20T10:00:00Z | 日次・月次の集計 |
analyzer_id | prebuilt-documentSearch | アナライザー別の利用量比較 |
operation_id | ポーラーから取得できる操作ID | 障害調査やジョブ追跡 |
input_type | pdf、image、audio、video | モダリティ別の傾向確認 |
usage | usage.as_dict() | ページ数、時間、トークン数の集計 |
status | succeeded、failed | 成功ジョブと失敗ジョブの分離 |
ただし、ログにはファイル本文、抽出結果の全文、顧客名、個人情報、機密文書名を不用意に入れないでください。usage自体は利用量メタデータですが、周辺情報の設計によっては個人情報や機密情報と結び付く可能性があります。
メトリクス化する場合は、次のような変換関数を用意しておくと扱いやすくなります。
def extract_usage_metrics(usage):
if usage is None:
return {
"usage_available": False,
}
data = usage.as_dict()
return {
"usage_available": True,
"document_pages_minimal": data.get("document_pages_minimal"),
"document_pages_basic": data.get("document_pages_basic"),
"document_pages_standard": data.get("document_pages_standard"),
"audio_hours": data.get("audio_hours"),
"video_hours": data.get("video_hours"),
"contextualization_tokens": data.get("contextualization_tokens"),
"tokens": data.get("tokens"),
}この形にしておけば、将来フィールドが増減しても、アプリケーションの主要処理に影響を与えにくくなります。
1.1.0で失敗しやすいポイント
result.usageを探してしまう
今回の変更は、分析結果のAnalysisResultにusageが入るという話ではありません。追加されたのはAnalyzeLROPollerとAnalyzeAsyncLROPollerのusageプロパティです。poller.result()で結果を取得した後、poller.usageを見る流れにしてください。(GitHub)
分析完了前にusageを読もうとする
usageは完了後の分析処理に対する利用量情報です。ポーリング中、タイムアウト直後、失敗時に必ず取得できると考えると、監視処理やバッチ処理が不安定になります。
安全な設計は次の通りです。
try:
result = poller.result()
usage = getattr(poller, "usage", None)
except Exception as exc:
usage = None
raise
finally:
# 必要に応じて、ジョブ状態とusageの有無を別々に記録する
passusageを請求金額と同一視する
usageは、ページ数、音声・動画時間、トークン消費などを把握するための情報です。コスト管理には非常に役立ちますが、実際の請求額はAzureの価格、契約条件、リージョン、割引、課金単位などと合わせて確認する必要があります。SDKログだけで請求額を断定しないでください。
プレビュー版から一気に上げる場合の差分を見落とす
1.0.0のGAリリースでは、プレビューSDKからの型名変更やプロパティ名変更、begin_analyzeの引数変更などがリリース履歴に記載されています。1.0.0b1などのプレビュー版から1.1.0へ直接上げる場合は、1.1.0のusage追加だけでなく、GA時点のAPI変更も確認が必要です。(GitHub)
たとえば、リリース履歴では次のような変更が示されています。
| 旧名称・旧仕様 | 新名称・新仕様 |
|---|---|
AnalyzeInput | AnalysisInput |
AnalyzeResult | AnalysisResult |
MediaContent | AnalysisContent |
MediaContentKind | AnalysisContentKind |
AnalysisInput.input_range | content_range |
begin_analyzeのinputs | 必須のキーワード引数 |
すでに1.0.0または1.0.1を利用しているチームは、主にusage追加部分を検証すればよいケースが多いです。一方、プレビュー版からの移行では、型名・引数・プロパティ名の差分まで含めて確認してください。
チーム別の優先度
1.1.0への対応優先度は、Azure AI Content Understanding SDK for Pythonをどの規模で使っているかによって変わります。
| 利用状況 | 優先度 | 理由 |
|---|---|---|
| 本番で大量のドキュメントを毎日処理している | 高 | ページ数やトークン消費をジョブ単位で把握できる価値が大きい |
| 顧客別・部署別に利用量を配賦したい | 高 | usageを内部課金や利用量レポートの材料にできる |
| RAG用の前処理を定期バッチで実行している | 高 | インデックス更新時の処理量やトークン増加を監視しやすい |
| 音声・動画分析を使っている | 中〜高 | audio_hoursやvideo_hoursの把握が運用上重要 |
| PoCや検証環境のみで使っている | 中 | 急ぎではないが、今後の本番化に備えて確認しておきたい |
| すでにREST API側で独自に利用量を取得している | 中 | SDK側へ統合できるかを検討する価値がある |
| 抽出結果だけを手動確認している | 低〜中 | 影響は小さいが、依存関係更新として検証しておくとよい |
導入後に見るべき運用指標
1.1.0を導入したら、単に「usageが取れた」で終わらせず、運用に使える指標へ落とし込むことが重要です。
ジョブ単位の利用量
まずは、1回の分析ジョブごとにページ数、トークン数、音声・動画時間を記録します。これにより、想定外に重い入力ファイルや、特定のアナライザーだけ負荷が高いケースを見つけやすくなります。
アナライザー別の平均利用量
prebuilt-documentSearch、prebuilt-invoice、カスタムアナライザーなど、analyzer_idごとに平均利用量を集計します。精度だけでなく、利用量の観点でもアナライザーを比較できます。
顧客・部署・ワークフロー別の月次推移
SaaSや社内業務システムに組み込んでいる場合は、顧客別、部署別、業務フロー別に利用量を見ます。急増が見られた場合、単純な利用拡大なのか、入力ファイルの変化なのか、処理設計の問題なのかを切り分けます。
失敗ジョブとの分離
失敗した分析処理、タイムアウトした処理、usageが取得できなかった処理は、成功ジョブと分けて集計します。成功ジョブだけで平均を出すと、実際の運用負荷を見誤る場合があります。
1.1.0への更新コマンドと依存関係の確認
通常の更新は、検証環境で次のように行います。
python -m pip install --upgrade azure-ai-contentunderstanding==1.1.0バージョン確認は次のコマンドで行います。
python -m pip show azure-ai-contentunderstandingrequirements.txtで管理している場合は、次のように明示します。
azure-ai-contentunderstanding==1.1.0pyproject.tomlで管理している場合も、意図せず古いバージョンに戻らないようにバージョン範囲を確認してください。
azure-ai-contentunderstanding = "1.1.0"非同期APIを使う場合、SDKのREADMEではaiohttpがデフォルトではインストールされないため、別途インストールが必要と説明されています。非同期サンプルやazure.ai.contentunderstanding.aioを使っているプロジェクトでは、SDK更新だけでなく非同期トランスポートの依存関係も確認してください。(GitHub)
python -m pip install aiohttp1.1.0に今すぐ上げるべきか
判断基準はシンプルです。
| 状況 | 判断 |
|---|---|
| 本番で大量処理しており、コストや利用量を可視化したい | 早めにステージング検証し、本番適用を計画する |
1.0.1でREST APIのusageがSDKから見えない問題に困っている | 1.1.0の検証優先度は高い |
| 抽出結果だけを利用し、利用量管理はまだ不要 | 急ぎではないが、依存関係更新として検証する |
| プレビュー版SDKを使っている | 1.0.0 GA時点の変更も含めて移行計画を立てる |
| 本番で厳密なバージョン固定をしている | ロックファイル更新、回帰テスト、監視項目追加をセットで行う |
今回の更新は、Azure AI Content Understanding SDK for Pythonを使う開発者にとって、派手な機能追加というより「運用に必要な情報がSDKから取りやすくなった」更新です。だからこそ、PoC段階よりも、本番運用・大量処理・コスト管理を始めたチームほど価値があります。
よくある質問
1.1.0にすると既存の分析結果の構造は変わりますか
公式リリースノート上、1.1.0の変更内容はAnalyzeLROPollerとAnalyzeAsyncLROPollerへのusageプロパティ追加として記載されています。少なくともリリースノート上では、1.1.0の項目に破壊的変更は明記されていません。ただし、実際の本番適用では自社の入力ファイル、アナライザー、型チェック、ログ処理で回帰テストを行ってください。(GitHub)
usageはいつ取得できますか
usageは、分析処理が正常に完了した後に利用できるプロパティです。Microsoft Learnでは、操作がまだ完了していない場合や利用量情報が利用できない場合はNoneになり得ると説明されています。(Microsoft Learn)
usageだけでAzureの請求額を計算できますか
usageは利用量の把握に役立つ情報ですが、請求額そのものではありません。最終的なコスト確認には、Azureの課金情報や契約条件と照合してください。SDK側では、ページ数、音声・動画時間、トークン消費などを運用メトリクスとして扱うのが現実的です。
REST APIを併用する必要はなくなりますか
usage情報を取得する目的でREST APIに戻る必要は減ります。ただし、利用している機能やワークフローによっては、SDKにない処理や独自のREST連携が残る場合があります。まずは現在REST APIを併用している理由を整理し、usage取得だけが目的ならSDK側へ寄せられるか検証してください。
1.0.1からの更新で特に見るべき点は何ですか
1.0.1利用者は、poller.result()後にpoller.usageを取得できるかを中心に確認してください。1.0.1ではREST APIが返すusageがSDK結果から見えないというIssueが報告されていたため、利用量管理に困っていたチームほど検証価値があります。(GitHub)
まとめ：最初にやるべきこと
Azure AI Content Understanding SDK for Python 1.1.0の実務上の要点は、usageプロパティによって分析処理の利用量をSDK側から扱いやすくなったことです。ドキュメント処理、音声・動画分析、RAG向け前処理を本番運用しているチームでは、コスト可視化と監視設計の改善につながります。
まずは、現在のazure-ai-contentunderstandingのバージョンを確認し、ステージング環境で1.1.0へ更新してください。そのうえで、代表的な分析ジョブを実行し、poller.result()後にpoller.usageを安全に取得できるかを確認します。usageは常に存在すると決め打ちせず、Noneを許容する実装にして、ページ数、トークン数、音声・動画時間をジョブ単位でログに残すところから始めるのが現実的です。
コメント