쓸모 쓸모연구소 · 실전 노트
제 825 호이번 주 새 글 49 편2026 · 11 · 14
챗GPT·제미나이⁠·AI 소식
JEV

Jev 이미지 분류 자동화, 영수증⁠·스크린샷 처리와 확신도 기준

Jev 이미지 분류 자동화는 영수증, 배송 사진, 문의 티켓에 붙은 스크린샷처럼 쌓여 있는 이미지를 빠르게 나누고 검토할 것만 골라내는 방식입니다. 이미지를 넣는 조건, 질문을 세우는 순서(대상이 있는지 먼저 묻고 위치는 그다음), 사례 8가지, 결과를 자동 처리와 사람 검토로 가르는 확신도 기준을 정리했습니다.

Jev 이미지 분류 자동화, 영수증·스크린샷 처리와 확신도 기준 삽화
삽화 · 쓸모연구소

이미지를 보는 Jev가 맡는 일

Jev는 글을 쓰지 않고 질문에 확률로 답하는 모델입니다. 이미지가 들어가도 방식은 같습니다. "이 사진에 마실 수 있는 것이 있나" 같은 예/아니요(Noul), "이 사진은 어느 분류인가" 같은 선택(Choice), 척도에 점수 매기기(Score)에 더해, 1.14부터는 이미지 속 위치를 상자로 찾는 Box 질문이 생겼습니다. 이전에는 이런 일에 이미지 분류 전용 모델을 따로 학습시켜야 했지만, 지금은 확인할 내용을 문장으로 적고 이미지를 같이 보내면 됩니다.

알아 둘 점이 세 가지 있습니다.

  • 이미지 입력은 1.13과 1.14 모두 되고, Box만 1.14(jev-1.14.0)가 필요합니다. 1.14는 2026년 10월 14일에 나왔습니다.
  • 이미지와 Box는 아직 미리 보기 단계입니다. 공식 문서가 요청 형식과 정확도가 릴리스마다 바뀔 수 있다고 안내하니 운영 서비스의 유일한 판단 근거로 삼지 않습니다.
  • 이미지는 별도 요금 없이 입력 토큰으로 계산됩니다. 입력 100만 토큰당 0.042달러, 출력 무료입니다(2026년 11월 기준, 바뀔 수 있음).

이미지를 보내기 전에 확인할 조건

요청마다 아래 헤더가 있어야 합니다. 이미지나 Box 질문이 들어간 요청에 이 헤더가 없으면 400 오류가 납니다.

프롬프트
TypeSafe-Danger-Zone-Images: true

이미지 조건은 이렇습니다(공식 이미지 문서 기준).

  • 형식: PNG 또는 JPEG 정지 이미지. GIF, WebP, HEIC는 먼저 PNG나 JPEG로 바꿉니다. 동영상과 오디오는 받지 않습니다.
  • 크기: 파일 하나 16MiB 이하, 가로세로 각각 280~1568픽셀
  • 요청 전체: 본문 32MiB 이하
  • 범위를 벗어난 이미지는 줄여 주지 않고 거부하며, 한 장이 거부되면 요청 전체가 실패합니다.
  • 범위를 넘으면 413 오류가 납니다.

큰 사진은 보내기 전에 줄입니다. 아래는 파이썬 Pillow로 방향을 바로잡고 긴 변을 1568픽셀로 줄이는 예입니다. 280픽셀보다 작은 이미지는 줄이는 문제가 아니라 거부되므로 그런 이미지는 원본을 키우지 않고 걸러 냅니다.

프롬프트
from PIL import Image, ImageOps

img = ImageOps.exif_transpose(Image.open("원본.jpg")).convert("RGB")
img.thumbnail((1568, 1568))
img.save("작게.jpg", "JPEG", quality=90)

크기가 한도를 넘어서 막힐 때는 크기 조정이나 자르기만으로 풀리는 경우가 많습니다.

질문은 Noul 먼저, Box는 그다음

Box에는 "찾을 수 없음"이라는 답이 없습니다. 이미지에 전혀 없는 물건을 찾으라고 해도 네 변의 좌표를 돌려줍니다. 그래서 같은 요청에 "이미지에 그게 있나"를 묻는 Noul을 함께 넣고, Noul 값이 낮으면 Box 결과를 버립니다.

