송장, 영수증, 양식에는 모두 같은 문제가 있습니다. 데이터는 이미지 속에 있는데, 필요한 곳은 데이터베이스입니다. 템플릿 기반 OCR은 새 거래처 레이아웃이 나올 때마다 깨집니다. 비전-언어 모델은 페이지를 읽고 필드를 바로 반환합니다. 문제는 자신 있게 틀릴 수 있다는 점이므로, 핵심 작업은 모델을 둘러싼 파이프라인에 있습니다. 이 글은 언어와 상관없이 쓸 수 있는 일반적인 파이프라인을 다룹니다. 아랍어 문서라면 설정은 비전 모델로 아랍어 송장 읽기를, 기존 OCR이 더 나은 경우는 아랍어 OCR과 비전 LLM 비교를 참고하세요.
파이프라인은 어떻게 구성되나요?
- 각 페이지를 준비합니다. PDF를 이미지로 렌더링하고, 회전을 바로잡고, 크기를 조정합니다.
- 추출합니다. 문서마다 필드별 프롬프트로 요청 하나를 보내고 JSON만 받습니다.
- 검증합니다. 파싱, 스키마 검사, 합계 검사를 합니다.
- 검증에 실패하면 오류 메시지를 넣어 한 번 재시도합니다.
- 검토합니다. 그래도 실패하면 이미지와 초안을 함께 사람에게 보냅니다.
- 레이블을 단 샘플로 필드 정확도를 측정하고, 모델이나 프롬프트를 바꿀 때마다 다시 실행합니다.
문서 이미지는 어떻게 준비하나요?
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 무제한 플랜에 이미지가 포함됩니다.

