CPN 한국어 자습서 · 러닝패스 2 / 4 — Building with the Claude API
Claude의 기능
Image support
Claude는 user 메시지에 image 블록을 넣어 이미지를 묘사·비교·세기할 수 있습니다. 한 요청에 최대 100장, 데이터는 base64 또는 URL로 넣고, 이미지도 토큰에 과금됩니다. 무엇보다 중요한 점 — 이미지에도 프롬프트 엔지니어링이 결과를 좌우합니다.
Stephen Grider · Anthropic 기술 스태프
다음으로 살펴볼 Claude의 고급 기능은 비전(vision) 능력입니다. user 메시지를 Claude에 보낼 때 메시지 안에 이미지를 함께 넣을 수 있습니다. 그러면 Claude에게 그 이미지로 상상할 수 있는 거의 모든 작업을 요청할 수 있습니다. 안에 무엇이 들어 있는지 말해 달라고 하거나, 서로 다른 이미지를 비교해 달라고 하거나, 여러 객체의 개수를 세어 달라고 할 수 있습니다. 가능성은 정말 다양합니다.
먼저 이미지 처리의 제한과 요구사항부터 이해해야 합니다. 한 요청 안의 모든 메시지를 통틀어 최대 100장의 이미지를 보낼 수 있습니다. 각 이미지의 크기, 그리고 높이와 너비에도 제한이 있습니다. 마지막으로, Claude에 이미지를 보내면 그만큼의 토큰이 과금된다는 점을 이해해야 합니다. 이미지의 픽셀 단위 높이와 너비를 바탕으로 과금 토큰 수를 대략 계산하는 공식이 있습니다.
이미지를 Claude에 보내려면 user 메시지 안에 또 다른 타입의 블록 — image 블록 — 을 넣습니다. 하나의 user 메시지 안에 여러 image 블록을 붙일 수 있고, 각 image 블록은 이미지 하나를 참조합니다. 이 image 블록 안에는 raw 이미지 데이터를 붙이거나(diagram에서 보여 준 형태), 아니면 온라인 어딘가에 호스팅된 이미지의 URL을 제공할 수 있습니다.
여기서 바로 짚고 넘어가고 싶은 정말 중요한 점이 있습니다. 엔지니어가 Claude로 이미지를 다루기 시작할 때, 매우 단순한 프롬프트를 쓰는 경우가 아주 많습니다. 이 예시에 있는 것처럼요. Claude로 이미지를 다룰 때 좋은 결과를 얻는 가장 중요한 방법은, 프롬프트 기법에 계속 강하게 집중하는 것입니다. 이미지만 Claude에 툭 던지고 아주 단순한 프롬프트를 넣으면, 좋은 결과를 못 얻는 경우가 정말 많습니다.
예를 들어 오른쪽 대화를 보면, 구슬 12개가 있는 이미지를 넣고 아주 단순하게 "이 이미지에 구슬이 몇 개 있나?"라고 물었습니다. 실제로 테스트해 봤더니 13개라는 틀린 개수가 돌아왔습니다. 우리는 코스 앞부분에서 배운 것과 똑같은 프롬프트 기법을 써서 이미지 작업의 정확도를 크게 높일 수 있습니다 — 가이드라인 제공, 분석 단계 제공, 또는 one-shot이나 multi-shot 예시 같은 기법들요.
프롬프트를 손쉽게 개선해 올바른 결과를 얻는 두 가지 방법을 보여 드리겠습니다. 첫째, Claude가 이미지를 분석할 때 거칠 일련의 단계를 제공합니다. 물론 이건 우리가 이미지의 내용을 어느 정도 이미 알고 있을 때만 잘 통합니다. 이 시나리오에서는 먼저 구슬을 하나씩 식별해 차례로 세고, 그다음 초기 개수를 검증하려고 다른 전략으로 한 번 더 세고, 마지막으로 두 개수를 비교해 올바른 답을 정하라고 요청합니다. 이렇게 더 정교한 프롬프트를 주니 12개라는 올바른 개수가 나왔습니다.
또 다른 기법은 one-shot 또는 multi-shot 프롬프팅입니다. user 메시지 안에서 image 파트와 text 파트를 번갈아 둡니다. 위에 이미지 파트, 그 아래 텍스트 파트, 그다음 또 이미지, 또 텍스트 파트 식으로요. 첫 쌍에서 구슬 11개짜리 이미지를 주고 "위 이미지에는 구슬이 11개 있다"라고 분명히 말합니다. 이런 예시를 제공하면 나중에 본 이미지를 다룰 때 Claude의 정확도를 쉽게 높일 수 있습니다.
이번엔 노트북에서 좀 더 복잡한 예시를 다뤄 봅니다. 진행할 시나리오를 미리 이해할 수 있도록 다이어그램으로 보여 드리겠습니다. 미국의 많은 지역에는 산불 문제가 심각해서, 산불이 한 지역을 휩쓸며 집을 통째로 태우곤 합니다. 이런 위험이 흔하다 보니 많은 사람이 집이 탈 경우를 대비해 화재 보험을 듭니다. 다만 보험사는 집이 내일이라도, 내년이라도 탈 수 있다는 걸 잘 압니다.
그래서 보험사는 보험에 들려는 집주인에게 집 주변 나무를 다듬거나 아예 베도록 요구하는 경우가 많습니다. 보험사는 집주인이 나무를 적절히 관리하는지 직접 확인해야 하는데, 그러려면 사람을 보내 1~2년에 한 번씩 각 집을 점검해야 합니다. 이건 비용이 정말 빠르게 불어납니다. 이 과정을 자동화하는 한 방법은, 고해상도의 최신 위성 이미지를 받아 Claude에 넣고 화재 위험 평가를 요청하는 것입니다.
특히 Claude에게 부지의 주 거주지를 찾고(위성 이미지 속 보험 대상 주택), 거주지 위로 뻗은 나뭇가지가 있는지(아주 흔한 화재 위험), 소방 서비스가 거주지에 접근하기 얼마나 어려운지(집까지 갈 명확한 경로가 있는지), 그리고 집 주변 나무가 너무 빽빽하지 않은지(그 자체로 화재 위험) 살펴봐 달라고 요청할 수 있습니다.
노트북 002 images로 가 봅니다. 이미 시작 프롬프트를 만들어 두었습니다. 이 프롬프트는 매우 상세하며, 이미지에서 분석하고 싶은 여러 지점을 Claude에게 단계별로 안내합니다. "이 부지의 위성 이미지로 화재 점수를 매겨라" 정도의 아주 단순한 프롬프트로 둘 수도 있었지만, 그러면 좋은 결과를 못 얻을 거라고 거의 장담할 수 있습니다. 그래서 앞서 배운 프롬프트 기법을 적용해 일련의 분석 단계를 제공했습니다.
1단계, 위성 사진에서 실제 주 거주지를 찾는다. 2단계, 수목 밀집도를 본다. 그다음 소방 서비스가 부지에 접근할 수 있는지, 지붕 위로 뻗은 나무·가지가 얼마나 되는지(아주 흔한 화재 위험)를 본다. 마지막으로 이 모든 특성을 바탕으로 화재 위험 등급을 매기고, 1·2·3·4 중 무엇이 적절한지 판단을 돕는 기준을 제공한다. 그리고 맨 아래에 각 항목을 한 문장으로 요약하고 최종 점수를 쓰게 합니다.
강의에 첨부된 images.zip을 풀어 images 디렉터리를 노트북과 같은 폴더에 두세요. 이 폴더에는 나무가 다양하게 있는 여러 집의 위성 이미지가 들어 있습니다. 코드에서는 먼저 이미지 파일을 열어 그 내용을 base64로 변환합니다. images 디렉터리에서 prop_7.png를 찾는데, 이 이미지를 고른 이유는 나무에 완전히 둘러싸여 있어 화재 위험이 크기 때문입니다. base64.standard_b64encode로 인코딩하고 utf-8로 디코딩합니다.
그다음 빈 messages 리스트를 만들고 user 메시지를 추가합니다. 이 메시지에는 블록 두 개가 들어갑니다 — 먼저 image 블록(보이는 구조 그대로: type이 image, source에 type base64, media_type image/png, data에 base64 인코딩한 image bytes), 그다음 실제 지시가 담긴 text 블록(type text, text에 prompt 변수)입니다. 마지막으로 chat을 호출해 messages를 넘깁니다.
실행하고 응답 맨 아래를 보면 화재 위험 등급이 보입니다. 이 경우엔 high, 점수로는 3이 나왔습니다. Claude가 주 거주지 주변 나무를 꽤 합리적으로 평가해 "문제가 있겠다"고 판단한 셈입니다. 끝으로 한 번 더 강조하면, 이미지로 좋은 결과를 얻는 것은 전적으로 프롬프트 기법에 달려 있습니다. 평문 텍스트에서 프롬프트를 개선하던 방법이 이미지 세계에도 똑같이 적용됩니다. 단순한 프롬프트에 의존하면 기대만큼 잘 작동하지 않을 가능성이 큽니다.
이 장에서 배우는 것What you'll learn
약 8분user 메시지에 image 블록을 넣어 묘사·비교·세기를 요청
제한: 한 요청에 최대 100장, 크기·해상도 제한, 이미지도 토큰 과금
데이터는 source에 base64 또는 URL로
가장 중요: 이미지에도 프롬프트 엔지니어링 — 단순하면 자주 틀린다
구슬 12개에 "몇 개?"만 → 13 오답. 분석 단계 제공 → 12 정답
use case: 위성 이미지 산불 위험 평가 → 등급 3(높음)
type:image). 한 메시지에 여러 개 가능.image/png, image/jpeg 등). source 안에 함께 명시한다.user 메시지 안에 image 블록을 넣으면 Claude가 그 이미지를 묘사·비교·세기할 수 있습니다. 한 메시지에 여러 개를 붙일 수 있고, 데이터는 source에 raw base64 또는 URL로 넣습니다.
한 요청의 모든 메시지를 통틀어 최대 100장. 각 이미지의 크기·높이·너비에 제한이 있고, 이미지도 토큰에 과금됩니다(픽셀 높이·너비로 대략 산정).
이미지를 다룰 때 좋은 결과의 1순위는 여전히 프롬프트 기법입니다. 이미지만 툭 던지고 단순한 질문을 하면 자주 틀립니다 — 구슬 12개에 "몇 개?"만 물으면 13개(오답)가 돌아옵니다.
정확도를 높이는 두 가지 방법입니다. ① 분석 단계 제공 — 하나씩 세고 → 다른 전략으로 재검증 → 두 개수를 비교해 결론. ② one/multi-shot — image 파트와 text 파트를 번갈아 두고 "위 이미지엔 구슬 11개"처럼 예시를 보여 줍니다. 둘 다 평문에서 쓰던 기법을 그대로 이미지에 적용한 것입니다.
실전 use case입니다. 보험사는 집 주변 나무 관리를 확인하려고 매년 사람을 보내야 하는데, 이건 비용이 큽니다. 위성 이미지를 Claude에 넣어 거주지 식별·지붕 위 가지·소방 접근성·수목 밀집을 평가하고 위험 등급(1-4)을 매겨 자동화합니다.
먼저 단순 프롬프트의 유혹을 버리고, 분석 단계를 또박또박 제공합니다.
# 단순 프롬프트 금지 — 분석 단계를 제공해야 좋은 결과가 나온다 prompt = """ 첨부된 위성 이미지를 다음 단계로 분석하세요: 1. 주 거주지 식별 — 위성 사진에서 보험 대상 주택을 찾으세요. 2. 수목 밀집도 — 집 주변 나무가 얼마나 빽빽한지 평가하세요. 3. 소방 접근성 — 소방 서비스가 거주지까지 갈 명확한 경로가 있나요? 4. 지붕 위 가지 비율 — 지붕 위로 뻗은 가지 비율(0-25 / 25-50 / 50-75 / 75-100%)을 추정하세요. 5. 화재 위험 등급(1-4)을 부여하세요. 1 = 매우 낮음 · 2 = 낮음 · 3 = 높음 · 4 = 매우 높음 각 항목을 한 문장으로 요약하고, 맨 끝에 최종 숫자 등급을 쓰세요. """
그다음 prop_7.png(나무에 둘러싸인 집)를 base64로 인코딩해 image 블록으로, 프롬프트를 text 블록으로 넣어 한 user 메시지로 보냅니다.
import base64 # 나무에 둘러싸인 prop_7.png 를 base64 로 인코딩 with open("images/prop_7.png", "rb") as f: image_bytes = base64.standard_b64encode(f.read()).decode("utf-8") messages = [] add_user_message(messages, [ { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": image_bytes, }, }, {"type": "text", "text": prompt}, ]) chat(messages) # → 산불 위험 등급 평가
1. 주 거주지: 부지 중앙의 단독 주택을 식별함.
2. 수목 밀집도: 주택을 둘러싼 나무가 매우 빽빽함.
3. 소방 접근성: 진입로가 수목에 가려 접근이 어려움.
4. 지붕 위 가지: 지붕의 50-75%가 가지로 덮임.
5. 최종 화재 위험 등급: high (3)데이터를 직접 인코딩하는 대신 온라인 이미지의 URL로 참조할 수도 있습니다 — source.type을 url로 바꾸면 됩니다.
# 또는 raw 데이터 대신 온라인 이미지의 URL 참조 add_user_message(messages, [ { "type": "image", "source": { "type": "url", "url": "https://example.com/prop_7.png", }, }, {"type": "text", "text": prompt}, ])
image 블록 — 한 요청 최대 100장, 이미지도 토큰 과금.source는 base64(media_type+data) 또는 URL.Q1한 요청에 보낼 수 있는 이미지는 최대 몇 장인가요?
한 요청 안의 모든 메시지를 통틀어 최대 100장입니다. 크기·해상도 제한도 있고, 이미지도 토큰에 과금됩니다.
Q2구슬 12개 이미지에 "몇 개?"만 단순히 물으면 무엇이 문제인가요?
단순 프롬프트는 자주 오답을 냅니다. 분석 단계 제공이나 one/multi-shot 예시 같은 기법을 적용하면 12개 정답에 도달합니다.
Q3image 블록의 source에 데이터를 넣는 두 가지 방법은?
source.type을 base64로 두고 media_type+data를 주거나, url로 두고 온라인 이미지를 참조합니다.
이미지를 읽었으니 다음은 거의 같은 코드로 PDF를 읽습니다 — 블록 type을 document, media_type을 application/pdf로 바꾸면 끝입니다. → PDF 지원
전 코스는 계속 무료입니다. 등록하면 이 코스의 남은 76개 레슨을 끝까지 읽을 수 있습니다.
이미 등록하셨다면 그때 쓰신 이메일을 넣어 주세요.