문서 인텔리전스 v3.1 마이그레이션

  • 아티클

이 콘텐츠의 적용 대상은 다음과 같습니다.checkmarkv4.0(미리 보기)checkmarkv3.1(GA)checkmarkv3.0(GA)checkmarkv2.1(GA)

Important

문서 인텔리전스 REST API v3.1은 REST API 요청에 주요 변경 사항을 도입하고 응답 JSON을 분석합니다.

v3.1 미리 보기 API 버전에서 마이그레이션

미리 보기 API는 주기적으로 지원 중단됩니다. 미리 보기 API 버전을 사용하는 경우 GA API 버전을 대상으로 하도록 애플리케이션을 업데이트하세요. SDK를 사용하여 2023-02-28 미리 보기 API 버전에서 2023-07-31(GA) API 버전으로 마이그레이션하려면 언어별 SDK의 현재 버전으로 업데이트합니다.

2023-07-31(GA) API에는 미리 보기 API 버전에서 몇 가지 업데이트 및 변경 내용이 있습니다.

  • 기본적으로 사용하도록 설정되는 기능은 대기 시간과 응답 크기가 줄어든다는 이점이 있는 특정 모델에 필수적인 기능으로 제한됩니다. 추가된 기능은 features 매개 변수의 열거형 값을 통해 사용하도록 설정할 수 있습니다.
  • prebuild-{document,invoice} 이외의 prebuild-read 및 keyValuePairs의 일부 레이아웃 기능은 더 이상 지원되지 않습니다.
  • 미리 빌드된 읽기 및 미리 빌드된 레이아웃에 대한 바코드, 미리 빌드된 읽기에 대한 언어 및 미리 빌드된 청구서에 대한 keyValuePairs를 기본적으로 사용하지 않도록 설정합니다.
  • 주석 추출이 제거되었습니다.
  • 쿼리 필드와 키-값 쌍의 일반 이름이 제거됩니다.
  • Office/HTML 파일은 미리 빌드된 읽기 모델에서 지원되며 경계 상자 없이 단어와 단락을 추출합니다. 삽입된 이미지는 더 이상 지원되지 않습니다. Office/HTML 파일에 대한 추가 기능이 요청되면 오류 없이 빈 배열이 반환됩니다.

분석 기능

Model ID 텍스트 추출 단락 단락 역할 선택 표시 테이블 키/값 쌍 언어 바코드 문서 분석 수식* StyleFont* OCR 고해상도*
prebuilt-read ✓ ✓ O O O O O
prebuilt-layout ✓ ✓ ✓ ✓ ✓ O O O O O
prebuilt-document ✓ ✓ ✓ ✓ ✓ ✓ O O O O O
prebuilt-businessCard ✓ ✓
prebuilt-idDocument ✓ O O ✓ O O O
prebuilt-invoice ✓ ✓ ✓ O O O ✓ O O O
prebuilt-receipt ✓ O O ✓ O O O
prebuilt-healthInsuranceCard.us ✓ O O ✓ O O O
prebuilt-tax.us.w2 ✓ ✓ O O ✓ O O O
prebuilt-tax.us.1098 ✓ ✓ O O ✓ O O O
prebuilt-tax.us.1098E ✓ ✓ O O ✓ O O O
prebuilt-tax.us.1098T ✓ ✓ O O ✓ O O O
prebuilt-contract ✓ ✓ ✓ ✓ O O ✓ O O O
{ customModelName } ✓ ✓ ✓ ✓ ✓ O O ✓ O O O

✓ - 사용 O - 선택적 수식/StyleFont/OCR 고해상도* - 프리미엄 기능에는 추가 비용 발생

v3.0에서 마이그레이션

