コンテンツ解釈アナライザーを作成する

ほとんどのシナリオでは、Content Understanding Studio のビジュアル インターフェイスを使用してアナライザーを作成およびテストすることを検討する必要があります。 ただし、場合によっては、目的のコンテンツ フィールドのスキーマの JSON 定義を API に送信してアナライザーを作成することが必要な場合があります。

アナライザーのスキーマの定義

アナライザーは、コンテンツ ファイルから抽出または生成するフィールドを定義するスキーマに基づいています。 最も単純なスキーマは、次のアナライザー定義の例に示すように、JSON ドキュメントで指定できるフィールドのセットです。

{
    "description": "Simple business card",
    "baseAnalyzerId": "prebuilt-document",
    "config": {
        "returnDetails": true
    },
    "fieldSchema": {
        "fields": {
            "ContactName": {
                "type": "string",
                "method": "extract",
                "description": "Name on business card"
            },
            "EmailAddress": {
                "type": "string",
                "method": "extract",
                "description": "Email address on business card"
            }
        }
    },
    "models": {
        "completion": "gpt-4.1",
        "embedding": "text-embedding-3-large"
    }
}

カスタム アナライザー スキーマのこの例は、事前構築済みの ドキュメント アナライザーに基づいており、名刺で見つかる 2 つのフィールド (ContactName と EmailAddress) について説明します。 どちらのフィールドも文字列データ型として定義されており、ドキュメントから 抽出 されることが想定されています (つまり、文字列値はドキュメント内に存在することが予想されるため、ドキュメントに関する情報を推測して 生成 できるフィールドではなく、"読み取り" できます)。 models オブジェクトは、アナライザーが処理に使用する生成モデルを指定します。

Python SDK を使用してアナライザーを作成する

アナライザー定義を設定したら、Python SDK を使用してアナライザーを作成できます。 ContentUnderstandingClient クラスは、非同期作成プロセスを自動的に処理するbegin_create_analyzer メソッドを提供します。

from azure.ai.contentunderstanding import ContentUnderstandingClient
from azure.core.credentials import AzureKeyCredential

# Authenticate the client
endpoint = "<YOUR_ENDPOINT>"
credential = AzureKeyCredential("<YOUR_API_KEY>")
client = ContentUnderstandingClient(endpoint=endpoint, credential=credential)

# Define the analyzer
analyzer_name = "business_card_analyser"
analyzer_definition = {
    "description": "Simple business card",
    "baseAnalyzerId": "prebuilt-document",
    "config": {"returnDetails": True},
    "fieldSchema": {
        "fields": {
            "ContactName": {
                "type": "string",
                "method": "extract",
                "description": "Name on business card"
            },
            "EmailAddress": {
                "type": "string",
                "method": "extract",
                "description": "Email address on business card"
            }
        }
    },
    "models": {
        "completion": "gpt-4.1",
        "embedding": "text-embedding-3-large"
    }
}

# Create the analyzer and wait for completion
poller = client.begin_create_analyzer(analyzer_name, body=analyzer_definition)
result = poller.result()
print(f"Analyzer created: {result.analyzer_id}")

REST API を使用してアナライザーを作成する

または、REST API を直接使用することもできます。 JSON データは、アナライザー作成操作を開始するために、要求ヘッダーの API キーを使用してエンドポイントに PUT 要求として送信されます。

PUT要求からの応答には、ヘッダーに Operation-Location が含まれています。このヘッダーには、要求を送信して要求の状態を確認するために使用できるGET URL が用意されています。

次の Python コードは、 card.json という名前のファイルの内容に基づいてアナライザーを作成する要求を送信します (前述の JSON 定義が含まれていると想定されます)。

import json
import requests

# Get the business card schema
with open("card.json", "r") as file:
    schema_json = json.load(file)

# Use a PUT request to submit the schema for a new analyzer
analyzer_name = "business_card_analyser"

headers = {
    "Ocp-Apim-Subscription-Key": "<YOUR_API_KEY>",
    "Content-Type": "application/json"}

url = f"{<YOUR_ENDPOINT>}/contentunderstanding/analyzers/{analyzer_name}?api-version=2025-11-01"

response = requests.put(url, headers=headers, data=json.dumps(schema_json))

# Get the response and extract the ID assigned to the operation
callback_url = response.headers["Operation-Location"]

# Use a GET request to check the status of the operation
result_response = requests.get(callback_url, headers=headers)

# Keep polling until the operation is complete
status = result_response.json().get("status")
while status == "Running":
    result_response = requests.get(callback_url, headers=headers)
    status = result_response.json().get("status")

print("Done!")