다음을 통해 공유

문서 인텔리전스 일괄 처리 분석

  • 아티클

일괄 처리 분석 API를 사용하면 하나의 비동기 요청을 사용하여 여러 문서를 대량 처리할 수 있습니다. 문서를 개별적으로 제출하고 여러 요청 ID를 추적하는 대신 청구서, 일련의 대출 문서 또는 사용자 지정 문서 그룹과 같은 문서 컬렉션을 동시에 분석할 수 있습니다. 일괄 처리 API는 Azure Blob Storage에서 문서를 읽고 Blob Storage에 결과를 쓰는 것을 지원합니다.

  • 일괄 처리 분석을 활용하려면 원본 문서와 처리된 출력 모두에 대한 특정 컨테이너가 있는 Azure Blob Storage 계정이 필요합니다.
  • 완료되면 일괄 처리 작업 결과에 해당 상태(예: succeeded, skipped 또는 failed)로 처리된 모든 개별 문서가 나열됩니다.
  • Batch API 미리 보기 버전은 종량제 가격으로 사용할 수 있습니다.

일괄 처리 분석 지침

  • 단일 일괄 처리 분석 요청당 처리되는 최대 문서 수(건너뛴 문서 포함)는 10,000개입니다.

  • 작업 결과는 완료 후 24시간 동안 보관됩니다. 문서 및 결과는 제공된 스토리지 계정에 있지만 완료 후 24시간이 지난 후에는 작업 상태를 더 이상 사용할 수 없습니다.

시작할 준비가 되셨나요?

필수 조건

  • 활성 상태인 Azure 구독이 필요합니다. Azure 구독이 없는 경우 체험 구독을 만들 수 있습니다.

  • Azure 구독이 있으면 Azure Portal에 문서 인텔리전스 인스턴스가 있습니다. 무료 가격 책정 계층(F0)을 사용하여 서비스를 시도할 수 있습니다.

  • 리소스가 배포된 후 리소스로 이동을 선택하고 키 및 엔드포인트를 찾아옵니다.

    • 애플리케이션을 문서 인텔리전스 서비스에 연결하려면 리소스의 키와 엔드포인트가 필요합니다. 키와 엔드포인트를 이 빠른 시작의 뒷부분에서 코드에 붙여넣습니다. Azure Portal 키 및 엔드포인트 페이지에서 다음 값을 찾을 수 있습니다.

  • Azure Blob Storage 계정 원본 및 결과 파일에 대한 Azure Blob Storage 계정에서 컨테이너를 만듭니다.

    • 원본 컨테이너. 이 컨테이너는 분석을 위해 파일을 업로드하는 위치입니다(필수).
    • 결과 컨테이너. 이 컨테이너는 처리된 파일이 저장되는 위치입니다(선택 사항).

원본 및 처리된 문서에 대해 동일한 Azure Blob Storage 컨테이너를 지정할 수 있습니다. 그러나 실수로 데이터를 덮어쓸 가능성을 최소화하려면 별도의 컨테이너를 선택하는 것이 좋습니다.

저장 컨테이너 권한 부여

다음 옵션 중 하나를 선택하여 문서 리소스에 대한 액세스 권한을 부여할 수 있습니다.

✔️ 관리 ID. 관리 ID는 Azure 관리되는 리소스를 위한 Microsoft Entra ID와 특정 권한을 만드는 서비스 주체입니다. 관리 ID를 사용하면 코드에 자격 증명을 포함하지 않고도 문서 인텔리전스 애플리케이션을 실행할 수 있습니다. 관리 ID는 스토리지 데이터에 대한 액세스 권한을 부여하고, SAS(공유 액세스 서명) 토큰을 원본 및 결과 URL에 포함해야 하는 요구 사항을 대체하는 더욱 안전한 방법입니다.

자세한 내용은 문서 인텔리전스용 관리 ID를 참조하세요.

관리 ID 흐름(역할 기반 액세스 제어)의 스크린샷

Important

  • 관리 ID를 사용하는 경우 HTTP 요청에 SAS 토큰 URL을 포함하지 마세요. 요청이 실패합니다. 관리 ID 사용은 SAS(공유 액세스 서명) 토큰을 포함해야 하는 요구 사항을 대체합니다.