v3.0과 비교하여, 문서 인텔리전스 v3.1에는 몇 가지 새로운 기능이 도입되었습니다.

  • 바코드 추출
  • 고해상도, 수식 및 글꼴 속성 추출을 포함한 추가 기능.
  • 문서 분할 및 분류를 위한 사용자 지정 분류 모델입니다.
  • 청구서 및 영수증 모델에서 언어 확장 및 새로운 필드가 지원됩니다.
  • ID 문서 모델에서 새로운 문서 형식이 지원됩니다.
  • 🆕 사전 빌드된 새로운 건강 보험 카드 모델.
  • Office/HTML 파일은 미리 빌드된 읽기 모델에서 지원되며 경계 상자 없이 단어와 단락을 추출합니다. 삽입된 이미지는 더 이상 지원되지 않습니다. Office/HTML 파일에 대한 추가 기능이 요청되면 오류 없이 빈 배열이 반환됩니다.
  • 사용자 지정 추출 및 분류 모델의 모델 만료 - 새로운 사용자 지정 모델은 품질 개선을 위해 정기적으로 업데이트되는 대규모 베이스 모델을 기반으로 합니다. 해당 베이스 모델을 사용 중지할 수 있도록 모든 사용자 지정 모델에 만료 날짜가 도입되었습니다. 사용자 지정 모델이 만료되면 최신 API 버전(베이스 모델)을 사용하여 모델을 다시 학습해야 합니다.
GET /documentModels/{customModelId}?api-version={apiVersion}
{
  "modelId": "{customModelId}",
  "description": "{customModelDescription}",
  "createdDateTime": "2023-09-24T12:54:35Z",
  "expirationDateTime": "2025-01-01T00:00:00Z",
  "apiVersion": "2023-07-31",
  "docTypes": { ... }
}
  • 사용자 지정 신경망 모델 빌드 할당량 - 각 구독이 매월 지역별로 빌드할 수 있는 신경망 모델 수는 제한되어 있습니다. GET /info에서 반환된 리소스 정보의 일부로 현재 사용량을 이해하는 데 도움이 되도록 결과 JSON을 확장하여 할당량 및 사용된 정보를 포함합니다.
{
  "customDocumentModels": { ... },
  "customNeuralDocumentModelBuilds": {
    "used": 1,
    "quota": 10,
    "quotaResetDateTime": "2023-03-01T00:00:00Z"
  }
}
  • 분석 작업에 대한 선택적 features 쿼리 매개 변수는 선택적으로 특정 기능을 사용하도록 설정할 수 있습니다. 일부 프리미엄 기능에는 추가 요금이 부과될 수 있습니다. 자세한 내용은 기능 목록 분석을 참조하세요.
  • 가능한 경우 추출된 통화 필드 개체를 확장하여 정규화된 통화 코드 필드를 출력합니다. 현재 필드는 금액(예: 123.45) 및 통화 기호(ex. $)를 반환할 수 있습니다. 이 기능은 통화 기호를 정식 ISO 4217 코드(예: USD)에 매핑합니다. 모델은 통화 코드를 명확하게 하거나 유추하기 위해 선택적으로 글로벌 문서 콘텐츠를 활용할 수 있습니다.
{
  "fields": {
    "Total": {
      "type": "currency",
      "content": "$123.45",
      "valueCurrency": {
        "amount": 123.45,
        "currencySymbol": "$",
        "currencyCode": "USD"
      },
      ...
    }
  }
}

모델 품질 개선 외에도 이러한 새로운 기능을 활용하려면 v3.1을 사용하도록 애플리케이션을 업데이트하는 것이 좋습니다.

v2.1 또는 v2.0에서 마이그레이션

문서 인텔리전스 v3.1은 가장 풍부한 기능, 대부분의 언어 및 문서 형식 범위, 개선된 모델 품질을 갖춘 최신 GA 버전입니다. v3.1에서 사용할 수 있는 기능에 대해서는 모델 개요를 참조하세요.

v3.0부터 더 나은 사용성을 위해 문서 인텔리전스 REST API가 새롭게 설계되었습니다. 이 섹션에서는 문서 인텔리전스 v2.0, v2.1 및 v3.1의 차이점과 최신 버전의 API로 이동하는 방법을 알아봅니다.

주의

  • REST API 2023-07-31 릴리스에는 REST API 분석 응답 JSON의 호환성이 손상되는 변경이 포함되어 있습니다.
  • 각 인스턴스에서 boundingBox 속성의 이름이 polygon으로 바뀝니다.

REST API 엔드포인트에 대한 변경 내용

v3.1 REST API는 documentModels 및 modelId를 레이아웃 분석(미리 빌드된 레이아웃) 및 미리 빌드된 모델에 할당하여 레이아웃 분석, 미리 빌드된 모델 및 사용자 지정 모델에 대한 분석 작업을 단일 작업 쌍으로 결합합니다.

POST 요청

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2023-07-31

GET 요청

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}/AnalyzeResult/{resultId}?api-version=2023-07-31

