BroadRouter

비전 LLM으로 송장·영수증·양식 데이터를 JSON으로 추출하기

BroadNet Inference 팀 · 4분 분량 · 게시

각 페이지를 이미지로 렌더링하고, 모든 필드와 형식을 명시한 프롬프트와 함께 비전 모델에 보내 JSON만 요청하세요. 그런 다음 코드로 검증합니다. 파싱하고, 스키마를 확인하고, 품목 금액의 합이 총액과 맞는지 확인하고, 실패하면 오류를 넣어 한 번 재시도하세요. 반복해서 실패하면 사람에게 넘기세요.

A paper invoice headed "فاتورة" (invoice) with tabs labelled Vendor, Date and Total, and the text "Turn documents into useful data."
Illustrative example.

송장, 영수증, 양식에는 모두 같은 문제가 있습니다. 데이터는 이미지 속에 있는데, 필요한 곳은 데이터베이스입니다. 템플릿 기반 OCR은 새 거래처 레이아웃이 나올 때마다 깨집니다. 비전-언어 모델은 페이지를 읽고 필드를 바로 반환합니다. 문제는 자신 있게 틀릴 수 있다는 점이므로, 핵심 작업은 모델을 둘러싼 파이프라인에 있습니다. 이 글은 언어와 상관없이 쓸 수 있는 일반적인 파이프라인을 다룹니다. 아랍어 문서라면 설정은 비전 모델로 아랍어 송장 읽기를, 기존 OCR이 더 나은 경우는 아랍어 OCR과 비전 LLM 비교를 참고하세요.

파이프라인은 어떻게 구성되나요?

  1. 각 페이지를 준비합니다. PDF를 이미지로 렌더링하고, 회전을 바로잡고, 크기를 조정합니다.
  2. 추출합니다. 문서마다 필드별 프롬프트로 요청 하나를 보내고 JSON만 받습니다.
  3. 검증합니다. 파싱, 스키마 검사, 합계 검사를 합니다.
  4. 검증에 실패하면 오류 메시지를 넣어 한 번 재시도합니다.
  5. 검토합니다. 그래도 실패하면 이미지와 초안을 함께 사람에게 보냅니다.
  6. 레이블을 단 샘플로 필드 정확도를 측정하고, 모델이나 프롬프트를 바꿀 때마다 다시 실행합니다.

문서 이미지는 어떻게 준비하나요?

PyMuPDF로 PDF를 이미지로 렌더링하고, 가장 작은 텍스트는 선명하게 유지하되 필요 이상의 픽셀은 보내지 마세요.

# pip install pymupdf pillow
import base64, io
import pymupdf  # older code imports it as fitz
from PIL import Image

def pdf_pages_as_data_urls(path, long_edge=1800):
    urls = []
    for page in pymupdf.open(path):
        pix = page.get_pixmap(dpi=200)
        img = Image.open(io.BytesIO(pix.tobytes("png"))).convert("RGB")
        img.thumbnail((long_edge, long_edge))
        buf = io.BytesIO()
        img.save(buf, format="JPEG", quality=90)
        urls.append("data:image/jpeg;base64," + base64.b64encode(buf.getvalue()).decode())
    return urls

BroadNet Inference에서 이미지는 정확한 MIME 타입을 붙인 data: URL로 메시지에 넣으며, 종량제에서는 입력 토큰으로 과금됩니다. 큰 이미지일수록 더 많이 씁니다. usage 블록으로 페이지당 토큰을 한 번 측정하고 그에 맞춰 배치 크기를 정하세요. 방법은 보내기 전에 토큰 세기에 있고, 비전 LLM 이미지당 비용은 토큰을 페이지당 비용으로 환산합니다. 아무것도 보내기 전에 페이지당 토큰을 추정하려면 샘플 스캔을 이미지 토큰 계산기에 넣어 보세요.

추출 프롬프트는 어떻게 작성해야 하나요?

키, 타입, 형식, 누락 값을 정확하게 지정하세요. 검증용이나 스키마를 강제하는 제공업체용으로 JSON Schema도 필요하다면, 무료 JSON 스키마 생성기가 샘플 송장으로 스키마를 만들어 줍니다.