✔️ SAS(공유 액세스 서명). 공유 액세스 서명은 문서 인텔리전스 서비스에 지정된 기간 동안 제한된 액세스 권한을 부여하는 URL입니다. 이 방법을 사용하려면 원본 및 결과 컨테이너에 대한 SAS(공유 액세스 서명) 토큰을 만들어야 합니다. 원본 및 결과 컨테이너에는 쿼리 문자열로 추가된 SAS(공유 액세스 서명) 토큰이 포함되어 있어야 합니다. 토큰은 컨테이너 또는 특정 Blob에 할당될 수 있습니다.

SAS 토큰이 추가된 스토리지 URI의 스크린샷.

  • 원본 컨테이너 또는 Blob에는 읽기, 쓰기, 나열, 삭제 액세스 권한이 지정되어 있어야 합니다.
  • 결과 컨테이너 또는 Blob에는 쓰기, 나열, 삭제 액세스 권한이 지정되어 있어야 합니다.

자세한 내용은 SAS 토큰 만들기를 참조하세요.

일괄 처리 분석 API 호출

  • azureBlobSource 또는 azureBlobFileListSource 개체 내의 원본 문서의 Azure Blob Storage 컨테이너 URL을 지정합니다.

입력 파일 지정

일괄 처리 API는 처리할 파일을 지정하는 두 가지 옵션을 지원합니다. 처리된 컨테이너 또는 폴더의 모든 파일이 필요하고 파일 수가 단일 일괄 처리 요청에 대한 10000 제한보다 작은 경우 컨테이너를 azureBlobSource 사용합니다.

처리할 컨테이너 또는 폴더에 특정 파일이 있거나 처리할 파일 수가 단일 일괄 처리에 대한 최대 제한을 초과한 경우 다음을 사용합니다 azureBlobFileListSource. 데이터 세트를 여러 일괄 처리로 분할하고 컨테이너의 루트 폴더에서 JSONL 형식으로 처리할 파일 목록을 사용하여 파일을 추가합니다. 파일 목록 형식의 예는 다음과 같습니다.

{"file": "Adatum Corporation.pdf"}
{"file": "Best For You Organics Company.pdf"}

결과 위치 지정

resultContainerUrl을 사용하여 일괄 처리 분석 결과의 Azure Blob Storage 컨테이너 URL을 지정합니다. 실수로 덮어쓰는 것을 방지하려면 원본 문서 및 처리된 문서에 별도의 컨테이너를 사용하는 것이 좋습니다.

동일한 파일 이름을 가진 overwriteExisting 기존 결과를 덮어쓰지 않으려면 부울 속성을 false로 설정합니다. 이 설정은 청구에 영향을 주지 않으며 입력 파일이 처리된 후에만 결과를 덮어쓰지 못하게 합니다.

resultPrefix 일괄 처리 API의 이 실행 결과를 네임스페이스로 설정합니다.

  • 입력과 출력 모두에 동일한 컨테이너를 사용하려는 경우 입력azureBlobSource을 resultPrefix 설정하고 resultContainerUrl 일치합니다.
  • 동일한 컨테이너를 사용하는 경우 분석 결과 파일을 사용하여 파일을 덮어쓸지 여부를 결정하는 overwriteExisting 필드를 포함할 수 있습니다.

POST 요청 빌드 및 실행

POST 요청을 실행하기 전에 {your-source-container-SAS-URL} 및 {your-result-container-SAS-URL}을 Azure Blob Storage 컨테이너 인스턴스의 값으로 바꿉니다.

다음 샘플에서는 요청에 속성을 추가하는 azureBlobSource 방법을 보여줍니다.

azureBlobSource 또는 azureBlobFileListSource 중 하나만 허용합니다.

POST /documentModels/{modelId}:analyzeBatch

{
  "azureBlobSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "prefix": "trainingDocs/"
  },
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "layoutresult/",
  "overwriteExisting": true
}

다음 샘플에서는 요청에 속성을 추가하는 azureBlobFileListSource 방법을 보여줍니다.

POST /documentModels/{modelId}:analyzeBatch

{
   "azureBlobFileListSource": {
      "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
      "fileList": "myFileList.jsonl"
    },
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "customresult/",
  "overwriteExisting": true
}

성공적인 응답

202 Accepted
Operation-Location: /documentModels/{modelId}/analyzeBatchResults/{resultId}

일괄 처리 분석 API 결과 검색

Batch API 작업이 실행된 후 GET 작업을 통해 일괄 처리 분석 결과를 검색할 수 있습니다. 이 작업에서는 작업 상태 정보, 작업 완료율, 작업 만들기와 업데이트 날짜/시간을 가져옵니다.