공식 문서의 Box 예제를 한국어로 바꾸면 아래와 같습니다. 이미지는 assets에 등록하고 state에서 이름으로 연결한 뒤, 질문에서 백틱으로 감싼 이름으로 가리킵니다.

명령어
curl https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "TypeSafe-Danger-Zone-Images: true" \
  -F 'request={
    "model": "jev-1.14.0",
    "state": {"photo": "6e1d0b7c-kitchen"},
    "assets": {"6e1d0b7c-kitchen": {"type": "image", "part": "kitchen-photo"}},
    "questions": {
      "has_mug": {"type": "noul", "instructions": "`photo`에 머그컵이 있나요?"},
      "mug": {"type": "box", "instructions": "`photo`의 머그컵"}
    }
  };type=application/json' \
  -F '[email protected];type=image/jpeg'

결과의 box는 top, bottom, left, right 네 값이고 전부 0~1 비율입니다. 왼쪽 위 모서리에서 잰 가로세로 비율이라서 픽셀 좌표가 필요하면 이미지 폭과 높이를 곱합니다. confidence도 0~1로 함께 옵니다. Box는 대상 하나에 질문 하나를 씁니다. 같은 물건이 여러 개면 원하는 하나를 설명하거나 이미지를 영역으로 나눕니다.

요청마다 이미지를 쓰는 곳은 세 군데입니다.

  • 상태(state): 판단할 대상 이미지. 글과 섞어 여러 장을 넣을 수 있습니다.
  • 질문 지침: 그 질문에만 쓰는 이미지. 여러 질문이 같은 이미지를 쓰면 상태에 한 번만 넣고 이름으로 가리키는 편이 용량을 아낍니다.
  • 기준(criteria): 선택지, 점수 단계, 예/아니요의 정의를 이미지로 줄 수 있습니다.

넣은 이미지는 질문 어딘가에서 반드시 가리켜야 합니다. 가리키지 않은 이미지가 있으면 400 오류가 납니다.

이미지를 쓰는 네 가지 패턴

  • 알려진 사진과 비교: 상태의 사진이 기준 사진과 같은 사람, 제품, 장소인지 묻습니다.
  • 선택지를 예시 이미지로 정의: 설명 글 없이 이미지만으로 보기를 정의합니다. 한 시험에서는 문제가 생겼을 때 반응할 밈 이미지 여러 장 중 하나를 고르게 하는 기준을 이미지로만 주었는데 맞는 이미지를 골랐다고 합니다.
  • 변화 감지: 영상에서 뽑은 이전 프레임을 함께 보내 움직임이 있었는지, 동물이 보이는지, 사람이 도착했는지 묻습니다. 선택할 보기는 직접 정해 줘야 합니다.
  • 고해상도 이미지: 이미지를 타일로 잘라 타일을 보기로 한 선택 질문을 하고, 고른 타일만 다시 고해상도로 잘라 자세히 묻습니다. 공식 Box 문서도 작은 대상은 먼저 영역을 찾은 뒤 그 부분을 잘라 다시 묻도록 안내합니다.

질문을 짜는 예, 선반 위 음료와 깨진 휴대폰

질문 유형마다 이미지가 어떻게 쓰이는지는 플레이그라운드(console.typesafe.ai/playground)에서 시험해 볼 수 있습니다. 한 제작자가 시연한 예는 이렇습니다.

  • 선반 위 액체 사진에 "마실 수 있는 것이 있나"를 Noul로 물으면 0.94 정도의 값이 나옵니다. 이미지에 마실 수 있는 무언가가 있다는 뜻이지만, Noul은 있는지만 알려 줄 뿐 어디에 있는지는 알려 주지 않습니다. 위치가 필요하면 Box를 더합니다.
  • 인화성 경고 그림을 주고 "어느 물질의 위험 표시인가"를 Choice로 물으면 보기 중에서 곡물 알코올 같은 인화성 물질을 고릅니다. 표백제 라벨에도 위험 아이콘은 붙지만 표백제는 인화성이 아니라는 식으로, 보기 설명을 구체적으로 적을수록 구별이 잘 됩니다.
  • 주방 조리대에서 타일 바닥으로 떨어져 화면이 깨졌다는 휴대폰 사진을 평가하는 예가 이미지 질문을 가장 잘 보여 줍니다. 손상 정도는 "없음"에서 "극심"까지의 Score 척도로 묻습니다. 사진이 그 주장을 뒷받침하는지, 아이폰인지 안드로이드인지는 Noul과 Choice로 따로 묻습니다. 결과는 "극심"이 아니라 "심각"이었고, 설명은 광범위한 균열이나 깊은 찌그러짐, 빠진 조각이 있는 상태가 "심각", 눈에 띄게 으스러진 상태가 "극심"이었습니다.