분석 작업

  • 요청 페이로드 및 호출 패턴은 변경되지 않은 상태로 유지됩니다.
  • 분석 작업은 입력 문서 및 콘텐츠별 구성을 지정하고 응답의 Operation-Location 헤더를 통해 결과 분석 URL을 반환합니다.
  • GET 요청을 통해 이 결과 분석 URL을 폴링하여 분석 작업의 상태를 확인합니다(권장되는 요청 간 최소 간격은 1초).
  • 성공하면 상태가 '성공'으로 설정되고 analyzeResult가 응답 본문에 반환됩니다. 오류가 발생하면 상태가 failed로 설정되고 오류가 반환됩니다.
모델 v2.0 v2.1 v3.1
요청 URL 접두사 https://{your-form-recognizer-endpoint}/formrecognizer/v2.0 https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
일반 문서 해당 없음 해당 없음 /documentModels/prebuilt-document:analyze
레이아웃 /layout/analyze /layout/analyze /documentModels/prebuilt-layout:analyze
사용자 지정 /custom/models/{modelId}/analyze /custom/{modelId}/analyze /documentModels/{modelId}:analyze
청구서 해당 없음 /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
영수증 /prebuilt/receipt/analyze /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
ID 문서 해당 없음 /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
명함 해당 없음 /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze
W-2 해당 없음 해당 없음 /documentModels/prebuilt-tax.us.w2:analyze
의료 보험 카드 해당 없음 해당 없음 /documentModels/prebuilt-healthInsuranceCard.us:analyze
계약 해당 없음 해당 없음 /documentModels/prebuilt-contract:analyze

요청 본문 분석

분석할 콘텐츠는 요청 본문을 통해 제공됩니다. URL 또는 base64로 인코딩된 데이터는 요청을 생성하는 사용자일 수 있습니다.

공개적으로 액세스할 수 있는 웹 URL을 지정하려면 Content-Type을 application/json으로 설정하고 다음 JSON 본문을 보냅니다.

{
  "urlSource": "{urlPath}"
}

Base 64 인코딩은 문서 인텔리전스 v3.0에서도 지원됩니다.

{
  "base64Source": "{base64EncodedContent}"
}

추가로 지원되는 매개 변수

계속 지원되는 매개 변수:

  • pages : 문서의 특정 페이지 하위 집합만 분석합니다. 분석할 번호 1에서 인덱싱된 페이지 번호 목록입니다. 예: "1-3,5,7-9"
  • locale : 텍스트 인식 및 문서 분석을 위한 로캘 힌트입니다. 값에는 언어 코드(예: en, fr) 또는 BCP 47 언어 태그(예: "en-US")만 포함될 수 있습니다.

더 이상 지원되지 않는 매개 변수:

  • includeTextDetails

새 응답 형식은 더 간결하고, 항상 전체 출력이 반환됩니다.

결과 분석에 대한 변경 내용

다중 페이지 요소를 지원하기 위해 응답 분석이 다음과 같은 최상위 결과로 리팩터링되었습니다.

  • pages
  • tables
  • keyValuePairs
  • entities
  • styles
  • documents

참고 항목

analyzeResult 응답 변경에는 페이지 속성에서 analyzeResult 내의 최상위 수준 속성으로 이동하는 것과 같은 여러 변경 내용이 포함됩니다.


