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

2025-08-30

일괄 처리 분석 API를 사용하면 하나의 요청을 사용하여 최대 10,000개의 문서를 대량으로 처리할 수 있습니다. 문서를 하나씩 분석하고 해당 요청 ID를 추적하는 대신 청구서, 대출 서류 또는 사용자 지정 문서와 같은 문서 컬렉션을 동시에 분석할 수 있습니다. 입력 문서는 Azure Blob Storage 컨테이너에 저장되어야 합니다. 문서가 처리되면 API는 지정된 스토리지 컨테이너에 결과를 씁니다.

일괄 처리 분석 제한

단일 일괄 처리 요청에 있을 수 있는 문서 파일의 최대 수는 10,000개입니다.
일괄 처리 작업 결과는 완료 후 24시간 동안 유지됩니다. 일괄 처리가 완료된 후 24시간 후에는 일괄 처리 작업 상태를 더 이상 사용할 수 없습니다. 입력 문서 및 해당 결과 파일은 제공된 스토리지 컨테이너에 남아 있습니다.

필수 조건

활성화된 Azure 구독. Azure 구독이 없는 경우 체험 구독을 만들 수 있습니다.
문서 인텔리전스 Azure 리소스: Azure 구독이 있으면 Azure Portal에서 Document Intelligence 리소스를 만듭니다. 무료 가격 책정 계층(F0)을 사용하여 서비스를 사용해 볼 수 있습니다. 리소스가 배포된 후 "리소스로 이동" 을 선택하여 키 와 엔드포인트를 검색합니다. 애플리케이션을 Document Intelligence 서비스에 연결하려면 리소스 키와 엔드포인트가 필요합니다. Azure Portal의 키 및 엔드포인트 페이지에서 이러한 값을 찾을 수도 있습니다.
Azure Blob Storage 계정. 원본 및 결과 파일에 대한 Azure Blob Storage 계정에 두 개의 컨테이너를 만듭니다.
- 원본 컨테이너: 이 컨테이너는 분석을 위해 문서 파일을 업로드하는 위치입니다.
- 결과 컨테이너: 이 컨테이너는 일괄 처리 분석 API의 결과가 저장되는 위치입니다.

저장 컨테이너 권한 부여

API가 Azure Storage 컨테이너에서 문서를 처리하고 결과를 작성할 수 있도록 하려면 다음 두 가지 옵션 중 하나를 사용하여 권한을 부여해야 합니다.

✔️ 관리 ID. 관리 ID는 Azure 관리되는 리소스를 위한 Microsoft Entra ID와 특정 권한을 만드는 서비스 주체입니다. 관리 ID를 사용하면 코드에 자격 증명을 포함하지 않고도 Document Intelligence 애플리케이션을 실행할 수 있습니다. 이렇게 하면 코드에 SAS(액세스 서명 토큰)를 포함하지 않고도 스토리지 데이터에 대한 액세스 권한을 더 안전하게 부여할 수 있습니다.

문서 인텔리전스에 대한 관리 ID를 검토하여 리소스에 대한 관리 ID를 사용하도록 설정하고 스토리지 컨테이너에 대한 액세스 권한을 부여하는 방법을 알아봅니다.

Important

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

✔️ SAS(공유 액세스 서명). 공유 액세스 서명은 스토리지 컨테이너에 대한 제한된 액세스 권한을 부여하는 URL입니다. 이 메서드를 사용하려면 원본 및 결과 컨테이너에 대한 SAS(공유 액세스 서명) 토큰을 만듭니다. Azure Portal의 스토리지 컨테이너로 이동하여 "공유 액세스 토큰" 을 선택하여 SAS 토큰 및 URL을 생성합니다.

원본 컨테이너 또는 Blob은 읽기, 쓰기, 나열 및 삭제 권한을 지정해야 합니다.
결과 컨테이너 또는 Blob은 쓰기, 목록,삭제 권한을 지정해야 합니다.

Azure Portal의 SAS 권한 필드를 보여 주는 스크린샷.

SAS 토큰 생성 및 작동 방식에 대해 자세히 알아보려면 SAS 토큰 만들기를 검토합니다.

일괄 처리 분석 API 호출

1. 입력 파일 지정

일괄 처리 API는 처리할 파일을 지정하는 두 가지 옵션을 지원합니다.

컨테이너 또는 폴더의 모든 파일을 처리하고 파일 수가 10000 제한보다 작은 경우 요청에 개체를 azureBlobSource 사용합니다.

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

{
  "azureBlobSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken"

},
{
   "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
   "resultPrefix": "trainingDocsResult/"
}

컨테이너 또는 폴더의 모든 파일을 처리하지 않고 해당 컨테이너 또는 폴더의 특정 파일을 처리하지 않으려면 개체를 azureBlobFileListSource 사용합니다. 이 작업을 수행하려면 처리할 파일을 나열하는 파일 목록 JSONL 파일이 필요합니다. JSONL 파일을 컨테이너의 루트 폴더에 저장합니다. 다음은 두 개의 파일이 나열된 예제 JSONL 파일입니다.
```
{"file": "Adatum Corporation.pdf"}
{"file": "Best For You Organics Company.pdf"}
```

다음 조건에 따라 파일 목록 JSONL 파일을 사용합니다.