GET /documentModels/{modelId}/analyzeBatchResults/{resultId}
200 OK

{
  "status": "running",      // notStarted, running, completed, failed
  "percentCompleted": 67,   // Estimated based on the number of processed documents
  "createdDateTime": "2021-09-24T13:00:46Z",
  "lastUpdatedDateTime": "2021-09-24T13:00:49Z"
...
}

상태 메시지 해석

각 문서의 집합에는 succeeded, failed, skipped 상태가 할당됩니다. 각 문서에는 결과의 유효성을 검사하기 위해 제공된 다음과 같은 두 개의 URL이 있습니다. sourceUrl은 성공한 입력 문서의 원본 Blob Storage 컨테이너이며, resultUrl은 resultContainerUrl과 resultPrefix를 결합하여 원본 파일과 .ocr.json의 상대 경로를 만들어 생성한 URL입니다.

  • notStarted 또는 running 상태. 일괄 처리 분석 작업이 시작되지 않았거나 완료되지 않았습니다. 모든 문서의 작업이 완료될 때까지 기다려 주세요.

  • completed 상태. 일괄 처리 분석 작업이 완료되었습니다.

  • failed 상태. 일괄 처리 작업이 실패했습니다. 이 응답은 일반적으로 요청에 전반적인 문제가 있는 경우에 발생합니다. 개별 파일의 실패는 모든 파일이 실패한 경우에도 일괄 처리 보고서 응답에서 반환됩니다. 예를 들어 스토리지 오류로 인해 일괄 처리 작업 전체가 중단되지는 않으므로 일괄 처리 보고서 응답을 통해 부분 결과에 액세스할 수 있습니다.

succeeded 상태의 파일에만 응답에서 생성된 resultUrl 속성이 있습니다. 이렇게 하면 모델 학습에서 .ocr.json으로 끝나는 파일 이름을 감지하고 이를 학습에 사용할 수 있는 유일한 파일로 식별할 수 있습니다.

succeeded 상태 응답의 예:

[
  "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 2,
    "details": [
      {
        "sourceUrl": "https://{your-source-container}/myContainer/trainingDocs/file2.jpg",
        "status": "failed",
        "error": {
          "code": "InvalidArgument",
          "message": "Invalid argument.",
          "innererror": {
            "code": "InvalidSasToken",
            "message": "The shared access signature (SAS) is invalid: {details}"
                   }
               }
          }
      ]
   }
]
...

failed 상태 응답의 예:

  • 이 오류는 전체 일괄 처리 요청에 오류가 있는 경우에만 반환됩니다.
  • 일괄 처리 분석 작업이 시작되면 모든 파일이 failed 상태이더라도 개별 문서 작업 상태는 전체 일괄 처리 작업의 상태에 영향을 주지 않습니다.
[
    "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 2,
    "details": [
        "sourceUrl": "https://{your-source-container}/myContainer/trainingDocs/file2.jpg",
        "status": "failed",
        "error": {
            "code": "InvalidArgument",
            "message": "Invalid argument.",
            "innererror": {
              "code": "InvalidSasToken",
              "message": "The shared access signature (SAS) is invalid: {details}"
                }
            }
        ]
    }
]
...

skipped 상태 응답의 예:

[
    "result": {
    "succeededCount": 3,
    "failedCount": 0,
    "skippedCount": 2,
    "details": [
        ...
        "sourceUrl": "https://myStorageAccount.blob.core.windows.net/myContainer/trainingDocs/file4.jpg",
        "status": "skipped",
        "error": {
            "code": "OutputExists",
            "message": "Analysis skipped because result file {path} already exists."
             }
        ]
    }
]
...

일괄 처리 분석 결과를 사용하면 성공적으로 분석된 파일을 식별하고 resultUrl의 파일을 resultContainerUrl의 출력 파일과 비교하여 분석 결과의 유효성을 검사할 수 있습니다.

참고 항목

전체 문서 집합 일괄 처리 분석이 완료될 때까지 개별 파일에 대한 분석 결과는 반환되지 않습니다. percentCompleted 이후의 자세한 진행률을 추적하려면 resultContainerUrl에 기록되는 *.ocr.json 파일을 모니터링하면 됩니다.

다음 단계

GitHub에서 코드 샘플을 봅니다.