{
// Basic analyze result metadata
"apiVersion": "2022-08-31", // REST API version used
"modelId": "prebuilt-invoice", // ModelId used
"stringIndexType": "textElements", // Character unit used for string offsets and lengths:
// textElements, unicodeCodePoint, utf16CodeUnit // Concatenated content in global reading order across pages.
// Words are generally delimited by space, except CJK (Chinese, Japanese, Korean) characters.
// Lines and selection marks are generally delimited by newline character.
// Selection marks are represented in Markdown emoji syntax (:selected:, :unselected:).
"content": "CONTOSO LTD.\nINVOICE\nContoso Headquarters...", "pages": [ // List of pages analyzed
{
// Basic page metadata
"pageNumber": 1, // 1-indexed page number
"angle": 0, // Orientation of content in clockwise direction (degree)
"width": 0, // Page width
"height": 0, // Page height
"unit": "pixel", // Unit for width, height, and polygon coordinates
"spans": [ // Parts of top-level content covered by page
{
"offset": 0, // Offset in content
"length": 7 // Length in content
}
], // List of words in page
"words": [
{
"text": "CONTOSO", // Equivalent to $.content.Substring(span.offset, span.length)
"boundingBox": [ ... ], // Position in page
"confidence": 0.99, // Extraction confidence
"span": { ... } // Part of top-level content covered by word
}, ...
], // List of selectionMarks in page
"selectionMarks": [
{
"state": "selected", // Selection state: selected, unselected
"boundingBox": [ ... ], // Position in page
"confidence": 0.95, // Extraction confidence
"span": { ... } // Part of top-level content covered by selection mark
}, ...
], // List of lines in page
"lines": [
{
"content": "CONTOSO LTD.", // Concatenated content of line (may contain both words and selectionMarks)
"boundingBox": [ ... ], // Position in page
"spans": [ ... ], // Parts of top-level content covered by line
}, ...
]
}, ...
], // List of extracted tables
"tables": [
{
"rowCount": 1, // Number of rows in table
"columnCount": 1, // Number of columns in table
"boundingRegions": [ // Polygons or Bounding boxes potentially across pages covered by table
{
"pageNumber": 1, // 1-indexed page number
"polygon": [ ... ], // Previously Bounding box, renamed to polygon in the 2022-08-31 API
}
],
"spans": [ ... ], // Parts of top-level content covered by table // List of cells in table
"cells": [
{
"kind": "stub", // Cell kind: content (default), rowHeader, columnHeader, stub, description
"rowIndex": 0, // 0-indexed row position of cell
"columnIndex": 0, // 0-indexed column position of cell
"rowSpan": 1, // Number of rows spanned by cell (default=1)
"columnSpan": 1, // Number of columns spanned by cell (default=1)
"content": "SALESPERSON", // Concatenated content of cell
"boundingRegions": [ ... ], // Bounding regions covered by cell
"spans": [ ... ] // Parts of top-level content covered by cell
}, ...
]
}, ...
], // List of extracted key-value pairs
"keyValuePairs": [
{
"key": { // Extracted key
"content": "INVOICE:", // Key content
"boundingRegions": [ ... ], // Key bounding regions
"spans": [ ... ] // Key spans
},
"value": { // Extracted value corresponding to key, if any
"content": "INV-100", // Value content
"boundingRegions": [ ... ], // Value bounding regions
"spans": [ ... ] // Value spans
},
"confidence": 0.95 // Extraction confidence
}, ...
],
"styles": [
{
"isHandwritten": true, // Is content in this style handwritten?
"spans": [ ... ], // Spans covered by this style
"confidence": 0.95 // Detection confidence
}, ...
], // List of extracted documents
"documents": [
{
"docType": "prebuilt-invoice", // Classified document type (model dependent)
"boundingRegions": [ ... ], // Document bounding regions
"spans": [ ... ], // Document spans
"confidence": 0.99, // Document splitting/classification confidence // List of extracted fields
"fields": {
"VendorName": { // Field name (docType dependent)
"type": "string", // Field value type: string, number, array, object, ...
"valueString": "CONTOSO LTD.",// Normalized field value
"content": "CONTOSO LTD.", // Raw extracted field content
"boundingRegions": [ ... ], // Field bounding regions
"spans": [ ... ], // Field spans
"confidence": 0.99 // Extraction confidence
}, ...
}
}, ...
]
}

모델 빌드 또는 학습

모델 개체에는 새 API에서 세 가지 업데이트가 있습니다.

  • modelId는 이제 사람이 읽을 수 있는 이름의 모델에 설정할 수 있는 속성입니다.
  • modelName가 description으로 이름이 바뀌었습니다.
  • buildMode는 사용자 지정 양식 모델의 경우 template 값이 있고, 사용자 지정 인공신경망 모델의 경우 neural 값이 있는 새 속성입니다.

build 작업은 모델을 학습시키기 위해 호출됩니다. 요청 페이로드 및 호출 패턴은 변경되지 않은 상태로 유지됩니다. 빌드 작업은 모델 및 학습 데이터 세트를 지정하고, 응답의 Operation-Location 헤더를 통해 결과를 반환합니다. GET 요청을 통해 이 모델 작업 URL을 폴링하여 빌드 작업의 상태를 확인합니다(권장되는 요청 간 최소 간격은 1초). v2.1과 달리 이 URL은 모델의 리소스 위치가 아닙니다. 대신 모델 URL은 지정된 modelId에서 생성할 수 있으며, 응답의 resourceLocation 속성에서도 검색할 수 있습니다. 성공하면 상태가 succeeded로 설정되고 결과에 사용자 지정 모델 정보가 포함됩니다. 오류가 발생하면 상태가 failed로 설정되고 오류가 반환됩니다.

