Day 8. Vision — "캐릭터가 자기 사진을 보고 첫 마디를 건네는, 멀티모달 입력의 결"

자, 본 Step 으로 들어가기 전에 — 왜 모델 라인업을 한 번 더 다뤄야 하는가 를 먼저 풀어볼게요.

Day 1 부터 우리는 ChatModel 하나로 텍스트 대화를 흘려보냈고, Day 2 에서는 프로바이더 추상화 라는 방식으로 Ollama / Gemini 를 .env 한 줄로 갈아끼우는 감각을 익혔어요.

어떤 모델이든 같은 인터페이스로 부른다 — 이게 그날의 중심이었죠.

그런데 오늘 Vision 으로 들어가자마자 — 그 형태에 한 가지 단서 가 붙어요.

"같은 ChatModel 인터페이스라도 — 모든 모델이 그림을 읽을 수 있는 건 아니다." 이게 오늘 Step 1 의 첫 주제이에요.

어떤 모델은 눈 을 가졌고, 어떤 모델은 눈이 없어요. 같은 인터페이스를 호출했는데 — 한쪽은 그림을 보고 답하고, 한쪽은 그림을 조용히 무시 하고 텍스트만 보고 답해요.

1. 첫 주제 — 모든 ChatModel 이 눈을 가졌는가

먼저 왜 어떤 모델은 눈이 있고 어떤 모델은 없는가 — 이 방식을 짧게 풀고 갈게요. 핵심은 학습 데이터의 차이 예요.

텍스트 LLM 은 — 책 · 논문 · 위키 · 깃허브 코드 · 블로그 같은 텍스트 코퍼스 만 학습해요.

토큰과 토큰 사이의 패턴 만 배운 모델이에요.

그래서 토큰을 예측 하는 능력은 강하지만 — 이미지 픽셀을 어떻게 해석할지 는 학습한 적이 없어요. 마치 글만 읽고 자란 사람한테 갑자기 그림을 들이미는 모습에 가까워요.

글자만 보고 자란 손은 — 그림이 와도 읽을 수 있는 결 이 없죠.

Vision LLM 은 다르게 학습돼요. 텍스트 + 이미지를 쌍으로 학습한 모델이에요. "이 그림은 분홍 토끼" 같은 캡션-이미지 쌍이 수억 개씩 학습 데이터에 들어가 있고, 모델은 이미지를 시각 토큰으로 변환 하는 별도의 인코더(보통 ViT 같은 vision transformer) 를 먼저 거친 다음 텍스트 디코더와 함께 정렬돼요.

학습 단계부터 이미지를 텍스트와 같은 방식으로 처리하는 회로 가 들어있는 모델이에요.

이 차이가 들어오면 — 왜 모델 라인업을 갈아끼워야 하는가 가 자연스럽게 풀려요.

Vision 학습이 들어간 모델 만 그림을 입력으로 받을 수 있어요.

텍스트 전용 모델한테 Media 입자를 끼워 넣어 보내면 — 모델이 그 입자를 그냥 무시 하거나 (image part is ignored), 프로바이더 단계에서 400 에러를 던지거나, 둘 중 하나가 펼쳐져요.

어느 쪽이든 원하는 답이 안 와요.

2026-04 시점, 눈을 가진 모델 라인업을 한 번 정리해볼게요.

⚠ 주의 한 줄 — 텍스트 전용 모델한테 이미지를 보내도 에러가 나지 않을 수도 있어요. 모델이 그냥 image part 를 조용히 무시 하고 텍스트만 보고 답하는. 응답이 엉뚱 하면 "앗, 모델이 그림을 못 봤구나" 부터 의심하세요. 조용한 무시 가 가장 디버깅 어려운 함정이에요.

여기서 기억해둘 결은 — "ChatModel 인터페이스로 주입했다고 끝이 아니다.

모델 라인업의 능력 (capability) 을 함께 의식해야 한다." Day 2 의 프로바이더 추상화는 호출 인터페이스의 통일 이었지, 모델 능력의 통일 이 아니에요.

능력은 모델마다 다르고, Vision 같은 새 모달리티가 등장할 때마다 — 라인업을 다시 한 번 점검 해야 해요.

2. 두 번째 주제 — Gemini 2.5 Flash 무료 티어 — 첫 번째 선택지

자, 본 강의의 첫 번째 선택지 를 결정해볼게요. 결론부터 말씀드리면 — gemini-2.5-flash (또는 코드베이스 디폴트 gemini-2.5-flash-lite) 무료 티어 예요. 여기엔 다섯 가지 결정 근거 가 있어요. 한 부분에 정리할게요.

장점 다섯 가지:

1. 한국어 강함 — 한국어 캡션 / 한국어 응답의 톤이 자연스러워요. ai-friends 캐릭터들이 한국어로 말을 거는 결에 잘 맞아요.
2. 멀티이미지 지원 — 한 메시지에 여러 장의 이미지를 동시에 보낼 수 있어요. 캐릭터 portrait + 사용자 셀카를 함께 보여주는 시나리오가 가능해요.
3. 일일 쿼터 충분 — 무료 티어 RPD (일일 호출 수) 가 학생 실습에 넉넉히 들어있어요. 분당 RPM 도 강의 한 반이 동시에 호출해도 대부분 견뎌요.
4. Day 7 환경 그대로 재사용 — 코드베이스 application.yml 의 ${GEMINI_API_KEY:} + ${GEMINI_MODEL:gemini-2.5-flash-lite} 가 그대로 Vision 도 지원 해요. .env 변경 0 건. Day 7 까지 익힌 환경이 오늘도 그대로 흘러가요.
5. API 키 한 줄로 시작 — Google AI Studio 에서 키 한 번 발급받으면 끝. 결제 카드 등록 불필요 (무료 티어 한정).

단점 네 가지:

1. 클라우드 호출 — 네트워크 의존이에요. 인터넷이 느리면 응답도 느려요.
2. 민감정보 우려 — 사용자가 업로드한 사진 한 장이 외부 (Google) 서버로 전송 돼요. 강의 실습 시나리오엔 큰 문제 없지만, 프라이버시가 핵심인 부분 엔 부적합해요.
3. API 키 노출 위험 — .env 에 평문으로 정리하는 키가 깃허브 commit 으로 새면 무료 쿼터가 빠르게 소진되거나 (드물게) 결제 청구가 오는 사고로 이어져요. Day 2 의 보안 규약 (.env 는 .gitignore, 키는 환경변수로만) 이 오늘도 그대로 살아있어요.
4. 모델 표기의 시점성 — 작년만 해도 gemini-2.0-flash 가 1순위였지만 2026-04 시점엔 사용 불가. 모델 라인업이 빠르게 진화 해서 — 1년 뒤 강의를 듣는 학생은 또 다른 이름 으로 갈아끼울 가능성이 있어요. 시점 면책.

한 가지 짚어둘 패턴 — 코드베이스 application.yml 의 디폴트는 gemini-2.5-flash-lite 예요. Lite 는 더 가볍고 빠르지만 Vision 처리에선 정식 gemini-2.5-flash 가 더 안정적 인 이에요. 응답 품질이 더 또렷하고, 멀티이미지 시나리오도 더 견고해요. 학습 시점에선 둘 다 동작 하지만 — 프로덕션에선 gemini-2.5-flash 정식 라인을 권장 합니다. .env 의 GEMINI_MODEL 한 줄로 갈아끼울 수 있어요.

코드베이스의 그 부분은 이렇게 들어있어요.

spring:
  ai:
    openai:
      api-key: ${GEMINI_API_KEY:}
      base-url: https://generativelanguage.googleapis.com/v1beta/openai
      chat:
        completions-path: /chat/completions
        options:
          model: ${GEMINI_MODEL:gemini-2.5-flash-lite}

이 ${GEMINI_MODEL:gemini-2.5-flash-lite} 한 줄이 — 오늘 Vision 으로 갈아끼우는 부분 예요.

.env 에 GEMINI_MODEL=gemini-2.5-flash 한 줄을 정리하면 — 모델 라인업이 정식 Flash 로 올라가요. 코드 변경 0 건. Day 2 의 프로바이더 추상화가 오늘도 그대로 회수 돼요.

3. 세 번째 주제 — Ollama 로컬 시연 — 두 번째 선택지 (완전 무료, 프라이버시)

자, 두 번째 선택지를 펼쳐볼게요.

Ollama 로 로컬에서 Vision 모델을 돌리는 모드 예요.

이 부분은 완전 무료 + 프라이버시 두 가지를 동시에 잡에요.

사용자 사진을 외부에 한 번도 보내지 않는 시나리오 — 예를 들어 의료 기록 사진 이나 주민등록증 검증 같은 부분를 가정해보면 — Gemini 같은 클라우드 모델은 처음부터 후보에서 제외 돼요.

거기에 Ollama 가 들어와요.

장점 네 가지:

1. 완전 로컬 (프라이버시) — 그림이 노트북 밖으로 한 발짝도 안 나가요. 외부 호출 0 건.
2. API 키 불필요 — 키 발급 / 결제 카드 등록 / .env 비밀 관리 전부 면제.
3. 완전 무료 — 모델 다운로드 한 번 하면 — 그 뒤로 호출 비용 0 원. 전기료 + GPU 자원만 소비.
4. 오프라인 가능 — 인터넷이 끊겨도 동작해요. 비행기 안에서도 ai-friends 가 그림을 봅니다.

단점 네 가지:

로컬 GPU/메모리 자원 필요 — llava 1.6 (7B) 은 최소 4~8GB VRAM, qwen2.5-vl (7B) 도 비슷해요.

Mac M-시리즈는 Metal 가속이 있어야 그나마 견딜 만하고, 윈도우 노트북은 NVIDIA GPU + CUDA 가 없으면 CPU 추론 으로 가는데 — 응답 한 번에 수십 초 걸려요. 2.

응답 품질이 Gemini 보다 떨어짐 — Vision 학습 데이터의 양 / 모델 크기 차이로, 그림을 묘사하는 디테일 에서 Gemini 가 압도적으로 더 또렷해요.

"분홍 토끼가 분홍 옷을 입고 있어요" 까지는 둘 다 가능하지만, "왼쪽 귀 끝에 작은 리본이 달려 있고 살짝 기울어져 있어요" 같은 디테일은 Gemini 만 잡아요. 3. 첫 호출 시 모델 다운로드 시간 — llava 7B 가 약 4.7GB, qwen2.5-vl 7B 가 약 4.5GB. 첫 ollama pull 에 인터넷 속도에 따라 5~30 분 걸려요. 4. 멀티이미지 제약 — llava 1.6 은 이미지 1 장만 권장돼요 (여러 장 보내면 첫 장만 처리되거나 응답이 흐려져요). qwen2.5-vl 은 멀티이미지 가능. 이미지 여러 장을 동시에 다루는 시나리오라면 모델 선택이 qwen2.5-vl 로 좁혀져요.

ai-friends 코드베이스에는 이미 Ollama 프로파일 이 들어있어요 (application.yml 의 ollama 프로파일). .env 에 SPRING_PROFILES_ACTIVE=docker,ollama + OLLAMA_MODEL=llava (또는 qwen2.5-vl) 한 줄을 정리하면.

프로바이더 스위칭이 일어나요. 자바 코드 변경 0 건. Day 2 의 프로바이더 추상화가 Vision 도메인에서 다시 등장 돼요.

Ollama 가 호스트에 깔리는 이유 — Day 2 에서 정리해뒀던 호스트 Ollama 흐름인데, Ollama 데몬은 Mac Metal / NVIDIA GPU 가속 을 살리려면 호스트에 직접 설치 하는 게 정석이에요. 컨테이너 안의 ai-friends 앱은 host.docker.internal:11434 로 호스트의 Ollama 데몬에게 호출을 보내요. docker-compose.yml 의 extra_hosts: ["host.docker.internal:host-gateway"] 한 줄이 그 다리를 놓아요.

5. 결정 트리 — 어떤 부분에서 어떤 모델을 고를 것인가

세 가지 축으로 주제를 잡아볼게요. 학생이 익히고 다닐 수 있는 결정 트리예요.

이 결정 트리에서 핵심은 축이 하나가 아니라 여러 개 라는 거예요. "무료라서 Ollama" 같은 단순한 결정은 그날의 판단 을 흐리게 만들어요. 축을 먼저 정하고 모델을 고르는 순서가 — 실무에서 모델 선택을 박을 때의 표준 호흡이에요.

6. 트레이드오프 매트릭스 — Gemini 2.5 Flash · Ollama llava · Ollama qwen2.5-vl 한 화면에 박기

마지막으로 — 세 옵션을 여섯 가지 축 으로 나란히 펼쳐볼게요. 이 매트릭스가 오늘 들어와야 할 흐름의 합본 부분이에요.

🟢 = 우수 / 🟡 = 보통 / 🔴 = 약점

이 매트릭스를 익히면 — 디폴트는 Gemini 2.5 Flash, 프라이버시 부분은 qwen2.5-vl 이라는 주제가 자연스럽게 떠올라요.

llava 는 매우 가벼운 단일 이미지 시연용 의.

세 모델이 서로 다른 부분 를 채우고, 본 강의는 그 부분들을 같은 ChatModel 인터페이스 위에서 자유롭게 갈아끼우는을 펼쳐요.

7. 💡 튜터의 결론 — Step 1 한 줄

"ChatModel 인터페이스는 통일됐지만 — 모델 능력 (Vision capability) 은 통일되지 않는다. 본 강의는 학생 진입장벽 + 응답 품질 + 멀티이미지 세 축에서 우세한 Gemini 2.5 Flash 무료 티어를 디폴트로 두고, 프라이버시가 핵심인 부분 에서만 .env 한 줄로 Ollama 로 갈아끼운다. Day 2 의 프로바이더 추상화가 — Vision 도메인에서 다시 등장 한다."

자, 어느 모델로 갈지 가 익히셨으니 — 이제 어떤 입자로 그림을 메시지에 끼워 넣을 것인가 가 다음 주제이에요.

Spring AI 가 우리한테 던져주는 첫 단어 — Media.

그 다음이 — Media 들을 담는 컨테이너 인터페이스 MediaContent.

Step 2 에서 멀티모달 메시지의 입자 부터 시그니처로 펼쳐봅시다.

자, Step 1 에서 어느 모델이 눈을 가졌는가 라는 주제가 익히어졌어요. 이제 그 눈에 그림을 어떻게 떠먹여 줄 것인가 — 이게 오늘의 두 번째 학습 포인트이에요. 손에 든 portrait URL 한 장을.

어떤 모양의 입자로 ChatModel.call(...) 의 인자에 끼워 넣어야 모델이 그림으로 인식 하는가. 이 질문 앞에서 Spring AI 가 우리한테 던져주는 입자 세 개가 있어요. Media · MediaContent · MimeType.

이 세 입자가 들어와야 — 다음 Step (Step 3) 에서 UserMessage.builder() 안에 텍스트 + Media 를 함께 조립하는으로 매끄럽게 들어갈 수 있어요. 오늘 Step 은 조립 전에 입자부터 익히는 부분이에요.

1. 첫 주제 — 왜 텍스트 한 줄로는 안 되는가

먼저 — 왜 입자라는 단어를 굳이 끌고 들어오는가 부터 풀어볼게요. Day 1 부터 Day 7 까지 우리가 ChatModel.call(...) 에 넣어온 메시지는 전부 텍스트 한 줄짜리 였어요. new UserMessage("hello") 또는 new Prompt("이 캐릭터의 이름을 지어줘")

한 String 안에 말하고 싶은 모든 것 이 들어가는이었죠. 지난 시간 Day 7 의 ImagePrompt(prompt) 도 입력은 텍스트 한 줄 이었어요. 출력만 이미지였을 뿐.

그런데 오늘 입력은 — 텍스트 + 이미지 두 가지가 함께 들어가야 해요.

"이 사진 어떤가요?" 라는 텍스트 옆에 그림 한 장 이 동시에 들어가야 하는.

이걸 한 String 으로 표현하려고 하면 — Base64 로 정리해 넣은 거대한 문자열 + 텍스트 같은 흐릿한 방식으로 얽혀버려요.

모델 입장에서도 어디까지가 텍스트고 어디부터가 이미지인지 분간하기 어려워져요.

그래서 Spring AI 는 — Message 를 입자 단위로 쪼갠 추상화 를 갖고 있어요.

UserMessage = 텍스트 (text) 한 칸 + Media[] (이미지/파일 입자들) 한 칸이 같은에 모인 컨테이너. 한 줄짜리 메시지가 아니라 입자들의 모임 으로 바라보에요.

이 방식이 들어오면 — 왜 이미지를 String 에 박지 않고 Media 라는 별도의 입자로 분리 하는지 자연스러워져요.

한 줄로 정리아둘 결: 메시지를 문장 한 줄로 보지 말고 — 입자들의 모임으로 보자. 텍스트도 한 입자, 이미지도 한 입자, 같은에 나란히 모이이에요.

2. 두 번째 주제 — Media 입자의 정체

자, 첫 입자 — Media 부터 손에 정리해볼게요. Spring AI 1.1.x 의 정식 패키지 위치는 이렇게 들어있어요.

import org.springframework.ai.content.Media;

이 부분은 예전엔 org.springframework.ai.model.Media 였다가 1.1.x 에서 org.springframework.ai.content.Media 로 옮겨진 케이스예요. 옛날 블로그를 따라하다 import 가 안 잡히는 상황에 빠지면 — content 패키지를 의심하세요.

Media 의 핵심 필드는 두 가지 예요.

• mimeType — 그림이 어떤 종류 인지 정리하는 라벨. image/png, image/jpeg, image/webp, image/gif 같은 표준 MIME 문자열을 org.springframework.util.MimeType 객체로 감싸 둔.
• data — 그림이 어디서 오는가 를 정리하는. 세 가지 통로 중 하나가 들어가요 — URI (외부/내부 URL), byte[] (메모리에 통째로 들고 있는 바이트), Resource (Spring 의 표준 리소스 추상화).

빌더 한 줄로 만들 수 있어요.

Media image = Media.builder()
        .mimeType(MimeTypeUtils.IMAGE_JPEG)
        .data(URI.create("https://example.com/portrait.jpg"))
        .build();

이게 — 그림 한 장을 메시지에 끼워 넣기 위해 정리해두는 가장 표준적인 모양 부분이에요. 두 줄 — 무엇인지 (mimeType) + 어디서 오는지 (data) 만 정리하면 끝.

세 가지 데이터 통로 — URI · byte[] · Resource

data(...)에 들어갈 수 있는 세 가지 통로 를 짧은 코드로 펼쳐볼게요. 어느 통로를 쓸지 가 그림이 어디에 있는가 에 따라 결정돼요.

(1) URI 로 보내기 — 가장 가벼움. 모델이 직접 다운로드.

Media fromUrl = Media.builder()
        .mimeType(MimeTypeUtils.IMAGE_JPEG)
        .data(URI.create("https://image.pollinations.ai/prompt/cute-pink-rabbit"))
        .build();

(2) byte[] 로 보내기 — 메모리에 이미 들고 있을 때.

byte[] bytes = Files.readAllBytes(Path.of("portrait.png"));
Media fromBytes = Media.builder()
        .mimeType(MimeTypeUtils.IMAGE_PNG)
        .data(bytes)
        .build();

(3) Resource 로 보내기 — Spring 표준 리소스 (classpath, 파일, MultipartFile 변환 등).

Resource resource = new ClassPathResource("static/portraits/sample.jpg");
Media fromResource = Media.builder()
        .mimeType(MimeTypeUtils.IMAGE_JPEG)
        .data(resource)
        .build();

세 통로가 같은 Media.builder() 위에서 똑같은 모양 으로 만들어진다는 진행을 손에 정리해두세요. 어디서 오는가 만 다를 뿐, 만든 뒤의은 동일해요.

어느 통로를 언제 쓰는가 — 한 표

본 강의는 — Step 4 에선 URI 통로 (지난 시간 만든 portrait URL 을 그대로 흘려보내는 결), Step 5 에선 byte[] 통로 (사용자가 업로드한 셀카를 메모리에서 즉시 처리하는 결) 두 가지를 손에 정리해둘 거예요. Resource 통로는 알고만 두시면 돼요.

3. 세 번째 주제 — MediaContent — Media 들을 담는 컨테이너 인터페이스

자, 입자 하나를 만들었으면 — 그 입자들을 어디에 담을 것인가 가 다음 주제이에요. 여기서 등장하는 단어가 — MediaContent 예요.

import org.springframework.ai.content.MediaContent;

이 인터페이스를 한 줄로 정리하면 — "Media 입자들을 담을 수 있는 메시지의 자격증 같은 거" 예요.

이 메시지는 Media 를 담을 수 있어요 라는 표시가 인터페이스로 들어간 곳.

Day 1 부터 익혀온 UserMessage 가 — 사실은 이 MediaContent 인터페이스를 구현 하고 있어요.

그래서 텍스트 옆에 Media 를 함께 박을 수 있는 거예요.

4. 네 번째 주제 — MimeType 의 역할 — 그림의 해독 키

자, 마지막 입자 — MimeType 이에요. Media 빌더에 .mimeType(...) 한 줄로 들어가는 그 라벨. 왜 굳이 이 라벨을 정리해야 하는가 — 여기에 결정적인이 있어요.

같은 byte[] 를 모델한테 던져도 — PNG 인지 JPEG 인지에 따라 디코딩 알고리즘이 완전히 달라요. PNG 는 무손실 압축 + 알파 채널 을 가진 포맷이고, JPEG 는 손실 압축 + 알파 없음 의 포맷이에요.

WebP 는 둘 사이의 현대형 절충안. 모델이 시각 토큰을 추출하려면 먼저 그림을 픽셀로 풀어야 하는데 — 어느 디코더로 풀지 를 결정하는 게 바로 MIME 타입이에요.

import org.springframework.util.MimeType;
import org.springframework.util.MimeTypeUtils;

MimeType png  = MimeTypeUtils.IMAGE_PNG;     // image/png
MimeType jpeg = MimeTypeUtils.IMAGE_JPEG;    // image/jpeg
MimeType gif  = MimeTypeUtils.IMAGE_GIF;     // image/gif
MimeType webp = MimeType.valueOf("image/webp"); // 상수 미제공 — 직접 valueOf

Spring 표준 라이브러리 (org.springframework.util.MimeType) 의 영역이에요 — Spring AI 만의 새 추상화가 아니에요. Day 1 부터 Spring 생태계가 갖고 있던을 그대로 가져와 쓰이에요.

PNG · JPEG · GIF 는 MimeTypeUtils 의 정적 상수로 들어가 있고, WebP 는 상수가 없어서 valueOf("image/webp") 한 줄로 만들어요.

URL 확장자 추론의 한계

Media 를 만들 때 — data(URI.create("https://.../portrait.jpg")) 같은 URL 을 정리하면 — 우리가 따로 mimeType 을 명시 해야 해요.

