【5분 만에 이해하는 Foundry Tools 시리즈】 Azure Document Intelligence로 청구서 읽기

이 기사에서 알 수 있는 것

Azure Document Intelligence에는 레이아웃 분석이나 신분증·영수증 등 많은 모델이 있지만, 이번에는 청구서(prebuilt-invoice)에 주목합니다.

이 기사에서는 다음 3가지를 직접 실행해 보면서, 청구서 모델이 무엇을 반환하는지 이해할 수 있도록 해설합니다.

청구서 모델(prebuilt-invoice)이 무엇을 입력으로 받아 어떤 구조화된 필드(structured field)를 반환하는가
부속된 Bicep을 사용하여 검증 환경을 2개의 명령어로 구축하는 방법
공개 샘플 청구서 PDF를 필드 및 신뢰도(confidence)와 함께 읽어내는 과정까지 (인증은 키를 사용하지 않는 Entra ID 방식)

이용 시나리오

Azure Document Intelligence의 청구서 모델은 종이나 PDF 청구서를 대량으로 처리해야 하는 상황에서 유용합니다. 구체적으로는 다음과 같은 케이스입니다.

Document Intelligence의 청구서 모델이란

Azure Document Intelligence는 문서에서 문자·표·구조를 추출하는 서비스입니다. 그중 청구서 모델(prebuilt-invoice)은 청구서라는 양식을 학습한 모델로, PDF나 이미지를 넣으면 벤더명(vendor name)·청구처·청구 번호·각종 날짜·소계 및 합계와 같은 항목을 필드명(field name)이 포함된 구조화된 데이터로 반환합니다.

각 필드에는 0~1 사이의 신뢰도(confidence)가 붙으며, 명세(Items)는 품목·수량·금액의 배열로 가져올 수 있습니다. 양식마다 템플릿을 일일이 만들지 않아도 공통된 필드명으로 결과를 받을 수 있는 것이 청구서 모델의 특징입니다.

데모 영상

입력에 사용할 청구서는 이것입니다. Azure-Samples가 공개하고 있는 샘플 PDF(CONTOSO LTD. 대상, PII 없음)로, 벤더명·청구처·청구 번호·각종 날짜·명세·소계 및 합계 등 청구서의 전형적인 항목들이 모두 포함되어 있습니다.

이 청구서 PDF를 전달하면 다음과 같이 필드와 신뢰도가 반환됩니다.

검증 방법

리소스 생성

검증용 Bicep과 샘플 코드는 공개 리포지토리의 docintel-invoice/에 있습니다.

Bicep의 내용(리소스 정의 부분)입니다.

이 템플릿은 kind=AIServices를 사용하고 있습니다. Document Intelligence 단독 리소스는 kind=FormRecognizer이지만, 통합된 AIServices로 설정해 두면 청구서 모델을 그대로 호출할 수 있고, 다른 Foundry Tools로 유용할 때도 kind만 변경하면 됩니다. 이번에는 japaneast의 S0에서 prebuilt-invoice가 동작하는 것을 확인했습니다.

최소 코드로 호출하기

포인트는 DefaultAzureCredential()을 전달하는 것만으로 키(key)가 필요 없다는 점과, begin_analyze_document("prebuilt-invoice", ...)에 샘플 청구서의 URL을 전달하는 것만으로 분석이 시작된다는 점입니다. 분석 대상은 Azure-Samples가 공개하고 있는 청구서 PDF(CONTOSO LTD. 대상, PII 없음)를 URL 지정 방식으로 읽어옵니다. 동일한 PDF는 공개 리포지토리의 docintel-invoice/sample-invoice.pdf에도 있으므로, 가지고 있는 파일을 url_source에서 교체하여 테스트할 수 있습니다.

pip install azure-ai-documentintelligence azure-identity
az login
python quickstart.py

실제 출력 결과입니다.

--- 청구서 #1 (doc 신뢰도=1.000) ---
벤더명 (VendorName): CONTOSO LTD. (confidence=0.938)
청구처 (CustomerName): MICROSOFT CORPORATION (confidence=0.917)
...