다음 코드는 SAS 토큰을 사용하는 샘플 빌드 요청입니다. 접두사 또는 폴더 경로를 설정할 때 후행 슬래시를 확인합니다.

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:build?api-version=2022-08-31

{
  "modelId": {modelId},
  "description": "Sample model",
  "buildMode": "template",
  "azureBlobSource": {
    "containerUrl": "https://{storageAccount}.blob.core.windows.net/{containerName}?{sasToken}",
    "prefix": "{folderName/}"
  }
}

모델 작성에 대한 변경 내용

모델 작성은 이제 단일 수준의 중첩으로 제한됩니다. 구성된 모델은 이제 modelId 및 description 속성을 추가하여 사용자 지정 모델과 일치합니다.

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:compose?api-version=2022-08-31
{
  "modelId": "{composedModelId}",
  "description": "{composedModelDescription}",
  "componentModels": [
    { "modelId": "{modelId1}" },
    { "modelId": "{modelId2}" },
  ]
}

모델 복사에 대한 변경 내용

모델 복사에 대한 호출 패턴은 변경되지 않은 상태로 유지됩니다.

  • authorizeCopy를 호출하는 대상 리소스를 사용하여 복사 작업에 대한 권한을 부여합니다. 이는 이제 POST 요청입니다.
  • copyTo를 호출하는 모델을 복사하려면 원본 리소스에 대한 권한 부여를 제출합니다.
  • 반환된 작업을 폴링하여 작업이 성공적으로 완료되었는지 확인합니다.

모델 복사 기능에 대한 유일한 변경 내용은 다음과 같습니다.

  • authorizeCopy에 대한 HTTP 작업은 이제 POST 요청입니다.
  • 권한 부여 페이로드에는 복사 요청을 제출하는 데 필요한 모든 정보가 포함됩니다.

복사 권한 부여

POST https://{targetHost}/formrecognizer/documentModels:authorizeCopy?api-version=2022-08-31
{
  "modelId": "{targetModelId}",
  "description": "{targetModelDescription}",
}

권한 부여 작업의 응답 본문을 사용하여 복사본에 대한 요청을 생성합니다.

POST https://{sourceHost}/formrecognizer/documentModels/{sourceModelId}:copyTo?api-version=2022-08-31
{
  "targetResourceId": "{targetResourceId}",
  "targetResourceRegion": "{targetResourceRegion}",
  "targetModelId": "{targetModelId}",
  "targetModelLocation": "https://{targetHost}/formrecognizer/documentModels/{targetModelId}",
  "accessToken": "{accessToken}",
  "expirationDateTime": "2021-08-02T03:56:11Z"
}

모델 목록에 대한 변경 내용

모델 목록은 이제 미리 빌드된 모델 및 사용자 지정 모델을 반환하도록 확장되었습니다. 모든 미리 빌드된 모델 이름은 prebuilt-로 시작합니다. 상태가 '성공'인 모델만 반환됩니다. 실패했거나 진행 중인 모델을 나열하려면 목록 작업을 참조하세요.

모델 목록 요청 샘플

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels?api-version=2022-08-31

모델 가져오기에 대한 변경 내용

이제 모델 가져오기에 미리 빌드된 모델이 포함되므로 가져오기 작업에서 docTypes 사전을 반환합니다. 각 문서 유형 설명에는 이름, 선택적 설명, 필드 스키마 및 선택적 필드 신뢰도가 포함됩니다. 필드 스키마는 문서 형식과 함께 반환될 수 있는 필드 목록을 설명합니다.

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2022-08-31

새 정보 가져오기 작업

서비스에 대한 info 작업에서 사용자 지정 모델 수와 사용자 지정 모델 제한을 반환합니다.

GET https://{your-form-recognizer-endpoint}/formrecognizer/info? api-version=2022-08-31

샘플 응답

{
  "customDocumentModels": {
    "count": 5,
    "limit": 100
  }
}

다음 단계