Spring AI 가 URL 의 확장자를 보고 자동으로 추론해주지 않아요. (HTTP HEAD 요청을 날려서 Content-Type 헤더를 보는 정교한 추론도 이론적으론 가능하지만, 호출 한 번 더 들어가는 비용이 있어서 라이브러리 차원에선 자동으로 안 해줘요.)

그래서 학생이 직접 — URL 끝부분을 보고 분기하는 작은 헬퍼 를 한 부분 정리해두는 진행이 자연스러워요. 지난 시간 손에 정리한 VisionChatService.detectMimeType(...) 가 — 그 부분예요. Step 4 에서 본격적으로 다룰 메서드인데, 여기선 미리보기로 한 번 펼쳐볼게요.

private MimeType detectMimeType(String imageUrl) {
    String lower = imageUrl.toLowerCase();
    if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) {
        return MimeTypeUtils.IMAGE_JPEG;
    }
    if (lower.endsWith(".gif")) {
        return MimeTypeUtils.IMAGE_GIF;
    }
    if (lower.endsWith(".webp")) {
        return MimeType.valueOf("image/webp");
    }
    return MimeTypeUtils.IMAGE_PNG;
}

이 메서드의 결정 근거 를 한 단락 정리할게요.

• 네 종류만 분기 — 본 강의는 PNG · JPEG · GIF · WebP 네 종류만 다뤄요. 이게 ai-friends 시나리오에서 95% 이상 을 커버해요.
• PNG 폴백 — 확장자가 없거나 알 수 없는 경우 PNG 로 폴백. Pollinations.ai 가 던지는 portrait URL 이 대부분 PNG 라서, 지난 시간 만든 portrait URL 이 폴백으로 들어와도 대부분 통과 해요.
• HTTP HEAD 같은 정교한 추론은 안 함 — 과잉. 한 부분 호출 한 번 더 들어가는 비용 + 비동기 처리 복잡성 + 실패 케이스 분기 — 학생 진입 단계에서 들이밀 무게가 아니에요. URL 끝부분 4 종 분기 가 학생이 익히고 다닐 수 있는 단순도 의 영역이에요.
• 정교한 추론이 필요한 부분 — 사용자가 임의의 URL 을 입력 하는 시나리오 (예: 외부 SNS URL · 단축 URL) 에선 확장자만으론 부족해요. 그 부분은 프로덕션 시나리오 — Apache Tika 같은 라이브러리로 바이트 매직 넘버를 보고 추론 하는 진행이 정석이에요. 본 강의는 그 부분를 알고만 두고 — 실습은 단순 분기로 멈춰요.

이 단순도가 — Step 4 에서 코드 한 화면에 다 들어오는 가독성 을 만들어줘요. 과잉을 잘라낸 부분 가 — 학생 익숙해질 수 있는 부분 라는 진행을 한 번 더 정리해둡니다.

5. 세 입자가 같은에 모이는

자, 세 입자를 손에 정리했으니 — 어떻게 한 부분에 모이는가 를 한 번에 펼쳐볼게요. 지난 시간 VisionChatService.describe(...) 의 첫 두 줄이 — 정확히 그 부분예요.

Media image = Media.builder()
        .mimeType(detectMimeType(imageUrl))   // ← MimeType 입자
        .data(URI.create(imageUrl))            // ← data 통로 (URI)
        .build();                              // ← Media 입자 완성

세 입자가 같은 한 줄에 모이는 형태 부분이에요.

• MimeType — detectMimeType(imageUrl) 가 돌려주는 해독 키.
• data 통로 — URI.create(imageUrl) — 어디서 오는가.
• Media — 위 두 입자를 한 입자로 묶은 결과.

그리고 이 Media 입자가 — 다음 Step (Step 3) 의 UserMessage.builder() 안에서 텍스트 옆에 끼워 넣어지는으로 흘러가요.

입자가 컨테이너 (MediaContent 를 구현한 UserMessage) 안으로 들어가는.

오늘 손에 정리한 입자들이 — 다음 시간이 아니라 바로 다음 Step 에서 조립되는 부분이에요.

6. 💡 튜터의 결론 — Step 2 한 줄

"Media = 한 장의 입자, MediaContent = 그 입자들을 담을 자격을 가진 컨테이너 인터페이스 (UserMessage 만 구현), MimeType = 그림이 어떻게 디코딩되어야 하는지를 정리해두는 라벨. 이 셋이 들어와야 — 다음 Step 에서 UserMessage.builder() 안에 텍스트 + Media 를 함께 조립 하는으로 매끈하게 들어갈 수 있다."

자, 입자 세 개가 익히셨으니 — 이제 그 입자들을 어떻게 한 메시지에 조립할 것인가 가 다음 주제이에요. 평범한 생성자 new UserMessage("hello") 를 빌더로 한 단계 끌어올린 패턴 — UserMessage.builder(). Step 3 에서 멀티모달 메시지의 표준 모양 을 손에 정리해봅시다.

자, Step 2 에서 세 입자 가 익히어졌어요 — Media · MediaContent · MimeType.

이제 그 입자들을 어떻게 한 메시지에 조립할 것인가 가 오늘의 세 번째 주제이에요.

Spring AI 1.1.x 가 우리한테 던져주는 답은 한 줄로 정리을 수 있어요 — UserMessage.builder().

두 줄짜리 빌더 호출이 멀티모달 메시지의 표준 모양 이라는 점, 손에 정리해봅시다.

이번 Step 은 짧아요. 빌더 패턴 자체는 직관적 이라 — 세 가지만 박고 가뿐히 Step 4 로 넘어갈 거예요. Step 4 에선 이 빌더 호출이 그대로 VisionChatService.describe(...) 안에서 호출되는 방식을 만나게 됩니다.

1. 첫 주제 — 왜 빌더 패턴인가

먼저 — 왜 굳이 빌더가 등장하는가 부터 풀고 가요. Day 1 부터 Day 7 까지 우리가 익혀온 UserMessage 의 모양은 — 생성자 한 줄짜리 였어요.

UserMessage simple = new UserMessage("안녕!");

문자열 한 줄을 받아서 그대로 텍스트 메시지가 되는 방식. 손에 깔끔하게 들어가 있던 형태예요. 그런데 오늘 — 이미지 한 장을 더하고 싶다 는 욕구가 들어와요. 생성자에 이미지를 더하면 어떻게 될까요? 다음 같은 방식이 떠올라요.

• new UserMessage(text, media) — 이미지 1 장 추가용 오버로드
• new UserMessage(text, media1, media2) — 이미지 2 장 추가용 오버로드
• new UserMessage(text, List<Media>) — varargs 회피용 List 오버로드

생성자 오버로딩이 기하급수 적으로 쌓여요. 게다가 언젠가 음성 입자 까지 들어가는 부분이 오면 (Day 9 복선 ) — 같은 폭발이 한 번 더 일어나요. 생성자만으로는 멀티모달의 가변 모양을 깔끔하게 받아낼 수 없는 부분이에요.

Spring AI 1.1.x 의 답은 — 빌더 패턴. 생성자 오버로딩 대신 체인 호출 로 필요한 입자만 골라서 정리하에요.

UserMessage withImage = UserMessage.builder()
        .text("이 사진 어때?")
        .media(image)
        .build();

텍스트는 .text(...), 이미지는 .media(...) — 빌더가 각 입자를 별도의 메서드 로 받아주는 모양이에요. .media(...) 는 varargs 라서 한 장이든 여러 장이든 같은 메서드 한 부분에서 받아내요. 가변 모양이 한 부분에 깔끔하게 풀리는 부분이에요.

비유로 정리해두면 — 한 줄 카운터에서 종이접시 한 장만 받던 모습 이 — 트레이 위에 텍스트와 그림을 함께 올리는 형태 으로 진화이에요. 생성자는 카운터, 빌더는 트레이. 트레이는 얹을 수 있는 부분가 여러 칸 이고, 원하는 칸에만 골라서 얹을 수 있어요.

2. 두 번째 주제 — 빌더 호출의 감각, 4 가지 모양

자, 빌더가 들어오는 거기서 — 어떤 모양으로 부를 수 있는가 를 한 화면에 정리할게요. 네 가지 패턴을 언제 쓰는지 와 함께 짚을게요.

// 1) 텍스트만 (Day 1 부터 손에 익은 그 모양)
UserMessage textOnly = UserMessage.builder().text("안녕!").build();

// 2) 텍스트 + 이미지 1 장 (오늘의 메인)
UserMessage withImage = UserMessage.builder()
        .text("이 사진 어때?")
        .media(image)
        .build();

// 3) 텍스트 + 이미지 여러 장 (varargs)
UserMessage withMultipleImages = UserMessage.builder()
        .text("두 사진 비교해줘")
        .media(image1, image2)
        .build();

// 4) 빌더 없이 평이 생성자 — 텍스트 전용 메시지 (Day 1~7 의 그 손맛)
UserMessage simple = new UserMessage("안녕!");

각 패턴의 언제 쓰는가 를 한 줄씩 정리할게요.

• (1) 텍스트만 — 빌더 형식 : 멀티모달 코드와 톤을 맞추고 싶을 때 쓰는 방식. 같은 서비스 안에서 어떤 호출은 텍스트만, 어떤 호출은 이미지 포함 인 경우라면 — 둘 다 UserMessage.builder() 로 통일하면 코드가 한결 매끈 해져요.
• (2) 텍스트 + 이미지 1 장 : 오늘의 메인. Step 4 의 VisionChatService.describe(...) 가 정확히 이 모양이에요. 캐릭터 portrait 한 장 + "이 그림 어때?" 한 줄.
• (3) 텍스트 + 이미지 여러 장 : 비교 시나리오. Step 6 의 캐릭터 portrait 두 장을 동시에 보여주고 비교 하는 장면에서 등장해요. .media(...) 가 varargs 라 콤마로 죽 늘어놓기만 하면 돼요.
• (4) 평이 생성자 : Day 1 부터 들어간 그 방식. 텍스트만 받는 부분이 명백히 텍스트 전용 이라면 (예: 시스템 메시지가 없는 단순 텍스트 챗) — 굳이 빌더로 끌어올릴 필요 없어요. 짧은 코드는 짧은 방식으로 두는 게 가독성이에요.

(1) 과 (4) 가 같은 결과인데 — 왜 빌더가 더 명시적인가

(1) 과 (4) 는 같은 결과 를 내요 — 텍스트만 담긴 UserMessage 한 개.

그런데 빌더 쪽이 더 명시적 이라는 진행이 있어요.

왜냐하면 — 빌더 호출문을 읽는 그 순간 .text(...) 가 명시적으로 들어있어서, "아, 이건 텍스트 부분구나" 가 한눈에 보여요.

생성자 new UserMessage("안녕!") 는.

문자열이 텍스트인지, 다른 무엇인지 코드를 읽는 사람이 생성자 시그니처를 한 번 더 확인 해야 알 수 있어요. 한 부분 두 부분 호흡 차이 지만, 코드 읽는 사람의 인지 부담 이 다른 이에요.

한 줄 결정 가이드 — 멀티모달이 섞이는 서비스라면 빌더 통일, 순수 텍스트 전용 부분라면 생성자 그대로. ai-friends 는 Day 8 부터 멀티모달이 섞이는 결 이라 — 본 강의 Step 4 이후의 모든 새 코드는 빌더로 통일해요.

3. 세 번째 주제 — 완성된 메시지로 가는 길, Prompt 와 ChatModel.call(...)

자, UserMessage 한 줄을 만들었다고 — 그게 곧 모델 호출 은 아니에요. Day 1 부터 들어간 결대로 — ChatModel 은 Prompt 객체를 받아요.

import org.springframework.ai.chat.prompt.Prompt;

ChatResponse response = chatModel.call(new Prompt(userMessage));

new Prompt(userMessage) — 단일 메시지 생성자. 이 방식이 들어있어야 — 시스템 메시지 / 대화 이력 / 옵션 이 더해지는 부분에서도 같은 호흡으로 확장할 수 있어요.

시스템 메시지 + 사용자 메시지 + 대화 이력이 함께 들어가는 결은 — Day 5 ChatMemory 에서 이미 손에 정리했죠.

오늘은 단발 호출 이라 — 가장 단순한 한 자리만 펼쳐요.

그리고 — 이 모든이 한 부분에 모이는 오늘의 핵심 흐름 을 코드로 정리할게요. VisionChatService.describe(...) 의 심장 부위예요.

Media image = Media.builder()
        .mimeType(detectMimeType(imageUrl))
        .data(URI.create(imageUrl))
        .build();

UserMessage userMessage = UserMessage.builder()
        .text(prompt)
        .media(image)
        .build();

ChatResponse response = chatModel.call(new Prompt(userMessage));

이 8 줄 — 오늘 Day 8 의 가장 핵심 감각 부분이에요.

• 첫 4 줄 — Step 2 에서 손에 정리한 Media 입자 만들기 (MimeType 라벨 + URI 통로).
• 다음 3 줄 — 오늘 Step 3 에서 손에 정리한 UserMessage.builder() 로 텍스트 + Media 조립.
• 마지막 1 줄 — Day 1 부터 들어간 chatModel.call(new Prompt(...)) 의 그 모양 그대로.

결정적인 한 결 — 마지막 줄이 지난 시간과 똑같다 부분이에요. chatModel.call(new Prompt(...)) — 텍스트 전용 호출이든, 멀티모달 호출이든 — 같은 인터페이스, 같은 호출 모양. 이게 Day 2 의 프로바이더 추상화가 Vision 도메인에서 회수 되는 부분이에요.

import 문도 짧게 한 번 짚고 갈게요.

• org.springframework.ai.chat.messages.UserMessage — UserMessage 와 .builder()
• org.springframework.ai.content.Media — Step 2 에서 짚은 그 부분 (1.1.x 에서 model → content 패키지로 이동)
• org.springframework.ai.chat.prompt.Prompt — Day 1 부터 들어간 곳 그대로

5. 💡 튜터의 결론 — Step 3 한 줄

"UserMessage.builder().text(...).media(...).build() — 두 줄짜리 빌더 호출이 멀티모달 메시지의 표준 모양이다. 그 메시지를 new Prompt(userMessage) 로 감싸 chatModel.call(...) 에 넘기면, 지난 시간과 똑같은 인터페이스 가 오늘은 그림을 보고 답한다."

자, 빌더를 익히셨으니 — 이제 이 8 줄을 실제 서비스 클래스로 정리해내는 자리가 다음 주제예요. VisionChatService — 오늘의 도메인 진입점. Step 4 에서 클래스 한 화면 을 펼쳐봅시다.

자, Step 1~3 의 결정이 세 가지의 이론 이었다면 — Step 4 는 그 셋이 한 클래스 안에 모이는 부분이에요.

어느 모델로 갈지 (Step 1) · 어떤 입자로 그림을 박을지 (Step 2) · 어떤 빌더로 메시지를 조립할지 (Step 3) — 세 가지가 오늘의 도메인 진입점 VisionChatService 한 부분에서 합류해요.

이번 Step 끝에 손에 남는 그림은 단순해요.

describe(imageUrl, prompt) 한 줄을 부르면 지난 시간 만든 portrait URL 이 그대로 입력이 되어 텍스트 응답으로 돌아오는.

이번 Step 의 호흡은 조금 길어요. 본 강의의 핵심 감각이 모이는 부분라 — 클래스 본문을 한 호흡으로 끝까지 박을 거예요.

✅ 동작 보장은 코드베이스 VisionChatServiceTest.java 에 5 케이스로 검증되어 있어요. (1) Prompt 가 ChatModel 에게 텍스트 + Media 1 장으로 전달되는지, (2) 응답 텍스트가 그대로 반환되는지, (3) 빈 응답 → 빈 문자열 폴백, (4) 외부 HTTPS URL 은 URI 문자열 그대로 패스스루, (5) 로컬 업로드 경로(/uploads/...)는 디스크에서 바이트를 읽어 인라인. 본 교안에는 프로덕션 본문 만 인용하고, 단위 테스트는 코드베이스에서 직접 열어보세요.

1. 첫 주제 — VisionChatService 본문 — 8 줄짜리 핵심, 그리고 그 8 줄을 둘러싼 가드

자, 테스트의 윤곽이 익히셨으니 — 이제 그 테스트를 Green 으로 만들어주는 본문 을 펼쳐볼게요. 클래스 한 화면을 그대로 정리할게요. lecture-source-code/ai-friends/src/main/java/kr/spartaclub/aifriends/vision/service/VisionChatService.java 입니다.

package kr.spartaclub.aifriends.vision.service;

import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.ai.chat.messages.UserMessage;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.content.Media;
import org.springframework.core.io.FileSystemResource;
import org.springframework.core.io.Resource;
import org.springframework.stereotype.Service;
import org.springframework.util.MimeType;
import org.springframework.util.MimeTypeUtils;

import java.net.URI;

/**
 * Day 8 Step 4 — Vision (멀티모달 입력) 의 도메인 진입점.
 *
 * <p>이미지 URL 한 장 + 텍스트 프롬프트를 받아 멀티모달 {@link UserMessage} 로 조립한 뒤
 * {@link ChatModel} 에 전달한다. 응답 텍스트를 그대로 돌려준다.</p>
 *
 * <p>{@link ChatModel} 은 인터페이스로만 주입받는다 (본 강의의 프로바이더 추상화 원칙). 빈은
 * Gemini · OpenAI · Ollama 어떤 프로바이더든 될 수 있고, 호출자는 모른다 — Vision 지원 모델은
 * {@code application.yml} 의 {@code spring.ai.model.chat} + 프로파일별 모델명으로만 결정된다
 * (예: {@code GEMINI_MODEL=gemini-2.5-flash}).</p>
 *
 * <h3>입력 URL 두 갈래 처리</h3>
 *
 * <p>이미지 URL 은 출처에 따라 두 가지 길로 갈린다 — 두 갈래를 한 메서드 안에서 분기 처리한다.</p>
 *
 * <ul>
 *   <li><b>외부 HTTPS URL</b> (예: Day 7 에서 받은 Pollinations URL) — URI 그대로 패스스루.
 *       프로바이더가 직접 URL 을 가져가서 fetch 한다.</li>
 *   <li><b>로컬 업로드 경로</b> (예: {@code /uploads/portraits/upload-xxx.jpg}) — 정적 리소스
 *       경로일 뿐 바깥에서 접근 가능한 절대 URL 이 아니므로, 디스크에서 바이트를 직접 읽어 Media 에
 *       인라인한다 (Spring AI 가 base64 로 인코딩해 프로바이더에 전달).
 *       이렇게 안 하면 Gemini OpenAI-compat 같은 일부 엔드포인트가 {@code 400 INVALID_ARGUMENT:
 *       Unsupported file URI type} 으로 거부한다.</li>
 * </ul>
 *
 * <p>학생용 단순도 유지: 응답이 비어 있으면 빈 문자열을 반환 (예외를 던지지 않는다).
 * 실패 케이스를 도메인 예외로 래핑하는 패턴은 Day 7 {@code ImageGenerationService} 에서 이미 다뤘다.</p>
 */
@Slf4j
@Service
public class VisionChatService {

    private static final String LOCAL_UPLOAD_PREFIX = "/uploads/";

    private final ChatModel chatModel;
    private final String uploadBaseDir;

    public VisionChatService(
            ChatModel chatModel,
            @Value("${aifriends.image.storage.upload-base-dir:./uploads}") String uploadBaseDir) {
        this.chatModel = chatModel;
        this.uploadBaseDir = uploadBaseDir;
    }

    /**
     * 이미지 URL + 텍스트 프롬프트를 ChatModel 의 Vision 입력으로 전달하고 응답 텍스트를 반환한다.
     *
     * @param imageUrl 외부 HTTPS URL 또는 로컬 업로드 경로 ({@code /uploads/...})
     * @param prompt   "이 이미지를 한 문장으로 묘사해줘" 같은 사용자 지시문
     * @return ChatModel 응답 텍스트. 응답이 비어 있으면 빈 문자열.
     */
    public String describe(String imageUrl, String prompt) {
        Media image = buildMedia(imageUrl);

        UserMessage userMessage = UserMessage.builder()
                .text(prompt)
                .media(image)
                .build();

        ChatResponse response = chatModel.call(new Prompt(userMessage));
        if (response == null || response.getResult() == null || response.getResult().getOutput() == null) {
            return "";
        }
        String text = response.getResult().getOutput().getText();
        return text == null ? "" : text;
    }

    /**
     * URL 의 모양에 따라 {@link Media} 를 두 갈래로 만든다.
     *
     * <ul>
     *   <li>{@code /uploads/...} 로 시작하면 → 디스크에서 {@link FileSystemResource} 로 읽어 인라인</li>
     *   <li>그 외 (HTTPS · file:// 절대 URL 등) → URI 그대로 패스스루</li>
     * </ul>
     */
    private Media buildMedia(String imageUrl) {
        MimeType mimeType = detectMimeType(imageUrl);
        if (isLocalUpload(imageUrl)) {
            String relativePath = imageUrl.substring(LOCAL_UPLOAD_PREFIX.length());
            Resource resource = new FileSystemResource(uploadBaseDir + "/" + relativePath);
            log.debug("Vision: local upload → inline bytes from {}", resource);
            return Media.builder()
                    .mimeType(mimeType)
                    .data(resource)
                    .build();
        }
        return Media.builder()
                .mimeType(mimeType)
                .data(URI.create(imageUrl))
                .build();
    }

    private boolean isLocalUpload(String imageUrl) {
        return imageUrl != null && imageUrl.startsWith(LOCAL_UPLOAD_PREFIX);
    }

    /**
     * URL 확장자만 보고 단순 추론한다. PNG 가 아닌 경우(jpg · jpeg · webp · gif) 만 별도 매핑.
     * 학생이 따라하기 쉬운 수준에서 멈추고, 모르는 확장자는 image/png 로 폴백.
     */
    private MimeType detectMimeType(String imageUrl) {
        String lower = imageUrl.toLowerCase();
        if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) {
            return MimeTypeUtils.IMAGE_JPEG;
        }
        if (lower.endsWith(".gif")) {
            return MimeTypeUtils.IMAGE_GIF;
        }
        if (lower.endsWith(".webp")) {
            return MimeType.valueOf("image/webp");
        }
        return MimeTypeUtils.IMAGE_PNG;
    }
}

자, 이 클래스를 여섯 부분 로 해부해볼게요. 한 부분씩이 들어가야 — 왜 이렇게 들어갔는가 가 풀려요.

해부 (1) — @Service + 생성자 주입 + 업로드 디렉토리 한 줄 — Day 1~7 의 패턴 + 한 인자 더

@Slf4j
@Service
public class VisionChatService {

    private static final String LOCAL_UPLOAD_PREFIX = "/uploads/";

    private final ChatModel chatModel;
    private final String uploadBaseDir;