이 예에서 얻는 설계 요령은 한 질문에 한 가지만 묻는 것입니다. 손상 정도, 주장과의 일치, 기종은 서로 다른 질문으로 나누고, 질문 여러 개를 같은 요청에 담으면 이미지는 한 번만 보내도 모두 같은 이미지로 평가됩니다. 질문끼리는 독립이어서 서로의 답을 참고하지 않으므로, 답이 어긋나는 경우가 생기면 그 어긋남 자체를 검토 신호로 삼을 수 있습니다.

이미지 분류 자동화 사례 8가지

1. 영수증 분류와 큰 지출 표시

영수증 이미지마다 작은 질문 세 개를 보냅니다. "영수증인가", "어떤 항목인가", "내 금액 한도를 넘는가"입니다. 한도를 넘은 영수증만 따로 목록으로 뽑아 증빙 정리와 큰 지출 확인에 씁니다. 금액이 중요한 일이라 Noul 값이 애매한 영수증은 사람이 확인하도록 기준을 둡니다(아래 확신도 기준 참고).

2. 사진 폴더 자동 분류

행사 사진처럼 수백 장이 쌓인 폴더를 "제품 사진", "테마 사진", "흐린 사진(버릴 것)" 같은 분류 이름으로 나눕니다. 분류 이름과 한 줄 설명을 Choice 보기로 주고 사진마다 한 번씩 돌립니다. 헷갈리는 보기는 설명에 무엇이 다른지 적어 줍니다.

3. 파손 소포 평가와 위치 표시

환불을 요청하며 고객이 보낸 파손 사진에 "소포가 파손됐나"를 Noul로 묻고, 예일 때 Box로 파손 위치를 표시합니다. 환불을 검토하는 사람이 전체 사진을 훑지 않고 표시된 곳부터 볼 수 있습니다. Noul이 낮으면 Box 결과는 쓰지 않습니다.

4. 배송 증빙 사진 확인

기사가 문 앞에서 찍은 배송 사진에서 "소포가 찍혔나", "사진이 선명한가"를 묻습니다. 흐리거나 소포가 없으면 문제 신호입니다. 기사용 앱에 붙여서 촬영 직후 검사하고 실패하면 떠나기 전에 다시 찍게 하는 구상이 있습니다. 아직은 설계 단계의 아이디어입니다.

5. 지원 티켓 스크린샷 분류

글로 된 문의는 이미 분류할 수 있었지만 버그 제보에 붙는 스크린샷까지 본다는 점이 다릅니다. "어느 화면인가", "오류 메시지가 있나", "결제 화면인가"를 묻고 답에 따라 담당 부서로 보냅니다. 고객 메일에 급하다는 내용이 있으면 앞순위로 올립니다. 스크린샷이 주장한 문제를 뒷받침하는지 Noul로 묻고, 뚜렷하지 않으면 사용자에게 다시 요청하는 앱도 만들 수 있습니다.

6. 쇼츠용 세로 크롭 위치 찾기

Jev는 동영상을 받지 않으므로 먼저 FFmpeg(무료 오픈소스 영상 도구)로 1초 간격 정지 프레임을 뽑고, 프레임마다 시간 정보를 같이 둡니다. 프레임에 Box로 "얼굴" 위치를 묻고, 그 위치를 기준으로 세로 영상 자르기를 합니다. 크롭 상자를 손으로 맞추거나 큰 모델이 이미지를 하나씩 읽으며 토큰을 쓰지 않아도 됩니다. 좀 더 틈새 용도입니다.