PROMPT = """Extract this invoice. Reply with one JSON object only, no prose.
Keys:
- vendor_name: string, as printed
- vendor_tax_id: string or null
- invoice_number: string
- invoice_date: string, YYYY-MM-DD
- currency: ISO 4217 code, e.g. USD, EUR, SAR
- line_items: list of {description: string, quantity: number, unit_price: number, line_total: number}
- subtotal: number
- tax: number or null
- total: number
Rules: numbers without currency symbols or thousands separators. If a field is not on the page, use null. Never guess."""

가장 중요한 것은 “Never guess”(추측 금지)와 명시적인 null입니다. 이것이 없으면 모델은 빈칸을 그럴듯한 값으로 채우는데, 이는 단순한 검사를 통과해 버리므로 빈칸보다 더 나쁩니다.

구조화된 출력은 어떻게 받고 어떻게 검증하나요?

구조화된 출력에는 두 단계가 있습니다. JSON 모드는 유효한 JSON을 보장합니다. 스키마 제약 출력은 형태까지 보장합니다. OpenAI 가이드는 분명하게 말합니다. 둘 다 유효한 JSON을 만들지만, 스키마 준수를 보장하는 것은 Structured Outputs뿐입니다. 어느 쪽을 지원하는지는 제공업체와 모델마다 다르므로, API가 무엇을 약속하든 코드에서 검증하세요.

import json, os
from decimal import Decimal
from pydantic import BaseModel, ValidationError, model_validator
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Line(BaseModel):
    description: str
    quantity: Decimal
    unit_price: Decimal
    line_total: Decimal

class Invoice(BaseModel):
    vendor_name: str
    vendor_tax_id: str | None = None
    invoice_number: str
    invoice_date: str
    currency: str
    line_items: list[Line]
    subtotal: Decimal
    tax: Decimal | None = None
    total: Decimal

    @model_validator(mode="after")
    def sums(self):
        tol = Decimal("0.02")
        if abs(sum(l.line_total for l in self.line_items) - self.subtotal) > tol:
            raise ValueError("line_totals do not sum to subtotal")
        if abs(self.subtotal + (self.tax or 0) - self.total) > tol:
            raise ValueError("subtotal + tax != total")
        return self

def extract(image_urls, model="broadnet/qwen3.8-27b"):
    content = [{"type": "text", "text": PROMPT}] + [
        {"type": "image_url", "image_url": {"url": u}} for u in image_urls]
    messages = [{"role": "user", "content": content}]
    for attempt in range(2):
        r = client.chat.completions.create(model=model, messages=messages, max_tokens=4000, temperature=0)
        raw = (r.choices[0].message.content or "").strip().removeprefix("```json").removesuffix("```")
        try:
            return Invoice.model_validate(json.loads(raw)), r.usage
        except (json.JSONDecodeError, ValidationError, ValueError) as e:
            messages += [{"role": "assistant", "content": raw},
                         {"role": "user", "content": f"That failed validation: {e}. Re-read the image and reply with corrected JSON only."}]
    return None, r.usage  # send to human review

금액에는 float가 아니라 Decimal을 쓰세요. max_tokens는 넉넉하게 두세요. Qwen3.8 27B는 답하기 전에 추론하며, 추론은 한도에 포함됩니다. 상한이 작으면 빈 문자열이 반환됩니다. 추론 모델이 빈 응답을 반환하는 이유를 참고하세요.

어떤 검사가 가장 많은 오류를 잡아내나요?

검사 잡아내는 오류 비용
JSON 파싱 JSON 주변의 설명 문장, 잘림 무료
스키마 검증 누락된 키, 잘못된 타입 무료
품목 합계와 소계 일치 잘못 읽은 숫자, 빠진 품목 무료
소계 + 세금 = 총액 잘못 읽은 총액이나 세금 무료
날짜 파싱 가능, 미래 날짜 아님 일/월 뒤바뀜, OCR 노이즈 무료
거래처 사업자 번호가 공급업체 목록과 일치 잘못된 거래처, 사기 조회 1회
거래처별 송장 번호 중복 이중 지급 쿼리 1회

합계 검사가 가장 효과적입니다. 숫자 하나만 잘못 읽어도 거의 항상 합이 맞지 않습니다. 영수증에는 품목 단위 정보가 없는 경우가 많으니, 있는 정보로 검사하고 영수증은 검사 수가 적은 것을 받아들이세요.