    public VisionChatService(
            ChatModel chatModel,
            @Value("${aifriends.image.storage.upload-base-dir:./uploads}") String uploadBaseDir) {
        this.chatModel = chatModel;
        this.uploadBaseDir = uploadBaseDir;
    }

기본 패턴은 — Day 1 부터 들어간 모양 그대로예요.

@Service 빈 등록 + private final 필드 + 생성자 주입.

@Autowired 어노테이션 0 건 (생성자 1 개라 Spring 이 알아서 주입).

@Slf4j 는 Lombok 이 깔아주는 log 필드 — buildMedia(...) 분기에서 디버그 로그를 한 줄 박는 데 사용해요.

한 가지 짚을 부분 — ChatModel 인터페이스로만 주입한다. OpenAiChatModel · GeminiChatModel 같은 구현체 타입 으로 박지 않아요. 이게 본 강의의 프로바이더 추상화 원칙 그대로의 영역이에요.

빈은 어떤 프로바이더든 될 수 있고, VisionChatService 는 그게 무엇인지 모른 상태로 호출만 해요.

Day 7 패턴에 한 줄 더 추가된 부분 — uploadBaseDir 필드. @Value("${aifriends.image.storage.upload-base-dir:./uploads}") 로 프로퍼티에서 주입되는 String 한 줄이에요. 왜 필요한가 는 해부 (3) 에서 풀어요.

사용자가 업로드한 사진이 디스크 어느 경로에 떨어졌는지 알아야 디스크에서 바이트를 읽어올 수 있는 모양이라, 루트 경로 한 줄 이 필요해요.

기본값 ./uploads 는 Day 7 의 StaticResourceConfig 가 /uploads/** → file:./uploads/ 로 매핑하던 그 결과 같습니다.

application.yml 에 키를 따로 박지 않아도 기본값이 살아 있어요.

LOCAL_UPLOAD_PREFIX = "/uploads/" 상수 한 줄도 같이 두에요 — 어떤 URL 이 로컬 업로드인지 를 판별할 때 문자열 한 곳에서만 정의되어야 오타 사고가 안 나요. 해부 (3) 의 분기 조건이 이 상수에 묶여요.

해부 (2) — describe(imageUrl, prompt) — 두 인자의 결정 근거

describe 메서드의 시그니처가 — 왜 두 인자만 받는가 부터 짚을게요.

public String describe(String imageUrl, String prompt) {

입력은 두 가지로 충분한가 — 충분해요. imageUrl 한 장 + 사용자 지시문 한 줄. 지난 시간 Day 7 의 ImageGenerationService.generate(prompt) 가 프롬프트 하나 만 받았던 결과 대칭 부분이에요.

지난 시간은 프롬프트 → 이미지, 오늘은 이미지 + 프롬프트 → 텍스트. 입출력의 화살표가 반대로 도는 부분에서, 입력에 이미지가 한 장 추가 되는 부분이에요.

결정적인 결 — Day 7 에서 만든 portrait URL 이 그대로 imageUrl 인자로 흘러올 수 있다 는 거예요. ImageGenerationService.generate(...) 의 응답에 들어가 있던 그 URL — 지난 시간의 출력이 오늘의 입력으로 매끈하게 흘러요. 지난 시간 마무리에서 약속드린 생성 → 인식의 클로저 가 —

정확히 이 한 줄짜리 String 인자에서 닫혀요.

한 가지 더 — imageUrl 인자는 두 모양 다 받아요. 외부 HTTPS URL (Pollinations · S3 · 임의의 외부 호스팅) 한 가지, 그리고 Step 5 에서 만들 사용자 업로드 경로 (/uploads/portraits/upload-xxx.jpg) 한 가지. 두 모양을 같은 메서드가 받아낸다 는 모양이.

컨트롤러 입장에선 URL 출처를 분기하지 않아도 되는 매끈함이에요. 분기는 메서드 안에서 풀린다 (해부 (3) 의 주제). 호출자는 그냥 String 한 줄 만 넘기면 끝.

반환 타입은 String 한 줄 — Mono<String> 이나 Flux<String> 같은 비동기이 아니에요. 단발 요청-응답이라 동기 하나 로 단순하게 들어갔어요. 스트리밍이 필요한 부분는 — Day 6 의 ChatStreamService 에서 이미 다뤘죠. 오늘은 짧은 한 문장 응답 이라 동기 호출로 충분해요.

해부 (3) — buildMedia(imageUrl) 두 갈래 분기 — URI 통로 vs Resource 통로

자, 여기가 — 본 클래스에서 가장 결정적인 한 부분 이에요. Media 한 장을 만드는데 — 한 가지 방식이 아니라 두 갈래 로 나뉘어요. 왜 그런지부터 풀고 들어갈게요.

왜 두 갈래로 나뉘는가 — 모든 URL 이 LLM 이 fetch 할 수 있는 URL이 아니다

Step 2 에서 세 통로 (URI · byte[] · Resource) 가 같은 도착지를 향한다고 정리했죠. 그때는 어느 통로든 골라 쓰면 된다 였는데 — 실제 사용에 들어가면 입력 URL 의 모양 에 따라 통로가 강제로 결정 되는 부분이 있어요.

한 가지 약속을 명확히 — Media.builder().data(URI.create(imageUrl)).build() 한 줄은 그 URL 을 LLM 프로바이더가 직접 fetch 한다 는 약속이에요. Gemini 도, OpenAI 도, Ollama 도 —

URI 를 받으면 그쪽 서버에서 직접 다운로드해서 모델 입력으로 넣어요. 그런데 이 약속에는 전제 가 있어요.

URL 이 바깥에서 닿을 수 있어야 한다는 것.

https://image.pollinations.ai/prompt/... 같은 공개 HTTPS URL 은 약속이 성립해요. Gemini 서버가 그 주소로 GET 요청을 보내면 그림이 돌아오니까요. 하지만 우리 앱이 막 만든 /uploads/portraits/upload-xxx.jpg 같은 상대 경로 는.

우리 앱 내부에서만 의미 있는 경로 예요. 바깥 LLM 서버가 이 경로로 GET 을 쏘면 — 닿을 곳이 없어요. Gemini OpenAI-compat 엔드포인트는 이 모양을 만나면 400 INVALID_ARGUMENT: Unsupported file URI type 으로 거부해요.

모델이 그림을 받지도 못한 채 호출이 끝나죠.

그래서 두 갈래로 분기해요.

이 분기 한 줄이 — Step 2 의 세 통로 중 두 통로를 진짜로 쓰는 첫 자리 예요. Step 2 에선 세 가지를 손에 정리 했고, Step 4 에선 그중 두 가지가 입력 URL 의 모양에 따라 자동으로 갈라지는 모습이에요.

buildMedia 의 본문 — 한 화면

private Media buildMedia(String imageUrl) {
    MimeType mimeType = detectMimeType(imageUrl);
    if (isLocalUpload(imageUrl)) {
        String relativePath = imageUrl.substring(LOCAL_UPLOAD_PREFIX.length());
        Resource resource = new FileSystemResource(uploadBaseDir + "/" + relativePath);
        log.debug("Vision: local upload → inline bytes from {}", resource);
        return Media.builder()
                .mimeType(mimeType)
                .data(resource)
                .build();
    }
    return Media.builder()
            .mimeType(mimeType)
            .data(URI.create(imageUrl))
            .build();
}

private boolean isLocalUpload(String imageUrl) {
    return imageUrl != null && imageUrl.startsWith(LOCAL_UPLOAD_PREFIX);
}

해부 다섯 줄로 풀게요.

한 줄 — MimeType mimeType = detectMimeType(imageUrl);: 분기 전에 MIME 타입을 먼저 결정해요. 어느 통로를 가든 .mimeType(...) 호출은 동일 해야 하니까 —

분기 안에 두 번 반복하지 않고 위로 끌어올렸어요. 코드의 DRY (Don't Repeat Yourself) 원칙의 잔결.

두 줄 — if (isLocalUpload(imageUrl)): 분기 조건. /uploads/ 로 시작하는지만 본다. 주소가 우리 앱에서 만들어진 것인지 의 한 가지 기준. 왜 더 정교하게 안 쓰는가.

URI.create(imageUrl).isAbsolute() 도 가능하지만 학습용 단순도 에서 멈췄어요. 운영 시나리오에선 file:// 절대 경로, s3:// 스킴 같은 패턴도 분기해야 하는데 그건 프로바이더별 어댑터 방식으로 풀어요.

세 줄 — String relativePath = imageUrl.substring(LOCAL_UPLOAD_PREFIX.length());: /uploads/portraits/upload-xxx.jpg 에서 앞의 /uploads/ 만 잘라내면 → portraits/upload-xxx.jpg.

URL 형태에서 디스크 형태로 변환 하는 한 줄.

네 줄 — Resource resource = new FileSystemResource(uploadBaseDir + "/" + relativePath);: 디스크 절대 경로 (정확히는 현재 작업 디렉토리 기준 상대 경로) 한 줄.

uploadBaseDir 이 기본 ./uploads 면 → ./uploads/portraits/upload-xxx.jpg 가 만들어져요.

FileSystemResource 는 Spring 의 Resource 한 구현체 — 디스크 파일 한 장을 가리키는 핸들 이에요. 바이트를 지금 읽지는 않아요 (lazy).

다섯 줄 — .data(resource) vs .data(URI.create(imageUrl)): 두 갈래의 진짜 차이. data(Resource) 를 받은 Media.builder() 는 내부적으로 resource.getContentAsByteArray() 를 호출해서 바이트를 즉시 읽어 보관 해요.

그러니까 Media.build() 가 끝나는 시점에 그림 바이트가 이미 메모리에 있어요. 그 다음 ChatModel.call(...) 호출 안에서 Spring AI 가 그 바이트를 base64 로 인코딩해서 요청 본문 (예: OpenAI 의 image_url: "data:image/jpeg;base64,...") 에 박아 넘겨요.

반면 data(URI) 를 받은 경우.

URI 문자열만 보관 하고, 바이트는 절대 우리 앱에서 안 읽어요. LLM 서버가 직접 가져가는 거예요.

왜 두 통로 둘 다 살려두는가 — 한쪽으로 일원화하지 않고

"그럼 그냥 Resource 통로 하나로 통일하면 안 되나요? 외부 URL 도 우리 앱이 한 번 다운로드해서 base64 로 박으면 일관성 있잖아요."

좋은 질문이에요. 세 가지 결 이 갈라요.

• 첫째 — 비용 — 외부 URL 을 우리 앱이 매번 다운로드하면 대역폭 비용 한 번 + LLM 으로 base64 전송 비용 한 번 이 둘 다 우리 쪽에서 발생해요. URI 패스스루면 우리 쪽 비용은 0 바이트.
• 둘째 — 캐싱 — 같은 외부 URL 을 100 명의 사용자가 동시에 보내면, URI 패스스루는 LLM 프로바이더 측의 fetch 캐시 가 살아요 (그쪽 인프라가 같은 URL 을 100 번 받지는 않음). Resource 통로면 우리 앱이 100 번 다운로드해서 100 번 base64 인코딩 하는 모양이에요.
• 셋째 — 응답 크기 — 외부 URL 1KB 짜리 문자열 vs base64 로 부풀어 오른 원본 그림 크기의 약 4/3 배 만큼의 페이로드. 1MB 그림이면 요청 본문이 1.3MB 정도로 커져요. URI 통로면 요청 본문이 URL 한 줄 로 끝.

그래서 외부 공개 URL 은 URI 통로, 우리 앱 내부 경로는 Resource 통로 의 분기가 기본값으로 옳은 결정 이에요.

운영 시나리오에서 외부 URL 도 인라인이 필요한 결 (예: 외부 URL 이 프라이빗 (인증 토큰 필요) 한 경우, LLM 프로바이더는 그 URL 에 닿지 못하니 우리가 한 번 fetch 해서 인라인 으로 보내야 함) 는.

같은 분기 한 가지를 더 추가하면 돼요. 분기 구조 자체가 확장 가능 해요.

해부 (4) — UserMessage 빌더 호출 — Step 3 주제의 회수

UserMessage userMessage = UserMessage.builder()
        .text(prompt)
        .media(image)
        .build();

이 3 줄도 — Step 3 의 빌더 패턴 주제 그대로. .text(...) + .media(...) 의 두 호출이 멀티모달 메시지의 표준 모양 이라는 점, Step 3 에서 정리해뒀던 그 부분이에요.

여기서 한 번 더 짚고 갈 패턴 — .media(image) 의에 Media 한 장만 들어가요 (varargs 라 여러 장도 가능하지만, 본 메서드는 한 장 시나리오).

멀티이미지 시나리오는 Step 6 의 부분 — 캐릭터 portrait 두 장을 동시에 비교 하는 장면에서 등장해요.

오늘은 단일 이미지 의 표준 모양만 손에 정리해요.

해부 (5) — chatModel.call(new Prompt(...)) + 응답 추출 — Day 1~6 의 패턴 그대로

ChatResponse response = chatModel.call(new Prompt(userMessage));
if (response == null || response.getResult() == null || response.getResult().getOutput() == null) {
    return "";
}
String text = response.getResult().getOutput().getText();
return text == null ? "" : text;

여기가 — 오늘 Day 8 가 지난 시간 Day 1~7 과 연결되는 부분이에요.

chatModel.call(new Prompt(userMessage)) 한 줄은 — Day 1 부터 들어간 그 모양 그대로. 텍스트 전용 호출이든, 멀티모달 호출이든 같은 인터페이스, 같은 호출 모양. 본 강의의 프로바이더 추상화 원칙 이 Vision 도메인에서 다시 등장 되는 부분이에요.

응답 추출은 3 단 추출 — response.getResult().getOutput().getText(). Day 1~6 의 ChatResponse 추출과 글자 단위로 동일 부분이에요.

• getResult() — Generation (단일 응답 후보)
• getOutput() — AssistantMessage (모델이 만든 메시지)
• getText() — 문자열 본문

그리고 — 가드 한 줄 들어간을 짚을게요.

if (response == null || response.getResult() == null || ...) 의 세 단 null 체크. 응답 자체가 비었거나, Generation 이 비었거나, Output 이 비었거나 — 어느 부분이 비어도 예외를 던지지 않고 빈 문자열 을 돌려줘요.

학생 진입 단순도 의 의도적 결정.

해부 (6) — detectMimeType(...) 의 단순함 — Step 2 주제 4 회수

private MimeType detectMimeType(String imageUrl) {
    String lower = imageUrl.toLowerCase();
    if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) {
        return MimeTypeUtils.IMAGE_JPEG;
    }
    if (lower.endsWith(".gif")) {
        return MimeTypeUtils.IMAGE_GIF;
    }
    if (lower.endsWith(".webp")) {
        return MimeType.valueOf("image/webp");
    }
    return MimeTypeUtils.IMAGE_PNG;
}

Step 2 의 주제 4 에서 미리보기로 펼쳤던 그 메서드. URL 끝부분 4 종 분기 의 단순도가 그대로 들어있어요.

왜 이 정도 단순도가 학생 진입에 맞는가 — 한 단락 더 박을게요. HTTP HEAD 요청을 날려서 Content-Type 헤더를 읽어 정교하게 추론 하는 결도 이론적으론 가능해요. 그런데 그 부분은 호출 한 번 더 + 비동기 처리 + 실패 케이스 분기 가 줄줄이 따라와요.

학생이 익히고 다닐 수 있는 단순도의 부분 로는 과잉. 본 강의는 URL 끝부분 분기 에서 멈춰요.

프로덕션 시나리오 에서 Apache Tika 매직 넘버 추론 같은 방식이 필요해지면 — 그때 한 부분 끌어올리에요.

3. Step 4 끝맺음 — 서비스 1 개, 컨트롤러는 다음 Step 의 부분

이번 Step 끝의은 단순 해요. VisionChatService 하나가 코드베이스에 들어갔고, HTTP 엔드포인트 는 아직 없는 부분예요. Step 5~6 에서 컨트롤러가 합류하면 끝에서 끝까지 (브라우저 → 컨트롤러 → 서비스 → ChatModel → 응답) 한 호흡으로 흘러요.

본 강의 길은 Step 5~6 끝에서 한 번에 통합 시연. @SpringBootTest 로 실제 Gemini 호출을 직접 확인해보고 싶다면 학생 실습 옵션 — 코드베이스에는 들어가 있지 않으니 직접 한두 번만 (무료 쿼터 소비 주의).

4. 💡 튜터의 결론 — Step 4 한 줄

"VisionChatService.describe(imageUrl, prompt) — 두 인자, 8 줄짜리 핵심 본문, 3 개 테스트 Green. Day 7 의 출력이었던 portrait URL 이 그대로 입력으로 흘러 텍스트 응답으로 돌아오는. 생성 → 인식의 클로저 가 한 클래스 안에 들어간. 다음 Step 에선 사용자가 업로드한 사진 도 같은 입구로 흘려넣는을 만들어요."

자, 서비스 하나를 익히셨으니 — 이제 그 입구를 사용자에게 열어주는 자리 가 다음 주제예요. 지난 시간까지의 입력 통로는 Day 7 portrait URL 한 가지였는데.

사용자가 직접 찍은 셀카, 갤러리에서 고른 사진 도 같은 describe(...)에 흘려넣고 싶잖아요. MultipartFile 하나 + 정적 리소스 재활용. Step 5 에서 URL 통로 옆에 byte[] 통로를 한 자리 더 여는 결을 만들어봅시다.

자, Step 4 에서 VisionChatService.describe(imageUrl, prompt) 하나를 익히셨어요. URL 한 줄만 받으면 그림을 보고 답하는. 지난 시간 Day 7 의 portrait URL 이 그대로 흘러갈 수 있는 매끈한 결까지 들어갔죠.

그런데 — 한 가지이 아직 빠져 있어요. 사용자가 지금 막 찍은 사진 을 캐릭터에게 보여주려면? 셀카, 갤러리에서 고른 사진, 친구가 카톡으로 보낸 이미지 한 장 — 이 부분은 URL 이 없어요. 외부에 호스팅돼 있지 않으니까요.

지난 시간까지 익힌 URL 우선 의 방식으로는 — 닿을 수가 없는 부분이 한 군데 남아 있이에요.

오늘 Step 5 의 미션은 — 그 빈 부분 를 URL 화 어댑터 하나로 채우는 거예요. 사용자가 multipart 로 업로드한 사진을 우리 서버에 한 번 정리해두고, /uploads/portraits/upload-xxx.png 같은 URL 모양 으로 돌려주는. 이 publicPath 가.

Step 6 에서 VisionChatService.describe(...) 의 첫 인자 로 그대로 흘러갈 거예요. 두 통로 (URL · 업로드) 가 결국 같은 입구 로 모이는 모양이에요.

1. 첫 주제 — URL 입력의 한계와 사용자 업로드의 필요성

먼저 왜 URL 만으로는 충분하지 않은가 — 두 통로의을 짧게 비교하고 갈게요.

URL 입력 시나리오 — Step 4 의 describe(imageUrl, prompt) 가 받아내는 부분이에요.

• 지난 시간 Day 7 의 Pollinations.ai portrait URL — 외부에서 누구나 GET 으로 받을 수 있는.
• 검색 엔진이 보여준 외부 이미지 검색 결과 — 그 부분도 URL 한 줄로 들어있어요.
• 다른 사용자가 공유한 링크 — 카톡 / 디스코드 / 슬랙 같은 곳에서 받은 URL.

이 부분들의 공통점은 — 이미지가 이미 외부 어딘가에 호스팅돼 있어서, URL 한 줄로 도달 가능 하다 는 거예요. 모델 (Gemini · GPT-4o · Ollama) 이 그 URL 한 줄로 직접 다운로드 해서 그림을 읽어요.

업로드 입력 시나리오 — 오늘 Step 5 의 영역이에요.

• 사용자가 방금 찍은 셀카 — 외부 호스팅 없음.
• 갤러리에서 고른 사진 — 본인 노트북/스마트폰에만 있는 부분.
• 카메라 앱에서 캡처한 한 장 — URL 자체가 존재하지 않는 경우.

이 부분에선 — URL 이 없어요. 사용자의 기기 안에만 있어서, 모델한테 건네줄 통로가 없는 부분이에요.

본 강의의 결정은 한 줄로 잡혀요.

"사용자 업로드는 일단 우리 서버에 저장 한다 → 정적 리소스 URL 한 줄로 URL 화 한다 → 그 URL 을 describe(...) 의 입력 통로로 합류 시킨다." 이렇게 정리하면 —

Step 4 에서 손에 정리한 URL 우선의 인터페이스가 그대로 살아요. 업로드는 URL 화 어댑터 한 자리 만 책임지면 돼요.

기존 인터페이스를 안 깨는 결정이에요.

이 형태이 들어오면 — 오늘 Step 5 가 왜 Vision 호출은 아직 안 하는가 가 자연스럽게 풀려요.

오늘은 URL 화 어댑터 한 부분 만 정리하는 부분 예요.

업로드 → 저장 → publicPath 응답 까지의 세 부분가 미션이고, Vision 호출 은 Step 6 에서 합류 시켜요.

한 Step 한 가지 의 호흡으로 단순도를 지키에요.

2. 두 번째 주제 — Day 7 의 ImageFileStorageService 재활용 + 새 오버로드 한 부분

자, URL 화 어댑터를 어디서 정리할 것인가 — 여기서 한 가지 결정이 펼쳐져요. Day 7 에서 정리한 ImageFileStorageService 를 재활용 한다. 새 클래스 하나 더 만들지 않고, 기존 자매를 한 단계 풍성 하게 만드에요.

Day 7 의 ImageFileStorageService.save(byte[] bytes, String fileNameHint) 시그니처를 한 번 더 떠올려 봅시다.

그 부분은 — 확장자 jpg 강제 였어요.

왜냐면 Pollinations.ai 가 jpg 만 줬으니까. 외부에서 받은 그림이 항상 jpg 라는 전제 조건 이 깔린 부분였죠.

그런데 — 사용자 업로드는 다르게 흘러와요. png · jpg · gif · webp 네 종류가 모두 들어올 수 있어요. 사용자가 어떤 포맷으로 업로드할지 — 우리는 미리 알 수 없는 부분이에요. 그래서 확장자를 인자로 받는 새 시그니처가 필요해요.

여기서 두 가지 길이 갈려요.

• 길 A: 기존 save(byte[], hint) 의 시그니처를 바꿔서 확장자 인자를 추가 — Day 7 호출부 (ImageDownloader 등) 가 한꺼번에 깨지는. 학생이 지난 시간 정리한 코드를 오늘 다시 뜯어고쳐야 해요.
• 길 B: 기존 메서드를 그대로 살려두고, 새 오버로드 한 부분 만 추가 — Day 7 호출부 변경 0 건. 새 오버로드는 내부적으로 기존 메서드에 위임 하는 방식.

본 강의는 길 B 를 택해요. 기존 학생 코드를 안 깨는 결정 + 단일 책임 원칙. 새 오버로드 한 자리만 잡혀요.

/**
 * 바이트 배열을 파일로 저장하고 정적 리소스 URL 을 돌려준다 (확장자 jpg 고정).
 *
 * <p>Day 7 의 호출부 호환을 위해 시그니처를 유지한다. 내부적으로
 * {@link #save(byte[], String, String)} 에 {@code "jpg"} 를 넘겨 위임한다.</p>
 */
public String save(byte[] bytes, String fileNameHint) throws IOException {
    return save(bytes, fileNameHint, "jpg");
}

/**
 * Day 8 Step 5 — 사용자 업로드용. 임의 확장자(png · jpg · gif · webp 등) 를 받아 저장한다.
 *
 * @param extension 확장자 (예: {@code "png"}). 영문자만 허용, 소문자 정규화, null/blank 면 {@code "jpg"} 폴백.
 */
public String save(byte[] bytes, String fileNameHint, String extension) throws IOException {
    Path dir = Paths.get(uploadDir);
    Files.createDirectories(dir);

    String safeHint = sanitize(fileNameHint);
    String safeExt = sanitizeExtension(extension);
    String fileName = safeHint + "-" + System.currentTimeMillis() + "." + safeExt;
    Path target = dir.resolve(fileName);
    Files.write(target, bytes);

    String publicPath = "/uploads/portraits/" + fileName;
    log.info("[ImageFileStorage] saved: bytes={}, path={}", bytes.length, target.toAbsolutePath());
    return publicPath;
}

이 부분을 한 단락 풀어드릴게요.

기존 save(byte[], hint) 가 새 오버로드에 위임 하는 모양 — return save(bytes, fileNameHint, "jpg"); 한 줄. 동작은 100% 같아요. Day 7 의 ImageDownloader 가 이 부분를 호출하던 결은 글자 하나 바뀌지 않아요.

지난 시간 들어간 곳가 오늘도 그대로 살아있어요.

새 오버로드는 extension 인자 한 부분가 추가된 모양 — 이 한 부분가 png · jpg · gif · webp 네 종을 모두 받아낼 수 있는 진행을 열어줘요. 파일명 조립 도 지난 시간과 같은 모양: safeHint + "-" + System.currentTimeMillis() + "." + safeExt.

timestamp 한 부분가 충돌 방지 라는 지난 시간의 결정 그대로 살아있어요.

sanitizeExtension(...) 헬퍼 — 학습용 단순도 의 결정이 한 부분 더 들어가 있어요.

private String sanitizeExtension(String extension) {
    if (extension == null || extension.isBlank()) {
        return "jpg";
    }
    String lower = extension.toLowerCase();
    if (!lower.matches("[a-z]+")) {
        return "jpg";
    }
    return lower;
}

세 단 분기가 들어있어요.

• null 또는 빈 문자열 — "jpg" 폴백.
• 영문자가 아닌 문자가 섞여 있음 (예: "png; rm -rf /") — "jpg" 폴백.
• 영문자만으로 구성됨 — 소문자로 정규화해서 그대로 사용.

왜 이 정도 단순도가 학습에 맞는가 — 한 단락만 더. 실무 시나리오라면 Apache Tika 매직 넘버 검사 로 파일의 진짜 정체 를 한 번 더 확인하는 진행이 정석이에요 (Step 4 에서 짚은 그 결과 같은 결). 그런데 학생이 익히고 다닐 수 있는 단순도 의 부분에선 —

영문자 화이트리스트 한 부분에서 멈춰요. 프로덕션에서 한 단계 끌어올릴 부분 라는 진행만 정리해두면 충분해요.

💡 왜 기존 메서드를 안 부수고 오버로드 로 갔는가

기존 호출부 호환성 + 단일 책임 원칙, 두 가지가 합쳐진 결정이에요.

기존 호출부 호환성 — Day 7 에서 들어간 ImageDownloader.downloadAndSave(...) 같은 부분가 save(byte[], hint) 를 호출하고 있어요. 시그니처를 바꾸면 — 거기가 컴파일 에러로 한꺼번에 깨져요. 지난 시간 학생이 정리한 코드가 오늘 한 번에 깨지는. 그건 학습 진행 입장에서 피해야 하는 부분 예요.

단일 책임 원칙 — save(byte[], hint) 는 "외부 다운로드 결과 (jpg 강제) 를 저장하는 부분", save(byte[], hint, ext) 는 "사용자 업로드 (임의 확장자) 를 저장하는." 두 부분은 책임이 다른 자리예요. 한 메서드에 모든 시나리오를 욱여넣지 않고 — 각자의 입구 를 마련하는 방식. 오버로드는 그 두 입구를 같은 클래스 안에 정리해두는 표준 도구 예요.

3. 세 번째 주제 — Vision 도메인 예외 + ErrorCode 3 형제 추가 — Day 7 의 자매

자, 새 컨트롤러를 박기 전에 — 예외 처리 인프라 한 자리부터 깔고 갈게요. Day 7 에서 정리한 ImageException + IMAGE_* ErrorCode 5 형제를 한 번 더 떠올려 봅시다. 그 자매가 오늘 자리잡아요. VisionException + VISION_* ErrorCode 3 형제.

먼저 ErrorCode 의 Vision 항목 세.

// Vision (Day 8)
VISION_IMAGE_REQUIRED(HttpStatus.BAD_REQUEST, "V001", "이미지 파일을 첨부해 주세요."),
VISION_INVALID_MIME_TYPE(HttpStatus.BAD_REQUEST, "V002", "지원하지 않는 이미지 형식입니다. (png, jpg, gif, webp)"),
VISION_UPLOAD_FAILED(HttpStatus.INTERNAL_SERVER_ERROR, "V003", "이미지 업로드에 실패했습니다.");

세 부분을 한 줄씩 짚을게요.

• VISION_IMAGE_REQUIRED (V001 · 400) — multipart 로 파일이 안 왔거나 (null) 빈 파일 (isEmpty()) 인 경우. 사용자 입력 검증 실패의 영역이에요.
• VISION_INVALID_MIME_TYPE (V002 · 400) — 파일은 왔지만 MIME 타입이 화이트리스트 밖 인 경우 (예: text/plain, application/pdf). 허용 4 종 밖의 모든 부분 가 여기로 떨어져요.
• VISION_UPLOAD_FAILED (V003 · 500) — 검증은 통과했지만 서버 내부의 저장 단계 에서 실패한 부분 (디스크 풀, 권한 문제, IOException 등). 사용자 책임이 아닌 서버 책임 이라 500.

코드 번호 V001 / V002 / V003 — Day 7 의 I001~I005 와 같은 이에요. 도메인 한 글자 + 일련번호 의 패턴, 본 강의 표준 모양 그대로.

이제 VisionException 본문이에요. 5 줄이에요.

public class VisionException extends BusinessException {

