다음을 통해 공유

REST API를 사용하여 사용자 지정 분석기 만들기

Content Understanding 분석기는 콘텐츠에서 인사이트를 처리하고 추출하는 방법을 정의합니다. 모든 콘텐츠에서 균일한 처리 및 출력 구조를 보장하여 안정적이고 예측 가능한 결과를 제공합니다. 일반적인 사용 사례 에 대해 미리 빌드된 분석기를 제공합니다. 이 가이드에서는 이러한 분석기를 요구 사항에 맞게 사용자 지정할 수 있는 방법을 보여 줍니다.

이 가이드에서는 cURL 명령줄 도구를 사용합니다. 설치되지 않은 경우 개발자 환경에 적합한 버전을 다운로드 할 수 있습니다.

필수 조건

시작하려면 다음과 같은 리소스와 권한이 있는지 확인합니다.

  • Azure 구독. Azure 구독이 없는 경우 무료 계정을 만드십시오.
  • Azure 구독을 신청한 후 Azure Portal에서 Microsoft Foundry 리소스를 만듭니다. 지원되는 지역에 만들어야 합니다.
    • 이 리소스는 포털의 Foundry>Foundry에 나열되어 있습니다.
  • Content Understanding 리소스에 대한 기본 모델 배포를 설정합니다. 기본값을 설정하면 Content Understanding 요청에 사용하는 Foundry 모델에 대한 연결이 만들어집니다. 다음 방법 중 하나를 선택합니다.
    1. Content Understanding 설정 페이지로 이동
    2. 왼쪽 위에서 "+ 리소스 추가" 단추를 선택합니다.
    3. 사용할 Foundry 리소스를 선택하고 다음을 클릭한 다음 저장
      • "기본값을 사용할 수 없는 경우 필수 모델에 대한 '자동 배포 사용' 옵션을 반드시 체크한 상태로 두십시오." 이렇게 하면 리소스가 필수적인 GPT-4.1, GPT-4.1-mini 및 text-embedding-3-large 모델로 완전히 구성됩니다. 미리 빌드된 분석기별로 다른 모델이 필요합니다.
    이러한 단계를 수행하여 Foundry 리소스에서 Content Understanding과 Foundry 모델 간에 연결을 설정합니다.

분석기 스키마 정의

사용자 지정 분석기를 만들려면 추출하려는 구조적 데이터를 설명하는 필드 스키마를 정의합니다. 다음 예제에서는 영수증 처리를 위해 미리 빌드된 문서 분석기를 기반으로 분석기를 만듭니다.

다음 콘텐츠로 명명된 JSON 파일을 만듭니다 receipt.json .

{
  "description": "Sample receipt analyzer",
  "baseAnalyzerId": "prebuilt-document",
  "models": {
      "completion": "gpt-4.1",
      "embedding": "text-embedding-ada-002"

    },
  "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"
            }
          }
        }
      }
    }
  }
}

처리해야 하는 다양한 유형의 문서가 있지만 영수증만 분류하고 분석하려는 경우 먼저 문서를 분류하는 분석기를 만들 수 있습니다. 그런 다음, 다음 스키마를 사용하여 위에서 만든 분석기로 라우팅합니다.

다음 콘텐츠로 명명된 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",
      "embedding": "text-embedding-ada-002"

    },
  "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 응답

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 요청에 다음과 같은 변경 내용을 적용합니다.

  1. {endpoint} 및 {key}를 Azure 포털의 Foundry 인스턴스에서 가져온 엔드포인트 및 키 값으로 교체하십시오.
  2. {analyzerId}를 categorize.json 파일을 사용하여 만든 사용자 정의 분석기의 이름으로 바꾸십시오.
  3. {fileUrl}을 분석할 파일의 공개적으로 액세스 가능한 URL(예: SAS(공유 액세스 서명)이 있는 Azure Storage Blob 경로 또는 샘플 URL https://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-Location 응답에서 POST를 사용하여 분석 결과를 검색합니다.

GET 요청

curl -i -X GET "{endpoint}/contentunderstanding/analyzerResults/{resultId}?api-version=2025-11-01" \
  -H "Ocp-Apim-Subscription-Key: {key}"

응답 가져오기

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
    }
  }
}

관련 콘텐츠

  • Last updated on