7. 자판기와 진열대 재고 알림

작은 카메라로 한 시간에 한 번 사진을 찍어 "빈 칸이 있나"를 묻고, 빈 칸 정보를 알림으로 보내는 구상입니다. 설치 환경이 정해져 있어야 하는 구상 단계의 사례입니다.

8. 문서를 페이지 이미지로 바꿔 분류하기

문서 한 쪽도 그림이 될 수 있습니다. 서류 묶음, 도면 세트, 대출 신청 서류 같은 큰 더미를 페이지 이미지로 바꿔 장별로 분류하면 글자를 읽는 단계 없이도 나눌 수 있습니다. 표와 도면처럼 시각 자료가 많은 문서는 이미지로 보는 방식이 맞을 수 있습니다. 글로 읽는 방식과 같은 문서 몇십 건으로 나란히 돌려 비교한 뒤 정합니다.

TypeSafe 쿡북의 실제 구성 예

공식 쿡북에는 이미지 판단을 여러 질문으로 짜는 예제가 있습니다.

  • 스캔한 예방접종 기록: 백신 16종마다 "이 페이지에 있나"(Noul)와 "그 줄이 어디인가"(Box)를 묻고, 찾은 줄마다 접종 연도를 Choice로 읽고 날짜가 읽히는지 Noul로 묻습니다. 날짜 계산은 코드가 합니다. 6종이 확인됐고 그중 두 줄이 간호사 확인 대상으로 표시됐습니다. 하나는 날짜가 스티커에 가려 읽을 수 없는 줄이고, 다른 하나는 날짜는 선명하지만 접종한 지 오래된 줄입니다. 읽기와 점검을 한 요청에 합치면 문제 있는 줄을 놓쳤다고 쿡북에 적혀 있어 요청을 나눠 구성했습니다. "읽을 수 없음"이라는 보기를 넣어 추측을 막은 것도 이 예제의 요점입니다.
  • 새 모이통 카메라: 101초짜리 영상을 1초에 한 장씩 자른 프레임에 질문 다섯 개(새가 있나, 몇 마리인가, 위치, 왼쪽과 오른쪽 새의 종)를 한 번에 보냈습니다. 프레임 101장에 요청 178건, 프레임당 중앙값 0.54초가 걸렸고 새가 있는지는 101프레임에서 사람이 붙인 정답과 모두 일치했습니다. 한 질문으로는 같은 종 여러 마리를 구별하지 못하고 한 프레임에서 두 마리까지만 다룬다는 한계가 적혀 있습니다.

이미지 수천 장의 비용 감 잡기

이미지는 입력 토큰으로 계산되므로 비용은 응답의 usage.input_tokens로 확인합니다. 이미지 한 장이 몇 토큰인지에 대한 공식 추정 안내는 아직 준비 중이라서, 먼저 이미지 몇 장을 보내 실제 토큰 수를 잰 뒤 계산하는 편이 정확합니다. 계산식은 단순합니다. 전체 입력 토큰을 100만으로 나눈 값에 0.042달러를 곱합니다.

예를 들어 이미지 한 장과 질문 세 개가 합쳐 1,500토큰이라고 가정하면 1,000장은 150만 토큰이라서 약 0.063달러입니다. 이 숫자는 설명을 위한 가정이고, 같은 이미지에도 모델에 따라 잡히는 토큰 수가 다를 수 있습니다. 단가가 싼 모델도 이미지가 토큰을 더 많이 쓰면 총액이 비슷해질 수 있으니 총액으로 비교합니다.

요청 하나에 담을 수 있는 양은 상태와 질문을 합쳐 6만 4천 토큰, 질문 하나당 3만 2천 토큰입니다. 이미지가 많으면 이 한도가 먼저 걸리고, 한도를 넘으면 max_tokens_exceeded 오류가 납니다. 그래서 큰 작업은 이미지를 나누어 여러 요청으로 보냅니다. 요청이 몰리면 조직 단위의 초당 토큰과 요청 수 한도에 걸려 429 오류가 나는데, 공식 SDK는 기본으로 다시 시도하고 retry-after 안내를 따릅니다.