값 자체는 공식이 나타내는 기대치와 일치했습니다. 주목해야 할 점은 필드(Field) 단위의 신뢰도(Confidence)입니다. 청구 번호나 각 날짜는 0.97 전후로 높은 반면, 합계(InvoiceTotal)는 0.723으로 다른 항목보다 낮게 나타났습니다. 동일한 청구서 내에서도 항목마다 신뢰도가 다르기 때문에, 전체를 하나로 묶지 않고 신뢰도가 낮은 항목만 수동으로 확인하는 등의 분류 작업에 활용할 수 있습니다.

결과값 읽기

구현 시 처음에 가장 많이 헤매는 부분이 필드 값의 추출 방법입니다. result.documents[].fields는 필드명을 키(Key)로 하는 딕셔너리(Dictionary)이지만, 값의 프로퍼티(Property)는 타입(Type)마다 다릅니다. "모두 .content로 가져오면 된다"는 식으로는 해결되지 않으며, 타입에 따라 추출 방식을 변경해야 합니다.

필드 예시	타입	추출 경로	반환 값
VendorName	문자열 (String)	`value_string`	`"CONTOSO LTD."`
InvoiceTotal	금액 (Currency)	`value_currency`	`.amount=110.0` / `.currency_symbol="$"`
InvoiceDate	날짜 (Date)	`value_date`	`date(2019, 11, 15)`
Items	배열 (Array)	`value_array`	명세 행(품목·수량·금액)의 나열

quickstart.py에서는 이러한 타입별 분기를 field_str()에 모아두었습니다.

def field_str(field):
    for attr in ("value_string", "value_number", "value_date",
                "value_currency", "content"):
        ...

또 다른 요령은 content와 value_*를 구분해서 사용하는 것입니다.

content: 청구서에 인쇄된 가공되지 않은 텍스트 (예: 청구일이 "11/15/2019")
value_*: 타입에 맞춰 정규화(Normalization)된 값 (예: 청구일이 date(2019, 11, 15), 금액이 수치인 amount)

집계나 대조 작업에는 표기법이 제각각인 content 대신, 정규화된 value_*를 사용하는 것이 청구서 모델을 실무에 적용할 때의 핵심 노하우입니다.

Tips

F0(무료) 계층은 2페이지/4MB 제한이 엄격하여, 여러 페이지로 구성된 청구서는 중간에 잘릴 수 있습니다. 검증이나 실제 운영은 S0 계층에서 진행해야 제한에 걸리지 않습니다.
신규 및 구형 SDK의 혼동에 주의하세요. 이번에 사용하는 것은 azure-ai-documentintelligence의 DocumentIntelligenceClient (API 버전 2024-11-30 / v4.0)입니다. 구형 azure-ai-formrecognizer의 DocumentAnalysisClient와는 패키지와 클래스가 모두 다르므로, 샘플을 찾을 때는 버전을 맞춰야 합니다.
필드 단위의 신뢰도(Confidence)를 임계값(Threshold) 운영에 활용하세요. 이번 사례에서는 합계가 0.723으로 낮았습니다. 예를 들어 0.8 미만의 항목만 수동 검토(Human Review)로 넘기는 방식으로 운영하면, 전수 육안 확인보다 확인 비용을 줄이면서 오인식을 방지할 수 있습니다.

요약

청구서 모델은 양식이 제각각인 청구서를 필드명이 포함된 구조화된 데이터(Structured Data)로 변환해 줍니다. 템플릿을 직접 만들 필요가 없으며, 제공되는 Bicep을 사용하면 몇 분 만에 테스트할 수 있습니다.

"신뢰도가 낮은 항목만 수동 검토로 넘긴다", "정규화된 value_*를 집계에 사용한다", "인증은 키리스(Keyless)로 한다" 이 세 가지 포인트를 잡으면 실무 적용이 훨씬 쉬워집니다.

이 시리즈에서는 Foundry Tools의 각 서비스를 하나씩 "5분 만에 개요 파악 + 즉시 배포"할 수 있는 형태로 소개할 예정입니다. 다음 편도 기대해 주세요.