운영 전에 정확도는 어떻게 측정하나요?

실제 문서 50~100개에 직접 레이블을 달고, 파이프라인을 실행하고, 문서 단위가 아니라 필드 단위로 채점하세요. 총액과 날짜는 설명 필드보다 더 엄격한 기준이 필요합니다. 필드 정확도, 재시도 없이 검증을 통과한 문서의 비율, 검토로 보낸 비율 세 가지를 추적하세요. 통과한 문서의 무작위 감사를 포함해 검토 단계를 설계하는 방법은 문서 AI 워크플로에 사람의 검토 포함하기에 있습니다. 다른 모델을 시도할 때는 같은 세트를 돌리세요. 방법은 모델을 바꾸기 전에 LLM 평가하기에서 다룹니다.

BroadNet Inference에서는 어떤 비전 모델이 맞나요?

모델 이미지 컨텍스트 비고
Qwen3.8 27B 예 262,144 도구, 구조화된 출력, 추론 지원 표시, BroadNet이 아랍어로 테스트
Gemma 4 VL 26B 예 32,768 BroadNet 최저가, 무료 크레딧과 시간제 키로 사용 가능
DeepSeek V4.1 Flash 예 1,048,576 무제한 플랜에 이미지 포함

100만 토큰당 가격은 가격 페이지에 있습니다. 측정한 페이지당 토큰에 월간 처리량을 곱한 계산은 LLM API 비용 계산기로 하세요.

BroadNet Inference가 맞는 경우

BroadNet Inference는 표준 OpenAI 메시지 형식으로 채팅 모델 세 개에서 이미지를 받으며, 요청이 끝난 뒤 프롬프트, 이미지, 답변을 보관하지 않습니다. 이름, 사업자 번호, 은행 정보로 가득한 송장에서는 중요한 점입니다(데이터 비보관). 문서에는 Qwen3.8 27B가 구조화된 출력을 지원한다고 나오지만 스키마 파라미터는 문서화되어 있지 않으므로, 스키마 강제를 API에 맡기지 말고 위의 검증 계층에 의존하세요. BroadNet은 이미지 크기 제한이나 전용 문서 AI 제품을 공개하지 않으며, 문서에는 PDF 업로드가 아니라 이미지 입력만 설명되어 있으니 먼저 페이지를 이미지로 렌더링하세요. 고정 예산으로 대량 처리를 하려면 DeepSeek V4.1 Flash 무제한 플랜에 이미지가 포함됩니다.

자주 묻는 질문

비전 LLM이 송장 OCR을 대체할 수 있나요?

많은 레이아웃에서는 가능합니다. 비전 모델은 이미지를 읽고 텍스트를 필드에 매핑하는 일을 한 단계로, 거래처별 템플릿 없이 처리합니다. 그래도 가끔 숫자를 잘못 읽으므로 검증과 검토 큐는 유지하세요.

비전 모델에서 안정적으로 JSON을 받으려면 어떻게 하나요?

프롬프트에 정확한 키, 타입, 형식을 나열하고, JSON만 요청하고, 코드에서 파싱하세요. 모델이 스키마 제약 출력을 지원하면 사용하세요. 어느 쪽이든 스키마 라이브러리로 검증하고, 실패하면 오류를 넣어 한 번 재시도하세요.

여러 페이지로 된 PDF 송장에서 데이터를 추출하려면 어떻게 하나요?

각 페이지를 이미지로 렌더링한 뒤, 모델의 컨텍스트에 들어간다면 송장 하나의 모든 페이지를 요청 하나로 보내세요. 그래야 마지막 페이지의 총액을 첫 페이지의 품목과 맞춰 볼 수 있습니다.

송장 이미지 해상도는 어느 정도가 적당한가요?

가장 작은 숫자가 선명할 만큼 높되, 그 이상은 필요 없습니다. 이미지가 클수록 입력 토큰을 더 씁니다. A4 페이지라면 긴 변 약 1,500~2,000픽셀이 무난한 출발점이며, 자신의 문서로 테스트하세요.

추출 정확도는 어떻게 측정하나요?

실제 문서 50~100개에 직접 레이블을 달고 필드별로 채점하세요. 총액과 날짜는 거래처명 같은 자유 텍스트 필드와 따로 추적하세요. 오류의 비용이 다르기 때문입니다.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기