확신도 기준선으로 자동 처리와 사람 검토를 나누기

이미지 분류는 틀리는 경우가 있으니 결과마다 붙는 숫자로 자동 처리할 것과 사람이 볼 것을 가릅니다.

  1. 질문마다 확률이나 확신도를 읽습니다. Noul은 값 하나, Choice와 Score는 확신도(0~1), Box는 상자와 확신도가 옵니다.
  2. 자동으로 넘길 기준선을 하나 정합니다. 공식 문서는 Noul은 0.7 이상이면 예, 0.3 이하면 아니요로 읽고 그 사이는 따로 처리하기를 제안합니다. Box는 권장 기준이 없어 내 이미지로 시험해서 정합니다.
  3. 기준선 이상이면 자동으로 처리합니다.
  4. 기준선 미만이면 사람 검토 목록에 모읍니다. 흐린 이미지는 확신도가 낮게 나오는 경우가 많고, 그런 이미지가 검토 목록으로 모이는 것이 이 구조의 목적입니다.
  5. 낮은 Box 확신도는 더 큰 이미지나 잘라 낸 부분으로 다시 묻거나 상자 주변을 넓혀 자릅니다.

합성 데이터 1,000건으로 해 본 실험

한 제작자가 버그 리포트 텍스트에 합성 스크린샷을 붙여 티켓 1,000건을 만들고 이 방식을 시험했습니다. 정답을 알고 있는 데이터입니다.

  • 속도와 비용: 한 번에 16건씩 묶어 1,000건에 약 20초, 11센트
  • 분류: 724건은 엉뚱한 스크린샷이라 고객에게 돌려보내고, 175건은 올바른 스크린샷과 상자가 확인돼 수락, 101건은 사람 검토로 보냈습니다.
  • 정확도 93.4%(934건 정답, 66건 오답). 오답은 모두 사람 검토로 보낸 101건 안에 있었고 자동으로 결정한 899건에서는 오답이 없었습니다.
  • 기준치는 확신도 65%로 잡았습니다. 이 값은 그 실험의 선택이며 권장값이 아닙니다.

배포 전에는 세 가지를 따로 봅니다. 정확도(얼마나 맞히나), 확신도(Jev가 자기 답을 얼마나 강하게 믿나), 보정(제시한 확률이 현실과 얼마나 맞나)입니다. 위 실험에서 자동 결정 899건은 평균 95.3%의 확률을 냈으니 실수가 약 42건 있어야 했는데 실제로는 0건이었습니다. 검토로 간 101건은 평균 확률이 48%였는데 실제 정확도는 약 34%였습니다. 즉 이 구간에서는 모델이 자신감을 과하게 보였습니다.

이 실험에서 눈여겨볼 점은 93.4%라는 전체 정확도보다 기준선이 틀린 답을 한쪽으로 몰아 주었다는 것입니다. 자동으로 넘긴 구간에는 오답이 없었고 사람이 볼 구간에 오답이 모였으니, 사람의 시간은 1,000건 가운데 101건에만 쓰였습니다. 반대로 기준선을 너무 낮추면 오답이 자동 구간으로 새어 나오고, 너무 높이면 사람이 볼 양이 늘어 자동화의 이점이 줄어듭니다. 두 비용을 저울질해 정하는 값이라서 업무마다 다릅니다.

이 수치는 합성 데이터에서 나온 것이라 다른 데이터에서 같을지는 모릅니다. 공개 버그 리포트 티켓에서도 상당수가 검토로 분류되어, 이런 판단 모델은 사람 개입 없이 전부 맡기기보다 값싸고 빠른 1차 분류로 쓰는 편이 맞습니다. 내 업무에 쓰기 전에 사람이 이미 확인한 이미지 수십 건으로 기준선을 정합니다.