컨테이너의 모든 파일 대신 특정 파일을 처리해야 하는 경우
입력 컨테이너 또는 폴더의 총 파일 수가 파일 일괄 처리 제한 10,000을 초과하는 경우
각 일괄 처리 요청에서 처리되는 파일을 더 자세히 제어하려는 경우

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

{
  "azureBlobFileListSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "fileList": "myFileList.jsonl"
    ...
  },
  ...
}

두 옵션 모두에 컨테이너 URL 또는 컨테이너 SAS URL이 필요합니다. 관리 ID를 사용하여 스토리지 컨테이너에 액세스하는 경우 컨테이너 URL을 사용합니다. SAS(공유 액세스 서명)를 사용하는 경우 SAS URL을 사용합니다.

2. 결과 위치 지정

매개 변수를 사용하여 resultContainerURL 결과를 저장할 Azure Blob Storage 컨테이너 URL(또는 컨테이너 SAS URL)을 지정합니다. 실수로 덮어쓰지 않도록 원본 및 결과에 별도의 컨테이너를 사용하는 것이 좋습니다.
overwriteExisting 부울 속성을 설정하여 False 동일한 문서에 대한 기존 결과를 덮어쓰지 않도록 합니다. 기존 결과를 덮어쓰려면 부울 True을 .로 설정합니다. 기존 결과를 덮어쓰지 않더라도 문서 처리에 대한 요금이 계속 청구됩니다.
결과를 특정 컨테이너 폴더에 그룹화하고 저장하는 데 사용합니다 resultPrefix .

3. POST 요청 빌드 및 실행

다음 샘플 컨테이너 URL 값을 Azure Blob Storage 컨테이너의 실제 값으로 바꿔야 합니다.

이 예제에서는 입력이 있는 POST 요청을 azureBlobSource 보여줍니다.

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

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

이 예제에서는 POST 요청과 azureBlobFileListSource 파일 목록 입력을 보여줍니다.

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

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

다음은 성공적인 응답의 예입니다.

202 Accepted
Operation-Location: /documentintelligence/documentModels/{modelId}/analyzeBatchResults/{resultId}?api-version=2024-11-30

4. API 결과 검색

GET POST 작업이 실행된 후 작업을 사용하여 일괄 처리 분석 결과를 검색합니다. GET 작업은 상태 정보, 일괄 처리 완료 비율, 작업 만들기 및 업데이트 날짜/시간을 가져옵니다. 이 정보는 일괄 처리 분석 이 완료된 후 24시간 동안만 보존 됩니다.

GET {endpoint}/documentintelligence/documentModels/{modelId}/analyzeBatchResults/{resultId}?api-version=2024-11-30
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"
...
}

5. 상태 메시지 해석

처리된 각 문서에 대해 상태가 할당됩니다succeededfailedrunningnotStartedskipped. 입력 문서의 원본 Blob Storage 컨테이너인 원본 URL이 제공됩니다.

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

succeeded 상태. 일괄 처리 작업이 성공했고 입력 문서가 처리되었습니다. 결과는 , 및 resultUrl 확장을 결합하여 resultContainerUrlresultPrefixinput filename생성되는 위치에서 .ocr.json사용할 수 있습니다. 성공한 파일에만 속성resultUrl이 있습니다.

succeeded 상태 응답의 예:

{
    "resultId": "myresultId-",
    "status": "succeeded",
    "percentCompleted": 100,
    "createdDateTime": "2025-01-01T00:00:000",
    "lastUpdatedDateTime": "2025-01-01T00:00:000",
    "result": {
        "succeededCount": 10,000,
        "failedCount": 0,
        "skippedCount": 0,
        "details": [
            {
                "sourceUrl": "https://{your-source-container}/inputFolder/document1.pdf",
                "resultUrl": "https://{your-result-container}/resultsFolder/document1.pdf.ocr.json",
                "status": "succeeded"
            },
          ...
            {
                "sourceUrl": "https://{your-source-container}/inputFolder/document10000.pdf",
                "resultUrl": "https://{your-result-container}/resultsFolder/document10000.pdf.ocr.json",
                "status": "succeeded"
            }
       ]

     }
}

failed 상태. 이 오류는 전체 일괄 처리 요청에 오류가 있는 경우에만 반환됩니다. 일괄 처리 분석 작업이 시작되면 모든 파일에 상태가 있더라도 개별 문서 작업 상태는 전체 일괄 처리 작업의 상태에 failed영향을 주지 않습니다.

failed 상태 응답의 예:

[
    "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 0,
    "details": [
        "sourceUrl": "https://{your-source-container}/inputFolder/document1.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://{your-source-container}/inputFolder/document1.pdf",
         "status": "skipped",
         "error": {
             "code": "OutputExists",
             "message": "Analysis skipped because result file https://{your-result-container}/resultsFolder/document1.pdf.ocr.json already exists."
              }
         ]
     }
]
...

참고 항목

전체 일괄 처리에 대한 분석이 완료될 때까지 개별 파일에 대한 분석 결과가 반환되지 않습니다. 자세한 percentCompleted진행 상황을 추적하려면 파일에 기록*.ocr.json된 대로 모니터링 resultContainerUrl 할 수 있습니다.

다음 단계

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

피드백

이 페이지가 도움이 되었나요?