Content Understanding 분석기는 콘텐츠에서 인사이트를 처리하고 추출하는 방법을 정의합니다. 모든 콘텐츠에서 균일한 처리 및 출력 구조를 보장하여 안정적이고 예측 가능한 결과를 제공합니다. 일반적인 사용 사례 에 대해 미리 빌드된 분석기를 제공합니다. 이 가이드에서는 이러한 분석기를 요구 사항에 맞게 사용자 지정할 수 있는 방법을 보여 줍니다.
이 가이드에서는 cURL 명령줄 도구를 사용합니다. 설치되지 않은 경우 개발 환경에 적합한 버전을 다운로드 할 수 있습니다.
분석기 스키마 정의
사용자 지정 분석기를 만들려면 추출하려는 구조적 데이터를 설명하는 필드 스키마를 정의합니다. 다음 예제에서는 영수증 처리를 위해 미리 빌드된 문서 분석기를 기반으로 분석기를 만듭니다.
다음 콘텐츠로 명명된 JSON 파일을 만듭니다 request_body.json .
{
"description": "Sample receipt analyzer",
"baseAnalyzerId": "prebuilt-documentAnalyzer",
"config": {
"returnDetails": true,
"enableFormula": false,
"disableContentFiltering": 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"
}
}
}
}
}
}
}
빌드 분석기
PUT 요청
curl -i -X PUT "{endpoint}/contentunderstanding/analyzers/{analyzerId}?api-version=2025-05-01-preview" \
-H "Ocp-Apim-Subscription-Key: {key}" \
-H "Content-Type: application/json" \
-d @request_body.json
PUT 응답
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-05-01-preview" \
-H "Ocp-Apim-Subscription-Key: {key}"
파일 분석
파일 보내기
이제 만든 사용자 지정 분석기를 사용하여 파일을 처리하고 스키마에서 정의한 필드를 추출할 수 있습니다.
cURL 명령을 실행하기 전에 HTTP 요청을 다음과 같이 변경합니다.
- Azure Portal Azure AI Foundry 인스턴스의 엔드포인트 및 키 값으로
{endpoint}및{key}을 바꾸십시오. - 앞에서 만든 사용자 지정 분석기의 이름으로 바꿉
{analyzerId}습니다. - SAS(공유 액세스 서명) 또는 샘플 URL을 사용하여 Azure Storage Blob에 대한 경로와 같이 분석할 파일의 공개적으로 액세스할 수 있는 URL
{fileUrl}로 바꿉https://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/receipt.png니다.
POST 요청
curl -i -X POST "{endpoint}/contentunderstanding/analyzers/{analyzerId}:analyze?api-version=2025-05-01-preview" \
-H "Ocp-Apim-Subscription-Key: {key}" \
-H "Content-Type: application/json" \
-d "{\"url\":\"{fileUrl}\"}"
POST 응답
응답에는 202 Accepted 이 비동기 작업의 상태를 추적하는 데 사용할 수 있는 항목이 포함됩니다 {resultId} .
{
"id": {resultId},
"status": "Running",
"result": {
"analyzerId": {analyzerId},
"apiVersion": "2025-05-01-preview",
"createdAt": "YYYY-MM-DDTHH:MM:SSZ",
"warnings": [],
"contents": []
}
}
분석 결과 가져오기
-
{endpoint}및{key}를 Azure 포털의 Azure AI Foundry 인스턴스에서 가져온 엔드포인트 및 키 값으로 바꾸십시오. -
{resultId}응답에서resultId을POST으로 교체하십시오.
GET 요청
curl -i -X GET "{endpoint}/contentunderstanding/analyzerResults/{resultId}?api-version=2025-05-01-preview" \
-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-05-01-preview",
"createdAt": "YYYY-MM-DDTHH:MM:SSZ",
"warnings": [],
"contents": [
{
"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.0848,
"width": 1743,
"height": 878,
"spans": [
{
"offset": 0,
"length": 375
}
],
"words": [
{
"content": "Contoso",
"span": {"offset": 0,"length": 7 },
"confidence": 0.995,
"source": "D(1,774,72,974,70,974,111,774,113)"
}, ...
],
"lines": [
{
"content": "Contoso",
"source": "D(1,774,71,973,70,974,111,774,113)",
"span": {"offset": 0,"length": 7}
}, ...
]
}
],
"paragraphs": [
{
"content": "Contoso",
"source": "D(1,774,71,973,70,974,111,774,113)",
"span": {"offset": 0,"length": 7}
}, ...
],
"sectios": [
{
"span": {"offset": 0,"length": 374 },
"elements": ["/paragraphs/0","/paragraphs/1", ...]
}
],
"tables": [
{
"rowCount": 2,
"columnCount": 2,
"cells": [
{
"kind": "content",
"rowIndex": 0,
"columnIndex": 0,
"rowSpan": 1,
"columnSpan": 1,
"content": "2 Surface Pro 6",
"source": "D(1,691,471,911,470,911,514,691,515)",
"span": {"offset": 115,"length": 15},
"elements": ["/paragraphs/4"]
}, ...
],
"source": "D(1,759,593,1056,592,1057,741,760,742)",
"span": {"offset": 223,"length": 151}
}
]
}
]
}
}