    public VisionException(ErrorCode errorCode) {
        super(errorCode);
    }
}

BusinessException 을 상속하고, ErrorCode 하나만 받아 부모 생성자에 위임. Day 7 의 ImageException 과 글자 단위로 동일한 모양. 새로 외울 부분 0 개 예요.

여기서 한 단락 — 왜 IllegalArgumentException 을 직접 던지지 않는가 의을 정리할게요.

본 강의의 GlobalExceptionHandler 는 — 도메인 예외 (BusinessException 의 자손) 만 잡아서 ApiResponse.fail(ErrorResponse) 형태로 변환해줘요.

그 방식으로 들어간 게 본 강의의 응답 표준 규약 이었어요 (정상은 ApiResponse.success, 실패도 ApiResponse.fail — 같은 봉투).

만약 컨트롤러에서 throw new IllegalArgumentException("이미지 필수") 를 직접 던지면 — GlobalExceptionHandler 의 @ExceptionHandler(BusinessException.class) 가 그걸 못 잡아요.

Spring MVC 의 기본 핸들러 가 받아서 400 평문 응답 으로 떨어뜨려요.

결과.

같은 엔드포인트에서 실패 응답이 두 가지 모양 (ApiResponse.fail vs 평문) 으로 갈리는 비대칭.

그래서 본 강의의 방침은 한 줄로 잡혀요. "검증 실패도 도메인 예외 — VisionException(ErrorCode.VISION_*) — 하나의 패턴으로만 던진다." 이 결정이 응답 표준의 일관성 을 지키는 핵심입니다.

4. 네 번째 주제 — VisionUploadController 한 화면 — Multipart 처리의 표준 모양

자, 인프라 두 부분가 깔렸으니 — 컨트롤러 한 화면 을 박을 차례예요. VisionUploadController 의 본문이에요.

@Slf4j
@RestController
@RequestMapping("/api/vision")
public class VisionUploadController {

    private static final Set<String> ALLOWED_MIME_TYPES = Set.of(
            "image/png",
            "image/jpeg",
            "image/gif",
            "image/webp"
    );

    private final ImageFileStorageService imageFileStorageService;

    public VisionUploadController(ImageFileStorageService imageFileStorageService) {
        this.imageFileStorageService = imageFileStorageService;
    }

    @PostMapping("/uploads")
    public ResponseEntity<ApiResponse<VisionUploadResponse>> upload(
            @RequestParam("image") MultipartFile image) {

        if (image == null || image.isEmpty()) {
            throw new VisionException(ErrorCode.VISION_IMAGE_REQUIRED);
        }

        String contentType = image.getContentType();
        if (contentType == null || !ALLOWED_MIME_TYPES.contains(contentType)) {
            throw new VisionException(ErrorCode.VISION_INVALID_MIME_TYPE);
        }

        String extension = mapExtension(contentType);

        try {
            String publicPath = imageFileStorageService.save(image.getBytes(), "upload", extension);
            VisionUploadResponse response = new VisionUploadResponse(
                    publicPath,
                    contentType,
                    image.getSize()
            );
            log.info("[VisionUpload] saved: contentType={}, size={}, publicPath={}",
                    contentType, image.getSize(), publicPath);
            return ResponseEntity.ok(ApiResponse.success(response));
        } catch (IOException e) {
            log.error("[VisionUpload] storage failed", e);
            throw new VisionException(ErrorCode.VISION_UPLOAD_FAILED);
        }
    }