막힐 때 확인할 곳

  • 이미지 요청이 400 오류로 거절됨: 헤더 TypeSafe-Danger-Zone-Images: true가 빠졌거나, 올린 이미지를 질문에서 가리키지 않았거나, 형식이 PNG와 JPEG가 아닌 경우입니다.
  • 413 오류: 파일 16MiB, 가로세로 280~1568픽셀, 요청 본문 32MiB 중 하나를 넘었습니다. 줄이거나 잘라서 다시 보냅니다.
  • 없는 물건인데 Box 좌표가 나옴: Box는 항상 상자를 돌려줍니다. 같은 요청에 대상이 있는지 묻는 Noul을 넣고 낮으면 상자를 버립니다.
  • Box 질문이 안 됨: 모델이 jev-1.14.0인지 확인합니다. jev-latest 같은 별칭은 새 버전이 나오면 가리키는 대상이 바뀌어 답이 달라질 수 있으니 버전을 고정해 쓰는 편이 안전합니다.
  • 여러 질문에 같은 이미지를 넣어 요청이 커짐: 상태에 한 번만 넣고 질문에서 이름으로 가리킵니다.
  • 동영상을 넣고 싶음: 정지 프레임을 PNG나 JPEG로 뽑아 이미지로 보냅니다.

시작 전 체크리스트

  • 이미지가 PNG 또는 JPEG이고 파일 16MiB 이하, 가로세로 280~1568픽셀, 요청 전체 32MiB 이하다.
  • 요청에 TypeSafe-Danger-Zone-Images: true 헤더를 넣었다.
  • 넣은 이미지를 모두 질문에서 이름으로 가리켰다.
  • Noul(대상이 있나)을 먼저, Box(어디에 있나)는 그다음으로 구성했다. Noul이 낮으면 Box 결과는 쓰지 않는다.
  • 자동 처리 기준선을 정했고 미만은 사람 검토로 보낸다.
  • 위치가 필요하면 jev-1.14.0으로 모델을 고정했다.
  • 기준선은 사람이 이미 확인한 이미지 수십 건으로 시험했다.

자주 묻는 질문

Jev에 이미지를 넣으려면 무엇이 필요한가요?

요청에 TypeSafe-Danger-Zone-Images: true 헤더를 넣고, 이미지를 PNG나 JPEG로 맞춥니다. 파일은 16MiB 이하, 가로세로 280~1568픽셀이어야 하고 요청 전체는 32MiB를 넘지 않아야 합니다. 이미지 입력은 1.13과 1.14에서 되고 Box는 1.14가 필요합니다.

이미지에 찾는 물건이 없으면 Box가 어떻게 답하나요?

Box는 없다고 답하지 않고 항상 상자를 돌려줍니다. 그래서 대상이 있는지 묻는 Noul 질문을 같은 요청에 넣고, 그 값이 낮으면 Box 결과를 쓰지 않습니다.

이미지 분류를 믿고 완전히 자동화해도 되나요?

권하지 않습니다. 이미지 기능은 미리 보기 단계이고 확률이 높아도 틀릴 수 있습니다. 확신도 기준선을 정해 기준 이상만 자동 처리하고 미만은 사람이 보게 하며, 금액이나 환불처럼 결과가 큰 일은 기준을 높입니다.

동영상도 분석할 수 있나요?

직접은 안 됩니다. 영상과 오디오는 받지 않으므로 FFmpeg 같은 도구로 정지 프레임을 뽑아 PNG나 JPEG로 보냅니다. 움직임 감지는 이전 프레임을 함께 보내서 비교하게 하는 방식으로 합니다.

이미지 한 장에 질문을 여러 개 보내도 되나요?

됩니다. 이미지를 상태에 한 번만 넣고 질문 여러 개가 이름으로 가리키면 이미지는 한 번만 전송되고, 질문은 같은 이미지를 기준으로 각각 독립적으로 답합니다. 영수증이면 "영수증인가", "무슨 항목인가", "한도를 넘나"를 한 요청에 담을 수 있고, 질문이 많아도 요청 한도(6만 4천 토큰)만 지키면 됩니다.

이 글의 본문은 아래 원본 유튜브 영상의 내용을 바탕으로 쓸모연구소가 다시 정리해 쓴 것입니다. 세부 내용과 최신 정보는 원본 영상과 공식 안내에서 확인해 주세요.

원본 영상 보러가기 ↗