Content Understanding 분석기는 콘텐츠에서 인사이트를 처리하고 추출하는 방법을 정의합니다. 모든 콘텐츠에서 균일한 처리 및 출력 구조를 보장하므로 안정적이고 예측 가능한 결과를 얻을 수 있습니다. 일반적인 사용 사례의 경우 미리 빌드된 분석기를 사용할 수 있습니다. 이 가이드에서는 이러한 분석기를 사용자 지정하여 요구에 더 잘 맞는 방법을 보여 줍니다.
이 가이드에서는 Content Understanding REST API 를 사용하여 콘텐츠에서 구조화된 데이터를 추출하는 사용자 지정 분석기를 만드는 방법을 보여 줍니다.
필수 조건
- 활성 Azure 구독입니다. Azure 계정이 없는 경우 체험 계정을 만드세요.
-
지원되는 지역에서 만든 Microsoft Foundry 리소스입니다.
- 포털은 Foundry>Foundry 아래에 이 리소스를 나열합니다.
- Content Understanding 리소스에 대한 기본 모델 배포를 설정합니다. 기본적으로 설정하면 Content Understanding 요청에 사용하는 Microsoft Foundry 모델에 대한 연결을 만듭니다. 다음 방법 중 하나를 선택합니다.
Content Understanding 설정 페이지로 이동합니다.
왼쪽 위에서 + 리소스 추가 단추를 선택합니다.
사용할 Foundry 리소스를 선택하고 다음>저장을 선택합니다.
사용 가능한 기본값이 없는 경우 필수 모델에 대한 자동 배포 사용 확인란이 선택되어 있는지 확인합니다. 이 선택은 리소스를 필요한
GPT-4.1,GPT-4.1-mini, 및text-embedding-3-large모델로 완전히 설정합니다. 미리 빌드된 분석기별로 다른 모델이 필요합니다.
- cURL이(가) 개발 환경에 설치되었습니다.
분석기 스키마 정의
사용자 지정 분석기를 만들려면 추출하려는 구조적 데이터를 설명하는 필드 스키마를 정의합니다. 다음 예제에서는 영수증 처리를 위해 미리 빌드된 문서 분석기를 기반으로 분석기를 만듭니다.
다음 콘텐츠로 명명된 JSON 파일을 만듭니다 receipt.json .
{
"description": "Sample receipt analyzer",
"baseAnalyzerId": "prebuilt-document",
"models": {
"completion": "gpt-4.1",
"embedding": "text-embedding-3-large"
},
"config": {
"returnDetails": true,
"enableFormula": false,
"estimateFieldSourceAndConfidence": true,
"tableFormat": "html"
},
"fieldSchema": {
"fields": {
"VendorName": {
"type": "string",
"method": "extract",
"description": "Vendor issuing the receipt"
},
"Items": {
"type": "array",
"method": "extract",
"items": {
"type": "object",
"properties": {
"Description": {
"type": "string",
"method": "extract",
"description": "Description of the item"
},
"Amount": {
"type": "number",
"method": "extract",
"description": "Amount of the item"
}
}
}
}
}
}
}
처리해야 하는 다양한 유형의 문서가 있지만 영수증만 분류하고 분석하려는 경우 먼저 문서를 분류하는 분석기를 만듭니다. 그런 다음, 다음 스키마를 사용하여 이전에 만든 분석기로 라우팅합니다.
다음 콘텐츠로 명명된 JSON 파일을 만듭니다 categorize.json .
{
"baseAnalyzerId": "prebuilt-document",
// Use the base analyzer to invoke the document specific capabilities.
//Specify the model the analyzer should use. This is one of the supported completion models and one of the supported embeddings model. The specific deployment used during analyze is set on the resource or provided in the analyze request.
"models": {
"completion": "gpt-4.1"
},
"config": {
// Enable splitting of the input into segments. Set this property to false if you only expect a single document within the input file. When specified and enableSegment=false, the whole content will be classified into one of the categories.
"enableSegment": false,
"contentCategories": {
// Category name.
"receipt": {
// Description to help with classification and splitting.
"description": "Any images or documents of receipts",
// Define the analyzer that any content classified as a receipt should be routed to
"analyzerId": "receipt"
},
"invoice": {
"description": "Any images or documents of invoice",
"analyzerId": "prebuilt-invoice"
},
"policeReport": {
"description": "A police or law enforcement report detailing the events that lead to the loss."
// Don't perform analysis for this category.
}
},
// Omit original content object and only return content objects from additional analysis.
"omitContent": true
}
//You can use fieldSchema here to define fields that are needed from the entire input content.
}
분석기 만들기
PUT 요청
먼저 영수증 분석기를 만든 다음 범주 분석기를 만듭니다.
curl -i -X PUT "{endpoint}/contentunderstanding/analyzers/{analyzerId}?api-version=2025-11-01" \
-H "Ocp-Apim-Subscription-Key: {key}" \
-H "Content-Type: application/json" \
-d @receipt.json
PUT 응답
응답은 URL이 있는 201 Created 헤더를 포함하며, 이 URL을 사용하여 Operation-Location 비동기 분석기 만들기 작업의 상태를 추적할 수 있습니다.
201 Created
Operation-Location: {endpoint}/contentunderstanding/analyzers/{analyzerId}/operations/{operationId}?api-version=2025-05-01-preview
작업이 완료되면 작업 위치 URL의 HTTP GET이 반환됩니다 "status": "succeeded".
curl -i -X GET "{endpoint}/contentunderstanding/analyzers/{analyzerId}/operations/{operationId}?api-version=2025-11-01" \
-H "Ocp-Apim-Subscription-Key: {key}"
파일 분석
파일 제출
이제 만든 사용자 지정 분석기를 사용하여 파일을 처리하고 스키마에서 정의한 필드를 추출할 수 있습니다.
cURL 명령을 실행하기 전에 HTTP 요청에 다음과 같은 변경 내용을 적용합니다.
-
{endpoint}및{key}를 Azure 포털의 Foundry 인스턴스에서 가져온 엔드포인트 및 키 값으로 교체하십시오. -
{analyzerId}를categorize.json파일을 사용하여 만든 사용자 정의 분석기의 이름으로 바꾸십시오. -
{fileUrl}을 분석할 파일의 공개적으로 액세스 가능한 URL(예: SAS(공유 액세스 서명)이 있는 Azure Storage Blob 경로 또는 샘플 URLhttps://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/receipt.png)로 바꿉니다.
POST 요청
이 예제에서는 파일과 함께 categorize.json 만든 사용자 지정 분석기를 사용하여 영수증을 분석합니다.
curl -i -X POST "{endpoint}/contentunderstanding/analyzers/{analyzerId}:analyze?api-version=2025-11-01" \
-H "Ocp-Apim-Subscription-Key: {key}" \
-H "Content-Type: application/json" \
-d '{
"inputs":[
{
"url": "https://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/receipt.png"
}
]
}'
POST 응답
응답에는 202 Accepted 이 비동기 작업의 상태를 추적하는 데 사용할 수 있는 항목이 포함됩니다 {resultId} .
{
"id": {resultId},
"status": "Running",
"result": {
"analyzerId": {analyzerId},
"apiVersion": "2025-11-01",
"createdAt": "YYYY-MM-DDTHH:MM:SSZ",
"warnings": [],
"contents": []
}
}
분석 결과 가져오기
응답의 Operation-LocationPOST 결과를 사용하여 분석 결과를 가져옵니다.
GET 요청
curl -i -X GET "{endpoint}/contentunderstanding/analyzerResults/{resultId}?api-version=2025-11-01" \
-H "Ocp-Apim-Subscription-Key: {key}"
GET 응답
200 OK 응답에는 작업의 진행률을 보여 주는 필드가 포함됩니다status.
-
status은(는) 작업이 성공적으로 완료된 경우Succeeded입니다. - 상태가
running아니면notStarted수동으로 API를 다시 호출하거나 스크립트를 사용합니다. 요청 사이에 1초 이상 기다립니다.
샘플 응답
{
"id": {resultId},
"status": "Succeeded",
"result": {
"analyzerId": {analyzerId},
"apiVersion": "2025-11-01",
"createdAt": "YYYY-MM-DDTHH:MM:SSZ",
"warnings": [],
"contents": [
{
"path": "input1/segment1",
"category": "receipt",
"markdown": "Contoso\n\n123 Main Street\nRedmond, WA 98052\n\n987-654-3210\n\n6/10/2019 13:59\nSales Associate: Paul\n\n\n<table>\n<tr>\n<td>2 Surface Pro 6</td>\n<td>$1,998.00</td>\n</tr>\n<tr>\n<td>3 Surface Pen</td>\n<td>$299.97</td>\n</tr>\n</table> ...",
"fields": {
"VendorName": {
"type": "string",
"valueString": "Contoso",
"spans": [{"offset": 0,"length": 7}],
"confidence": 0.996,
"source": "D(1,774.0000,72.0000,974.0000,70.0000,974.0000,111.0000,774.0000,113.0000)"
},
"Items": {
"type": "array",
"valueArray": [
{
"type": "object",
"valueObject": {
"Description": {
"type": "string",
"valueString": "2 Surface Pro 6",
"spans": [ { "offset": 115, "length": 15}],
"confidence": 0.423,
"source": "D(1,704.0000,482.0000,875.0000,482.0000,875.0000,508.0000,704.0000,508.0000)"
},
"Amount": {
"type": "number",
"valueNumber": 1998,
"spans": [{ "offset": 140,"length": 9}
],
"confidence": 0.957,
"source": "D(1,952.0000,482.0000,1048.0000,482.0000,1048.0000,508.0000,952.0000,509.0000)"
}
}
}, ...
]
}
},
"kind": "document",
"startPageNumber": 1,
"endPageNumber": 1,
"unit": "pixel",
"pages": [
{
"pageNumber": 1,
"angle": -0.0944,
"width": 1743,
"height": 878
}
],
"analyzerId": "{analyzerId}",
"mimeType": "image/png"
}
]
},
"usage": {
"documentPages": 1,
"tokens": {
"contextualization": 1000
}
}
}
클라이언트 라이브러리 | 샘플 | SDK 원본
이 가이드에서는 Content Understanding Python SDK를 사용하여 콘텐츠에서 구조화된 데이터를 추출하는 사용자 지정 분석기를 만드는 방법을 보여 줍니다. 사용자 지정 분석기는 문서, 이미지, 오디오 및 비디오 콘텐츠 형식을 지원합니다.
필수 조건
- 활성 Azure 구독입니다. Azure 계정이 없는 경우 체험 계정을 만드세요.
- 지원되는 지역에서 만든 Microsoft Foundry 리소스입니다.
- 리소스 엔드포인트 및 API 키(Azure Portal의 키 및 엔드포인트 에서 찾을 수 있습니다).
- 리소스에 대해 구성된 모델 배포 기본값입니다. 설정 지침을 보려면 모델 및 배포 또는 이 일회성 구성 스크립트를 참조하세요.
- Python 3.9 이상.
설정
pip를 사용하여 Python용 Content Understanding 클라이언트 라이브러리를 설치합니다.
pip install azure-ai-contentunderstanding필요에 따라 Microsoft Entra 인증을 위한 Azure ID 라이브러리를 설치합니다.
pip install azure-identity
환경 변수 설정하기
Content Understanding 서비스를 사용하여 인증하려면 샘플을 실행하기 전에 사용자 고유의 값으로 환경 변수를 설정합니다.
-
CONTENTUNDERSTANDING_ENDPOINT- Content Understanding 리소스의 엔드포인트입니다. -
CONTENTUNDERSTANDING_KEY은 Content Understanding API 키를 의미하며, 만약 Microsoft Entra ID 의 DefaultAzureCredential을 사용하는 경우에는 생략할 수 있습니다.
윈도우즈
setx CONTENTUNDERSTANDING_ENDPOINT "your-endpoint"
setx CONTENTUNDERSTANDING_KEY "your-key"
Linux/macOS
export CONTENTUNDERSTANDING_ENDPOINT="your-endpoint"
export CONTENTUNDERSTANDING_KEY="your-key"
클라이언트 만들기
필요한 라이브러리 및 모델을 가져온 다음 리소스 엔드포인트 및 자격 증명을 사용하여 클라이언트를 만듭니다.
import os
import time
from azure.ai.contentunderstanding import ContentUnderstandingClient
from azure.core.credentials import AzureKeyCredential
endpoint = os.environ["CONTENTUNDERSTANDING_ENDPOINT"]
key = os.environ["CONTENTUNDERSTANDING_KEY"]
client = ContentUnderstandingClient(
endpoint=endpoint,
credential=AzureKeyCredential(key),
)
사용자 지정 분석기 만들기
다음 예제에서는 미리 빌드된 문서 기반 분석기를 기반으로 사용자 지정 문서 분석기를 만듭니다. 리터럴 텍스트는 extract으로, AI 생성 필드나 해석은 generate으로, 그리고 분류는 classify으로 세 가지 추출 방법을 사용하여 필드를 정의합니다.
from azure.ai.contentunderstanding.models import (
ContentAnalyzer,
ContentAnalyzerConfig,
ContentFieldSchema,
ContentFieldDefinition,
ContentFieldType,
GenerationMethod,
)
# Generate a unique analyzer ID
analyzer_id = f"my_document_analyzer_{int(time.time())}"
# Define field schema with custom fields
field_schema = ContentFieldSchema(
name="company_schema",
description="Schema for extracting company information",
fields={
"company_name": ContentFieldDefinition(
type=ContentFieldType.STRING,
method=GenerationMethod.EXTRACT,
description="Name of the company",
estimate_source_and_confidence=True,
),
"total_amount": ContentFieldDefinition(
type=ContentFieldType.NUMBER,
method=GenerationMethod.EXTRACT,
description="Total amount on the document",
estimate_source_and_confidence=True,
),
"document_summary": ContentFieldDefinition(
type=ContentFieldType.STRING,
method=GenerationMethod.GENERATE,
description=(
"A brief summary of the document content"
),
),
"document_type": ContentFieldDefinition(
type=ContentFieldType.STRING,
method=GenerationMethod.CLASSIFY,
description="Type of document",
enum=[
"invoice", "receipt", "contract",
"report", "other",
],
),
},
)
# Create analyzer configuration
config = ContentAnalyzerConfig(
enable_formula=True,
enable_layout=True,
enable_ocr=True,
estimate_field_source_and_confidence=True,
return_details=True,
)
# Create the analyzer with field schema
analyzer = ContentAnalyzer(
base_analyzer_id="prebuilt-document",
description=(
"Custom analyzer for extracting company information"
),
config=config,
field_schema=field_schema,
models={
"completion": "gpt-4.1",
"embedding": "text-embedding-3-large",
}, # Required when using field_schema and prebuilt-document base analyzer
)
# Create the analyzer
poller = client.begin_create_analyzer(
analyzer_id=analyzer_id,
resource=analyzer,
)
result = poller.result() # Wait for creation to complete
# Get the full analyzer details after creation
result = client.get_analyzer(analyzer_id=analyzer_id)
print(f"Analyzer '{analyzer_id}' created successfully!")
if result.description:
print(f" Description: {result.description}")
if result.field_schema and result.field_schema.fields:
print(f" Fields ({len(result.field_schema.fields)}):")
for field_name, field_def in result.field_schema.fields.items():
method = field_def.method if field_def.method else "auto"
field_type = field_def.type if field_def.type else "unknown"
print(f" - {field_name}: {field_type} ({method})")
예제 출력은 다음과 같습니다.
Analyzer 'my_document_analyzer_ID' created successfully!
Description: Custom analyzer for extracting company information
Fields (4):
- company_name: ContentFieldType.STRING (GenerationMethod.EXTRACT)
- total_amount: ContentFieldType.NUMBER (GenerationMethod.EXTRACT)
- document_summary: ContentFieldType.STRING (GenerationMethod.GENERATE)
- document_type: ContentFieldType.STRING (GenerationMethod.CLASSIFY)
팁 (조언)
이 코드는 SDK 리포지토리의 분석기 만들기 샘플을 기반으로 합니다.
필요에 따라 분류자 분석기를 만들어 문서를 분류하고 결과를 사용하여 문서를 미리 빌드된 분석기 또는 사용자 지정 분석기에 라우팅할 수 있습니다. 분류 워크플로에 대한 사용자 지정 분석기를 만드는 예제는 다음과 같습니다.
import time
from azure.ai.contentunderstanding.models import (
ContentAnalyzer,
ContentAnalyzerConfig,
ContentCategoryDefinition,
)
# Generate a unique analyzer ID
analyzer_id = f"my_classifier_{int(time.time())}"
print(f"Creating classifier '{analyzer_id}'...")
# Define content categories for classification
categories = {
"Loan_Application": ContentCategoryDefinition(
description="Documents submitted by individuals or businesses to request funding, "
"typically including personal or business details, financial history, "
"loan amount, purpose, and supporting documentation."
),
"Invoice": ContentCategoryDefinition(
description="Billing documents issued by sellers or service providers to request "
"payment for goods or services, detailing items, prices, taxes, totals, "
"and payment terms."
),
"Bank_Statement": ContentCategoryDefinition(
description="Official statements issued by banks that summarize account activity "
"over a period, including deposits, withdrawals, fees, and balances."
),
}
# Create analyzer configuration
config = ContentAnalyzerConfig(
return_details=True,
enable_segment=True, # Enable automatic segmentation by category
content_categories=categories,
)
# Create the classifier analyzer
classifier = ContentAnalyzer(
base_analyzer_id="prebuilt-document",
description="Custom classifier for financial document categorization",
config=config,
models={"completion": "gpt-4.1"},
)
# Create the classifier
poller = client.begin_create_analyzer(
analyzer_id=analyzer_id,
resource=classifier,
)
result = poller.result() # Wait for creation to complete
# Get the full analyzer details after creation
result = client.get_analyzer(analyzer_id=analyzer_id)
print(f"Classifier '{analyzer_id}' created successfully!")
if result.description:
print(f" Description: {result.description}")
팁 (조언)
이 코드는 SDK 리포지토리의 분류자 만들기 샘플을 기반으로 합니다.
사용자 지정 분석기 사용
분석기를 만든 후 이 분석기를 사용하여 문서를 분석하고 사용자 지정 필드를 추출합니다. 더 이상 필요하지 않은 경우 분석기를 삭제합니다.
# --- Use the custom document analyzer ---
from azure.ai.contentunderstanding.models import AnalysisInput
print("\nAnalyzing document...")
document_url = (
"https://raw.githubusercontent.com/"
"Azure-Samples/"
"azure-ai-content-understanding-assets/"
"main/document/invoice.pdf"
)
poller = client.begin_analyze(
analyzer_id=analyzer_id,
inputs=[AnalysisInput(url=document_url)],
)
result = poller.result()
if result.contents and len(result.contents) > 0:
content = result.contents[0]
if content.fields:
company = content.fields.get("company_name")
if company:
print(f"Company Name: {company.value}")
if company.confidence:
print(
f" Confidence:"
f" {company.confidence:.2f}"
)
total = content.fields.get("total_amount")
if total:
print(f"Total Amount: {total.value}")
summary = content.fields.get(
"document_summary"
)
if summary:
print(f"Summary: {summary.value}")
doc_type = content.fields.get("document_type")
if doc_type:
print(f"Document Type: {doc_type.value}")
else:
print("No content returned from analysis.")
# --- Clean up ---
print(f"\nCleaning up: deleting analyzer '{analyzer_id}'...")
client.delete_analyzer(analyzer_id=analyzer_id)
print(f"Analyzer '{analyzer_id}' deleted successfully.")
예제 출력은 다음과 같습니다.
Analyzing document...
Company Name: CONTOSO LTD.
Confidence: 0.81
Total Amount: 610.0
Summary: This document is an invoice from CONTOSO LTD. to Microsoft Corporation for consulting, document, and printing services provided during the service period. It details line items, subtotal, sales tax, total, previous unpaid balance, and the final amount due.
Document Type: invoice
Cleaning up: deleting analyzer 'my_document_analyzer_ID'...
Analyzer 'my_document_analyzer_ID' deleted successfully.
팁 (조언)
SDK 샘플에서 분석기를 실행하는 더 많은 예제를 확인하세요.
클라이언트 라이브러리 | 샘플 | SDK 원본
이 가이드에서는 Content Understanding .NET SDK를 사용하여 콘텐츠에서 구조화된 데이터를 추출하는 사용자 지정 분석기를 만드는 방법을 보여 줍니다. 사용자 지정 분석기는 문서, 이미지, 오디오 및 비디오 콘텐츠 형식을 지원합니다.
필수 조건
- 활성 Azure 구독입니다. Azure 계정이 없는 경우 체험 계정을 만드세요.
- 지원되는 지역에서 만든 Microsoft Foundry 리소스입니다.
- 리소스 엔드포인트 및 API 키(Azure Portal의 키 및 엔드포인트 에서 찾을 수 있습니다).
- 리소스에 대해 구성된 모델 배포 기본값입니다. 설정 지침을 보려면 모델 및 배포 또는 이 일회성 구성 스크립트를 참조하세요.
- .NET의 현재 버전입니다.
설정
새 .NET 콘솔 애플리케이션을 만듭니다.
dotnet new console -n CustomAnalyzerTutorial cd CustomAnalyzerTutorial.NET용 Content Understanding 클라이언트 라이브러리를 설치합니다.
dotnet add package Azure.AI.ContentUnderstanding필요에 따라 Microsoft Entra 인증을 위한 Azure ID 라이브러리를 설치합니다.
dotnet add package Azure.Identity
환경 변수 설정하기
Content Understanding 서비스를 사용하여 인증하려면 샘플을 실행하기 전에 사용자 고유의 값으로 환경 변수를 설정합니다.
-
CONTENTUNDERSTANDING_ENDPOINT- Content Understanding 리소스의 엔드포인트입니다. -
CONTENTUNDERSTANDING_KEY은 Content Understanding API 키를 의미하며, 만약 Microsoft Entra ID 의 DefaultAzureCredential을 사용하는 경우에는 생략할 수 있습니다.
윈도우즈
setx CONTENTUNDERSTANDING_ENDPOINT "your-endpoint"
setx CONTENTUNDERSTANDING_KEY "your-key"
Linux/macOS
export CONTENTUNDERSTANDING_ENDPOINT="your-endpoint"
export CONTENTUNDERSTANDING_KEY="your-key"
클라이언트 만들기
using Azure;
using Azure.AI.ContentUnderstanding;
string endpoint = Environment.GetEnvironmentVariable(
"CONTENTUNDERSTANDING_ENDPOINT");
string key = Environment.GetEnvironmentVariable(
"CONTENTUNDERSTANDING_KEY");
var client = new ContentUnderstandingClient(
new Uri(endpoint),
new AzureKeyCredential(key)
);
사용자 지정 분석기 만들기
다음 예제에서는 미리 빌드된 문서 분석기를 기반으로 사용자 지정 문서 분석기를 만듭니다. 세 가지 extract 리터럴 텍스트, generate AI 생성 요약 및 classify 분류 추출 방법을 사용하여 필드를 정의합니다.
string analyzerId =
$"my_document_analyzer_{DateTimeOffset.UtcNow.ToUnixTimeSeconds()}";
var fieldSchema = new ContentFieldSchema(
new Dictionary<string, ContentFieldDefinition>
{
["company_name"] = new ContentFieldDefinition
{
Type = ContentFieldType.String,
Method = GenerationMethod.Extract,
Description = "Name of the company"
},
["total_amount"] = new ContentFieldDefinition
{
Type = ContentFieldType.Number,
Method = GenerationMethod.Extract,
Description =
"Total amount on the document"
},
["document_summary"] = new ContentFieldDefinition
{
Type = ContentFieldType.String,
Method = GenerationMethod.Generate,
Description =
"A brief summary of the document content"
},
["document_type"] = new ContentFieldDefinition
{
Type = ContentFieldType.String,
Method = GenerationMethod.Classify,
Description = "Type of document"
}
})
{
Name = "company_schema",
Description =
"Schema for extracting company information"
};
fieldSchema.Fields["document_type"].Enum.Add("invoice");
fieldSchema.Fields["document_type"].Enum.Add("receipt");
fieldSchema.Fields["document_type"].Enum.Add("contract");
fieldSchema.Fields["document_type"].Enum.Add("report");
fieldSchema.Fields["document_type"].Enum.Add("other");
var config = new ContentAnalyzerConfig
{
EnableFormula = true,
EnableLayout = true,
EnableOcr = true,
EstimateFieldSourceAndConfidence = true,
ShouldReturnDetails = true
};
var customAnalyzer = new ContentAnalyzer
{
BaseAnalyzerId = "prebuilt-document",
Description =
"Custom analyzer for extracting"
+ " company information",
Config = config,
FieldSchema = fieldSchema
};
customAnalyzer.Models["completion"] = "gpt-4.1";
customAnalyzer.Models["embedding"] =
"text-embedding-3-large"; // Required when using field_schema and prebuilt-document base analyzer
var operation = await client.CreateAnalyzerAsync(
WaitUntil.Completed,
analyzerId,
customAnalyzer);
ContentAnalyzer result = operation.Value;
Console.WriteLine(
$"Analyzer '{analyzerId}'"
+ " created successfully!");
// Get the full analyzer details after creation
var analyzerDetails =
await client.GetAnalyzerAsync(analyzerId);
result = analyzerDetails.Value;
if (result.Description != null)
{
Console.WriteLine(
$" Description: {result.Description}");
}
if (result.FieldSchema?.Fields != null)
{
Console.WriteLine(
$" Fields"
+ $" ({result.FieldSchema.Fields.Count}):");
foreach (var kvp
in result.FieldSchema.Fields)
{
var method =
kvp.Value.Method?.ToString()
?? "auto";
var fieldType =
kvp.Value.Type?.ToString()
?? "unknown";
Console.WriteLine(
$" - {kvp.Key}:"
+ $" {fieldType} ({method})");
}
}
예제 출력은 다음과 같습니다.
Analyzer 'my_document_analyzer_ID' created successfully!
Description: Custom analyzer for extracting company information
Fields (4):
- company_name: string (extract)
- total_amount: number (extract)
- document_summary: string (generate)
- document_type: string (classify)
팁 (조언)
이 코드는 SDK 리포지토리의 분석기 만들기 샘플을 기반으로 합니다.
필요에 따라 분류자 분석기를 만들어 문서를 분류하고 결과를 사용하여 문서를 미리 빌드된 분석기 또는 사용자 지정 분석기에 라우팅할 수 있습니다. 분류 워크플로에 대한 사용자 지정 분석기를 만드는 예제는 다음과 같습니다.
// Generate a unique analyzer ID
string classifierId =
$"my_classifier_{DateTimeOffset.UtcNow.ToUnixTimeSeconds()}";
Console.WriteLine(
$"Creating classifier '{classifierId}'...");
// Define content categories for classification
var classifierConfig = new ContentAnalyzerConfig
{
ShouldReturnDetails = true,
EnableSegment = true
};
classifierConfig.ContentCategories
.Add("Loan_Application",
new ContentCategoryDefinition
{
Description =
"Documents submitted by individuals"
+ " or businesses to request"
+ " funding, typically including"
+ " personal or business details,"
+ " financial history, loan amount,"
+ " purpose, and supporting"
+ " documentation."
});
classifierConfig.ContentCategories
.Add("Invoice",
new ContentCategoryDefinition
{
Description =
"Billing documents issued by"
+ " sellers or service providers"
+ " to request payment for goods"
+ " or services, detailing items,"
+ " prices, taxes, totals, and"
+ " payment terms."
});
classifierConfig.ContentCategories
.Add("Bank_Statement",
new ContentCategoryDefinition
{
Description =
"Official statements issued by"
+ " banks that summarize account"
+ " activity over a period,"
+ " including deposits,"
+ " withdrawals, fees,"
+ " and balances."
});
// Create the classifier analyzer
var classifierAnalyzer = new ContentAnalyzer
{
BaseAnalyzerId = "prebuilt-document",
Description =
"Custom classifier for financial"
+ " document categorization",
Config = classifierConfig
};
classifierAnalyzer.Models["completion"] =
"gpt-4.1";
var classifierOp =
await client.CreateAnalyzerAsync(
WaitUntil.Completed,
classifierId,
classifierAnalyzer);
// Get the full classifier details
var classifierDetails =
await client.GetAnalyzerAsync(classifierId);
var classifierResult =
classifierDetails.Value;
Console.WriteLine(
$"Classifier '{classifierId}'"
+ " created successfully!");
if (classifierResult.Description != null)
{
Console.WriteLine(
$" Description:"
+ $" {classifierResult.Description}");
}
팁 (조언)
이 코드는 분류 워크플로에 대한 분류자 만들기 샘플을 기반으로 합니다.
사용자 지정 분석기 사용
분석기를 만든 후 이 분석기를 사용하여 문서를 분석하고 사용자 지정 필드를 추출합니다. 더 이상 필요하지 않은 경우 분석기를 삭제합니다.
var documentUrl = new Uri(
"https://raw.githubusercontent.com/"
+ "Azure-Samples/"
+ "azure-ai-content-understanding-assets/"
+ "main/document/invoice.pdf"
);
var analyzeOperation = await client.AnalyzeAsync(
WaitUntil.Completed,
analyzerId,
inputs: new[] {
new AnalysisInput { Uri = documentUrl }
});
var analyzeResult = analyzeOperation.Value;
if (analyzeResult.Contents?.FirstOrDefault()
is DocumentContent content)
{
if (content.Fields.TryGetValue(
"company_name", out var companyField))
{
var name =
companyField is ContentStringField sf
? sf.Value : null;
Console.WriteLine(
$"Company Name: "
+ $"{name ?? "(not found)"}");
Console.WriteLine(
" Confidence: "
+ (companyField.Confidence?
.ToString("F2") ?? "N/A"));
}
if (content.Fields.TryGetValue(
"total_amount", out var totalField))
{
var total =
totalField is ContentNumberField nf
? nf.Value : null;
Console.WriteLine(
$"Total Amount: {total}");
}
if (content.Fields.TryGetValue(
"document_summary", out var summaryField))
{
var summary =
summaryField is ContentStringField sf
? sf.Value : null;
Console.WriteLine(
$"Summary: "
+ $"{summary ?? "(not found)"}");
}
if (content.Fields.TryGetValue(
"document_type", out var typeField))
{
var docType =
typeField is ContentStringField sf
? sf.Value : null;
Console.WriteLine(
$"Document Type: "
+ $"{docType ?? "(not found)"}");
}
}
// --- Clean up ---
Console.WriteLine(
$"\nCleaning up: deleting analyzer"
+ $" '{analyzerId}'...");
await client.DeleteAnalyzerAsync(analyzerId);
Console.WriteLine(
$"Analyzer '{analyzerId}'"
+ " deleted successfully.");
예제 출력은 다음과 같습니다.
Company Name: CONTOSO LTD.
Confidence: 0.88
Total Amount: 610
Summary: This document is an invoice from CONTOSO LTD. to MICROSOFT CORPORATION for consulting services, document fees, and printing fees, detailing service periods, billing and shipping addresses, itemized charges, and the total amount due.
Document Type: invoice
Cleaning up: deleting analyzer 'my_document_analyzer_ID'...
Analyzer 'my_document_analyzer_ID' deleted successfully.
팁 (조언)
.NET SDK 샘플에서 분석기를 실행하는 더 많은 예제를 확인하세요.
클라이언트 라이브러리 | 샘플 | SDK 원본
이 가이드에서는 Content Understanding Java SDK를 사용하여 콘텐츠에서 구조화된 데이터를 추출하는 사용자 지정 분석기를 만드는 방법을 보여 줍니다. 사용자 지정 분석기는 문서, 이미지, 오디오 및 비디오 콘텐츠 형식을 지원합니다.
필수 조건
- 활성 Azure 구독입니다. Azure 계정이 없는 경우 체험 계정을 만드세요.
- 지원되는 지역에서 만든 Microsoft Foundry 리소스입니다.
- 리소스 엔드포인트 및 API 키(Azure Portal의 키 및 엔드포인트 에서 찾을 수 있습니다).
- 리소스에 대해 구성된 모델 배포 기본값입니다. 설정 지침을 보려면 모델 및 배포 또는 이 일회성 구성 스크립트를 참조하세요.
- JDK(Java Development Kit) 버전 8 이상
- Apache Maven.
설정
새 Maven 프로젝트를 만듭니다.
mvn archetype:generate -DgroupId=com.example \ -DartifactId=custom-analyzer-tutorial \ -DarchetypeArtifactId=maven-archetype-quickstart \ -DinteractiveMode=false cd custom-analyzer-tutorial섹션의 pom.xml 파일에
<dependencies>Content Understanding 종속성을 추가합니다.<dependency> <groupId>com.azure</groupId> <artifactId>azure-ai-contentunderstanding</artifactId> <version>1.0.0</version> </dependency>필요에 따라 Microsoft Entra 인증을 위한 Azure ID 라이브러리를 추가합니다.
<dependency> <groupId>com.azure</groupId> <artifactId>azure-identity</artifactId> <version>1.14.2</version> </dependency>
환경 변수 설정하기
Content Understanding 서비스를 사용하여 인증하려면 샘플을 실행하기 전에 사용자 고유의 값으로 환경 변수를 설정합니다.
-
CONTENTUNDERSTANDING_ENDPOINT- Content Understanding 리소스의 엔드포인트입니다. -
CONTENTUNDERSTANDING_KEY은 Content Understanding API 키를 의미하며, 만약 Microsoft Entra ID 의 DefaultAzureCredential을 사용하는 경우에는 생략할 수 있습니다.
윈도우즈
setx CONTENTUNDERSTANDING_ENDPOINT "your-endpoint"
setx CONTENTUNDERSTANDING_KEY "your-key"
Linux/macOS
export CONTENTUNDERSTANDING_ENDPOINT="your-endpoint"
export CONTENTUNDERSTANDING_KEY="your-key"
클라이언트 만들기
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import com.azure.core.credential.AzureKeyCredential;
import com.azure.core.util.polling.SyncPoller;
import com.azure.ai.contentunderstanding
.ContentUnderstandingClient;
import com.azure.ai.contentunderstanding
.ContentUnderstandingClientBuilder;
import com.azure.ai.contentunderstanding.models.*;
String endpoint =
System.getenv("CONTENTUNDERSTANDING_ENDPOINT");
String key =
System.getenv("CONTENTUNDERSTANDING_KEY");
ContentUnderstandingClient client =
new ContentUnderstandingClientBuilder()
.endpoint(endpoint)
.credential(new AzureKeyCredential(key))
.buildClient();
사용자 지정 분석기 만들기
다음 예제에서는 미리 빌드된 문서 분석기를 기반으로 사용자 지정 문서 분석기를 만듭니다. 세 가지 extract 리터럴 텍스트, generate AI 생성 요약 및 classify 분류 추출 방법을 사용하여 필드를 정의합니다.
String analyzerId =
"my_document_analyzer_"
+ System.currentTimeMillis();
Map<String, ContentFieldDefinition> fields =
new HashMap<>();
ContentFieldDefinition companyNameDef =
new ContentFieldDefinition();
companyNameDef.setType(ContentFieldType.STRING);
companyNameDef.setMethod(
GenerationMethod.EXTRACT);
companyNameDef.setDescription(
"Name of the company");
fields.put("company_name", companyNameDef);
ContentFieldDefinition totalAmountDef =
new ContentFieldDefinition();
totalAmountDef.setType(ContentFieldType.NUMBER);
totalAmountDef.setMethod(
GenerationMethod.EXTRACT);
totalAmountDef.setDescription(
"Total amount on the document");
fields.put("total_amount", totalAmountDef);
ContentFieldDefinition summaryDef =
new ContentFieldDefinition();
summaryDef.setType(ContentFieldType.STRING);
summaryDef.setMethod(
GenerationMethod.GENERATE);
summaryDef.setDescription(
"A brief summary of the document content");
fields.put("document_summary", summaryDef);
ContentFieldDefinition documentTypeDef =
new ContentFieldDefinition();
documentTypeDef.setType(ContentFieldType.STRING);
documentTypeDef.setMethod(
GenerationMethod.CLASSIFY);
documentTypeDef.setDescription(
"Type of document");
documentTypeDef.setEnumProperty(
Arrays.asList(
"invoice", "receipt", "contract",
"report", "other"
));
fields.put("document_type", documentTypeDef);
ContentFieldSchema fieldSchema =
new ContentFieldSchema();
fieldSchema.setName("company_schema");
fieldSchema.setDescription(
"Schema for extracting company information");
fieldSchema.setFields(fields);
Map<String, String> models = new HashMap<>();
models.put("completion", "gpt-4.1");
models.put("embedding", "text-embedding-3-large"); // Required when using field_schema and prebuilt-document base analyzer
ContentAnalyzer customAnalyzer =
new ContentAnalyzer()
.setBaseAnalyzerId("prebuilt-document")
.setDescription(
"Custom analyzer for extracting"
+ " company information")
.setConfig(new ContentAnalyzerConfig()
.setOcrEnabled(true)
.setLayoutEnabled(true)
.setFormulaEnabled(true)
.setEstimateFieldSourceAndConfidence(
true)
.setReturnDetails(true))
.setFieldSchema(fieldSchema)
.setModels(models);
SyncPoller<ContentAnalyzerOperationStatus,
ContentAnalyzer> operation =
client.beginCreateAnalyzer(
analyzerId, customAnalyzer, true);
ContentAnalyzer result =
operation.getFinalResult();
System.out.println(
"Analyzer '" + analyzerId
+ "' created successfully!");
if (result.getDescription() != null) {
System.out.println(
" Description: "
+ result.getDescription());
}
if (result.getFieldSchema() != null
&& result.getFieldSchema()
.getFields() != null) {
System.out.println(
" Fields ("
+ result.getFieldSchema()
.getFields().size() + "):");
result.getFieldSchema().getFields()
.forEach((fieldName, fieldDef) -> {
String method =
fieldDef.getMethod() != null
? fieldDef.getMethod()
.toString()
: "auto";
String type =
fieldDef.getType() != null
? fieldDef.getType()
.toString()
: "unknown";
System.out.println(
" - " + fieldName
+ ": " + type
+ " (" + method + ")");
});
}
예제 출력은 다음과 같습니다.
Analyzer 'my_document_analyzer_ID' created successfully!
Description: Custom analyzer for extracting company information
Fields (4):
- total_amount: number (extract)
- company_name: string (extract)
- document_summary: string (generate)
- document_type: string (classify)
팁 (조언)
이 코드는 SDK 리포지토리의 분석기 만들기 샘플을 기반으로 합니다.
필요에 따라 분류자 분석기를 만들어 문서를 분류하고 결과를 사용하여 문서를 미리 빌드된 분석기 또는 사용자 지정 분석기에 라우팅할 수 있습니다. 분류 워크플로에 대한 사용자 지정 분석기를 만드는 예제는 다음과 같습니다.
// Generate a unique analyzer ID
String classifierId =
"my_classifier_" + System.currentTimeMillis();
System.out.println(
"Creating classifier '"
+ classifierId + "'...");
// Define content categories for classification
Map<String, ContentCategoryDefinition>
categories = new HashMap<>();
categories.put("Loan_Application",
new ContentCategoryDefinition()
.setDescription(
"Documents submitted by individuals"
+ " or businesses to request funding,"
+ " typically including personal or"
+ " business details, financial"
+ " history, loan amount, purpose,"
+ " and supporting documentation."));
categories.put("Invoice",
new ContentCategoryDefinition()
.setDescription(
"Billing documents issued by sellers"
+ " or service providers to request"
+ " payment for goods or services,"
+ " detailing items, prices, taxes,"
+ " totals, and payment terms."));
categories.put("Bank_Statement",
new ContentCategoryDefinition()
.setDescription(
"Official statements issued by banks"
+ " that summarize account activity"
+ " over a period, including deposits,"
+ " withdrawals, fees,"
+ " and balances."));
// Create the classifier
Map<String, String> classifierModels =
new HashMap<>();
classifierModels.put("completion", "gpt-4.1");
ContentAnalyzer classifier =
new ContentAnalyzer()
.setBaseAnalyzerId("prebuilt-document")
.setDescription(
"Custom classifier for financial"
+ " document categorization")
.setConfig(new ContentAnalyzerConfig()
.setReturnDetails(true)
.setSegmentEnabled(true)
.setContentCategories(categories))
.setModels(classifierModels);
SyncPoller<ContentAnalyzerOperationStatus,
ContentAnalyzer> classifierOp =
client.beginCreateAnalyzer(
classifierId, classifier, true);
classifierOp.getFinalResult();
// Get the full classifier details
ContentAnalyzer classifierResult =
client.getAnalyzer(classifierId);
System.out.println(
"Classifier '" + classifierId
+ "' created successfully!");
if (classifierResult.getDescription() != null) {
System.out.println(
" Description: "
+ classifierResult.getDescription());
}
팁 (조언)
이 코드는 분류 워크플로에 대한 분류자 만들기 샘플을 기반으로 합니다.
사용자 지정 분석기 사용
분석기를 만든 후 이 분석기를 사용하여 문서를 분석하고 사용자 지정 필드를 추출합니다. 더 이상 필요하지 않은 경우 분석기를 삭제합니다.
String documentUrl =
"https://raw.githubusercontent.com/"
+ "Azure-Samples/"
+ "azure-ai-content-understanding-assets/"
+ "main/document/invoice.pdf";
AnalysisInput input = new AnalysisInput();
input.setUrl(documentUrl);
SyncPoller<ContentAnalyzerAnalyzeOperationStatus,
AnalysisResult> analyzeOperation =
client.beginAnalyze(
analyzerId, Arrays.asList(input));
AnalysisResult analyzeResult =
analyzeOperation.getFinalResult();
if (analyzeResult.getContents() != null
&& !analyzeResult.getContents().isEmpty()
&& analyzeResult.getContents().get(0)
instanceof DocumentContent) {
DocumentContent content =
(DocumentContent) analyzeResult
.getContents().get(0);
ContentField companyField =
content.getFields() != null
? content.getFields()
.get("company_name") : null;
if (companyField
instanceof ContentStringField) {
ContentStringField sf =
(ContentStringField) companyField;
System.out.println(
"Company Name: " + sf.getValue());
System.out.println(
" Confidence: "
+ companyField.getConfidence());
}
ContentField totalField =
content.getFields() != null
? content.getFields()
.get("total_amount") : null;
if (totalField != null) {
System.out.println(
"Total Amount: "
+ totalField.getValue());
}
ContentField summaryField =
content.getFields() != null
? content.getFields()
.get("document_summary") : null;
if (summaryField
instanceof ContentStringField) {
ContentStringField sf =
(ContentStringField) summaryField;
System.out.println(
"Summary: " + sf.getValue());
}
ContentField typeField =
content.getFields() != null
? content.getFields()
.get("document_type") : null;
if (typeField
instanceof ContentStringField) {
ContentStringField sf =
(ContentStringField) typeField;
System.out.println(
"Document Type: " + sf.getValue());
}
}
// --- Clean up ---
System.out.println(
"\nCleaning up: deleting analyzer '"
+ analyzerId + "'...");
client.deleteAnalyzer(analyzerId);
System.out.println(
"Analyzer '" + analyzerId
+ "' deleted successfully.");
예제 출력은 다음과 같습니다.
Company Name: CONTOSO LTD.
Confidence: 0.781
Total Amount: 610.0
Summary: This document is an invoice from CONTOSO LTD. to Microsoft Corporation for consulting services, document fees, and printing fees, detailing service dates, itemized charges, taxes, and the total amount due.
Document Type: invoice
Cleaning up: deleting analyzer 'my_document_analyzer_ID'...
Analyzer 'my_document_analyzer_ID' deleted successfully.
팁 (조언)
Java SDK 샘플에서 분석기를 실행하는 더 많은 예제를 확인하세요.
클라이언트 라이브러리 | 샘플 | SDK 원본
이 가이드에서는 Content Understanding JavaScript SDK를 사용하여 콘텐츠에서 구조화된 데이터를 추출하는 사용자 지정 분석기를 만드는 방법을 보여 줍니다. 사용자 지정 분석기는 문서, 이미지, 오디오 및 비디오 콘텐츠 형식을 지원합니다.
필수 조건
- 활성 Azure 구독입니다. Azure 계정이 없는 경우 체험 계정을 만드세요.
- 지원되는 지역에서 만든 Microsoft Foundry 리소스입니다.
- 리소스 엔드포인트 및 API 키(Azure Portal의 키 및 엔드포인트 에서 찾을 수 있습니다).
- 리소스에 대해 구성된 모델 배포 기본값입니다. 설정 지침을 보려면 모델 및 배포 또는 이 일회성 구성 스크립트를 참조하세요.
- Node.js LTS 버전입니다.
설정
새 Node.js 프로젝트를 만듭니다.
mkdir custom-analyzer-tutorial cd custom-analyzer-tutorial npm init -yContent Understanding 클라이언트 라이브러리를 설치합니다.
npm install @azure/ai-content-understanding필요에 따라 Microsoft Entra 인증을 위한 Azure ID 라이브러리를 설치합니다.
npm install @azure/identity
환경 변수 설정하기
Content Understanding 서비스를 사용하여 인증하려면 샘플을 실행하기 전에 사용자 고유의 값으로 환경 변수를 설정합니다.
-
CONTENTUNDERSTANDING_ENDPOINT- Content Understanding 리소스의 엔드포인트입니다. -
CONTENTUNDERSTANDING_KEY은 Content Understanding API 키를 의미하며, 만약 Microsoft Entra ID 의 DefaultAzureCredential을 사용하는 경우에는 생략할 수 있습니다.
윈도우즈
setx CONTENTUNDERSTANDING_ENDPOINT "your-endpoint"
setx CONTENTUNDERSTANDING_KEY "your-key"
Linux/macOS
export CONTENTUNDERSTANDING_ENDPOINT="your-endpoint"
export CONTENTUNDERSTANDING_KEY="your-key"
클라이언트 만들기
const { AzureKeyCredential } =
require("@azure/core-auth");
const {
ContentUnderstandingClient,
} = require("@azure/ai-content-understanding");
const endpoint =
process.env["CONTENTUNDERSTANDING_ENDPOINT"];
const key =
process.env["CONTENTUNDERSTANDING_KEY"];
const client = new ContentUnderstandingClient(
endpoint,
new AzureKeyCredential(key)
);
사용자 지정 분석기 만들기
다음 예제에서는 미리 빌드된 문서 분석기를 기반으로 사용자 지정 문서 분석기를 만듭니다. 세 가지 extract 리터럴 텍스트, generate AI 생성 요약 및 classify 분류 추출 방법을 사용하여 필드를 정의합니다.
const analyzerId =
`my_document_analyzer_${Math.floor(
Date.now() / 1000
)}`;
const analyzer = {
baseAnalyzerId: "prebuilt-document",
description:
"Custom analyzer for extracting"
+ " company information",
config: {
enableFormula: true,
enableLayout: true,
enableOcr: true,
estimateFieldSourceAndConfidence: true,
returnDetails: true,
},
fieldSchema: {
name: "company_schema",
description:
"Schema for extracting company"
+ " information",
fields: {
company_name: {
type: "string",
method: "extract",
description:
"Name of the company",
},
total_amount: {
type: "number",
method: "extract",
description:
"Total amount on the"
+ " document",
},
document_summary: {
type: "string",
method: "generate",
description:
"A brief summary of the"
+ " document content",
},
document_type: {
type: "string",
method: "classify",
description: "Type of document",
enum: [
"invoice", "receipt",
"contract", "report", "other",
],
},
},
},
models: {
completion: "gpt-4.1",
embedding: "text-embedding-3-large", // Required when using field_schema and prebuilt-document base analyzer
},
};
const poller = client.createAnalyzer(
analyzerId, analyzer
);
await poller.pollUntilDone();
const result = await client.getAnalyzer(
analyzerId
);
console.log(
`Analyzer '${analyzerId}' created`
+ ` successfully!`
);
if (result.description) {
console.log(
` Description: ${result.description}`
);
}
if (result.fieldSchema?.fields) {
const fields = result.fieldSchema.fields;
console.log(
` Fields`
+ ` (${Object.keys(fields).length}):`
);
for (const [name, fieldDef]
of Object.entries(fields)) {
const method =
fieldDef.method ?? "auto";
const fieldType =
fieldDef.type ?? "unknown";
console.log(
` - ${name}: `
+ `${fieldType} (${method})`
);
}
}
예제 출력은 다음과 같습니다.
Analyzer 'my_document_analyzer_ID' created successfully!
Description: Custom analyzer for extracting company information
Fields (4):
- company_name: string (extract)
- total_amount: number (extract)
- document_summary: string (generate)
- document_type: string (classify)
팁 (조언)
이 코드는 SDK 리포지토리의 분석기 만들기 샘플을 기반으로 합니다.
필요에 따라 분류자 분석기를 만들어 문서를 분류하고 결과를 사용하여 문서를 미리 빌드된 분석기 또는 사용자 지정 분석기에 라우팅할 수 있습니다. 분류 워크플로에 대한 사용자 지정 분석기를 만드는 예제는 다음과 같습니다.
const classifierId =
`my_classifier_${Math.floor(
Date.now() / 1000
)}`;
console.log(
`Creating classifier '${classifierId}'...`
);
const classifierAnalyzer = {
baseAnalyzerId: "prebuilt-document",
description:
"Custom classifier for financial"
+ " document categorization",
config: {
returnDetails: true,
enableSegment: true,
contentCategories: {
Loan_Application: {
description:
"Documents submitted by"
+ " individuals or"
+ " businesses to request"
+ " funding, typically"
+ " including personal or"
+ " business details,"
+ " financial history,"
+ " loan amount, purpose,"
+ " and supporting"
+ " documentation.",
},
Invoice: {
description:
"Billing documents issued"
+ " by sellers or service"
+ " providers to request"
+ " payment for goods or"
+ " services, detailing"
+ " items, prices, taxes,"
+ " totals, and payment"
+ " terms.",
},
Bank_Statement: {
description:
"Official statements"
+ " issued by banks that"
+ " summarize account"
+ " activity over a"
+ " period, including"
+ " deposits, withdrawals,"
+ " fees, and balances.",
},
},
},
models: {
completion: "gpt-4.1",
},
};
const classifierPoller =
client.createAnalyzer(
classifierId, classifierAnalyzer
);
await classifierPoller.pollUntilDone();
const classifierResult =
await client.getAnalyzer(classifierId);
console.log(
`Classifier '${classifierId}' created`
+ ` successfully!`
);
if (classifierResult.description) {
console.log(
` Description: `
+ `${classifierResult.description}`
);
}
팁 (조언)
이 코드는 분류 워크플로에 대한 분류자 만들기 샘플을 기반으로 합니다.
사용자 지정 분석기 사용
분석기를 만든 후 이 분석기를 사용하여 문서를 분석하고 사용자 지정 필드를 추출합니다. 더 이상 필요하지 않은 경우 분석기를 삭제합니다.
const documentUrl =
"https://raw.githubusercontent.com/"
+ "Azure-Samples/"
+ "azure-ai-content-understanding-assets/"
+ "main/document/invoice.pdf";
const analyzePoller = client.analyze(
analyzerId, [{ url: documentUrl }]
);
const analyzeResult =
await analyzePoller.pollUntilDone();
if (analyzeResult.contents
&& analyzeResult.contents.length > 0) {
const content = analyzeResult.contents[0];
if (content.fields) {
const company =
content.fields["company_name"];
if (company) {
console.log(
`Company Name: `
+ `${company.value}`
);
console.log(
` Confidence: `
+ `${company.confidence}`
);
}
const total =
content.fields["total_amount"];
if (total) {
console.log(
`Total Amount: `
+ `${total.value}`
);
}
const summary =
content.fields["document_summary"];
if (summary) {
console.log(
`Summary: ${summary.value}`
);
}
const docType =
content.fields["document_type"];
if (docType) {
console.log(
`Document Type: `
+ `${docType.value}`
);
}
}
}
// --- Clean up ---
console.log(
`\nCleaning up: deleting analyzer`
+ ` '${analyzerId}'...`
);
await client.deleteAnalyzer(analyzerId);
console.log(
`Analyzer '${analyzerId}' deleted`
+ ` successfully.`
);
예제 출력은 다음과 같습니다.
Company Name: CONTOSO LTD.
Confidence: 0.739
Total Amount: 610
Summary: This document is an invoice from CONTOSO LTD. to Microsoft Corporation for consulting, document, and printing services provided during the service period. It details line items, subtotal, sales tax, total, previous unpaid balance, and the final amount due.
Document Type: invoice
Cleaning up: deleting analyzer 'my_document_analyzer_ID'...
Analyzer 'my_document_analyzer_ID' deleted successfully.
팁 (조언)
JavaScript SDK 샘플에서 분석기를 실행하는 더 많은 예제를 확인하세요.
클라이언트 라이브러리 | 샘플 | SDK 원본
이 가이드에서는 Content Understanding TypeScript SDK를 사용하여 콘텐츠에서 구조화된 데이터를 추출하는 사용자 지정 분석기를 만드는 방법을 보여 줍니다. 사용자 지정 분석기는 문서, 이미지, 오디오 및 비디오 콘텐츠 형식을 지원합니다.
필수 조건
- 활성 Azure 구독입니다. Azure 계정이 없는 경우 체험 계정을 만드세요.
- 지원되는 지역에서 만든 Microsoft Foundry 리소스입니다.
- 리소스 엔드포인트 및 API 키(Azure Portal의 키 및 엔드포인트 에서 찾을 수 있습니다).
- 리소스에 대해 구성된 모델 배포 기본값입니다. 설정 지침을 보려면 모델 및 배포 또는 이 일회성 구성 스크립트를 참조하세요.
- Node.js LTS 버전입니다.
- TypeScript 5.x 이상.
설정
새 Node.js 프로젝트를 만듭니다.
mkdir custom-analyzer-tutorial cd custom-analyzer-tutorial npm init -yTypeScript 및 Content Understanding 클라이언트 라이브러리를 설치합니다.
npm install typescript ts-node @azure/ai-content-understanding필요에 따라 Microsoft Entra 인증을 위한 Azure ID 라이브러리를 설치합니다.
npm install @azure/identity
환경 변수 설정하기
Content Understanding 서비스를 사용하여 인증하려면 샘플을 실행하기 전에 사용자 고유의 값으로 환경 변수를 설정합니다.
-
CONTENTUNDERSTANDING_ENDPOINT- Content Understanding 리소스의 엔드포인트입니다. -
CONTENTUNDERSTANDING_KEY은 Content Understanding API 키를 의미하며, 만약 Microsoft Entra ID 의 DefaultAzureCredential을 사용하는 경우에는 생략할 수 있습니다.
윈도우즈
setx CONTENTUNDERSTANDING_ENDPOINT "your-endpoint"
setx CONTENTUNDERSTANDING_KEY "your-key"
Linux/macOS
export CONTENTUNDERSTANDING_ENDPOINT="your-endpoint"
export CONTENTUNDERSTANDING_KEY="your-key"
클라이언트 만들기
import { AzureKeyCredential } from "@azure/core-auth";
import {
ContentUnderstandingClient,
} from "@azure/ai-content-understanding";
import type {
ContentAnalyzer,
ContentAnalyzerConfig,
ContentFieldSchema,
} from "@azure/ai-content-understanding";
const endpoint =
process.env["CONTENTUNDERSTANDING_ENDPOINT"]!;
const key =
process.env["CONTENTUNDERSTANDING_KEY"]!;
const client = new ContentUnderstandingClient(
endpoint,
new AzureKeyCredential(key)
);
사용자 지정 분석기 만들기
다음 예제에서는 미리 빌드된 문서 분석기를 기반으로 사용자 지정 문서 분석기를 만듭니다. 세 가지 extract 리터럴 텍스트, generate AI 생성 요약 및 classify 분류 추출 방법을 사용하여 필드를 정의합니다.
const analyzerId =
`my_document_analyzer_${Math.floor(
Date.now() / 1000
)}`;
const fieldSchema: ContentFieldSchema = {
name: "company_schema",
description:
"Schema for extracting company"
+ " information",
fields: {
company_name: {
type: "string",
method: "extract",
description:
"Name of the company",
},
total_amount: {
type: "number",
method: "extract",
description:
"Total amount on the document",
},
document_summary: {
type: "string",
method: "generate",
description:
"A brief summary of the"
+ " document content",
},
document_type: {
type: "string",
method: "classify",
description: "Type of document",
enum: [
"invoice", "receipt",
"contract", "report", "other",
],
},
},
};
const config: ContentAnalyzerConfig = {
enableFormula: true,
enableLayout: true,
enableOcr: true,
estimateFieldSourceAndConfidence: true,
returnDetails: true,
};
const analyzer: ContentAnalyzer = {
baseAnalyzerId: "prebuilt-document",
description:
"Custom analyzer for extracting"
+ " company information",
config,
fieldSchema,
models: {
completion: "gpt-4.1",
embedding: "text-embedding-3-large", // Required when using field_schema and prebuilt-document base analyzer
},
} as unknown as ContentAnalyzer;
const poller = client.createAnalyzer(
analyzerId, analyzer
);
await poller.pollUntilDone();
const result = await client.getAnalyzer(
analyzerId
);
console.log(
`Analyzer '${analyzerId}' created`
+ ` successfully!`
);
if (result.description) {
console.log(
` Description: ${result.description}`
);
}
if (result.fieldSchema?.fields) {
const fields = result.fieldSchema.fields;
console.log(
` Fields`
+ ` (${Object.keys(fields).length}):`
);
for (const [name, fieldDef]
of Object.entries(fields)) {
const method =
fieldDef.method ?? "auto";
const fieldType =
fieldDef.type ?? "unknown";
console.log(
` - ${name}: `
+ `${fieldType} (${method})`
);
}
}
예제 출력은 다음과 같습니다.
Analyzer 'my_document_analyzer_ID' created successfully!
Description: Custom analyzer for extracting company information
Fields (4):
- company_name: string (extract)
- total_amount: number (extract)
- document_summary: string (generate)
- document_type: string (classify)
팁 (조언)
이 코드는 SDK 리포지토리의 분석기 만들기 샘플을 기반으로 합니다.
필요에 따라 분류자 분석기를 만들어 문서를 분류하고 결과를 사용하여 문서를 미리 빌드된 분석기 또는 사용자 지정 분석기에 라우팅할 수 있습니다. 분류 워크플로에 대한 사용자 지정 분석기를 만드는 예제는 다음과 같습니다.
const classifierId =
`my_classifier_${Math.floor(
Date.now() / 1000
)}`;
console.log(
`Creating classifier '${classifierId}'...`
);
const classifierAnalyzer: ContentAnalyzer = {
baseAnalyzerId: "prebuilt-document",
description:
"Custom classifier for financial"
+ " document categorization",
config: {
returnDetails: true,
enableSegment: true,
contentCategories: {
Loan_Application: {
description:
"Documents submitted by"
+ " individuals or"
+ " businesses to request"
+ " funding, typically"
+ " including personal or"
+ " business details,"
+ " financial history,"
+ " loan amount, purpose,"
+ " and supporting"
+ " documentation.",
},
Invoice: {
description:
"Billing documents issued"
+ " by sellers or service"
+ " providers to request"
+ " payment for goods or"
+ " services, detailing"
+ " items, prices, taxes,"
+ " totals, and payment"
+ " terms.",
},
Bank_Statement: {
description:
"Official statements"
+ " issued by banks that"
+ " summarize account"
+ " activity over a"
+ " period, including"
+ " deposits, withdrawals,"
+ " fees, and balances.",
},
},
} as unknown as ContentAnalyzerConfig,
models: {
completion: "gpt-4.1",
},
} as unknown as ContentAnalyzer;
const classifierPoller =
client.createAnalyzer(
classifierId, classifierAnalyzer
);
await classifierPoller.pollUntilDone();
const classifierResult =
await client.getAnalyzer(classifierId);
console.log(
`Classifier '${classifierId}' created`
+ ` successfully!`
);
if (classifierResult.description) {
console.log(
` Description: `
+ `${classifierResult.description}`
);
}
팁 (조언)
이 코드는 분류 워크플로에 대한 분류자 만들기 샘플을 기반으로 합니다.
사용자 지정 분석기 사용
분석기를 만든 후 이 분석기를 사용하여 문서를 분석하고 사용자 지정 필드를 추출합니다. 더 이상 필요하지 않은 경우 분석기를 삭제합니다.
const documentUrl =
"https://raw.githubusercontent.com/"
+ "Azure-Samples/"
+ "azure-ai-content-understanding-assets/"
+ "main/document/invoice.pdf";
const analyzePoller = client.analyze(
analyzerId, [{ url: documentUrl }]
);
const analyzeResult =
await analyzePoller.pollUntilDone();
if (analyzeResult.contents
&& analyzeResult.contents.length > 0) {
const content = analyzeResult.contents[0];
if (content.fields) {
const company =
content.fields["company_name"];
if (company) {
console.log(
`Company Name: `
+ `${company.value}`
);
console.log(
` Confidence: `
+ `${company.confidence}`
);
}
const total =
content.fields["total_amount"];
if (total) {
console.log(
`Total Amount: `
+ `${total.value}`
);
}
const summary =
content.fields["document_summary"];
if (summary) {
console.log(
`Summary: ${summary.value}`
);
}
const docType =
content.fields["document_type"];
if (docType) {
console.log(
`Document Type: `
+ `${docType.value}`
);
}
}
}
// --- Clean up ---
console.log(
`\nCleaning up: deleting analyzer`
+ ` '${analyzerId}'...`
);
await client.deleteAnalyzer(analyzerId);
console.log(
`Analyzer '${analyzerId}' deleted`
+ ` successfully.`
);
예제 출력은 다음과 같습니다.
Company Name: CONTOSO LTD.
Confidence: 0.818
Total Amount: 610
Summary: This document is an invoice from CONTOSO LTD. to MICROSOFT CORPORATION for consulting, document, and printing services provided during the service period 10/14/2019 - 11/14/2019. It details line items, subtotal, sales tax, total, previous unpaid balance, and the final amount due.
Document Type: invoice
Cleaning up: deleting analyzer 'my_document_analyzer_ID'...
Analyzer 'my_document_analyzer_ID' deleted successfully.
팁 (조언)
TypeScript SDK 샘플에서 분석기를 실행하는 더 많은 예제를 확인하세요.
관련 콘텐츠
- 코드 샘플 검토: 시각적 문서 검색.
- 코드 샘플 검토: 분석기 템플릿.
- 더 많은 Python SDK 샘플 살펴보기
- 더 많은 .NET SDK 샘플 살펴보기
- 더 많은 Java SDK 샘플 살펴보기
- 더 많은 JavaScript SDK 샘플 살펴보기
- 더 많은 TypeScript SDK 샘플 살펴보기
- Foundry에서 Content Understanding을 사용하여 문서 콘텐츠를 처리해 보세요.