    /**
     * contentType → 파일 확장자 단순 매핑. 학습용 단순도 유지를 위해 if-else 로 박는다.
     */
    private String mapExtension(String contentType) {
        return switch (contentType) {
            case "image/png" -> "png";
            case "image/jpeg" -> "jpg";
            case "image/gif" -> "gif";
            case "image/webp" -> "webp";
            default -> "jpg";
        };
    }
}

자, 이 컨트롤러를 다섯 부분 로 해부해볼게요.

해부 (1) — @PostMapping("/uploads") + @RequestParam("image") MultipartFile image

@PostMapping("/uploads")
public ResponseEntity<ApiResponse<VisionUploadResponse>> upload(
        @RequestParam("image") MultipartFile image) {

이 부분은 — Spring MVC 의 multipart 처리 표준 모양 그대로예요.을 한 줄씩 짚을게요.

• @PostMapping("/uploads") — 클래스 레벨 @RequestMapping("/api/vision") 와 합쳐져서 POST /api/vision/uploads 엔드포인트가 잡혀요. POST 인 이유는 — 업로드는 서버 상태를 바꾸는 동작 (파일 저장) 이기 때문에, GET 이 아니라 POST 가 정석이에요.
• @RequestParam("image") MultipartFile image — multipart/form-data 요청에서 image 라는 part 이름 으로 들어온 파일을 받아내요. HTML <input type="file" name="image"> 또는 curl 의 -F "image=@cat.png" 같은 부분에서 part 이름이 image 로 들어있어야 매칭돼요.
• 반환 타입 ResponseEntity<ApiResponse<VisionUploadResponse>> — 본 강의의 응답 표준 규약 그대로. raw record 직접 반환 금지, ApiResponse.success(...) 봉투로 감싸는 방식.

해부 (2) — MIME 타입 화이트리스트

private static final Set<String> ALLOWED_MIME_TYPES = Set.of(
        "image/png",
        "image/jpeg",
        "image/gif",
        "image/webp"
);

여기서 한 결정이 잡혀요. "화이트리스트 vs 블랙리스트 — 화이트리스트로 간다." 결정 근거는 한 줄로 풀려요.

블랙리스트 는 — 위험한 부분만 골라서 막는 모양이에요 (예: .exe, .sh 차단). 그런데 위험한 형식의 종류는 무한대 라 — 우리가 모르는 새 위험 이 등장하면 그대로 통과 해요. 보안 관점에서 위험한 방식이에요.

화이트리스트 는 — 허용되는 부분만 골라서 들여보내는 모양. 모르는 형식은 모두 차단 이라 — 예측 불가능한 위험 까지 한 번에 막혀요. 알려진 4 종 (png · jpg · gif · webp) 만 들어오는. 학생 업로드 시나리오에 충분한 부분이에요.

특히 실행 가능 파일 위장 차단 이 중요해요.

사용자가 malicious.exe 의 확장자만 .png 로 바꿔서 보내면 — 파일명 만으로는 못 막아요 (이름은 텍스트일 뿐).

하지만 MIME 타입 은 브라우저가 파일의 진짜 정체 를 보고 결정하는 이에요 (절대 완벽하진 않지만, 1 차 방어막으로는 충분).

MIME 타입 화이트리스트는 그 방식의 첫 관문.

해부 (3) — mapExtension(contentType) switch

private String mapExtension(String contentType) {
    return switch (contentType) {
        case "image/png" -> "png";
        case "image/jpeg" -> "jpg";
        case "image/gif" -> "gif";
        case "image/webp" -> "webp";
        default -> "jpg";
    };
}

MIME 타입 → 파일 확장자 4 종 매핑이 들어간 곳. 학습용 단순도 의 결정이에요.

왜 default -> "jpg" 가 들어가 있나 — 화이트리스트 검증을 이미 통과한 부분 라 default 로는 절대 안 떨어져야 정상이에요. 그런데 방어적으로 한 줄 정리해두에요. 만약 화이트리스트가 바뀌었는데 switch 가 안 따라간 경우 같은 프로그래머 실수 의 부분에서도.

jpg 폴백 으로 조용히 동작 해요. 컴파일러가 안 잡아주는 진행을 default 가 한 부분 막아주는.

⚠ 운영 보안 한계 — MIME 타입만으로는 부족하다

이 코드의 한계를 한 단락 짚어두고 갈게요. MIME 타입 은 — 브라우저가 보고한 값 이라 조작 가능 해요. curl 로 직접 요청을 만들면 Content-Type: image/png 헤더를 임의로 박을 수 있어요. 그래서 MIME 타입 화이트리스트만으로는 진짜 png 인지 확인이 안 돼요.

실무 시나리오 라면 — 파일 시그니처 (매직 넘버) 검사 가 한 부분 더 들어가야 정석이에요. PNG 파일은 첫 8 바이트가 89 50 4E 47 0D 0A 1A 0A 로 들어있어요. JPG 는 FF D8 FF. 바이트 단위로 진짜 정체를 확인 하는 진행이 Apache Tika 같은 라이브러리에 들어있어요.

본 강의는 — MIME 화이트리스트 + 확장자 매핑 의 2 단 검증 까지가 부분의 끝이에요. 프로덕션에서 한 단계 더 끌어올릴 부분 라는 진행만 정리해두고, 학습 단순도 에서 멈춰요.

해부 (4) — imageFileStorageService.save(image.getBytes(), "upload", extension) — Day 7 자매를 그대로 호출

String publicPath = imageFileStorageService.save(image.getBytes(), "upload", extension);

이 한 줄이 — 오늘 Step 5 의 핵심 부분 예요. 두 번째 학습 포인트에서 정리한 새 오버로드 가 여기서 회수 돼요.

세 인자을 짚을게요.

• image.getBytes() — MultipartFile 의 바이트 배열 추출. 메모리에 한 번 통째로 읽어 들어오는. 큰 파일에선 메모리 부담 이 있는 이에요 (한계 한 줄은 잠시 뒤 학생 질문에서 다뤄요).
• "upload" — 파일명 힌트. 지난 시간 Day 7 에선 "portrait-uuid" 같은에 생성된 portrait 의 ID 가 들어갔는데, 오늘은 모든 사용자 업로드를 upload- 접두어로 통일해요. 어떤 부분에서 온 파일인지 가 파일명 자체로 보이는 방식.
• extension — mapExtension(contentType) 으로 결정된 4 종 중 하나. 두 번째 학습 포인트의 새 오버로드가 받아내는.

반환된 publicPath 는 — /uploads/portraits/upload-xxx-1714500000000.png 같은 모양이에요.

이 한 줄짜리 String 이 — Step 6 에서 VisionChatService.describe(imageUrl, prompt) 의 첫 인자로 그대로 흘러갈 자리 예요.

두 통로가 한 입구로 모이는 형태의 그 클로저 점.

해부 (5) — IOException → VisionException(VISION_UPLOAD_FAILED) 래핑

try {
    String publicPath = imageFileStorageService.save(image.getBytes(), "upload", extension);
    // ...
} catch (IOException e) {
    log.error("[VisionUpload] storage failed", e);
    throw new VisionException(ErrorCode.VISION_UPLOAD_FAILED);
}

이 try-catch 부분은 — Day 7 에서 들어간 예외 래핑 표준 패턴 의 회수 예요. ImageFileStorageService.save(...) 가 디스크 풀 / 권한 문제 / 디렉토리 생성 실패 등으로 IOException 을 던지면 — 컨트롤러가 그걸 잡아서 도메인 예외로 래핑 하는 패턴이에요.

왜 IOException 을 그대로 throws 안 하고 잡아서 던지나 — IOException 은 Java 표준 체크 예외 라 BusinessException 의 자손이 아니에요.

GlobalExceptionHandler 의 @ExceptionHandler(BusinessException.class) 가 못 잡아요. 그러면 Spring 기본 핸들러 가 받아 500 평문 응답 으로 떨어뜨려요. 결과 — 응답 표준이 깨지는.

그래서 — try-catch 한 줄에서 도메인 예외로 래핑 하는 진행이 잡혀요.

log.error(...) 로 원인 스택트레이스는 로그에 남기고, 사용자에게는 표준 에러 응답 ({"success": false, "error": {"code": "V003", ...}}) 으로 떨어뜨리는 방식.

내부 디버깅 정보는 로그에, 사용자 가시 정보는 표준 응답에 — 두 채널이 분리돼요.

응답 record VisionUploadResponse 의 모양도 짧게 짚을게요.

public record VisionUploadResponse(
        String publicPath,
        String contentType,
        long sizeBytes
) {
}

세 부분 — publicPath (Step 6 으로 흘려보낼 URL), contentType (확인용), sizeBytes (확인용). 학습에 충분한 단순도예요.

spring:
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 10MB

6. Step 5 끝맺음 — 사용자 업로드 → publicPath 한 줄, 검증 포인터

이 부분의 동작 보장은 — 코드베이스 ImageFileStorageServiceTest (5 케이스: 오버로드 · 위임 · 확장자 · 폴백 · sanitize) + VisionUploadControllerTest (4 케이스: 정상 png · 정상 jpg · 빈 파일 · 잘못된 MIME) 에 들어있어요.

단위 테스트 본문은 코드베이스에서 직접 열어보시고, 본 교안은 프로덕션 컨트롤러 + 서비스 본문 까지만 인용해요.

요약하면 — MIME 화이트리스트 + 확장자 매핑 + V001/V002 도메인 예외 세 부분가 컨트롤러 + 서비스 + 검증의 세 켜 에 한 호흡으로 흘러요.

7. 후속 결합 — prod 흡수 (사용자 업로드 → 캐릭터 코멘트, Day 7 셀카 prod 의 대칭)

재방문 박스 — 이 부분은 Step 5 가 처음 들어있던 URL 화 어댑터 까지만 멈춰 있던 것을 prod 결합 한 부분 더 로 정리하는 후속 결합 작업이에요. 지난 시간 Day 7 의 셀카 prod (LLM 텍스트 + AI 가 만든 이미지) 의 대칭 부분 — 사용자가 업로드한 사진을 vision 모드 응답 한 줄 로 채팅 본문에 정리하는 흐름이에요.

① lab capability → prod 결합 (같은 Day 안에 닫히는 두 부분)

Step 5 까지의 결과만으로는 capability에서 멈춰요. POST /api/vision/uploads 가 multipart 한 장을 /uploads/portraits/upload-xxx.png URL 로 정리해주는 URL 화 어댑터 자체는 동작하지만.

그 URL 이 실제 채팅 도메인 에 어떻게 박히는지이 없어요. 학생 데모 시점에 "이 업로드가 채팅 어디로 흘러가요?" 의 답이 curl 한 줄로만 나오는이라면 본 강의의 점진 리팩토링 메시지 가 흐려져요 — 학생이 진짜 레거시 코드를 리팩토링하는 감각 을 못 가져가요.

그래서 prod 결합 한 단계 더 를 정리해요.

POST /api/chat 의 컨트랙트를 옵션 1자리 확장 — AiChatRequest 에 imageUrl 한 줄을 추가하면, 채팅이 텍스트만 받던 방식 에서 텍스트 + 사용자 사진을 받는 방식 으로 한 단계 자라요.

Day 7 셀카 prod 가 키워드 매칭으로 자동 셀카 생성 으로 prod 에 들어간 흐름의 대칭.

Day 8 의 사용자 업로드는 명시적 첨부 분기 로 prod 에 잡혀요.

② Before/After — AiChatRequest 의 옵션 필드 한 줄 (학생 데모 무파괴의 결)

먼저 기존 컨트랙트를 안 깨는 결 이 중요해요. 학생이 git checkout day07-image-generation 으로 돌아갔다가 day08 로 돌아왔을 때 기존 POST /api/chat 호출이 그대로 살아 있어야 본 강의의 점진 리팩토링 메시지가 살아요.

// Before — Day 7 시점까지 (line 8~17)
public record AiChatRequest(
        @NotNull(message = "이성친구 ID는 필수입니다.")
        Long soulmateId,

        @NotBlank(message = "메시지를 입력해 주세요.")
        String userMessage
) {
}

// After — Day 8 후속 결합 (옵션 필드 한 줄 + 호환 생성자)
public record AiChatRequest(
        @NotNull(message = "이성친구 ID는 필수입니다.")
        Long soulmateId,

        @NotBlank(message = "메시지를 입력해 주세요.")
        String userMessage,

        /**
         * (Day 8) 사용자가 첨부한 이미지의 정적 리소스 경로. {@code null}/blank 면 텍스트 채팅.
         * 일반적으로 {@code POST /api/vision/uploads} 응답의 {@code publicPath} 가 그대로 들어온다.
         */
        String imageUrl
) {
    /**
     * 호환 생성자 — Day 7 시점까지의 호출처를 그대로 살린다 (학생 데모 무파괴).
     * 컨트랙트가 깨지지 않게 *옵션 필드를 null 로 채우는* 흐름을 명시적으로 보여줍니다.
     */
    public AiChatRequest(Long soulmateId, String userMessage) {
        this(soulmateId, userMessage, null);
    }
}

record 의 새 필드 추가는 모든 호출처 의 컴파일을 깨뜨릴 수 있어요. 옵션은 두 가지였어요:

1. 모든 호출처에 null 명시 추가 — 학생이 봤을 때 옵션 필드의 결 이 보이지만, 기존 테스트 7~10 부분을 다 손대야 해요.
2. 2-arg 호환 생성자 한 줄 — 호출처 무수정. 신규 부분에서만 3-arg 로 옵션 명시. 채택.

이 작은 한 줄(public AiChatRequest(Long, String) { this(soulmateId, userMessage, null); })이 옵션 필드의 사용 모습 을 학생 데모 무파괴 와 함께 살리는 결정타예요.

JSON deserialization 측면에서도 무파괴 — Jackson 이 missing 필드는 null 로 처리하니 프론트가 imageUrl 을 안 보내도 컨트랙트가 안 깨져요.

③ VisionCommentService — chat ↔ vision 결합 책임 분리 (Day 7 SelcaService 의 대칭)

다음 결정 — vision 결합 한 단계를 어디에 둘 것인가. 후보 3 부분:

후보 B 가 정합이에요. Day 7 의 SelcaService 가 chat ↔ image 결합 을 캡슐화한 것과 같은 패턴 같은 부분 (kr.spartaclub.aifriends.chat.service) — chat 도메인의 교차 관심사 한 자리.

④ VisionCommentService 본문 — 가드 1회 + describe 1회 + 인격 톤 후처리

package kr.spartaclub.aifriends.chat.service;

import kr.spartaclub.aifriends.chat.dto.VisionCommentResult;
import kr.spartaclub.aifriends.common.exception.ErrorCode;
import kr.spartaclub.aifriends.domain.Soulmate;
import kr.spartaclub.aifriends.vision.exception.VisionException;
import kr.spartaclub.aifriends.vision.service.VisionChatService;
import kr.spartaclub.aifriends.vision.service.VisionDailyQuotaGuard;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

@Slf4j
@Service
@RequiredArgsConstructor
public class VisionCommentService {

    private static final String QUOTA_EXCEEDED_FALLBACK =
            "오늘 사진 너무 많이 봤더니 눈이 좀 피곤하네 ㅠㅠ 내일 다시 보여줄래?";

    private static final String VISION_FAILED_FALLBACK =
            "어, 사진이 잘 안 보이네 ㅠㅠ 다른 사진으로 한 번 더 보내줄래?";

    private final VisionChatService visionChatService;
    private final VisionDailyQuotaGuard quotaGuard;

    public boolean hasImage(String imageUrl) {
        return imageUrl != null && !imageUrl.isBlank();
    }

    public VisionCommentResult comment(Soulmate soulmate, String imageUrl, String userMessage) {
        try {
            quotaGuard.checkAndIncrement();
        } catch (VisionException e) {
            if (e.getErrorCode() == ErrorCode.VISION_QUOTA_EXCEEDED) {
                log.info("[VisionComment] quota exceeded — falling back to character voice");
                return VisionCommentResult.quotaExceeded(QUOTA_EXCEEDED_FALLBACK);
            }
            throw e;
        }

        try {
            String prompt = composePrompt(soulmate, userMessage);
            String aiComment = visionChatService.describe(imageUrl, prompt);
            if (aiComment == null || aiComment.isBlank()) {
                log.warn("[VisionComment] describe returned blank — falling back");
                return VisionCommentResult.failed(VISION_FAILED_FALLBACK);
            }
            return VisionCommentResult.success(aiComment);
        } catch (RuntimeException e) {
            log.warn("[VisionComment] vision call failed: {}", e.getMessage());
            return VisionCommentResult.failed(VISION_FAILED_FALLBACK);
        }
    }

    String composePrompt(Soulmate soulmate, String userMessage) {
        String trimmed = userMessage == null ? "" : userMessage.trim();
        StringBuilder sb = new StringBuilder();
        sb.append("당신은 '").append(soulmate.getName()).append("' 라는 이름의 캐릭터예요. ")
                .append("성격: ").append(soulmate.getPersonalityKeywords()).append(". ")
                .append("취미: ").append(soulmate.getHobbies()).append(". ")
                .append("사용자가 사진을 보내왔어요. ");
        if (!trimmed.isEmpty()) {
            sb.append("사용자 메시지: \"").append(trimmed).append("\". ");
        }
        sb.append("이 사진을 보고 한국어 한~두 문장으로 친근한 말투로 코멘트해 주세요.");
        return sb.toString();
    }
}

세 가지가 눈에 들어와요. 첫째 — 가드 한도 초과 와 describe 빈 응답/예외 가 다른 방식의 fallback 메시지 로 분리돼요. 한도 초과는 오늘 사진 너무 많이 봤더니 눈이 좀 피곤 (캐릭터의 피로 톤), describe 실패는 어, 사진이 잘 안 보이네 (캐릭터의 어색함 톤)

같은 기술적 차단/실패 라도 왜 안 됐는지가 다르면 캐릭터 인격 의 어휘도 다르게 잡혀요.

이게 Day 7 의 SelcaService 가 카메라 배터리 / 핸드폰 말썽 두 갈래로 분리한 결과의 대칭 이에요.

둘째 — composePrompt 가 SystemMessage 분리 없이 한 덩어리 자연어로 잡혀요.

학습용 단순도.

Step 2 의 세 입자가 한 군데에 모이는 결을 Soulmate 컨텍스트가 자연어 prompt 안에 들어간 모양으로 한 줄에 보여줘요. 셋째 — comment 의 시그니처가 (Soulmate, String imageUrl, String userMessage) 세 인자예요.

Day 7 SelcaService.generate(Soulmate, String userMessage) 가 두 인자 인 결과 한 인자 더 (imageUrl) — 입력 모달리티가 추가되면 시그니처도 한 인자 자란다 는 패턴이에요.

⑤ AiChatService.processChat 의 vision 분기 — facade 가 두 방식을 모두 흘려보내는 결

@Service
@RequiredArgsConstructor
public class AiChatService {

    /** 사용자가 사진을 보내준 친밀감을 호감도 +1 로 환산 — 학습용 단순값. */
    private static final int VISION_AFFECTION_DELTA = 1;

    private final SoulmateRepository soulmateRepository;
    private final ChatLogRepository chatLogRepository;
    private final SoulmateAchievementRepository achievementRepository;

    private final SoulmateChatService soulmateChatService;
    private final SelcaService selcaService;
    private final VisionCommentService visionCommentService;

    @Transactional
    public AiChatResponse processChat(AiChatRequest request) {
        Long soulmateId = request.soulmateId();
        String userMessage = request.userMessage();
        String userImageUrl = request.imageUrl();

        Soulmate soulmate = soulmateRepository.findById(soulmateId)
                .orElseThrow(() -> new BusinessException(ErrorCode.SOULMATE_NOT_FOUND));

        // (Day 8) 사용자가 이미지 첨부 → LLM 텍스트 호출 우회, vision 모드로 처리
        if (visionCommentService.hasImage(userImageUrl)) {
            return processVisionChat(soulmate, userMessage, userImageUrl);
        }

        // 일반 텍스트 채팅 — LLM 호출 + Day 7 셀카 분기
        AiReply reply = soulmateChatService.chat(soulmateId, userMessage);
        // ... (셀카 분기 + ChatLog + 호감도 + 응답 합성)
    }

    private AiChatResponse processVisionChat(Soulmate soulmate, String userMessage, String userImageUrl) {
        VisionCommentResult vision = visionCommentService.comment(soulmate, userImageUrl, userMessage);

        String aiMessage = vision.aiComment() != null ? vision.aiComment() : vision.fallbackMessage();
        int affectionDelta = vision.aiComment() != null ? VISION_AFFECTION_DELTA : 0;

        chatLogRepository.save(new ChatLog(null, soulmate.getId(), "USER", userMessage, null));
        chatLogRepository.save(new ChatLog(null, soulmate.getId(), "AI", aiMessage, null));

        soulmate.addAffection(affectionDelta);
        int newLevel = 1 + (soulmate.getAffectionScore() / 10);
        soulmate.setLevel(newLevel);
        List<String> newBadges = checkAndGrantBadges(soulmate);

        return new AiChatResponse(
                userMessage,
                aiMessage,
                List.of(),                   // vision 분기는 선택지 없음
                soulmate.getId(),
                soulmate.getAffectionScore(),
                soulmate.getLevel(),
                newBadges,
                userImageUrl                 // 사용자가 보낸 이미지를 그대로 echo (UI 표시용)
        );
    }
}

여기서 한 가지 결정이 눈에 들어가야 해요.

vision 분기는 SoulmateChatService.chat 호출을 우회 해요. Day 7 셀카 분기는 LLM 호출 + 셀카 생성 둘 다 의 흐름인데, Day 8 vision 분기는 vision 모드 응답 한 줄로 채팅 본문을 대체.

왜 다를까요? 이어지는 부분의 매트릭스에서 풀어요.

⑥ 입력 모달리티가 출력 합성을 결정하는 (Day 7 셀카 vs Day 8 비전 매트릭스)

핵심 신호 한 줄: "입력 모달리티가 한 가지 더 자라면 (텍스트 → 이미지) 출력 합성 방식도 한 단계 다르게 들어간다." 셀카는 이미지를 출력 자산으로 추가 하는 방식, 비전은 이미지를 입력의 한 가지로 받고 응답 합성을 대체 하는 방식. 같은 도메인 (chat) 안에 정리한 다른 두 방식 이에요.

⑧ 💡 튜터의 결론 — Step 5 후속 결합의 한 줄

"AiChatRequest 의 옵션 필드 한 줄 + 호환 생성자 한 줄 + VisionCommentService 한 단계. 셋이 합쳐져 — 5 일 전 Day 7 셀카 prod 와 대칭으로 Day 8 사용자 업로드가 /api/chat 의 한 가지로 들어갔어요. 입력 모달리티가 한 가지 자라면 출력 합성 방식도 한 단계 다르게 들어간다 — 이 방식이 들어갔다면, Day 9 (Voice) 의 오디오 입력 주제 가 박힐 때도 같은 방식의 한 단계 가 자라요. 모달리티 ↔ 결합 패턴 이 들어갔어요."

⑨ 테스트 케이스 — 단위 시그니처 8, 한 화면에 박기

검증된 코드의 부분도 한눈에 들어가야 학생이 내가 따라할 때 어디가 Green 인지 가 보여요. 두 테스트 클래스의 케이스 시그니처를 한 화면에 모아둡니다:

VisionCommentServiceTest (6 케이스, 모두 Green)

1. hasImage — null 또는 공백이면 false, 값이 있으면 true (5 부분 한 묶음)
2. comment 성공 — 가드 통과 + describe 응답 텍스트를 그대로 success 로 감싼다
3. comment — 가드가 VISION_QUOTA_EXCEEDED 던지면 캐릭터 인격 우회 메시지 + quotaExceeded=true, describe 미호출
4. comment — describe 가 빈 문자열을 반환하면 failed fallback
5. comment — describe 가 예외를 던지면 failed fallback (캐릭터 인격 톤)
6. comment — userMessage 가 비어도 캐릭터 컨텍스트로 prompt 합성하여 호출

AiChatServiceTest (+2 케이스 추가, 모두 Green) 7. Vision 분기 — 사용자 imageUrl 첨부 시 LLM chat 호출 우회, VisionCommentService 가 응답 본문 책임 + imageUrl echo + 호감도 +1 8. Vision 분기 — 한도 초과 시 캐릭터 인격 우회 메시지 + 호감도 변화 없음 + imageUrl 은 사용자 업로드 그대로 echo

위 8 케이스가 VisionCommentServiceTest · AiChatServiceTest 두 클래스에 들어있어요. 단위 테스트 본문은 코드베이스에서 직접 열어보세요.

⑩ 면접관을 홀리는 한 줄

"입력 모달리티가 한 가지 자라면 출력 합성 방식도 한 단계 다르게 들어간다 — 셀카는 이미지를 출력 자산으로 추가, 비전은 이미지를 입력의 한 가지로 받고 응답 합성을 대체. 같은 도메인 안의 다른 두 방식을 대칭으로 정리하면, Day 9 의 오디오 입력 주제가 자랄 때도 같은 방식의 한 단계가 자연스럽게 따라옵니다."

8. 💡 튜터의 결론 — Step 5 한 줄

"Multipart 한 장이 /uploads/portraits/upload-xxx-1714500000000.png 같은 URL 모양 으로 들어간다. Step 4 의 describe(imageUrl, prompt) 가 그 URL 한 줄을 그대로 받아 다음에서 캐릭터의 첫 마디로 흘러갈 거예요. URL 입력과 업로드 입력 — 두 통로가 결국 같은 입구 로 모이는 진행이 익히셨어요. 그리고 후속 결합 작업 으로 그 URL 한 줄이 POST /api/chat 의 옵션 필드 로 한 단계 더 들어가, 사용자 업로드 → 캐릭터 코멘트 prod 결합 부분까지 같은 Day 안에 닫혔어요."

자, URL 화 어댑터 하나 + prod 결합 한 단계 가 익혀졌어요. Day 7 의 portrait URL 도, 사용자가 방금 업로드한 셀카도.

같은 모양의 URL 한 줄 로 변환돼서 VisionChatService.describe(...) 의 첫 인자로 흘러들어가고, 동시에 AiChatRequest.imageUrl 한 옵션 필드 로 채팅 도메인에 잡혀요. 두 통로가 한 입구로 모이는 + prod 결합 한 단계 의 클로저 점, 들어갔습니다.

다음 Step 에선 — 진짜 클로저 가 닫혀요. 지난 시간 Day 7 에서 만든 캐릭터 portrait 한 장을 오늘의 ChatModel 에게 보여주면, 그 캐릭터가 자기 자신을 보고 첫 마디를 건네는. 생성 → 인식 → 대화 의 세 형태이 한 부분에 모여 닫히는 부분이에요. Step 6 에서 만나요.

자, 드디어 — 오늘의 시그니처 부분 에 도착했어요.

Step 1 부터 Step 5 까지 손에 정리한 다섯 주제를 한 줄씩 떠올려 봅시다.

모델 라인업 + 비용 감각 (Step 1), Media · MimeType · 세 통로 (Step 2), UserMessage.builder() 의 빌더 부분 (Step 3), VisionChatService.describe(imageUrl, prompt) 의 8 줄 핵심 (Step 4),.

MultipartFile → publicPath URL 화 어댑터 (Step 5). 다섯 주제가 전부 합쳐져 — 오늘 이 한 부분 에서 다시 만나요. Day 7 에서 만든 portrait URL 한 줄이, 오늘의 입력으로 그대로 흘러 캐릭터의 첫 자기소개 텍스트로 돌아오는. 생성 → 인식 → 대화 의 세 형태 중 —

지난 시간 → 오늘의 매끈한 이음새 가 익숙해지는 부분이에요.

1. 첫 주제 — Day 7 portrait 의 클로저, 지난 시간의 출력이 오늘의 입력으로

먼저 — 지난 시간 Day 7 의 결과물 을 한 번만 다시 떠올려 봅시다. 사용자가 "a cute pink rabbit, anime style" 같은 prompt 한 줄을 던지면.

Pollinations.ai 가 portrait 한 장을 그려주고, ImageFileStorageService.save(...) 가 그 바이트를 /uploads/portraits/portrait-xxx-1714500000000.jpg 같은 publicPath URL 한 줄로 정리해줬어요.

그리고 그 URL 이 Soulmate.characterImageUrl 필드 에 잡혀.

캐릭터 카드의 한 자리 에 영구히 머물고 있는 모양이에요.

오늘 Step 6 의 미션은 — 그 URL 한 줄을 VisionChatService.describe(...) 의 첫 인자로 그대로 흘려보내는 거예요.

지난 시간 들어간 URL 의 한 글자도 변경하지 않고, 한 번도 재인코딩하지 않고, 단순히 DB 에서 꺼내서 → 메서드 인자에 흘려넣는 패턴.

지난 시간의 출력이 오늘의 입력이 되는 매끈한 이음새.

Day 7 마무리에서 약속드렸던 그 클로저 점 부분이에요.

이 결정이 왜 자연스러운가 — 한 줄로 정리할게요. Soulmate.characterImageUrl 은 이미 Spring Boot 정적 리소스 핸들러 가 서빙하는 URL 이라.

외부에서 GET 으로 받을 수 있는 부분이에요. Step 4 의 describe(imageUrl, prompt) 가 외부 호스팅 URL 을 받아내는 방식으로 들어갔으니, 우리 서버의 /uploads/portraits/... 경로도 그 입구를 그대로 통과 해요.

별도 변환 없음, 별도 다운로드 없음, 별도 base64 인코딩 없음. 매끈한 부분예요.

2. 두 번째 주제 — 왜 서비스 한 부분를 새로 박는가, VisionChatService 한 번 더 한 층 위에서

여기서 한 가지 결정이 펼쳐져요. CharacterVisionService 라는 새 서비스 하나 를 정리한다. Step 4 의 VisionChatService 옆에 한 층 위 의 부분을 한 부분 더 두에요.

왜 한 단계를 더 두는가 — 두 서비스의 책임을 짚어볼게요.

VisionChatService (Step 4 의 부분) — 순수 어댑터 예요. URL 한 장 + prompt 한 줄을 받아서 텍스트 한 줄 을 돌려주는 자리. 도메인을 모르는 부분이에요. Soulmate 가 뭔지, 캐릭터가 뭔지, DB 가 어디에 있는지 —

전혀 모르는 얇고 단순한 클래스. 모델 호출 하나 + Media 빌더 + UserMessage 빌더만 알아요.

CharacterVisionService (Step 6 의 부분) — 그 위 한 단계. 캐릭터 도메인을 알고 있는 부분 예요. 캐릭터 ID 를 받아서.

DB 에서 Soulmate 엔티티를 조회하고, portrait URL 을 추출하고, 캐릭터의 성격 · 취미가 들어간 prompt 를 조립하고, VisionChatService 에 위임 해서 응답을 받아내고, DTO 로 포장 해서 돌려주는 자리. 오케스트레이션 한 부분.

이 책임 분리의 패턴 은 — 본 강의에서 이미 한 번 들어간 곳이 있어요.

Day 5 의 ChatService ↔ ChatMemoryAdvisor 분리. ChatMemoryAdvisor 는 메모리 자체만 책임지는 얇은 어댑터, ChatService 는 대화의 오케스트레이션 을 책임지는 한 층 위의 서비스. 같은 패턴이 Vision 도메인에서 한 번 더 다시 만나요.

어댑터 vs 도메인 오케스트레이션 — 이 두 자리를 분리해 두는 게, 학생이 "저 클래스가 왜 저기 있는가" 를 익히기 쉬운 모양이에요.

💡 튜터의 결론 — 왜 두 서비스를 분리했는가

어댑터 와 오케스트레이션을 한 클래스에 섞어 두면 — 테스트가 무거워지고, 재사용이 어려워지고, 도메인이 바뀔 때마다 어댑터까지 함께 흔들려요. 본 강의는 두 책임을 분리해서 — VisionChatService 는 다른 도메인 (예: 외부 이미지 검색 결과 분석) 에서도 그대로 재사용 가능하고, CharacterVisionService 는 캐릭터 도메인에서만 도는 모양. Single Responsibility 가 익숙해지는 부분 이에요.

3. 세 번째 주제 — CharacterVisionService 한 화면, 5 줄 핵심 + prompt 조립

자, 이제 클래스 본문을 펼쳐볼게요. CharacterVisionService 의 핵심 메서드 introduce(...) 한 화면이에요.

@Slf4j
@Service
public class CharacterVisionService {

    private final SoulmateRepository soulmateRepository;
    private final VisionChatService visionChatService;

    public CharacterVisionService(SoulmateRepository soulmateRepository,
                                  VisionChatService visionChatService) {
        this.soulmateRepository = soulmateRepository;
        this.visionChatService = visionChatService;
    }

    @Transactional(readOnly = true)
    public SoulmateIntroductionResponse introduce(Long soulmateId) {
        Soulmate soulmate = soulmateRepository.findById(soulmateId)
                .orElseThrow(() -> new BusinessException(ErrorCode.SOULMATE_NOT_FOUND));

        String portraitUrl = soulmate.getCharacterImageUrl();
        if (portraitUrl == null || portraitUrl.isBlank()) {
            throw new VisionException(ErrorCode.VISION_PORTRAIT_NOT_AVAILABLE);
        }

        String prompt = buildIntroductionPrompt(soulmate);
        String introduction = visionChatService.describe(portraitUrl, prompt);

        log.info("[CharacterVision] introduce: soulmateId={}, name={}, portraitUrl={}",
                soulmate.getId(), soulmate.getName(), portraitUrl);

        return new SoulmateIntroductionResponse(
                soulmate.getId(),
                soulmate.getName(),
                portraitUrl,
                introduction
        );
    }

생성자 + introduce(...) 본문 한 화면. 여기가 오늘의 시그니처 메서드 예요. 네 단락으로 해부할게요.

해부 (1) — @Transactional(readOnly = true) — Day 1~6 의 패턴 회수

@Transactional(readOnly = true)
public SoulmateIntroductionResponse introduce(Long soulmateId) {

이 어노테이션 한 줄 — Day 1 부터 들어간 Soulmate 엔티티 조회 트랜잭션 의 모양 그대로예요. 읽기 전용 플래그 를 정리해서 — JPA 의 dirty checking 을 끄고, 트랜잭션 커밋 시 변경 감지 비용 을 줄여요. 조회만 하고 끝나는 부분 의 표준 모양.

본 메서드는 DB 에 쓰기 작업이 없어요. portrait URL 을 꺼내서, prompt 를 조립해서, 모델한테 던지고, 응답을 DTO 로 포장하는 패턴 — 전부 읽기. readOnly = true 의 영역이에요.

해부 (2) — SoulmateRepository.findById(...).orElseThrow(...) — Day 1 부터 손에 정리한 패턴

Soulmate soulmate = soulmateRepository.findById(soulmateId)
        .orElseThrow(() -> new BusinessException(ErrorCode.SOULMATE_NOT_FOUND));

이 Optional.orElseThrow(...) 의 패턴 은 — Day 1 의 SoulmateService 에서 시작해서 Day 2~7 까지 몇 번이고 다시 등장한 본 강의의 표준 감각 부분이에요.

없으면 도메인 예외 — BusinessException(ErrorCode.SOULMATE_NOT_FOUND).

GlobalExceptionHandler 가 이 예외를 받아서.

404 + ApiResponse.fail(ErrorResponse) 의 표준 에러 응답으로 변환해 줘요.

여기서 — 학생이 새로 외울 게 아무것도 없어요. Day 1 부터 익숙한 패턴 그대로. Vision 도메인이 어렵다는 인상이 있을지 몰라도, 진짜 어려운 건 외부 모델 호출 한 부분뿐 부분이에요. 도메인 예외 · 트랜잭션 · DTO — 전부 익숙해진 패턴 그대로.

해부 (3) — portrait URL null/blank 가드 — Day 7 의 V004 한 부분

String portraitUrl = soulmate.getCharacterImageUrl();
if (portraitUrl == null || portraitUrl.isBlank()) {
    throw new VisionException(ErrorCode.VISION_PORTRAIT_NOT_AVAILABLE);
}

이 3 줄 가드 — Day 7 에서 portrait 을 아직 만들지 않은 캐릭터 를 위한 부분예요.

신규 캐릭터를 방금 막 등록 했는데 Day 7 의 portrait 생성 호출이 아직 안 끝난, 또는 portrait 생성이 실패해서 URL 이 비어 있는 부분 — 이 두 장면에서 VISION_PORTRAIT_NOT_AVAILABLE 이 떨어져요.

왜 BusinessException 이 아니라 VisionException 인가 — Step 5 에서 정리한 Vision 도메인 전용 예외 계열 의 모양 그대로. V001 (이미지 누락) · V002 (잘못된 MIME) · V003 (서버 저장 실패) 옆에 —

V004: VISION_PORTRAIT_NOT_AVAILABLE 한 부분가 들어있어요. Vision 도메인의 진입 실패 4 형제 가 한 부분에 모이에요.

GlobalExceptionHandler 는 VisionException 을 받아서 — 400 + ApiResponse.fail(ErrorResponse(code: "V004", message: "캐릭터에 portrait 이 아직 생성되지 않았습니다",...)) 의 표준 에러 응답으로 변환해요.

학생 코드에 try-catch 한 부분도 박지 않아도 — 자동으로 표준 응답 봉투에 담겨 나가요.

해부 (4) — buildIntroductionPrompt(soulmate) + visionChatService.describe(...) 위임 — 도메인 컨텍스트가 들어간 자연어 한 줄

String prompt = buildIntroductionPrompt(soulmate);
String introduction = visionChatService.describe(portraitUrl, prompt);

이 2 줄 이 — 오늘의 시그니처 호출 부분이에요. portrait URL 한 줄 + 도메인 컨텍스트가 들어간 prompt 한 줄 이 위 켜의 어댑터 에 흘러들어가서 — 캐릭터의 자기소개 텍스트 한 줄로 돌아와요.

buildIntroductionPrompt(...) 의 본문도 한 화면 펼쳐볼게요.

/**
 * 캐릭터 컨텍스트(이름 · 성격 키워드 · 취미)를 박은 자기소개 프롬프트.
 * 학습용 단순도 유지를 위해 SystemMessage 분리 없이 한 덩어리 텍스트로 전달한다.
 */
private String buildIntroductionPrompt(Soulmate soulmate) {
    return "당신은 '" + soulmate.getName() + "' 라는 이름의 캐릭터예요. "
            + "성격: " + soulmate.getPersonalityKeywords() + ". "
            + "취미: " + soulmate.getHobbies() + ". "
            + "이 그림은 당신의 자화상이에요. 그림을 보고 한국어 2~3 문장으로 자기소개해 주세요. 친근한 말투로요.";
}

문자열 한 덩어리 — 캐릭터의 이름 · 성격 키워드 · 취미 세 가지가 한 자연어 문장 안에 잡혀요. 그리고 마지막 한 줄 이 — "이 그림은 당신의 자화상이에요" 라는 결정적인 문장. 모델한테 "이 이미지는 당신 자신 이라는 자기 인식 컨텍스트 를 한 번 던져줘요. 이 한 줄이 빠지면.

모델이 3 인칭 묘사 ("그림 속 캐릭터는 분홍색 토끼이며...") 를 내뱉어요. 한 줄 정리하면 — 1 인칭 자기소개 ("안녕! 나는 분홍색 토끼야...") 로 톤이 깨끗이 바뀌어요. prompt 한 줄의 무게예요.

5. 네 번째 주제 — CharacterVisionController 한 줄 위임의 표준 모양

자, 서비스가 들어갔으니 — 그 입구를 HTTP 로 열어주는 부분이에요. 컨트롤러 본문 통째 펼쳐볼게요.

@Slf4j
@RestController
@RequestMapping("/api/vision")
public class CharacterVisionController {

    private final CharacterVisionService characterVisionService;

    public CharacterVisionController(CharacterVisionService characterVisionService) {
        this.characterVisionService = characterVisionService;
    }

    @PostMapping("/characters/{soulmateId}/introduce")
    public ResponseEntity<ApiResponse<SoulmateIntroductionResponse>> introduce(
            @PathVariable Long soulmateId) {
        SoulmateIntroductionResponse response = characterVisionService.introduce(soulmateId);
        return ResponseEntity.ok(ApiResponse.success(response));
    }
}

컨트롤러 한 화면 — 단 12 줄. 세 부분을 짚을게요.

첫째, POST /api/vision/characters/{soulmateId}/introduce — body 없음, path variable 만. 캐릭터 ID 하나만 받으면 —

그 캐릭터의 portrait URL 은 이미 DB 에 들어가 있으니까 추가 입력이 필요 없어요. 호출자 입장에서 가장 단순한 입구. curl -X POST .../1/introduce 한 줄로 트리거돼요.

둘째, ResponseEntity<ApiResponse<SoulmateIntroductionResponse>> — 본 강의의 ApiResponse 래핑 규약 재등장이에요.

Step 5 에서 정리한 VisionUploadController 와 완전히 같은 모양. ResponseEntity.ok(ApiResponse.success(response)) 의 표준 한 줄.

정상 응답 봉투 와 에러 응답 봉투 (GlobalExceptionHandler 가 자동 변환) 가 대칭으로 흘러가는 진행이 — Day 8 의 모든 컨트롤러에서 일관되게 들어있어요.

셋째, 왜 GET 이 아니라 POST 인가 — 짧게 한 단락 박을게요. 모델 호출은 비용과 부작용이 있는 호출이에요. 호출 한 번 = 토큰 소비 + 쿼터 차감 + 로그 누적. 만약 GET 으로 정리하면.

브라우저 · CDN · 프록시 가 응답을 캐싱 해서, 같은 URL 두 번째 호출이 모델을 안 거치고 캐시에서 떨어지는 부작용 이 생겨요. 그게 우리가 원하는 진행인가 —

아니에요. 모델 호출의 결정성 (매번 새로 호출, 매번 새 응답) 을 보장하려면 POST 가 결정적인. HTTP 메서드 선택이 비용 가드와 직결 되는 부분이에요.

그리고 — SoulmateIntroductionResponse DTO 도 한 화면 펼쳐볼게요.

/**
 * Day 8 Step 6 — 캐릭터 자기소개 응답 DTO.
 *
 * <p>Day 7 에서 생성한 portrait URL 을 Day 8 의 Vision 입력으로 흘려보낸 결과 —
 * 캐릭터가 자기 자화상을 보고 한 자기소개 텍스트를 함께 돌려준다.</p>
 *
 * @param soulmateId   캐릭터 PK
 * @param name         캐릭터 표시 이름
 * @param portraitUrl  Vision 입력으로 사용된 portrait URL
 * @param introduction ChatModel 이 생성한 자기소개 텍스트 (한국어 2~3 문장)
 */
public record SoulmateIntroductionResponse(
        Long soulmateId,
        String name,
        String portraitUrl,
        String introduction
) {
}

record 4 필드. 응답 DTO 의 필요 최소 — 어떤 캐릭터의 (id, name) / 어떤 portrait 을 입력으로 썼는가 (portraitUrl) / 모델이 무엇을 돌려줬는가 (introduction). 호출자가 알아야 할 모든 것 이 4 필드에 들어있어요.

portraitUrl 을 응답에 함께 정리하는 이유.

프론트엔드가 응답을 받자마자 그림 + 자기소개 텍스트를 한 화면에 같이 띄울 수 있도록 하에요. 서버 한 번 호출 → 화면에 필요한 모든 데이터 한 봉투 의 패턴.

6. 다섯 번째 주제 — 통합 시연: curl 한 번 + 응답 모습

자, 모든 부분이 들어갔으니 — 진짜로 돌려보는 부분이에요. Day 7 시나리오 + 오늘 호출 을 한 방식으로 펼쳐볼게요.

시나리오:

지난 시간 Day 7 — 사용자가 "a cute purple cape rabbit, anime style" prompt 를 던져서 쿠로미 라는 이름의 캐릭터가 생성됐다고 가정.

portrait URL /uploads/portraits/portrait-3f1e...-1714500000000.jpg 가 Soulmate(id=1).characterImageUrl 에 들어있어요. 2. 오늘 Day 8 Step 6 — curl 한 줄로 introduce 엔드포인트를 호출. 3. 응답 — Gemini 가 portrait 그림을 시각 토큰으로 변환 해서 읽고, 캐릭터의 성격 · 취미 컨텍스트 와 자화상이라는 자기 인식 prompt 를 결합해서 1 인칭 자기소개 한 덩어리 를 돌려줘요.

curl 한 줄 — body 가 없어서 정말 단순해요.

$ curl -X POST http://localhost:8080/api/vision/characters/1/introduce

응답 봉투 는 이렇게 잡혀요.

{
  "success": true,
  "data": {
    "soulmateId": 1,
    "name": "쿠로미",
    "portraitUrl": "/uploads/portraits/portrait-3f1e...-1714500000000.jpg",
    "introduction": "안녕! 나는 쿠로미야. 까칠하지만 정 많은 성격이고, 음악 듣는 거랑 공포영화 보는 걸 좋아해. 이 그림 속 보라색 망토가 내 트레이드마크야. 잘 부탁해!"
  }
}

이 응답 한 봉투의 의미 — 한 단락 박을게요. portraitUrl 은 지난 시간 Day 7 에서 들어간 그 URL 한 글자도 변하지 않은 부분 예요. 그 URL 이 오늘 Step 4 의 describe(imageUrl, prompt) 의 첫 인자로 그대로 흘러갔고, Gemini 가 그림을 읽어서.

"보라색 망토" 라는 시각 인식 결과 를 자기소개 텍스트에 정리했어요. 이게 Vision 의 진짜 감각 — 그림에 없는 정보를 (캐릭터 이름 · 성격 · 취미는 prompt 에 있고, 보라색 망토라는 시각 정보 만 그림에서 인식) 모델이 그림에서 직접 읽어내는 부분이에요.

동작 보장 — 이 부분은 코드베이스 CharacterVisionServiceTest (정상 introduce + 3 예외 케이스: 캐릭터 없음 · portrait null · portrait blank) + CharacterVisionControllerTest (200 정상 응답 + 400 V004 에러 응답) 으로 서비스 한 층 + 컨트롤러 한 층 이 검증되어 있어요.

단위 테스트 본문은 코드베이스에서 직접 열어보세요.

7. 💡 튜터의 결론 — Step 6 한 줄

"Day 7 에서 만든 portrait URL 한 줄이 — 오늘 한 번도 변경 없이 VisionChatService.describe(url, prompt) 의 입력으로 흘러간다. 그리고 Gemini 가 그 그림을 보고 캐릭터의 자기소개 텍스트 로 풀어낸다. 생성 → 인식 → 대화 의 세 형태 중 지난 시간 → 오늘의 매끈한 이음새 가 들어갔어요. 다음 Step 에선 이 호출이 비용을 어떻게 가두는지 의 답을 박을 거예요."

자, Day 7 portrait → Day 8 introduce 의 클로저 가 닫혔어요. 지난 시간 들어간 URL 한 줄이 — 오늘 한 글자도 변하지 않고 모델한테 흘러가서, 캐릭터의 1 인칭 자기소개 로 돌아오는. 생성 → 인식 → 대화 의 세 형태 중 두 가지가 한 줄로 이어진 자리 예요.

그런데 — 한 가지가 아직 손에 안 들어있어요. 이 호출이 비용을 어떻게 가두는가. Vision 호출 한 번이 텍스트의 1.5~2 배 비용이라고 Step 1 에서 정리했죠.

만약 학생이 실수로 for 루프 안에 introduce 호출 을 정리해두면 — 100 번 호출 = 텍스트 200 번 호출 분량의 비용이 순식간에 새어나가요.

다음 Step 에선.

호출 횟수 가드 + 동일 입력 캐싱 으로 비용을 가두는 하나 를 정리해봅시다. 학습용에서 운영용으로 한 층 끌어올리는 부분 — Step 7 에서 만나요.

자, Day 8 의 마지막 Step 에 들어왔어요.

Step 6 까지 지난 시간 → 오늘의 클로저 가 매끈하게 닫혔지만 — 비용을 가두는 자루 가 아직 손에 안 들어있어요.

이 부분은 Day 7 에서 한 번 정리한 패턴이 두 번째로 회수 되는 부분이에요.

같은 방식을 Vision 도메인 옆자리 에 한 번 더 정리해두면, 비용 큰 모달리티에 가드를 끼우는 패턴 이 손에 부분을 잡아요.

이번 Step 의 호흡은 단순해요.

VisionDailyQuotaGuard 한 클래스를 정리한다 → CharacterVisionService.introduce(...) 의 첫 줄 에 끼워 넣는다 → 자정 경계까지 검증하는 테스트 4 케이스로 마침표.

그리고 응답 캐싱은 Day 19 Harness 의 부분 라는 진행만 한 줄 비추고 본 Step 에선 가드까지만 정리해둘 거예요.

1. 첫 번째 주제 — Vision 비용의 모양, 텍스트 1.5~2 배가 누적되는 모습

오프닝의 비용 표를 한 번 더 떠올려 볼게요. Vision 1 회 호출 비용 ≈ 텍스트 1 회의 1.5~2 배. 이미지 한 장이 수백~수천 개의 시각 토큰 으로 변환되는 진행이라, 같은 모델을 호출해도 입력 토큰 수가 더 많은 부분이에요.

그런데 — Day 7 의 비용 곡선과 Day 8 의 비용 곡선은이 달라요.

• Day 7 (이미지 생성) — 건당 비용은 큰 한 방 부분이에요. 텍스트 호출의 30~80 배. 대신 호출 빈도가 낮은 부분 — 캐릭터 한 명 만들 때 portrait 한 장만 그리면 끝. 큰 한 방을 가끔 던지는 모양이에요.
• Day 8 (Vision 인식) — 건당 비용은 작아요 (텍스트의 1.5~2 배). 대신 호출 빈도가 훨씬 잦은 부분이에요. 캐릭터마다 자기소개를 부를 수도 있고, 사용자 업로드 사진을 매번 분석할 수도 있고, 대화 도중에 portrait 을 함께 흘려보내는 형태까지 — 작은 호출이 쌓이는 부분이에요.

시나리오 한 부분만 풀어볼게요.

사용자가 100 명, 각자 캐릭터 introduce 를 하루 한 번씩만 호출해도 — 100 회 × Vision 1 회 = 텍스트 호출 약 150~200 회 분량 의 토큰을 소비해요.

Gemini 무료 일일 쿼터 (모델별로 다르지만 대략 1,500 회 분량 의 토큰) 의 1/10 ~ 1/5 가 한 호출 패턴 하나로 소모돼요.

공짜로 보이는 호출이 누적되면 유료 라인 진입 까지 무심코 흘러가는 패턴 — 그게 Vision 의 비용 이에요.

그래서 — 호출 횟수 자체를 가두는 결 이 필요해요. Day 7 에서 정리한 ImageDailyQuotaGuard 와 완전히 같은 결 을 Vision 옆자리 에 한 번 더 정리하는. 두 번째 등장이에요.

2. 두 번째 주제 — VisionDailyQuotaGuard 본문 — Day 7 자매 패턴 그대로

자, 코드 본문 통째 펼쳐볼게요. Day 7 의 ImageDailyQuotaGuard 와 글자 단위로 같은 결이에요. 차이는 단 두 부분만 — 기본 한도 값 과 throw 하는 도메인 예외.

package kr.spartaclub.aifriends.vision.service;

import kr.spartaclub.aifriends.common.exception.ErrorCode;
import kr.spartaclub.aifriends.vision.exception.VisionException;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

import java.time.Clock;
import java.time.LocalDate;

/**
 * Day 8 Step 7 — 일일 Vision (멀티모달 입력) 호출 횟수 가드.
 *
 * <p><b>학습용 단순 모양</b>이라 in-memory + synchronized 로 카운터를 관리한다.
 * 실제 운영에서는 다음 두 한계를 반드시 고려해야 한다:
 * <ul>
 *   <li>인스턴스 다중화: WAS 가 N대면 카운터가 N배 부풀려진다 → Redis {@code INCR} + {@code EXPIRE} 로 공유.</li>
 *   <li>유저별 격리: 지금은 "전체 호출" 한도다 → 운영에서는 {@code key = "vision:quota:{userId}:{yyyyMMdd}"} 로 키 분리.</li>
 * </ul>
 * Vision 호출은 텍스트 LLM 1.5~2 배 비용이 들기 때문에 Day 7 {@code ImageDailyQuotaGuard} 보다
 * 한도를 살짝 작게(기본 20) 잡았다. Day 8 의 학습 목표는 "비용이 큰 모달리티에 가드를 끼우는 패턴"
 * 그 자체이므로 이 단순 구현으로 충분하다.</p>
 */
@Component
public class VisionDailyQuotaGuard {

    private final int dailyLimit;
    private final Clock clock;

    private LocalDate currentDate;
    private int counter;

    public VisionDailyQuotaGuard(@Value("${aifriends.vision.quota.daily-limit:20}") int dailyLimit) {
        this(dailyLimit, Clock.systemDefaultZone());
    }

    /**
     * 테스트 한정 — Clock 을 외부에서 주입해 자정 경계 시나리오를 검증할 수 있게 한다.
     */
    VisionDailyQuotaGuard(int dailyLimit, Clock clock) {
        this.dailyLimit = dailyLimit;
        this.clock = clock;
        this.currentDate = LocalDate.now(clock);
        this.counter = 0;
    }

    /**
     * 호출 횟수를 1 증가시키고, 한도를 넘기면 {@link VisionException} 을 던진다.
     * 자정을 넘기면 카운터가 자동으로 0으로 리셋된다.
     */
    public synchronized void checkAndIncrement() {
        LocalDate today = LocalDate.now(clock);
        if (!today.equals(currentDate)) {
            currentDate = today;
            counter = 0;
        }
        if (counter + 1 > dailyLimit) {
            throw new VisionException(ErrorCode.VISION_QUOTA_EXCEEDED);
        }
        counter++;
    }

    /**
     * 현재 사용량 (디버깅/관리 엔드포인트 노출용 — 학습용으로 두지만 노출은 신중히).
     */
    public synchronized int currentCount() {
        return counter;
    }
}

Day 7 의 ImageDailyQuotaGuard 와 비교 해보면 — 클래스 골격, 두 생성자 (운영용 + 테스트용 Clock 주입), synchronized checkAndIncrement(), 자정 경계 자동 리셋, currentCount() 디버그 메서드 —

모든 부분이 같은 모양 이에요. 한 번 정리한 패턴은 다음 도메인에서 그대로 재사용 하는 진행이에요.

💡 왜 한도를 20 으로 잡았는가 — Image 30 보다 작은 결정 근거

Day 7 의 ImageDailyQuotaGuard 는 기본 30 이었어요. 오늘 Vision 가드는 기본 20. 더 작은 이에요. 두 가지 이유가 들어있어요.

첫째, Vision 호출의 건당 비용이 1.5~2 배 더 비싸다. Day 7 그림 생성은 Pollinations.ai 무료 어댑터 였어서 비용이 0 이었지만, Day 8 Vision 은 Gemini 무료 티어 일일 쿼터 를 실제로 차감해요. 같은 호출 횟수 한도 라도 Vision 쪽이 쿼터를 더 빨리 소진 하는 모양이에요.

둘째, Vision 호출 빈도 자체가 더 잦은 패턴이에요. Day 7 은 캐릭터 생성 시점에만 한 번 호출되고, Day 8 은 introduce · upload · (다음 Day 들에서 추가될) 사진 분석 등 여러 입구가 모두 Vision 모델을 거쳐가요. 호출 빈도가 잦은 만큼 한도를 살짝 더 깐깐하게. 두 방식이 만나는 지점에서 30 → 20 의 결정이 들어갔어요.

물론 — 학생 본인 프로젝트의 사용 패턴 에 따라 application.yml 의 aifriends.vision.quota.daily-limit 한 줄로 얼마든지 조정 가능 한 부분예요. 기본값은 본 강의 시연 시나리오에 맞춘 결 이라는 점만 기억해주세요.

⚠ 운영 확장의 패턴 — 학습용 단순 모양 의 한계

이 가드는 — 학습용 단순 모양 이라 세 부분가 운영에 못 미쳐요. 한 단락씩 짚을게요.

첫째, synchronized + in-memory 카운터. 단일 JVM 인스턴스에서만 동작해요. WAS 가 N 대로 다중화 되면 카운터가 N 배 부풀려져요 — 인스턴스 1 에서 10 회, 인스턴스 2 에서 10 회 호출이 박히면 합계 20 회를 호출했는데도 두 인스턴스 모두 한도 미만(인스턴스별 10 회)으로 인식 해요. 운영 부분 에선 — Redis INCR + EXPIRE 로 모든 인스턴스가 같은 카운터를 공유 하는 방식으로 끌어올려야 해요. Day 5 에서 정리한 Redis 인프라 가 거기에 그대로 흘러갈 수 있어요.

둘째, 유저별 격리가 없어요. 지금은 전체 호출 한도 라 — 한 명의 사용자가 한도를 다 써버리면 다른 사용자는 호출을 못 해요. 운영 부분에선 — 키를 vision:quota:{userId}:{yyyyMMdd} 로 분리 해서 각 사용자에게 개별 한도 를 주는 진행이 정석이에요. 학습 단순도에선 하나로 충분 하지만, 사용자 격리가 빠진 부분라는 점은 의식해두세요.

셋째, 시간 윈도우의 형태. 지금은 고정 자정 리셋 (fixed window) 방식이에요. 자정 직전에 한도를 다 쓰고 자정 직후에 또 다 쓰면 — 1 분 간격으로 2 배 호출 이 가능한 자리예요. 운영에선 — sliding window (지난 24 시간 기준) 또는 token bucket (시간당 N 회 충전) 패턴이 더 깐깐이에요. Spring Cloud Gateway 의 RedisRateLimiter 같은 곳에 이런 패턴이 들어있어요.

이 세 부분는 — Day 19 Harness 엔지니어링 에서 Spring AI 의 Rate Limit 추상화와 함께 다시 만나요. 본 Step 에선 학습용 단순 모양 까지가 끝이에요.

3. 세 번째 주제 — CharacterVisionService.introduce 의 첫 줄 — 가장 위에서 거르는 결

자, 가드 클래스가 들어갔으니 — 어디에 끼워 넣을 것인가 의 영역이에요. CharacterVisionService.introduce(...) 의 첫 줄 에 정리해요. 변경된 의존성과 메서드 첫 줄을 펼쳐볼게요.

@Slf4j
@Service
public class CharacterVisionService {

    private final SoulmateRepository soulmateRepository;
    private final VisionChatService visionChatService;
    private final VisionDailyQuotaGuard quotaGuard;

    public CharacterVisionService(SoulmateRepository soulmateRepository,
                                  VisionChatService visionChatService,
                                  VisionDailyQuotaGuard quotaGuard) {
        this.soulmateRepository = soulmateRepository;
        this.visionChatService = visionChatService;
        this.quotaGuard = quotaGuard;
    }

    @Transactional(readOnly = true)
    public SoulmateIntroductionResponse introduce(Long soulmateId) {
        quotaGuard.checkAndIncrement();

        Soulmate soulmate = soulmateRepository.findById(soulmateId)
                .orElseThrow(() -> new BusinessException(ErrorCode.SOULMATE_NOT_FOUND));

        String portraitUrl = soulmate.getCharacterImageUrl();
        if (portraitUrl == null || portraitUrl.isBlank()) {
            throw new VisionException(ErrorCode.VISION_PORTRAIT_NOT_AVAILABLE);
        }

        String prompt = buildIntroductionPrompt(soulmate);
        String introduction = visionChatService.describe(portraitUrl, prompt);

        // ... (이하 Step 6 와 동일 — log + return SoulmateIntroductionResponse)
    }
}

변경된 부분 는 세 곳 부분이에요.

첫째, 필드 한 부분 추가 — private final VisionDailyQuotaGuard quotaGuard;. 두 자매 의존성 (SoulmateRepository, VisionChatService) 옆에 세 번째 부분 가 들어갔어요.

둘째, 생성자 인자 한 부분 추가 — Spring 이 생성자 주입 으로 자동으로 빈을 넣어줘요. @Component 가 들어있어서 컴포넌트 스캔으로 자동 등록돼요.

셋째 — 진짜 핵심 부분 — introduce(...) 메서드의 첫 줄. quotaGuard.checkAndIncrement(); 한 줄이 모든 다른 코드 위에 잡혀요. 이 한 자리의 결정이 오늘 Step 7 의 시그니처 예요.

왜 첫 줄 인가 — 한 단락 풀어드릴게요. introduce(...) 안에는 비용이 있는 부분가 세 곳 부분이에요.

1. soulmateRepository.findById(soulmateId) — DB 조회 비용 (작지만 0 은 아님).
2. portraitUrl 검증 — null/blank 가드 — 비용 거의 없음.
3. visionChatService.describe(portraitUrl, prompt) — 오늘의 진짜 비싼, Vision 모델 호출.

가장 비싼 부분은 3 번이에요. 그러면 3 번 직전 (visionChatService 호출 직전) 에 가드를 박을 수도 있어요. 대안 패턴 부분이에요. 그런데 학습용 단순도의 결정 은 — 가장 위 (메서드 첫 줄) 에 정리하는 거예요. 두 방식이 다른 형태을 만들어요.

• 모델 호출 직전에 정리하면 — 모델 호출만 가두지만 DB 조회 횟수는 못 막아요. 한도 초과 후에도 DB 조회는 계속 돌아가는.
• 메서드 첫 줄에 정리하면 — 모든 비용 부분을 하나로 가둬요. 한도 초과 시 DB 조회조차 안 돌아가요. 광범위한 보호.

본 강의는 학습 단순도 + 광범위한 가드 의 방식으로 첫 줄 을 선택했어요. 프로덕션 부분 에선 — 모델 호출 직전에 정리하는 방식 이 더 적절한 시나리오도 있어요 (예: DB 조회 결과로 가드 조건이 분기되는 부분). 각자의 선택.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "success": false,
  "error": {
    "code": "V005",
    "message": "Vision 호출 일일 한도(20회)를 초과했습니다",
    "timestamp": "2026-04-30T15:23:00Z"
  }
}

5. Step 7 끝맺음 — 가드 동작 보장 + Clock 주입 패턴 노트 ✅

이 부분의 동작 보장은 코드베이스의 11 개 그린 테스트 로 검증돼요.

• VisionDailyQuotaGuardTest — 4 케이스 (한도 미만 증가 · 정확히 한도 통과 · 초과 시 V005 · 자정 경계 리셋)
• CharacterVisionServiceTest — 5 케이스 (정상 introduce + 4 예외 케이스로 quota 초과 포함)
• CharacterVisionControllerTest — 2 케이스 (200 정상 / 400 V004)

가드 단독 + 서비스 통합 + HTTP 응답 봉투까지 세 층이 검증돼요.

💡 Clock 주입 패턴 — 시간 부작용을 외부 의존성으로 추상화하는 Spring 패턴

한 가지 짚고 갈 패턴 — VisionDailyQuotaGuard 의 생성자가 Clock 을 받아요. Day 1~7 까지 한 번도 안 들어간 패턴 인데, 오늘 처음 등장했어요.

LocalDate.now() 직접 호출은 — 코드가 시스템 시계에 강하게 묶이는 부분이에요. 운영 부분에선 충분히 돌아가지만, "내일 시점에서 어떻게 동작할까" 같은 가설을 검증하기가 깔끔하지 않아요.

LocalDate.now(clock) + Clock 주입은 — 시간이라는 부작용을 외부 의존성으로 추상화 하에요. 운영에선 Clock.systemDefaultZone() 빈이 진짜 시계로 흐르고, 별도 시점 검증이 필요한 부분에선 Clock.fixed(Instant.parse("2026-04-30T23:59:00Z"), ZoneOffset.UTC) 같은 고정 시계 로 갈아끼울 수 있어요. 같은 코드, 다른 시계. Spring 의 의존성 주입 철학이 시간이라는 부작용에도 그대로 적용되는 부분이에요.

이 패턴의 자매들 — Random random (시드 고정), UUID Supplier (결정적 ID 발급), Environment env (프로파일 분기). 손에 한 번 정리해두면 — Day 11 (Tool Calling) 부터 등장하는 부분들에서 다시 만나요.

6. 다섯 번째 주제 — 응답 캐싱의 부분 — Day 19 Harness 의 예고로만

자, 가드까지 들어갔으니 — 비용 가두는 자루 의 반쪽 이 들어갔어요. 나머지 반쪽 은 — 응답 캐싱 부분이에요. 본 Step 에선 예고만 박고 본격 구현은 Day 19 까지 한 줄도 박지 않아요. 한 단락만 짚고 갈게요.

응답 캐싱의 결 은 — 같은 입력에 같은 출력이 반복되는 곳에서 모델 호출 자체를 건너뛰는 패턴이에요. 시나리오 하나만 펼쳐볼게요. 사용자가 같은 캐릭터의 introduce 를 1 시간 안에 5 번 호출한다면.

(soulmateId=1, portraitUrl="/uploads/portraits/portrait-3f1e...-1714500000000.jpg") 라는 동일한 입력 조합 이 5 번 들어와요.

매번 모델을 호출하면 비용 5 배, 응답도 대부분 비슷한 텍스트 가 나와요.

5 번 중 4 번은 캐시에서 내리는 결이 비용 가드의 자매 자루.

Spring 에서 이 방식을 정리하는 표준 모양 은 — @Cacheable 어노테이션 한 줄 + Caffeine 같은 인메모리 캐시 라이브러리 한 부분에요. 예시 모양 만 정리할게요 — 지금 코드베이스에는 박지 않은 부분 라는 점, 명시할게요.

// ⚠️ 시연용 예시 — 본 코드베이스에는 박혀 있지 않은 자리
// Day 19 Harness 엔지니어링에서 정식으로 다룬다
@Cacheable(value = "visionIntroductions", key = "#soulmateId")
@Transactional(readOnly = true)
public SoulmateIntroductionResponse introduce(Long soulmateId) {
    quotaGuard.checkAndIncrement();
    // ... 이하 동일
}

이 한 줄 어노테이션이 박히면 — Spring 이 visionIntroductions 캐시에 soulmateId=1 키로 저장 해뒀다가, 같은 호출이 또 들어오면 메서드 본문을 아예 안 거치고 캐시 값을 돌려줘요. 5 회 호출 → 모델 호출 1 회 + 캐시 히트 4 회 의 모양이에요.

비용은 1/5, 응답 지연은 밀리초 단위로 떨어져요.

하지만 — 이 부분에는 결정해야 할 부분들이 더 있어요. 캐시 TTL (1 시간? 1 일?) / 캐시 무효화 (캐릭터 정보가 바뀌면 어떻게?) / 캐시 키 설계 (soulmateId 만? portraitUrl 함께?) / 분산 캐시 (인스턴스 다중화) 등.

각각이 한 묶음의 트레이드오프 라, Day 19 Harness 엔지니어링 에서 Spring AI Agent Client + Caffeine + Redis 캐시 추상화와 함께 한 부분에 모아서 다룰 거예요.

Day 19 복선 — Harness 엔지니어링 에서 모이는 4 가지 패턴

Day 19 의을 오늘에서 살짝 비춰볼게요. Harness 엔지니어링은 AI 호출의 운영 안전망 을 한 묶음으로 다루는 부분이에요. 4 가지 패턴이 한 도시에 모여요.

1. 가드 (Rate Limit / Quota) — 오늘 정리한 VisionDailyQuotaGuard 의 운영급 진화형. Spring AI 의 선언적 Rate Limit 추상화로 한 줄로 정리되는 방식.
2. 캐싱 (Response Cache) — 본 Step 에서 예고만 한 부분. @Cacheable + Caffeine + Redis 의 세 켜 가 한 부분에 모여요.
3. 리소스 격리 (Bulkhead / Circuit Breaker) — Vision 모델이 다운돼도 다른 호출이 영향을 안 받는 방식. Resilience4j 같은 부분.
4. 속도 제한 (Token Bucket / Sliding Window) — 시간당 N 회 충전 형태의 더 깐깐한 윈도우 패턴.

이 4 가지가 Spring AI 의 한 층 위 추상화 로 들어있어서 — Day 14 에서 손으로 짠 가드레일 (maxIterations · 타임아웃 · 토큰 예산 · 툴 호출 횟수 제한) 이 Day 19 에선 선언적으로 한 줄로 처리 되는을 만나요. 손으로 한 번 짜본 손이 추상화의 진짜 가치 를 알아보는 부분이에요. Day 19 까지 단단히 손에 정리해두고 만나요.

7. 💡 튜터의 결론 — Step 7 한 줄

"VisionDailyQuotaGuard.checkAndIncrement() 한 줄이 Day 7 자매 패턴 그대로 들어갔다. 비용 큰 모달리티에 가드를 끼우는 결이 두 번째로 들어간 곳. 그리고 응답 캐싱은 Day 19 Harness 의 자리 — 오늘은 가드까지만, 캐싱은 그때 함께 다시 만나요."

자, Day 8 의 마지막 주제가 닫혔어요.

지난 시간 정리한 ImageDailyQuotaGuard 와 같은 방식의 가드를 Vision 옆자리 에 한 번 더 박았고, CharacterVisionService.introduce(...) 의 첫 줄 에 끼워 넣었고, 자정 경계까지 검증하는 4 케이스 테스트 가 그린 으로 들어갔어요.

비용 큰 모달리티에 가드를 끼우는 패턴 이.

Day 7 첫 박힘 → Day 8 두 번째 등장 으로 손에 단단히 자리를 잡았어요.

그리고 — 응답 캐싱은 Day 19 Harness 엔지니어링의 부분 라는 복선 한 줄 도 함께 심어뒀어요. 가드 / 캐싱 / 리소스 격리 / 속도 제한의 4 가지 harness 패턴 이 한 도시에 모이는. Day 14 에서 손으로 짠 가드레일이 Day 19 에서 추상화 한 줄로 풀리는 — 그때 다시 만나요.

이제 — Day 8 의 모든 Step 이 끝났어요. 멀티모달 입력의 세 단어 (Media / MediaContent / UserMessage.builder()) 부터 지난 시간 → 오늘의 클로저 까지, 그리고 비용 가드의 두 번째 등장 까지. 한 번 호흡을 가다듬고 — 마무리에서 만나요.

1. 오늘의 여정 한눈에 — 익힌 여덟 주제

Day 8 의 3 시간을 한 문장으로 요약하면 — "캐릭터에게 눈 을 달아준 하루 — ChatModel 이 사실 멀티모달 추상화 였다" 였어요.

지난 시간 Day 7 에서 AI 화가에게 그림 의뢰하는 부분 를 익힌 손이, 오늘 그 그림을 다시 ChatModel 에게 보여주는에서 — 생성 → 인식 → 대화 의 클로저를 닫았어요.

지난 시간의 출력 (portrait URL) 이 오늘의 입력으로 매끈하게 흘러가요.

같은 인터페이스 가 반대 방향 도 받아낸다는 진행이 — 손에 단단히 들어왔어요.

오늘 익힌 여덟 주제 를 한 줄씩 묶을게요. (마지막 한 가지는 후속 결합 작업 으로 들어온 prod 결합 부분이에요 — Day 7 셀카 prod 의 대칭.)

이 여덟 개를 다 외우라는 게 아니에요.

"ChatModel 은 사실 멀티모달 추상화였다 — UserMessage.builder() 안에 텍스트 + Media 를 함께 담으면 그림을 보고 답하는 모드가 열린다" 와 "지난 시간의 출력 (portrait URL) 이 오늘의 입력으로 매끈하게 흘러가는 — 생성 → 인식 → 대화 의 클로저" 두 문장만 3 개월 뒤에도 기억하시면 오늘 수업은 성공이에요.

💡 Day 8 의 한 문장 요약

"ChatModel 은 텍스트 모델이 아니라 멀티모달 추상화 였다. Day 2 에서 손에 정리한 프로바이더 추상화 가, 오늘 모달리티 추상화 의 방식으로 한 층 위로 풀렸다. 같은 인터페이스 위에서 — 텍스트도, 이미지 입력도, 같은 빈으로 호출된다는."

lab → prod 흡수 보존 — 같은 Day 안에 닫히는 두 부분 (Day 7 패턴 반복 회수)

Day 7 에서 셀카 prod 결합 (Step 8 5트랙 외모 + Step 9 챗 셀카) 두 자리가 같은 Day 안에 lab → prod 흡수를 닫는 첫 사례로 들어갔어요. Day 8 도 같은 방식의 두 자리가 잡혀요:

• Step 6 — Day 7 portrait 재등장 prod: CharacterVisionController.introduce 가 AI 가 만든 portrait URL 을 다시 ChatModel 에게 보여줘 캐릭터의 첫 자기소개 텍스트를 받는. 생성 → 인식 → 대화 의 클로저.
• Step 5 후속 — 사용자 업로드 prod: AiChatRequest.imageUrl 옵션 한 줄 + VisionCommentService 한 단계로 POST /api/chat 이 사용자 업로드 사진을 받는 형태. Day 7 셀카 prod (자동 키워드 매칭) 의 대칭 — 비전은 명시적 첨부 분기.

두 자리가 같은 도메인 (chat) 안에 다른 두 방식 으로 잡혀요. 입력 모달리티가 생성 자산 (Day 7) 이냐 사용자 자산 (Day 8) 이냐에 따라 책임 분리 한 단계 (SelcaService / VisionCommentService) 가 대칭으로 자라는 모양이에요. 이 패턴이 Day 9 (오디오) · Day 10 (영상) · Day 11 (Tool Calling) 에서도 반복으로 다시 만나요 — 모달리티 한 가지가 자랄 때마다 책임 분리 한 단계 가 따라 자라요.

2. Day 9 (음성) 복선 — 눈 다음의 귀와 입

자, 오늘의 마지막 주제이자 다음 시간의 첫 글자.

오늘 우리는 — 캐릭터에게 눈 을 달았어요. Media 입자에 portrait URL 이 들어가 흘러들어가면 — 캐릭터가 그림을 보고 텍스트로 답을 건네는이었죠. 입력 모달리티가 텍스트 한 줄에서 텍스트 + 이미지로 늘어난 첫.

다음 시간은 — 그 다음 모달리티 가 펼쳐져요. 눈 다음의 귀와 입.

다음 시간에 만날 그림은 — 마이크 → STT → ChatClient → TTS → 스피커 의 5 단 파이프라인이에요.

사용자가 마이크에 대고 말하면 — 그 음성이 텍스트로 변환되고 (STT, Speech-to-Text), ChatClient 가 답변 텍스트를 만들고, 그 텍스트가 다시 음성으로 합성 돼서 (TTS, Text-to-Speech) 스피커에서 흘러나오는.

대화의 모든 입출력이 음성으로 흐르는 부분이에요.

핵심 키워드 미리 던져둘게요.

• STT (Speech-to-Text) — OpenAI Whisper API, Gemini Audio, 로컬 무료 옵션 whisper.cpp. 마이크 입력 → 텍스트 의 변환.
• TTS (Text-to-Speech) — OpenAI TTS, Gemini TTS, 무료 대안 edge-tts / 브라우저의 SpeechSynthesis Web API. 텍스트 → 음성 합성.
• 파이프라인 — 브라우저 MediaRecorder 로 음성 녹음 → 백엔드 /api/voice/transcribe 에서 STT → ChatClient 호출 → /api/voice/speak 에서 TTS → 음성 응답을 브라우저가 재생.

오늘과 같은 패턴으로 — 프로바이더 추상화 도 다시 만나요.

STT/TTS 도 Spring AI 가 TranscriptionModel / SpeechModel 같은 자매 추상화 로 정리해두고 있어서, 어느 프로바이더로 갈지 의 결정만 .env 한 줄로 끝나요.

Day 2 의 감각이 세 번째 모달리티 에서도 그대로 살아있어요.

💡 Day 9 클로저 한 줄

"오늘 눈 을 달았으면, 다음 시간엔 귀와 입 을 달 차례. 캐릭터가 사용자의 목소리를 듣고 자기 목소리로 답하는 — 대화의 모든 입출력이 음성으로 흐르는. Day 9 에서 만나요."

오늘 손에 정리한 다섯 가지를 내 손에서 한 번 더 펼쳐보는 부분이에요.

• ChatModel 의 멀티모달 입구
• Media / MediaContent / UserMessage.builder() 세 단어
• MultipartFile 업로드 → 정적 URL
• CharacterVisionController 의 생성 → 인식 → 대화 클로저
• VisionDailyQuotaGuard + Clock 주입

오늘 만든 두 컨트롤러를 결합 하는 방식, 멀티 이미지 비교 의 새 패턴, 프로바이더 추상화의 마지막 회수 까지 — 세 가지 흐름의 도전 과제를 정리할게요.

[구현 1] 사용자 사진 → 캐릭터 반응 — 두 컨트롤러의 결합 ⭐⭐ 📸

배경 시나리오

ai-friends 의 PM 이 또 한 가지 부탁을 들고 왔어요.

"튜터님, 오늘 만든 사진 업로드 (Step 5) 와 캐릭터가 자기소개를 하는 부분 (Step 6) — 사용자가 보기엔 두 개를 한 번에 하고 싶을 거예요. 사용자가 해변 사진 한 장을 업로드하면, 거기서 내 캐릭터가 그 사진을 보고 한 마디 건네주는. '어머, 바다 진짜 예쁘다! 다음에 같이 가자!' 같은 방식으로요. 그러면 진짜 친구한테 사진 보여주는 느낌이 살 것 같아요."

오늘 만든 두 컨트롤러가 결합 되는 부분이에요. 업로드 → publicPath 받기 → 그 publicPath 를 캐릭터에게 보여주고 한 마디 받기 — 두 단계을 한 엔드포인트 로 묶어내는 모양이에요.

💡 왜 굳이 이 과제를 할까요?

1. 두 서비스의 조합 감각 — 오늘 만든 VisionUploadController 의 처리부와 VisionChatService.describe(...) 두 호출을 한 곳에 묶는 자리. 같은 도메인 (vision) 안의 서비스 조합 이 컨트롤러 한 군데에서 어떻게 풀리는지 손에 잡혀요.

호스트 절대 URL 구성의 첫 감각 — 업로드의 결과는 상대 경로 (/uploads/portraits/upload-xxx.png).

Vision 모델에 흘려보내려면 호스트 절대 URL (http://localhost:8080/uploads/portraits/upload-xxx.png) 로 끌어올려야 해요.

내부 경로 ↔ 외부 모델이 접근할 URL 의을 손으로 만지는. 3. 비용 가드의 세 번째 등장 — Step 7 에서 정리한 VisionDailyQuotaGuard.checkAndIncrement() 가 새 흐름의 첫 줄 에도 들어가야 해요. 비용 가드가 모든 Vision 호출의 입구 에 박히는 패턴이 손에 단단히 박혀요.

✅ 요구사항

1. 새 엔드포인트 — POST /api/vision/characters/{soulmateId}/react

• Content-Type: multipart/form-data
• Part: image (MultipartFile)
• PathVariable: soulmateId (Long)

2. 동작 — 다섯 부분
3. VisionDailyQuotaGuard.checkAndIncrement() 첫 줄에 박기 (한도 초과 시 V005)
4. 업로드 처리 → publicPath (예: /uploads/portraits/upload-...png) 획득
5. 호스트 절대 URL 구성 — http://localhost:8080{publicPath} (학습용은 application.yml 의 host 값을 그대로 박거나 @Value("${aifriends.host:http://localhost:8080}") 로 주입)
6. SoulmateRepository.findById(soulmateId) 로 캐릭터 조회 (없으면 BusinessException)
7. VisionChatService.describe(absoluteUrl, prompt) 호출 → 캐릭터 반응 텍스트 획득
8. prompt 의 모양 — "당신은 '{name}' 라는 캐릭터예요. 성격: {personality}. 사용자가 방금 이 사진을 보여줬어요. 친근한 말투로 한국어 2~3 문장 반응을 해주세요." 같은 형태. 학생이 직접 다듬기.
9. 응답 모양 — ResponseEntity<ApiResponse<SoulmateReactionResponse>>

   record SoulmateReactionResponse(
       Long soulmateId,
       String name,
       String uploadedImagePath,   // 업로드 결과의 publicPath (상대 경로)
       String reaction              // 캐릭터의 반응 텍스트
   ) {}

5. 새 컨트롤러 / 새 서비스 분리 — 기존 두 컨트롤러는 한 줄도 수정 금지. 새 CharacterReactController + (선택) CharacterReactService 를 새로 만들어 두 서비스를 조합.
6. 테스트 2 케이스 (필수)

• 업로드 + 반응 통과 — MockMultipartFile 로 이미지 업로드 → ChatModel 모킹으로 반응 텍스트 받기 → 200 응답에 $.data.reaction, $.data.uploadedImagePath 박힘 확인
• 한도 초과 — VisionDailyQuotaGuard 가 한도 초과 상태 → 새 react 호출이 V005 로 차단됨 (./gradlew test --tests "*ReactControllerTest*")

확인 방법

./run.sh up

# 1) 사용자 사진 업로드 + 캐릭터 반응 — 한 번에
curl -X POST "http://localhost:8080/api/vision/characters/1/react" \
     -F "image=@./test-images/beach.jpg"

# 응답:
#  {
#    "success": true,
#    "data": {
#      "soulmateId": 1,
#      "name": "분홍 토끼",
#      "uploadedImagePath": "/uploads/portraits/upload-...png",
#      "reaction": "어머, 바다 진짜 예쁘다! 다음에 같이 가자~"
#    }
#  }

# 2) 한도 초과 시 V005 발동 — quota.daily-limit 을 1 로 낮추고 재시도
curl -X POST "http://localhost:8080/api/vision/characters/1/react" \
     -F "image=@./test-images/sky.jpg"
# 두 번째 호출에서 429 + V005 응답

💡 힌트

• 두 가지 흐름의 조합 선택 — (A) VisionUploadController 의 처리부를 서비스로 추출 해서 (VisionUploadService) 새 컨트롤러에서 재사용하는 방식 (리팩터링 보너스). (B) 새 컨트롤러에서 ImageFileStorageService.save(...) + VisionChatService.describe(...) 두 줄을 직접 호출 하는 방식 (가벼움). 학습 목적이면 (B) 로 시작 → 여유가 되면 (A) 로 한 단계 풀어내기.
• 호스트 절대 URL 의 결 — Vision 모델 (특히 외부 호스팅 Gemini) 이 컨테이너 내부의 localhost 를 못 보는 환경이면 — 호스트 측 IP / 공개 도메인 / ngrok 같은 방식을 동원해야 해요. 본 학습은 Ollama 로컬 시연 이면 host.docker.internal 도 OK. 프로덕션 결 은 공개 CDN 또는 사전 서명 URL — Day 19 에서 다시.
• MultipartFile 검증 재사용 — Step 5 의 ImageFileStorageService.validate(...) 같은 부분가 이미 들어가 있으면 그대로 호출. 없으면 새 컨트롤러에서 size / contentType 검증 한 줄.

제약 / 금지

• 기존 컨트롤러 수정 금지 — VisionUploadController · CharacterVisionController 의 코드를 한 줄도 건드리지 마세요. 중간 합류 학생의 기준 코드 보호.
• ChatModel 직접 구현체 주입 금지 — OpenAiChatModel / OllamaChatModel 같은 구체 타입 X. 인터페이스 그대로.
• 새 ErrorCode 는 V 시리즈 — Vision 도메인의 코드는 V006, V007... 의 방식으로 이어가세요.

[구현 2] 멀티 이미지 비교 — 두 사진을 보고 캐릭터가 코멘트 ⭐⭐⭐🖼

배경 시나리오

같은 PM 이 한 가지 더 들고 왔어요.

"튜터님, 오늘 만든 자기소개 부분 — 캐릭터가 자기 portrait 한 장 만 보잖아요. 사용자가 어제의 portrait 과 오늘 새로 그린 portrait 두 장을 보여주고 '어느 쪽이 더 마음에 들어?' 라고 물어보는 부분도 있으면 좋을 것 같아요. 캐릭터가 둘을 비교 하면서 '음~ 오른쪽이 더 따뜻한 느낌이라 좋아!' 같은 코멘트를 주면 — 사용자가 진짜 친구한테 의견 묻는 감각이 살 것 같아요."

Step 3 에서 UserMessage.builder().media(image1, image2) 의 varargs 를 한 번 짚었어요. 그 패턴의 회수 가 본 과제예요. 한 메시지 안에 이미지 두 장 이 잡혀 비교 가 일어나는 모양을 직접 정리해보는 과제입니다.

💡 왜 굳이 이 과제를 할까요?

1. Media[] varargs 의 첫 감각 — 지금까지 손에 정리한 건 Media 한 장 이었어요. 여러 장 이 한 메시지에 들어가는 부분은 모델의 멀티이미지 처리 능력 이 진짜로 발휘되는 자리. 수능 비교 문제 같은 형태을 모델이 풀어내는.
2. 모델별 멀티이미지 제한의 시점성 — Gemini 2.5 Flash 는 한 메시지당 ~16 장 까지, GPT-4o 는 ~10 장 까지, llava 는 1 장만 같은 식으로 모델별 한도가 다 달라요. 본 과제에선 2~3 장 까지 로 가드를 정리하면서 그 이상은 어떻게 알아내는가 의 결까지 손에 잡혀요.
3. 입력 검증의 도메인 예외 결 — imageUrls 가 비었거나 1 장 이하 면 BAD_REQUEST. Bean Validation (@Size(min=2, max=3)) 이 박힐지, 서비스 첫 줄의 if 분기 가 박힐지의 결정도 학생의.

✅ 요구사항

1. VisionChatService 에 새 메서드 추가 — compare(List<String> imageUrls, String prompt) 또는 기존 describe 의 오버로드 로 추가 (학생 선택)

• 입력 검증: imageUrls 가 2~3 장 이 아니면 도메인 예외 (예: VisionException(VISION_COMPARE_BAD_REQUEST))
• 동작: Media[] 만들기 → UserMessage.builder().text(prompt).media(mediaArray).build() → ChatModel.call(...) → String 응답

2. 새 엔드포인트 — POST /api/vision/characters/{soulmateId}/compare

• Content-Type: application/json
• 요청 Body:

     { "imageUrls": ["http://...", "http://..."] }
     ```
 - 응답: `ResponseEntity<ApiResponse<SoulmateComparisonResponse>>`

 record SoulmateComparisonResponse(
     Long soulmateId,
     String name,
     List<String> imageUrls,
     String comment
 ) {}
 ```

3. 새 ErrorCode — VISION_COMPARE_BAD_REQUEST (V006 정도, status 400)
4. prompt 의 모양 — "당신은 '{name}' 캐릭터예요. 사용자가 두 장의 사진을 보여줬어요. 한국어 2~3 문장으로 둘을 비교해서 코멘트해주세요." 같은 형태.
5. 테스트 2 케이스 (필수)

• 2 장 입력의 정상 흐름 — ArgumentCaptor<Prompt> 로 ChatModel.call(...) 의 인자를 잡아서 — Prompt 의 첫 메시지가 UserMessage 이고, 그 안의 Media 가 2 개 임을 검증
• 1 장 / 0 장 입력의 차단 — VisionException(VISION_COMPARE_BAD_REQUEST) 가 발동되며 400 응답 + V006

확인 방법

./run.sh up

# 1) 두 장 비교 — 어제 portrait + 오늘 portrait
curl -X POST "http://localhost:8080/api/vision/characters/1/compare" \
     -H "Content-Type: application/json" \
     -d '{
           "imageUrls": [
             "http://localhost:8080/uploads/portraits/portrait-aaa.jpg",
             "http://localhost:8080/uploads/portraits/portrait-bbb.jpg"
           ]
         }'
# 응답에 "comment": "음~ 오른쪽이 더 따뜻한 느낌이라 좋아!" 같은 흐름이 박히면 OK 🌸

# 2) 한 장만 보낼 때 — 400 차단
curl -X POST "http://localhost:8080/api/vision/characters/1/compare" \
     -H "Content-Type: application/json" \
     -d '{ "imageUrls": ["http://localhost:8080/uploads/portraits/portrait-aaa.jpg"] }'
# 400 + V006 응답

# 3) 단위 테스트 한 줄
./gradlew test --tests "*VisionChatService*compare*"
./gradlew test --tests "*CompareControllerTest*"

💡 힌트

• Media[] 만들기 — imageUrls.stream().map(url -> Media.builder().mimeType(detectMimeType(url)).data(URI.create(url)).build()).toList().toArray(new Media[0]) 같은 형태. UserMessage.builder().media(mediaArray) 가 varargs 라 배열 spread 가 자연스럽게 잡혀요.
• detectMimeType 헬퍼 재활용 — Step 4 의 VisionChatService 에 들어간 private 헬퍼가 있으면 — 패키지 노출 로 살짝 풀거나 (MimeTypeDetector 같은 새 유틸로 추출), 서비스 안에서 호출 가능한 부분 로 빼기. 두 방식 모두 OK 한 학습 부분이에요.
• 모델별 한도의 결 — Gemini Vision 은 한 메시지당 ~16 장 까지 (2026-04 시점). 본 과제는 2~3 장 으로 학습용 한도. 그 이상의 검증 책임은 모델 측에 위임 하는 결도 OK.

제약 / 금지

• detectMimeType 의 public 노출 강행 금지 — 패키지 노출 또는 유틸로 추출 두 방식 중 하나만. private 을 그냥 public 으로 바꾸지 마세요 (캡슐화 깨짐).
• ChatClient 사용 금지 — Day 11 부터 본격 등장. 오늘 부분은 ChatModel 인터페이스 + Prompt + UserMessage.builder() 방식으로만.
• 모델 라인업 변경 금지 — application.yml 의 gemini-2.5-flash 또는 gemini-2.5-flash-lite 그대로. 멀티이미지 가능 모델이 디폴트로 들어있어요.

[구현 3] 프로바이더 스위칭 — Ollama llava 로 같은 시연 ⭐⭐⭐⭐ 🦙

배경 시나리오

PM 이 마지막으로 한 가지를 부탁해요.

"튜터님, 본 강의 디폴트가 Gemini 2.5 Flash 무료 티어 잖아요. 완전 오프라인 / API 키 없이 시연해야 하는 부분도 있을 것 같아요. 회사 보안 정책상 외부 API 호출이 막힌 망 에서 시연을 해야 한다든지, 전시회 부스 에서 인터넷 없이 시연한다든지. Ollama 의 llava 모델 로 같은 부분를 그대로 돌릴 수 있는지 — 시연만이라도 한 번 정리해주세요."

Day 2 에서 손에 정리한 프로바이더 추상화 의 마지막 회수 부분이에요. .env 한 줄 변경 으로 코드 0 줄 수정 하면서 완전 무료 로컬 시연 까지 풀어내는. 같은 ChatModel 인터페이스 위에서 Gemini 와 Ollama 가 같은 빈처럼 동작 하는 진행을 진짜로 손에 정리해두는.

💡 왜 굳이 이 과제를 할까요?

1. 프로바이더 추상화의 마지막 증명 — Day 2 부터 7 일 내내 들어간 흐름이 마지막 한 번 재등장. .env 한 줄 + ollama pull llava 한 번이 전부 라는 감각이 손에 단단히 잡혀요.
2. 모델별 응답 품질의 직접 체감 — Gemini Flash 의 한국어 응답과 llava 의 (영어 위주) 응답이 같은 prompt 에서 어떻게 갈리는지 를 내 눈으로 비교. 모델 라인업의 현실적 트레이드오프 가 들어와요.
3. 로컬 모델의 운영 감각 — ollama pull llava 의 모델 크기 (~5GB), 첫 호출의 모델 로딩 지연, GPU 가속의 차이 같은 부분이 실무 운영의 그림자 로 잡혀요. Day 9 (음성) · Day 16 (RAG 임베딩) 에서도 비슷한 흐름이 다시 등장.

✅ 요구사항

1. .env 또는 별도 .env.ollama 에 프로바이더 스위칭 한 줄 박기

• SPRING_AI_MODEL_CHAT=ollama (Day 2 의 프로바이더 스위치 키)
• OLLAMA_VISION_MODEL=llava 또는 qwen2.5-vl (vision 가능 모델)
• 기타 Ollama 관련 설정 (예: OLLAMA_BASE_URL=http://host.docker.internal:11434)

2. application.yml 의 ollama 프로파일에 vision 모델 설정 추가

• spring.ai.ollama.chat.options.model: ${OLLAMA_VISION_MODEL:llava} 같은 결

3. 호스트에 vision 가능 모델 미리 풀 받기

   ollama pull llava
   # 또는
   ollama pull qwen2.5-vl

4. VisionChatService 코드 변경 0 — ./run.sh 재기동만으로 풀려야 함
5. 시연 비교 노트 — 같은 캐릭터 / 같은 portrait 으로 POST /api/vision/characters/1/introduce 두 번 호출 (Gemini 모드 1 회 + Ollama 모드 1 회) → 응답 두 부분를 비교한 짧은 후기 1 페이지 작성 (코드는 아니어도 OK)

확인 방법

# 1) Ollama 측 준비 (호스트에서 한 번)
ollama serve &           # Ollama 데몬 기동 (이미 떠 있으면 생략)
ollama pull llava        # 모델 풀 (~5GB, 첫 1 회만)

# 2) Gemini 모드 시연
echo "SPRING_AI_MODEL_CHAT=gemini" > .env.demo
echo "GEMINI_API_KEY=..." >> .env.demo
echo "GEMINI_MODEL=gemini-2.5-flash-lite" >> .env.demo
./run.sh up
curl -X POST "http://localhost:8080/api/vision/characters/1/introduce"
# Gemini 응답 캡처 — 한국어 자기소개 자연스럽게

# 3) Ollama 모드로 갈아끼움
./run.sh down
echo "SPRING_AI_MODEL_CHAT=ollama" > .env.demo
echo "OLLAMA_VISION_MODEL=llava" >> .env.demo
echo "OLLAMA_BASE_URL=http://host.docker.internal:11434" >> .env.demo
./run.sh up
curl -X POST "http://localhost:8080/api/vision/characters/1/introduce"
# Ollama 응답 캡처 — 영어 위주 / 한국어 약함 / 응답 시간 느림 — 비교 노트

💡 힌트

• application.yml 프로파일 분기 — Day 2 에서 정리한 spring.ai.model.chat=ollama 스위치가 그대로 동작해요. vision 옵션 만 ollama 측에 추가하면 됨.
• llava 의 한국어 약함 — 영어 prompt 로 시연 하면 응답 품질이 한 단계 올라가요. 본 강의의 prompt 를 영어 버전 으로 한 줄 추가하는 결도 OK (학습용).
• 첫 호출 지연 — Ollama 가 모델 로딩에 5~30 초 걸려요. 첫 curl 호출에서 timeout 발생하면 두 가지 방법으로 잡아요.
  • application.yml 의 spring.ai.ollama.timeout 을 60s 정도로 늘리기
  • 호출 전 ollama 측에 warm-up 한 번 흘리기 (curl http://localhost:11434/api/generate -d '{"model":"llava","prompt":"hi"}')
• GPU 가속 — Mac M 칩셋이면 Metal 가속이 자동, NVIDIA GPU 면 CUDA 가속. CPU only 면 응답이 수십 초~ 수 분 까지 갈 수 있으니 — 작은 사진 으로 시연하는 게 학습에 좋음.

제약 / 금지

• VisionChatService 코드 수정 금지 — .env + application.yml 만으로 풀려야 추상화의 가치 가 증명돼요. Java 코드 한 줄이라도 건드리면 본 과제의 본질이 깨짐.
• 새 프로바이더 어댑터 작성 금지 — Spring AI 의 OllamaChatModel 이 이미 들어있어요. 새 어댑터를 만들면 Day 7 의 PollinationsImageModel 부분와 섞임.

이 섹션의 목적 — 정답이 정해져 있지 않은 질문들이에요. 오늘 배운 Media 멀티모달 입력 · 비용 가드 · 정적 URL 노출 의 결정들을 한 발 떨어져 바라보고, "왜 이렇게 결정했지?" 와 "다른 길은 없었나?" 를 사고하는 부분이에요. 면접에서도 자주 등장하는 토픽들이라, 가능하면 문장으로 적어보세요. 머릿속 생각과 글로 적은 생각은 다릅니다.

주제 1 — Vision 응답을 ChatMemory 에 저장해야 할까?

Day 5 에서 손에 정리한 JdbcChatMemoryRepository 는 텍스트 대화 을 누적하는 부분였어요. 사용자와 캐릭터가 주고받은 말이 세션 ID 별로 한 줄씩 쌓이고, 다음 대화에 과거 N 개 메시지 가 함께 모델에 흘러들어가는 진행이었죠.

그런데 — 오늘 만든 CharacterVisionController.introduce(...) 의 자기소개 응답 은 ChatMemory 에 저장되지 않아요. 한 번 호출되면 그 텍스트가 응답으로 떨어지고 — 그걸로 끝. 같은 캐릭터의 자기소개를 100 번 호출 해도 ChatMemory 는 아무것도 모르는 상태 그대로예요.

이 부분은 의도된 결정 이지만 — 다른 결도 충분히 합리적 부분이에요. 캐릭터의 자기소개가 대화의 시작점 으로 여겨진다면 — 첫 인사 로 ChatMemory 의 첫 줄에 들어가야 자연스러워요. 이후 사용자의 답변과 문맥이 이어지는. 반대로 자기소개는 캐싱 가능한 정적 응답 이라고 본다면.

ChatMemory 가 아닌 Caffeine / Redis 캐시 에 들어가야 비용 + 응답 시간 이 같이 줄어요.

🎯 핵심 질문 — 같은 캐릭터의 자기소개를 100 번 호출하면 ChatMemory 가 어떻게 변해야 하는가? 사용자가 기억해야 할 정보는 어디이고, 기억하지 않아도 되는 정보의 부분은 어디인가? Vision 응답이 대화의 일부 인지 정적 컨텐츠 인지의 경계는 어떻게 긋는가?

생각해볼 자료:

• Day 5 의 JdbcChatMemoryRepository — 세션 단위 로 메시지가 누적되는 방식. 자기소개도 그 세션의 첫 메시지 로 박힐 수 있을까?
• Day 7 의 portrait 생성 — 그 결과는 DB의 Soulmate.portraitUrl 컬럼 에 들어갔어요. 생성 결과 = DB 의 방식. 오늘의 자기소개도 Soulmate.introduction 컬럼 에 정리하는 진행이 합리적일까?
• Day 19 (Harness) 의 응답 캐싱 부분 — @Cacheable + Caffeine 으로 같은 입력 = 같은 출력 의 패턴. 자기소개가 이 방식으로 가는 게 맞다면 — ChatMemory 와는 완전히 다른 부분 에 들어가야.

주제 2 — URL 기반 Vision 입력의 보안 주의점

오늘 만든 VisionChatService.describe(imageUrl, prompt) 는 imageUrl 을 받아서 모델에 흘려보내는 단순이에요. 학습용으로는 충분하지만 — 운영 환경 에서는 이 imageUrl 한 부분가 치명적인 보안 구멍 이 될 수 있어요.

생각해보세요.

사용자가 외부 입력 으로 imageUrl 을 직접 던질 수 있는 부분에서 — http://internal.company.com/secrets/badge.jpg 같은 내부 네트워크 URL 을 흘려넣으면 어떻게 될까요? 외부 LLM 모델 (Gemini · GPT-4o) 이 그 URL 을 다운로드해서 모델에 입력으로 넣으려고 시도해요.

만약 AWS 메타데이터 서비스 (http://169.254.169.254/latest/meta-data/) 같은 클라우드 내부 자산 의 URL 이라면 — 민감한 인프라 정보가 외부 모델로 흘러나가는. SSRF (Server-Side Request Forgery) 의 정통 이에요. 🚨

그리고 이미지 폭탄 의 결도 있어요. 공격자가 수 GB 짜리 가짜 이미지 URL 을 흘려넣으면 — 모델 측이 그걸 다운로드하면서 우리 측 토큰 / 비용 / 응답 지연이 폭발해요. DoS 의 변형.

업계의 정석적 대응은 몇 주제 가 있어요.

화이트리스트 (허용된 도메인만 — localhost, our-cdn.com, s3.amazonaws.com/...), 사전 다운로드 + 검증 (백엔드가 먼저 받아보고 안전성 / 크기 / MIME 검증 후에야 모델로 흘려보내기), 프록시 패턴 (이미지를 우리 측 임시 URL 로 복사해서 모델에 넘기기).

셋 다 트레이드오프가 다른 이에요.

🎯 핵심 질문 — 사용자가 imageUrl=http://internal.company.com/secrets/badge.jpg 같은 내부 URL 을 흘려넣으면 어떻게 막을 것인가? 화이트리스트 (도메인 제한) / 사전 다운로드 + 검증 / 프록시 (재호스팅) — 어느 방식으로 갈 것인가? 그리고 본 강의 코드는 왜 이 가드를 안 정리해도 됐는가 — 그 합리화는 운영 환경에서도 통하는가?

생각해볼 자료:

• 본 강의 코드의 imageUrl — Day 7 portrait URL 또는 사용자 업로드 후 publicPath 만 흘러들어가요. 외부에서 자유롭게 imageUrl 을 던지는 엔드포인트는 없어요. 이게 학습용 가드의 정체.
• AWS 메타데이터 서비스 SSRF 사고 — 2019 년 Capital One 해킹의 정통 사례. 이미지 URL 의 SSRF 도 같은 가족.
• Spring Boot 과정에서 만들었던 URL 기반 외부 호출 부분 (예: Open Graph 미리보기, 이미지 프록시) — 그 부분들에서 어떻게 막았나, 안 막았다면 위험은 어디였나.

주제 3 — Vision 비용을 사용자별로 격리하려면 — 멀티테넌시 가드

Step 7 에서 우리는 VisionDailyQuotaGuard 를 정리했어요. 전체 호출 한도 를 하루 20 회로 두는 단순한 방식. 학습용으론 충분 하지만 — 운영 환경 에선 한 가지 결정적 한계가 있어요. 사용자별 격리가 0 이라는 거예요.

상상해보세요. 한 명의 악의적 사용자가 20 회를 한 번에 호출하면 — 다른 모든 사용자의 Vision 호출이 그날 0 회 가 돼요. 공평성 (fairness) 이 무너지는 모양이에요. 운영급 가드는 유저별 / 조직별 / 테넌트별 로 카운터를 분리해야 해요.

이 부분의 결정 트리는 몇 단 부분이에요. 가장 단순 한 방식은 — Map<UserId, Counter> 를 인메모리에 두는 거예요. 학습 환경 / 단일 인스턴스에선 충분. 다음 단 은.

Redis INCR + EXPIRE. INCR vision:user:{userId}:{date} + EXPIRE 86400 한 부분에 정리하면 분산 환경 + 자정 자동 리셋 이 한 번에 풀려요. 그 다음 은 토큰 버킷 — 시간당 N 회 충전 의 방식. 마지막 은 슬라이딩 윈도우 카운터 —

지난 24 시간 기준 (자정 경계가 아닌 호출 시점 기준) 의 더 깐깐한 방식.

각 단계마다 복잡도 / 분산 보장 / 정확도 / 운영 부담 의 트레이드오프가 다 달라요. 어느 단까지 박을지 의 결정은 서비스의 성숙도와 비용 민감도 에 따라 갈려요.

🎯 핵심 질문 — Map<UserId, Counter> 인메모리 → Redis INCR + EXPIRE → 토큰 버킷 → 슬라이딩 윈도우 — 어느 결정 트리를 따라 어디까지 박을지의 트레이드오프는? 우리 ai-friends 가 유저 100 명 / 1000 명 / 10 만 명 으로 성장할 때 각 시점에서 어느 단계까지 가 있어야 적정 인가? 그리고 과대투자 와 과소투자 의 위험은 각각 무엇인가?

생각해볼 자료:

• Step 7 의 VisionDailyQuotaGuard 의 전체 카운터 1 개 패턴 — 학습용 의 단순함은 이미 들어갔어요.
• Spring Boot 과정에서 만났던 Redis 의 INCR + EXPIRE 부분 (예: 인스타그램 클론의 좋아요 카운터 · 조회수 같은 패턴) — 이미 익숙해진 패턴이라 한 부분에서 빌려올 수 있는 자리예요.
• Day 19 (Harness) 의 Spring AI Rate Limit 추상화 — 우리가 손으로 짜는 부분 이 선언적으로 한 줄 로 풀려요. 손으로 한 번 짜본 손이 추상화의 진짜 가치 를 알아본다는 점.