자, 본격적으로 새 도구 (BeanOutputConverter) 를 손에 쥐기 전에, 왜 그게 필요한지 부터 몸으로 느끼고 가야 해요. 그래야 도구가 들어왔을 때 "와, 이거 진짜 살았다" 라는 감각이 옵니다.

오늘은 우리가 이미 코드베이스에 갖고 있는 레거시 GeminiService 를 한 번 더 펼쳐서, 거기 숨어있는 4 가지 함정 을 하나씩 해부해볼게요.

지난 시간까지 우리가 알던 GeminiService

ai-friends/src/main/java/kr/spartaclub/aifriends/service/GeminiService.java 을 잠깐 다시 펼쳐봅시다.

Day 3 Step 7 에서 우리는 이 클래스의 시스템 프롬프트 부분만 외부 .st 파일로 빼냈어요.

그런데 사실 이 클래스는 JSON 응답을 만들고 받는 부분 도 같이 손으로 짜고 있었어요.

그쪽은 지난 시간엔 안 건드렸죠.

그 부분, 이렇게 생겼어요. 두 덩어리만 발췌해볼게요.

// 1번 덩어리: 응답 JSON Schema 를 손으로 조립
private static Map<String, Object> buildResponseJsonSchema() {
    Map<String, Object> schema = new LinkedHashMap<>();
    schema.put("type", "object");

    Map<String, Object> properties = new LinkedHashMap<>();
    properties.put("aiMessage", Map.of(
            "type", "string",
            "description", "캐릭터가 플레이어에게 하는 대사. 화면에 그대로 표시됩니다."));

    properties.put("choices", Map.of(
            "type", "array",
            "items", Map.of("type", "string"),
            "description", "플레이어가 고를 수 있는 선택지 2~4개. 없으면 빈 배열 []."));

    properties.put("affectionDelta", Map.of(
            "type", "integer",
            "description", "호감도 증감치. -5 ~ +5 정수."));

    schema.put("properties", properties);
    schema.put("required", List.of("aiMessage", "choices", "affectionDelta"));
    return schema;
}

// 2번 덩어리: LLM 이 돌려준 JSON 문자열을 ObjectMapper 로 수동 파싱
String rawText = response.extractText();
if (!StringUtils.hasText(rawText)) {
    throw new BusinessException(ErrorCode.AI_UNAVAILABLE);
}
log.info("Gemini raw JSON length={}", rawText.length());

GeminiParsedResponse parsed;
try {
    parsed = OBJECT_MAPPER.readValue(rawText.trim(), GeminiParsedResponse.class);
} catch (Exception e) {
    log.error("Gemini JSON 응답 파싱 실패. raw 길이={}", rawText != null ? rawText.length() : 0, e);
    throw new BusinessException(ErrorCode.AI_UNAVAILABLE);
}
if (parsed == null) {
    throw new BusinessException(ErrorCode.AI_UNAVAILABLE);
}

겉으로 보면 "잘 짜여 있는데?" 싶죠. 동작도 잘 해요. 하지만 이 코드 안에 4 가지 함정이 숨어있어요. 하나씩 까봅시다.

함정 ① — JSON Schema 손 조립 지옥

buildResponseJsonSchema() 메서드를 다시 보세요.

LinkedHashMap 을 new 하고, properties 라는 또 다른 LinkedHashMap 을 만들고, 거기에 Map.of("type", "string", "description", "...") 같은 걸 손으로 박고 있어요.

JSON Schema 명세를 자바 자료구조로 옮겨 적는 작업이에요.

지금은 필드가 3 개뿐이니까 봐줄 만한데, 만약 PM 이 다음 스프린트에 이런 요구를 들고 오면요?

"튜터님, 캐릭터 응답에 emotion 필드 (happy / sad / angry / neutral 중 하나) 도 추가해주세요. 그리고 relatedKeywords 라는 List<String> 도요. 아, 그리고 metadata 라는 Map<String, String> 도..."

매 필드가 늘어날 때마다 우리는 세 군데 를 같이 고쳐야 해요.

1. GeminiParsedResponse record 에 필드 추가
2. buildResponseJsonSchema() 의 properties.put(...) 한 줄 추가
3. required 리스트에도 추가 (필수 필드라면)

그리고 만약 1번만 고치고 2번을 깜빡하면? 컴파일은 통과합니다. LLM 도 응답을 줍니다. 다만 LLM 이 새 필드를 안 채워줘서 record 에 null 이 박힐 뿐이에요. 디버깅 한참 헤매죠.

함정 ② — ObjectMapper.readValue try-catch 지옥

2 번 덩어리의 코드, 다시 보세요.

GeminiParsedResponse parsed;
try {
    parsed = OBJECT_MAPPER.readValue(rawText.trim(), GeminiParsedResponse.class);
} catch (Exception e) {
    log.error("Gemini JSON 응답 파싱 실패. raw 길이={}", ...);
    throw new BusinessException(ErrorCode.AI_UNAVAILABLE);
}

LLM 이 JSON 을 깨뜨려서 보낼 가능성이 0% 가 아니에요. 모델이 가끔 이런 짓을 합니다.

• 앞에 ```json 마크다운 펜스를 붙여서 보냄 (Gemini 의 responseMimeType: application/json 을 쓰면 거의 안 그러긴 하지만, OpenAI 는 자주 그래요)
• 뒤에 부연 설명을 한 줄 더 붙임 ("위 JSON 은 ~~ 의미입니다")
• 키 이름을 살짝 바꿈 (affectionDelta → affection_delta)
• 문자열 안의 특수문자 이스케이프 누락

이게 터지면 우리 코드의 대응은 AI_UNAVAILABLE 를 던지고 끝. 사용자한텐 그냥 "AI 가 응답하지 않습니다" 만 보여요. 사실은 모델이 응답을 줬는데 우리가 못 읽은 거 인데도요.

재시도 한 번이라도 해볼 수 있을까요? 지금 코드에선 재시도 로직을 손으로 짜야 해요. 한 번 더 호출하고, 그래도 깨지면 또 잡고... 이걸 구현하기 시작하면 코드가 또 30 줄 늘어납니다.

함정 ③ — record 와 Schema 의 "이중 진실"

이게 가장 음흉한 함정이에요. 우리한텐 지금 "진실을 담은 두 군데" 가 있어요.

1. GeminiParsedResponse record — 자바 컴파일러가 강제하는 진실
2. buildResponseJsonSchema() 의 Map — LLM 한테 보내는 진실

이 둘이 항상 같아야 동작이 안정적이에요. 그런데 자바 컴파일러는 둘이 어긋나는 걸 절대 못 잡아줘요. 그도 그럴 게, schema 는 그냥 Map<String, Object> 안에 들어있는 문자열이거든요. 컴파일러 입장에선 그냥 평범한 자료구조죠.

이런 코드, 6 개월 뒤에 새로 합류한 동료가 record 만 바꾸고 schema 는 안 바꾸면? 터지지 않고 조용히 동작하는 버그 가 됩니다. 운영에서 가장 무서운 게 이거예요.

함정 ④ — 프로바이더 락인

이게 Day 2 와 직접 연결되는 함정이에요. 우리가 Day 2 에서 뭘 배웠죠?

"spring.ai.model.chat 프로퍼티 한 줄로 Ollama ↔ Gemini 가 갈아끼워진다. 이게 ChatModel 추상화의 힘이다."

자, 그런데 GeminiService.buildResponseJsonSchema() 의 결과는 어디로 들어가죠? GeminiRequest.GenerationConfig 의 responseJsonSchema 필드로요.

이거 Gemini API 만의 기능 이에요.

OpenAI 는 같은 위치에 response_format: { type: "json_schema", schema: ... } 라는 다른 스키마 형식을 써요.

Ollama 는 또 다르고요.

Anthropic 은 또 달라요.

즉, 지금 코드는 "Gemini 한테만 작동하는 JSON 강제 방식" 에 단단히 묶여 있어요. Day 2 에서 배운 그 추상화가, 응답 스키마 강제 부분에선 안 통한다는 뜻 이에요.

만약 다음 주에 PM 이 "비용 때문에 일부 트래픽을 Ollama 로 돌리자" 라고 하면, 우리는 GeminiService 를 통째로 들어내고 OllamaService 를 새로 짜야 해요. JSON 강제 로직이 프로바이더에 묶여 있어서요.

💡 튜터의 결론

지금까지 본 4 가지 함정을 한 표로 정리하면 이래요.

이 4 가지를 한 번에 잡는 도구 가 바로 다음 Step 의 주인공, .entity(Class<T>) 와 그 뒤에 숨어있는 BeanOutputConverter 예요. Step 2 에서는 가장 단순한 record 하나로 PoC 를 돌려보고, Step 3 에서는 그 도구의 내부를 한 꺼풀씩 벗겨볼 거예요.

자, 짐을 다 봤으니 이제 짐을 내려놓으러 갑시다!

자, Step 1 에서 짐을 4 개나 발견했죠. 그 짐을 한 번에 내려놓는 도구가 어떻게 생겼는지, 이번엔 가장 단순한 예제 로 먼저 만나볼 거예요. 의도적으로 ai-friends 의 복잡한 도메인 (소울메이트 페르소나, 호감도, 선택지 등) 은 잠시 옆으로 치워두고, 새 데모용 컨트롤러 하나만 추가해봅시다.

💡 왜 메인 코드 (SoulmateChatService, GeminiService) 를 바로 안 고치나요? 새 도구를 도입할 땐 항상 가장 작은 표면적 에서 먼저 검증하는 게 안전해요. 우리가 쓰던 큰 코드를 바로 갈아엎으면, 도구 자체의 이슈와 도메인 이슈가 뒤섞여서 디버깅이 지옥이 됩니다. Step 5 에서 본격 리팩토링할 때까지는 데모 컨트롤러로 도구만 손에 익혀요.

가장 단순한 record 하나 — Quote

데모용 도메인은 일부러 단순하게 잡을게요. 명언 한 줄 을 받는 record 입니다.

public record Quote(String text, String author) { }

필드 두 개.

끝.

text 는 명언 본문, author 는 누가 한 말.

이거 하나만 보고 LLM 이 "아 명언 본문이랑 작가 이름을 JSON 으로 줘야 하는구나" 라고 알아챌 수 있을까요? — 놀랍게도 가능합니다. 그게 어떻게 가능한지가 오늘 Step 3 의 주제예요.

일단 Step 2 에선 먼저 돌아가는 걸 본 다음에 그 비밀을 풀어봅시다.

데모 컨트롤러 — StructuredOutputDemoController

Day 1 에서 짠 HelloAiController 기억하시죠? 그 패턴을 그대로 따라갑니다.

package kr.spartaclub.aifriends.structured.api;

import kr.spartaclub.aifriends.common.response.ApiResponse;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * Day 4 Step 2 — 구조화 출력 PoC 데모 컨트롤러.
 *
 * 가장 단순한 record (Quote) 하나로 .entity(Class<T>) 의 동작을 체험하기 위한 일회용 데모.
 * SoulmateChatService 같은 본 도메인 코드는 Step 5 에서 본격 리팩토링한다.
 */
@RestController
public class StructuredOutputDemoController {

    private final ChatClient chatClient;

    public StructuredOutputDemoController(ChatClient.Builder builder) {
        // Day 2 에서 강조한 ChatModel 인터페이스 주입 원칙은 그대로.
        // ChatClient.Builder 는 spring-ai-starter 가 자동 주입해주는 빌더이고,
        // 그 뒤에 들어있는 ChatModel 은 spring.ai.model.chat 프로퍼티로 결정된다.
        this.chatClient = builder.build();
    }

    public record Quote(String text, String author) { }

    /**
     * topic 에 관한 짧은 명언 한 줄을 Quote record 로 받아 표준 응답 래퍼에 담아 반환한다.
     *
     * 핵심: chatClient ... .call().entity(Quote.class) — 이 한 줄.
     * 응답은 ApiResponse 로 감싸서 GlobalExceptionHandler 의 에러 응답과 형태를 통일한다.
     */
    @GetMapping("/api/structured/quote")
    public ResponseEntity<ApiResponse<Quote>> quote(@RequestParam(defaultValue = "용기") String topic) {
        Quote quote = chatClient.prompt()
                .user(u -> u.text("'{topic}' 에 관한 짧은 명언 한 줄을 알려줘.").param("topic", topic))
                .call()
                .entity(Quote.class); // ← 오늘의 주인공
        return ResponseEntity.ok(ApiResponse.success(quote));
    }
}

코드 전체가 30 줄도 안 돼요. 그리고 진짜 중요한 건 마지막 한 줄, .call().entity(Quote.class) 입니다. 이거 하나가 Step 1 에서 본 4 가지 짐을 한 번에 들어 옮기는 일꾼이에요.

⚠️ 참고: 위 데모는 Step 5 의 본격 리팩토링 전 일회용 PoC 입니다. Day 5 이후엔 다른 컨트롤러들과 패키지를 정리하면서 자연스럽게 정돈될 거예요. 지금은 "도구의 모양만 손에 익히는 게 목적" 이라는 호흡으로 가벼이 봅시다.

한 번 돌려봅시다 🚀

.env · 프로파일 세팅은 Day 1~3 에서 다 해놨으니 그대로 기동만 하면 됩니다.

cd ai-friends
./run.sh up

# 호출 1 — 기본 토픽 ("용기")
curl "http://localhost:8080/api/structured/quote"

# 호출 2 — 토픽 변경
curl "http://localhost:8080/api/structured/quote?topic=인내"

응답은 이런 식으로 떨어져요. (정확한 본문은 모델 따라 달라요)

{
  "success": true,
  "data": {
    "text": "용기는 두려움이 없는 것이 아니라, 두려움을 이겨내는 판단이다.",
    "author": "넬슨 만델라"
  }
}

{
  "success": true,
  "data": {
    "text": "인내는 쓰지만, 그 열매는 달다.",
    "author": "장 자크 루소"
  }
}

JSON 파싱 코드 한 줄도 안 짰는데 record 가 채워져서 ApiResponse.success(...) 한 단계만 감싸 컨트롤러 응답으로 흘러나갔어요. Spring MVC 가 Quote 객체를 자동으로 JSON 직렬화해서 응답 본문으로 던지고, 우리는 표준 래퍼만 한 줄 얹은 거예요. 🎯

Step 1 의 4 가지 짐, 어떻게 됐나?

기억하시죠? Step 1 에서 봤던 4 가지 함정.

코드 30 줄에서 짐 4 개가 동시에 빠졌어요. 짐이 빠진 공간에 우리는 도메인 본질 만 남길 수 있게 됐죠.

💡 튜터의 결론

Step 2 의 한 문장 요약은 이래요.

"record 한 줄 + .entity(Class<T>) 한 줄 = LLM 응답을 타입 안전하게 받기."

이게 오늘 우리가 손에 쥔 첫 도구예요. 아직은 "왜 동작하는지" 는 몰라요. 그냥 동작합니다. 그리고 Step 3 에선 그 비밀을 들여다보고, Step 4 에선 List<T> · Map<K,V> 같은 더 복잡한 타입까지 확장하고, Step 5 에선 ai-friends 의 본 도메인 (소울메이트) 을 진짜로 갈아엎을 거예요.

지금 이 PoC 컨트롤러는 Step 2 의 단계 학습용 일회용 코드 입니다. 한 번 돌려보고 머리에 도구의 모양을 박아두는 게 목적이에요.

자, 도구의 모양을 봤으니 이제 도구의 속을 까볼 시간입니다. Step 3 으로 갈까요?

자, Step 2 에서 .entity(Quote.class) 한 줄로 마법처럼 record 가 채워지는 걸 봤죠. 그런데 마법은 좀 거슬려요. 운영에서 마법은 디버깅 못 하는 코드가 됩니다. 모델이 가끔 엉뚱한 답을 줬을 때 "왜 그랬지?" 를 추적하려면, 마법의 안쪽에서 정확히 무슨 일이 일어나는지 한 번은 직접 봐둬야 해요.

오늘 Step 3 의 목표는 단 하나예요. .entity(Class<T>) 가 LLM 한테 정확히 무엇을 보내는지 우리 눈으로 보는 것. 그 핵심 일꾼이 바로 BeanOutputConverter 입니다.

BeanOutputConverter 가 누구인가

먼저 정체부터 짚고 갑시다. org.springframework.ai.converter.BeanOutputConverter<T> 는 Spring AI 가 제공하는 두 얼굴의 일꾼 이에요.

.call().entity(Class<T>) 는 이 둘을 한 번에 해주는 편의 메서드예요. 호출 흐름을 풀어 쓰면 이렇습니다.

1. entity(Quote.class) 진입 → 내부에서 BeanOutputConverter<Quote> 인스턴스 생성
2. getFormat() 호출 → 결과를 사용자 프롬프트 끝에 자동으로 붙여서 LLM 호출
3. LLM 응답 (문자열 JSON) 도착
4. convert(rawText) 호출 → Quote 인스턴스 반환

마법처럼 보였던 한 줄이 사실은 이 4 단계예요. 그리고 우리가 가장 보고 싶은 건 2 번에서 정확히 어떤 텍스트가 보내지는가 죠. 직접 봅시다.

디버그 엔드포인트 추가

Step 2 에서 만든 StructuredOutputDemoController 에 작은 엔드포인트 하나만 더 얹으면 돼요. LLM 호출은 안 합니다. 그냥 BeanOutputConverter<Quote> 를 손으로 인스턴스화해서 두 메서드를 호출한 결과를 그대로 응답 본문으로 떨어뜨려요.

import org.springframework.ai.converter.BeanOutputConverter;
import org.springframework.http.MediaType;
// ... 기존 import 생략

@GetMapping(value = "/api/structured/quote/format-debug",
            produces = MediaType.TEXT_PLAIN_VALUE)
public String quoteFormatDebug() {
    BeanOutputConverter<Quote> converter = new BeanOutputConverter<>(Quote.class);
    return """
            === BeanOutputConverter<Quote>.getJsonSchema() ===
            %s

            === BeanOutputConverter<Quote>.getFormat() ===
            %s
            """.formatted(converter.getJsonSchema(), converter.getFormat());
}

핵심 포인트 몇 가지.

• text/plain 으로 응답합니다. JSON 안에 또 JSON Schema 텍스트가 들어가면 이스케이프 지옥이 펼쳐져서 가독성이 망해요. 학습 목적이니 평문 그대로 — 다른 엔드포인트들은 ApiResponse 로 감싸지만, 이 디버그 출력만은 일부러 raw 평문으로 둬요. "BeanOutputConverter 가 LLM 한테 보내는 텍스트를 있는 그대로" 보여주는 게 학습 의도이니까요.
• 이 엔드포인트는 LLM 호출 없음 입니다. BeanOutputConverter 의 첫 번째 얼굴(스키마 생성) 만 보는 거예요. 그래서 Ollama 가 안 떠 있어도, Gemini 키가 없어도 동작합니다. 🎯
• Step 2 데모 컨트롤러처럼 이 엔드포인트도 일회용 학습 보조 도구 예요. 본격 리팩토링 할 때 정돈됩니다.

한 번 돌려봅시다 🚀

cd ai-friends
./run.sh up

curl http://localhost:8080/api/structured/quote/format-debug

응답이 두 섹션으로 떨어져요. 하나씩 차분히 살펴봅시다.

첫 번째 섹션 — getJsonSchema() 의 결과

=== BeanOutputConverter<Quote>.getJsonSchema() ===
{
  "$schema" : "https://json-schema.org/draft/2020-12/schema",
  "type" : "object",
  "properties" : {
    "author" : {
      "type" : "string"
    },
    "text" : {
      "type" : "string"
    }
  },
  "additionalProperties" : false
}

겨우 record Quote(String text, String author) 한 줄을 적었을 뿐인데, JSON Schema 한 덩어리가 자동으로 만들어졌어요. 이 출력에서 짚어둘 포인트가 4 개 있습니다.

1. $schema 메타필드 — https://json-schema.org/draft/2020-12/schema 라는 URL 이 박혀 있어요. "이건 JSON Schema 명세 Draft 2020-12 를 따른다" 는 표지판이에요.

이 표지판이 있으면 모델이 schema 의 의미를 더 정확히 해석 합니다 (요즘 모델은 모두 JSON Schema 를 학습 데이터에서 봤거든요).

2. type: "object" — 응답 루트가 객체여야 한다는 뜻.

record 가 곧 객체로 매핑되는 거죠.

만약 우리가 record QuoteList(List<Quote> items) 같이 짰다면 여기에도 object 가 박히지만, 그 안의 items 필드가 array 가 됐을 거예요.

(이건 다음 Step 4 의 주제예요.)

3. properties 안의 author, text — 알파벳 순으로 정렬되어 있어요 (a 가 t 보다 앞이라).

record 선언 순서랑 다를 수 있어요.

헷갈리지 마세요.

이 정렬은 BeanOutputConverter 가 내부적으로 안정적인 비교를 위해 정렬해서 출력하는 거예요.

모델이 응답할 때의 키 순서랑은 무관 합니다.

4. additionalProperties: false — 이게 가장 중요해요.

"위 schema 에 정의되지 않은 필드는 응답에 넣지 마라" 는 강제 신호예요.

모델이 text, author 외에 자기 멋대로 language 같은 필드를 추가하는 걸 막아요.

만약 추가했다 하더라도 BeanOutputConverter 의 convert() 단계에서 ObjectMapper 가 무시해버립니다.

우리 record 가 안전하게 채워지는 핵심 방어선이에요.

💡 한 줄 직관 — record 는 자바 컴파일러가 강제하는 진실, JSON Schema 는 LLM 한테 강제하는 진실. 두 진실이 자동 동기화돼요. Day 4 오프닝에서 약속했던 "이중 진실 함정 ③" 이 여기서 사라지는 거예요.

두 번째 섹션 — getFormat() 의 결과

이게 진짜 주인공이에요. getJsonSchema() 는 그냥 스키마 텍스트일 뿐이고, 실제로 LLM 한테 보내지는 건 getFormat() 의 결과 입니다.

=== BeanOutputConverter<Quote>.getFormat() ===
Your response should be in JSON format.
Do not include any explanations, only provide a RFC8259 compliant JSON response following this format without deviation.
Do not include markdown code blocks in your response.
Remove the ```json markdown from the output.
Here is the JSON Schema instance your output must adhere to:
```{
  "$schema" : "https://json-schema.org/draft/2020-12/schema",
  "type" : "object",
  "properties" : {
    "author" : {
      "type" : "string"
    },
    "text" : {
      "type" : "string"
    }
  },
  "additionalProperties" : false
}```

자세히 뜯어보면 이 텍스트는 자연어 지시문 4 줄 + JSON Schema 박스 1 개 로 구성돼요.

자, 이제 진짜 중요한 질문 — 이 텍스트가 언제 어디로 보내지는 거죠?

답: .entity(Quote.class) 를 호출하는 그 순간, Spring AI 가 여러분이 작성한 user 메시지 끝에 이 텍스트를 슬쩍 붙여서 LLM 한테 보냅니다. 즉 LLM 입장에서 받는 user 메시지는 이렇게 생겼어요.

'용기' 에 관한 짧은 명언 한 줄을 알려줘.

Your response should be in JSON format.
Do not include any explanations, only provide a RFC8259 compliant JSON response following this format without deviation.
Do not include markdown code blocks in your response.
Remove the ```json markdown from the output.
Here is the JSON Schema instance your output must adhere to:
```{ "$schema": ..., "properties": { "text": ..., "author": ... }, "additionalProperties": false }```

위쪽이 우리가 짠 부분, 아래쪽이 BeanOutputConverter 가 자동으로 붙인 부분이에요. 합쳐진 결과 가 LLM 한테 가는 거고요. 🎯

Day 3 의 RCTFE 와 연결 짓기

지난 시간 (Day 3) 우리가 시스템 프롬프트의 RCTFE 5 축 중 F (Format) 섹션에 손으로 뭐라고 썼었죠?

# Format
- aiMessage: 화면에 보여질 캐릭터의 대사 (문자열)
- choices: 유저가 고를 수 있는 다음 발화/행동 2~4개의 배열
- affectionDelta: 호감도 증감치, -5~+5 정수

자연어로 형식을 설명하는 방식이었어요. 잘 동작했지만 단점이 있었죠 — 필드 추가하면 두 군데를 같이 고쳐야 했고, 모델이 affectionDelta 를 affection_delta 로 바꿔도 막을 수 없었어요.

💡 Day 5 예고 — 위 6 줄짜리 # Format 섹션은 BeanOutputConverter 도입과 함께 통째로 들어내요. 다음 시간 Step 6 (수렴) 에서 prompts/soulmate/system-v1.st 파일을 진짜로 사용하기 시작 할 때, 코드와 프롬프트가 같은 정보를 두 군데 들고 있는 중복 을 BeanOutputConverter 자동 주입으로 갈음하면서 자연스럽게 사라지는 결입니다.

이제 Step 3 의 메커니즘을 알았으니 다시 보면 Day 3 의 그 Format 섹션이 정확히 getFormat() 의 출력으로 자동 대체 되는 거예요. 자연어 설명이 아닌 JSON Schema 명세 로요. RCTFE 의 F 축이 코드(record) 에서 자동 생성 되는 거죠.

이렇게 자동화되니까 "나는 record 를 진실의 원본으로 다루기만 하면 된다" 는 감각이 새겨져요. Format 섹션의 동기화 책임이 사라지는 거예요.

💡 튜터의 결론

Step 3 의 한 문장 요약은 이래요.

".entity(Class<T>) 의 마법은 사실 마법이 아니다. BeanOutputConverter 가 record 에서 JSON Schema 를 자동 생성해 사용자 프롬프트 끝에 슬쩍 붙이는 것뿐이다."

마법이 평범한 도구로 변환된 순간이에요. → 평범하니까 디버깅 가능 하고, 디버깅 가능하니까 운영에 올릴 수 있어요. Step 1 의 함정 ③ "이중 진실" 이 사라진 진짜 메커니즘을 우리 눈으로 봤죠.

여기까지가 단일 record 의 이야기였어요.

그런데 진짜 운영에선 응답이 항상 단일 객체일 수가 없죠.

List<Quote> 같은 컬렉션이나 Map<String, Integer> 같은 동적 키 집합도 받아야 해요.

이걸 받으려면 Class<T> 만으로는 부족하고 ParameterizedTypeReference<T> 라는 또 하나의 도구가 필요해져요.

자, 도구의 모양도 봤고 속도 깠으니 이제 다양한 용기에 담아볼 시간입니다. Step 4 로 갈까요?

자, Step 2/3 까지 우리가 받아본 응답은 모두 단일 객체 (Quote record 한 덩어리) 였어요. 그런데 운영에선 그것만 가지고 안 됩니다. 이런 요구가 흔해요.

• 명언을 3 개 한 번에 받고 싶다 → List<Quote>
• 문장에서 키워드별 등장 횟수 를 받고 싶다. 키 이름은 미리 정할 수 없다 → Map<String, Integer>

오늘 Step 4 의 목표는 이런 컬렉션 타입을 타입 안전하게 받는 방법, 그리고 그 과정에서 자바의 한 가지 오래된 한계 (type erasure) 를 맞닥뜨리는 경험입니다. 만나야 할 새 도구는 하나, ParameterizedTypeReference<T> 예요.

첫 시도가 막히는 자리

Step 2 의 패턴을 그대로 따라 가서, 명언을 3 개 받고 싶다고 해봅시다. 자연스럽게 이렇게 쓰고 싶어져요.

// 기대 — 컴파일러가 "List<Quote> 가 아니라고" 뱉어주길.
// 현실 — 컴파일은 통과한다.
List<Quote> quotes = chatClient.prompt()
        .user("명언 3 개 줘.")
        .call()
        .entity(List.class);   // ❓

이 코드, 컴파일은 통과해요. 컴파일러는 행복합니다. 그런데 받아본 결과를 한번 까보면 Quote 가 아니라 LinkedHashMap 들이 들어있는 리스트가 나와요. quotes.get(0).text() 같은 호출은 런타임에 ClassCastException 으로 깨집니다.

왜 이렇게 됐을까요? 자연스럽게 떠오르는 다음 시도는 이거죠.

// 자바 문법상 작성 자체가 불가능하다.
.entity(List<Quote>.class)   // ❌ 컴파일 에러: "cannot select from parameterized type"

자바에선 List<Quote> 라는 클래스 리터럴이 존재하지 않아요. 왜?

자바 type erasure 1 분 복습

자바의 제네릭은 컴파일 타임에는 강하게 검증되지만, 런타임에는 그 정보가 지워집니다. 컴파일된 바이트코드에는 List 만 남고 <Quote> 부분은 사라져요. 이걸 type erasure 라고 해요.

그래서 클래스 리터럴 (SomeClass.class) 도 type 파라미터를 못 담아요. List.class 는 있어도 List<Quote>.class 는 없습니다. 자바 언어 차원의 한계예요.

💡 한 줄 직관 — Class<T> 한 개만으로는 컬렉션의 원소 타입을 LLM 한테 알릴 방법이 없다. 그래서 컴파일러를 한 번 속여서 type 정보를 런타임까지 살리는 트릭 이 필요해진다.

ParameterizedTypeReference 의 익명 서브클래스 트릭

스프링 코어가 오래 전부터 들고 있던 도구가 있어요. org.springframework.core.ParameterizedTypeReference<T> — Spring AI 도 그대로 빌려 씁니다. 사용법은 한 줄로 끝나요.

new ParameterizedTypeReference<List<Quote>>() {}

중괄호 두 개 {} 가 핵심이에요. 이게 익명 서브클래스를 즉석에서 만든다 는 자바 문법이거든요. 그러면 다음 일이 벌어져요.

1. 우리는 ParameterizedTypeReference<List<Quote>> 의 익명 서브클래스 인스턴스를 만든 셈
2. 자바는 클래스의 정의에는 type 파라미터 정보를 보관해요 (서브클래스의 superclass type 정보는 살아남아요)
3. ParameterizedTypeReference 가 자기 superclass 의 type 파라미터를 리플렉션 으로 끄집어내서 List<Quote> 라는 정보를 살려둠

즉, 빈 중괄호 한 쌍이 type erasure 의 빈틈을 때우는 표 인 거예요. 처음 보면 이상해 보이지만 자바 생태계 전체가 이 트릭을 씁니다 (Jackson 의 TypeReference, Spring 의 ParameterizedTypeReference, Guava 의 TypeToken 모두 같은 원리).

이 한 줄을 .entity(...) 의 또 다른 오버로드 — .entity(ParameterizedTypeReference<T>) — 에 그대로 넘기면 됩니다.

List<Quote> 엔드포인트 추가

Step 2/3 의 데모 컨트롤러에 메서드 하나만 더 얹어요. import 두 줄 (ParameterizedTypeReference, java.util.List) + 메서드 하나가 늘어나요. 응답은 Step 2 와 같은 방식으로 ApiResponse 로 한 번 더 감싸 표준 형태를 유지합니다.

import org.springframework.core.ParameterizedTypeReference;
import java.util.List;

@GetMapping("/api/structured/quotes")
public ResponseEntity<ApiResponse<List<Quote>>> quotes(
        @RequestParam(defaultValue = "용기") String topic,
        @RequestParam(defaultValue = "3") int count) {
    List<Quote> quotes = chatClient.prompt()
            .user(u -> u.text("'{topic}' 에 관한 짧은 명언을 서로 다른 인물의 것으로 {count} 개 알려줘.")
                    .param("topic", topic)
                    .param("count", count))
            .call()
            .entity(new ParameterizedTypeReference<List<Quote>>() {});
    return ResponseEntity.ok(ApiResponse.success(quotes));
}

핵심 한 줄은 여전히 .entity(new ParameterizedTypeReference<List<Quote>>() {}) — 이게 우리 trick. 마지막 줄의 ApiResponse.success(quotes) 는 본 강의의 표준 응답 형태를 유지하기 위한 한 단계 래핑이에요. 자, 한 번 돌려봅시다.

curl "http://localhost:8080/api/structured/quotes?topic=인내&count=3"

응답 (모델 따라 본문은 달라요):

{
  "success": true,
  "data": [
    { "text": "인내는 쓰지만, 그 열매는 달다.", "author": "장 자크 루소" },
    { "text": "기다림은 사랑의 또 다른 이름이다.", "author": "마하트마 간디" },
    { "text": "고요는 기다림이 자란 자리다.", "author": "라이너 마리아 릴케" }
  ]
}

List<Quote> 가 data 필드에 그대로 채워져서 응답으로 흘러나갔어요. 컴파일러는 이게 진짜 List<Quote> 라는 걸 알고 있고, 우리는 quotes.get(0).text() 같은 호출을 안전하게 쓸 수 있어요. 🎯

무대 뒤 — List<Quote> 의 schema 는 어떻게 생겼을까

Step 3 에서 BeanOutputConverter<Quote> 의 schema 를 들여다봤었죠. 같은 방식으로 BeanOutputConverter<List<Quote>> 의 schema 도 직접 출력해볼 수 있어요. 이렇게 떨어집니다.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "author": { "type": "string" },
      "text": { "type": "string" }
    },
    "additionalProperties": false
  }
}

핵심 변화 두 가지.

1. 루트가 "type": "array" — 응답 전체가 배열이라는 신호. Step 3 의 단일 Quote 에서는 루트가 "type": "object" 였죠.
2. items 필드 안에 Quote 의 schema 가 그대로 박혔어요. JSON Schema 의 표준 표현이에요 — "이 배열의 각 원소는 이 모양의 객체다."

즉 List<Quote> 라는 자바 타입이 array of Quote 라는 JSON Schema 로 자동 번역된 거예요. Spring AI 가 우리 타입 정보를 정확히 받아내서 schema 를 깊이 있게 만들 수 있다는 증거죠.

Map<String, Integer> — 키가 미리 정해지지 않을 때

이번엔 다른 종류의 응답이에요. 키 이름을 우리가 미리 정할 수 없는 데이터. 예를 들어:

"다음 문장에서 핵심 키워드를 추출해 등장 횟수를 알려줘."

키워드가 무엇이 될지는 입력 문장에 따라 다르죠. record 로는 표현이 어려워요 (필드 이름이 컴파일 타임에 정해져 있어야 하니까). 이럴 때 자연스러운 선택이 Map<String, Integer> 예요.

엔드포인트는 똑같은 패턴 (응답을 ApiResponse 로 감싸는 것까지 포함).

import java.util.Map;

@GetMapping("/api/structured/keyword-counts")
public ResponseEntity<ApiResponse<Map<String, Integer>>> keywordCounts(
        @RequestParam(defaultValue = "Spring AI 는 자바 백엔드에서 Spring으로 LLM 을 다루는 표준 추상화를 제공한다.") String text) {
    Map<String, Integer> counts = chatClient.prompt()
            .user(u -> u.text("다음 문장에서 핵심 명사를 추출해 키워드별 등장 횟수를 JSON 객체로 반환해줘. 문장: {text}")
                    .param("text", text))
            .call()
            .entity(new ParameterizedTypeReference<Map<String, Integer>>() {});
    return ResponseEntity.ok(ApiResponse.success(counts));
}

호출.

curl "http://localhost:8080/api/structured/keyword-counts?text=Spring AI 는 자바 백엔드에서 Spring으로 LLM 을 다루는 표준 추상화를 제공한다."

응답 예시.

{
  "success": true,
  "data": {
    "Spring": 2,
    "자바": 1,
    "백엔드": 1,
    "LLM": 1,
    "추상화": 1
  }
}

깔끔하죠. 그런데 이 Map<String, Integer> 응답에는 한 가지 솔직한 한계 가 있어요. Step 5~6 으로 넘어가기 전에 잠깐 짚고 갑시다.

Map 응답의 솔직한 한계 — schema 강제력이 약하다 ⚠️

BeanOutputConverter<Map<String, Integer>> 의 schema 를 출력해보면 이렇게 떨어져요.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false
}

properties 가 아예 없어요. 그리고 additionalProperties: false 가 박혀 있죠. 이걸 글자 그대로 해석하면 "필드를 하나도 가지지 않은 빈 객체만 허용" 이라는 모순적인 신호예요.

왜 이렇게 됐을까요? 컴파일 시점에 어떤 키가 들어올지 알 수 없기 때문 에 schema 생성기가 properties 자리를 비워둘 수밖에 없어요. 그리고 안전 장치로 additionalProperties: false 를 박아둔 건데, 둘이 합쳐지면 schema 가 사실상 "아무것도 허용 안 함" 을 말해요.

그런데 실제로는 동작합니다. 왜?

1. 모델은 schema 를 절대적 명령으로 받지 않아요. "참고하라" 정도로 받아들이고, 사용자 메시지("키워드별 등장 횟수를 JSON 으로 반환") 와 함께 종합해서 응답을 만들죠. 모델 입장에선 사용자 의도가 더 강해 보이니까 정상적인 객체를 응답해줘요.
2. 응답 역직렬화 단계에선 schema 검증이 안 일어나요. Spring AI 는 받은 JSON 문자열을 ObjectMapper 로 그냥 Map<String, Integer> 에 부어넣어요. 모순적인 schema 든 말든 ObjectMapper 한텐 무관해요.

즉 모델의 관용성 + 클라이언트 deserialization 의 schema 무관성 이 합쳐져서 동작하는 거예요. 우아하진 않아요. 솔직히 record 로 받을 수 있는 응답이라면 record 가 더 안전해요. 트레이드오프를 표로 정리하면 이래요.

결론: Map 은 마지막 선택지. 가능한 record 로 모델링하고, 진짜 동적 키일 때만 Map 으로 가자.

💡 튜터의 결론

Step 4 의 한 문장 요약은 이래요.

"Class<T> 만으로 컬렉션을 못 받는 자바의 한계를, new ParameterizedTypeReference<...>() {} 익명 서브클래스 트릭으로 우회한다. 그리고 가능한 record 로 감싸라."

여기까지가 데모 컨트롤러로 도구 손에 익히는 마지막 Step 이에요. Step 1~4 동안 우리는:

도구가 다 들어왔어요.

이제 데모 컨트롤러를 떠나 진짜 우리 ai-friends 코드 로 옮겨갈 시간입니다.

지난 시간 (Day 3) 우리가 한 축씩 다듬어둔 SoulmateChatService 를 String 반환에서 AiReply record 반환 으로 갈아엎고, 그 과정에서 지난 시간까지 못 건드린 레거시 GeminiService 의 ObjectMapper 수동 파싱 30 줄도 함께 정돈할 거예요.

자, 도구는 다 챙겼으니 이제 본 도메인으로 갑시다. Step 5 로 갈까요?

자, 데모 컨트롤러로 도구를 충분히 손에 익혔어요. Step 1~4 까지 우리가 만진 코드는 본 도메인 밖 의 일회용 학습용 컨트롤러였죠. 이제 본 도메인 으로 돌아갈 시간입니다.

오늘의 과업은 명확해요. Day 3 까지 쌓아둔 SoulmateChatService 의 String chat(...) 메서드를 AiReply chat(...) 로 갈아엎기. 그게 다예요. 시그니처 한 줄, 호출 체인 한 줄, 그리고 record 한 개 신설.

잠깐 — 오늘 손대는 자리는 lab 의 진화 단계 입니다 (in-place 형 수술은 Day 5)

Day 3 Step 2 에서 약속드렸죠. "SoulmateChatService 는 학습용 lab 이고, Day 5 마무리에 기존 AiChatController 의 백엔드를 흡수한다". 오늘 Step 5 가 그 lab 을 한 단계 더 자라게 하는 단계예요.

시점	lab (SoulmateChatService) 가 받는 것	그 시점 prod (AiChatController 백엔드) 상태
Day 3 (지난 시간)	ChatClient + PromptTemplate (RCTFE 5 축)	RestClient + 수동 JSON 파싱 그대로
Day 4 (오늘)	+ AiReply record + .entity(AiReply.class) — 응답 구조화	GeminiService.parseGeminiResponse 가 deprecated 후보 로 표시 (들어내기 직전)
Day 5	+ MessageChatMemoryAdvisor + JdbcChatMemoryRepository	AiChatController 의 백엔드를 lab 으로 갈아끼움 → GeminiService 제거 (수렴 지점)

그래서 오늘 우리는 두 가지를 동시에 안 합니다. 레거시 GeminiService 의 30 줄짜리 ObjectMapper 수동 파싱 — 그건 Step 7 에서 한 번 더 짚지만, 들어내는 건 Day 5 의 일 이에요. 오늘은 lab 한 곳만 깔끔하게 record 반환으로 자라는 걸 손에 익힙니다. 외부 계약(메서드 시그니처)을 동결한 채 내부만 교체 하는 in-place 형 수술의 정석은 Day 3 Step 5 (GeminiService 의 PromptTemplate 도입) 에서 이미 한 번 손에 익혔고, Day 5 에서 한 번 더 와요.

변경 전 — Day 3 까지의 SoulmateChatService

먼저 지난 시간 끝낸 코드를 한 번 더 펼쳐봅시다. 위치: chat/service/SoulmateChatService.java.

public String chat(String anonymizedUserName, String mood, String userMessage) {
    return soulmateChatClient.prompt()
            .system(system -> system
                    .text("""
                            너는 {userName} 님의 AI 친구야.
                            유저의 현재 기분은 '{mood}' 이야.
                            답변은 3문장 이내로, 반말로 친근하게 해.
                            """)
                    .param("userName", anonymizedUserName)
                    .param("mood", mood))
            .user(userMessage)
            .call()
            .content();
}

마지막 두 줄이 오늘 우리가 칼을 댈 곳이에요.

• .content() — LLM 응답을 평문 String 으로 그대로 반환
• 메서드 시그니처도 String chat(...)

지금까지는 친구 한 마디 받아 화면에 그대로 뿌리는 정도라 String 으로 충분했어요. 그런데 ai-friends 는 미연시 게임 도메인이에요. 게임 한 턴엔 3 가지가 같이 흐르죠.

이 셋을 한 응답에 묶어서 받아야 해요. 그리고 그걸 record 로 받는 게 오늘의 목표.

AiReply record 신설 — chat/dto/AiReply.java

먼저 새 record 파일을 만들어요. 위치는 도메인 친화적인 chat.dto 패키지로.

package kr.spartaclub.aifriends.chat.dto;

import java.util.List;

public record AiReply(
        String aiMessage,
        List<String> choices,
        int affectionDelta
) { }

세 줄짜리 record. 이게 곧 LLM 응답의 진실의 원본 이에요. Step 3 에서 봤듯이 이 record 의 모양에서 BeanOutputConverter 가 JSON Schema 를 자동 생성하고, Step 1 의 함정 ③ "이중 진실" 이 깨끗하게 사라집니다.

💡 이름 짓기 — 왜 GeminiParsedResponse 가 아니라 AiReply 인가? 레거시 GeminiService 안에 거의 같은 모양의 GeminiParsedResponse 라는 record 가 있어요 (필드 셋 동일). 그런데 Day 4 부터는 응답 타입을 프로바이더 중립적인 이름 으로 가져갑니다. Day 2 에서 추상화한 ChatModel 인터페이스의 정신과 같아요 — Ollama 로 갈아끼우든 Gemini 든, 우리 도메인 코드는 "AI 의 답장(AiReply)" 만 알면 됩니다. 이름이 곧 약속이에요.

SoulmateChatService 시그니처 + 호출 체인 갈아엎기

이제 본체를 칠 차례. 시그니처 + 호출 체인의 한 줄 + 시스템 프롬프트에 두 줄 보강. 이게 전부예요.

import kr.spartaclub.aifriends.chat.dto.AiReply;

public AiReply chat(String anonymizedUserName, String mood, String userMessage) {
    return soulmateChatClient.prompt()
            .system(system -> system
                    .text("""
                            너는 {userName} 님의 AI 친구야.
                            유저의 현재 기분은 '{mood}' 이야.
                            답변은 3문장 이내로, 반말로 친근하게 해.
                            유저가 이어서 보낼 만한 짧은 답장 후보(choices) 를 2~3개 함께 제안해.
                            이번 한 턴으로 너에 대한 호감도(affectionDelta) 가 -5~+5 사이에서 얼마나 변할지 정수로 추정해.
                            """)
                    .param("userName", anonymizedUserName)
                    .param("mood", mood))
            .user(userMessage)
            .call()
            .entity(AiReply.class);
}

세 군데가 바뀌었어요.

한 박스 회고 — Step 1 의 함정 ② 가 오늘 한 줄로 사라졌어요

좀 더 멀리서 한 번 짚고 갈게요. 우리가 오늘 Step 5 에서 바꾼 건 SoulmateChatService.chat(...) 의 마지막 한 줄 뿐이에요. 그런데 그 한 줄이 Step 1 에서 본 레거시 GeminiService 의 30 줄짜리 짐을 어떻게 압축했는지 한 번 비교해보면 — 오늘 학습의 무게감이 다르게 잡힙니다.

축	Before — 레거시 GeminiService (Step 1 함정 ②)	After — 오늘의 SoulmateChatService
JSON 받기	String rawText = response.extractText();	.entity(AiReply.class)
파싱	OBJECT_MAPPER.readValue(rawText.trim(), GeminiParsedResponse.class)	(자동 — BeanOutputConverter 가 처리)
파싱 실패 처리	try { ... } catch(Exception e) { log + throw BusinessException(AI_UNAVAILABLE) }	(Step 6 에서 recover-retry 로 별도 다룸)
Schema 손 조립	buildResponseJsonSchema() — Map.put 으로 type/properties/required 30 줄	(자동 — record 컴포넌트에서 추출)
코드 줄 수	약 30 줄	호출 체인의 마지막 한 줄

Step 1 에서 "이 30 줄이 진짜 다 필요한가?" 라고 의심했었죠. 오늘 Step 5 에서 그 답이 나왔어요. lab (SoulmateChatService) 측은 그 짐을 한 줄로 줄였고, prod (GeminiService) 측의 30 줄은 Day 5 의 ChatMemory 합류 시점에 통째로 들어내집니다. 오늘 AiReply 가 만들어진 건 그 Day 5 의 들어내기를 위한 다리 (record) 가 미리 깔린 거예요.

특히 시스템 프롬프트 추가 두 줄 을 짚어둘게요.

record 에 choices, affectionDelta 필드가 생긴 것만으로는 부족해요.

BeanOutputConverter 가 schema 를 자동 주입해서 "이런 키들이 있는 JSON 으로 줘" 라고 모델한테 강제하긴 하는데, 모델이 각 필드를 어떤 의미로 채워야 하는지 는 우리가 시스템 프롬프트에서 알려줘야 해요.

안 알려주면 모델이 choices 를 빈 배열 [] 로, affectionDelta 를 0 으로 채워버립니다 — schema 는 통과하지만 비어 있는 응답이죠.

💡 한 줄 직관 — BeanOutputConverter 는 형식 을 강제하고, 시스템 프롬프트는 내용 을 강제한다. 둘이 짝이다.

컨트롤러까지 타입 흘려보내기 + 표준 응답 래핑

서비스가 record 를 반환하니, 컨트롤러도 record 를 그대로 받아 응답하면 됩니다. 다만 본 강의의 모든 새 컨트롤러는 표준 응답 래퍼 ApiResponse<T> 로 한 번 더 감싸요 — Step 2~4 의 데모 컨트롤러에서 봤던 그 패턴이에요.

import kr.spartaclub.aifriends.chat.dto.AiReply;
import kr.spartaclub.aifriends.common.response.ApiResponse;
import org.springframework.http.ResponseEntity;

@GetMapping("/api/chat/soulmate")
public ResponseEntity<ApiResponse<AiReply>> soulmate(
        @RequestParam Long userId,
        @RequestParam String mood,
        @RequestParam String message
) {
    String anonymizedName = userAnonymizer.anonymize(userId);
    AiReply reply = service.chat(anonymizedName, mood, message);
    return ResponseEntity.ok(ApiResponse.success(reply));
}

import 두 줄, 반환 타입 한 줄, 마지막 줄의 래핑 한 줄. 끝이에요. 익명화 로직(UserAnonymizer.anonymize) 은 Day 3 에서 박아둔 그대로 — 그쪽은 손댈 이유가 없어요. 응답 타입 한 군데가 바뀌면 그 타입을 흘려받는 모든 자리가 자동으로 따라온다 는 게 record 기반 흐름의 깔끔함이에요.

💡 왜 ApiResponse 로 또 감싸나요? GlobalExceptionHandler 가 모든 예외 응답을 자동으로 ApiResponse.fail(...) 로 감싸기 때문이에요. 정상 응답을 raw 로 두면 같은 엔드포인트가 정상 응답은 raw, 에러 응답은 {"success": false, ...} 형태로 비대칭이 됩니다. 표준 래핑 한 줄로 그 비대칭이 사라져요. Day 4 부터 만드는 모든 새 컨트롤러는 이 패턴을 따라요.

한 번 호출해봅시다 🚀

cd ai-friends
./run.sh up

curl "http://localhost:8080/api/chat/soulmate?userId=1&mood=우울&message=오늘 진짜 별로였어"

응답 (모델 따라 본문은 달라요).

{
  "success": true,
  "data": {
    "aiMessage": "에이, 무슨 일 있었어? 천천히 얘기해봐. 내가 들어줄게.",
    "choices": [
      "괜찮아, 그냥 좀 피곤해서",
      "사실 회사에서 일이 있었어",
      "잘 모르겠어, 그냥 우울해"
    ],
    "affectionDelta": 1
  }
}

data 안 세 필드가 모두 의미 있게 채워져서 떨어졌죠. record 의 형식 강제 + 시스템 프롬프트의 내용 가이드, 두 짝이 같이 일했기 때문이에요. 미연시 게임 프론트엔드는 이 JSON 한 덩어리만 받으면 data 를 꺼내서 화면에 캐릭터 대사 + 선택지 버튼 3 개 + 호감도 게이지 변화 애니메이션을 모두 띄울 수 있어요.

잠깐 — 레거시 GeminiService 는 어떻게 됐나?

여기서 한 가지 의문이 들 수 있어요.

"튜터님, Step 1 에서 까봤던 그 무거운 GeminiService — responseJsonSchema 손 조립 + ObjectMapper.readValue 30 줄 — 그건 안 걷어내나요? Day 3 마무리에서 'Day 4 에서 걷어낸다' 고 약속하셨잖아요?"

좋은 기억이에요. 정답은 — 오늘은 일부러 안 걷어냅니다. 이유 두 가지.

1. GeminiService 는 시스템 프롬프트가 풀 페르소나 (캐릭터의 성별·이름·성격·취미·말투 5 슬롯) 로 짜여 있어요. 단순히 .entity(AiReply.class) 로 갈아끼우는 것만으론 부족하고, 대화 이력 (이전 턴들) 까지 같이 흘려야 자연스러운 미연시 게임이 돼요.

그게 Day 5 ChatMemory 의 주제입니다.

2. Day 4 에서 모든 걸 다 걷어내면 학습 호흡이 너무 가팔라져요. 오늘은 "구조화 출력 도구를 손에 익히고, 가벼운 SoulmateChatService 부터 갈아끼운 다음, 그 패턴을 Day 5 의 ChatMemory 와 함께 본격 페르소나에 적용한다" 는 두 단계 작업으로 나누는 게 안전해요.

즉 오늘 만든 AiReply record 는 Day 5 까지 가는 다리 예요. 단순 케이스에서 패턴을 굳히고, 다음 Day 에서 본 도메인 풀 페르소나에 같은 패턴을 입힙니다. 한 턴씩 진도를 빼는 호흡이에요.

자, Step 5 까지 우리는 응답을 record 로 받는 깨끗한 길을 닦았어요. 그런데 운영 한 달째, PM 이 슬랙으로 이런 메시지를 던집니다.

"튜터님, 어제 새벽 3시에 30 분 동안 /api/chat/soulmate 가 5xx 응답률 12% 찍었어요. 로그 보니까 'Could not parse the given text...' 라는 예외가 줄줄이 떴고요. 모델이 가끔 형식을 안 지켜서 응답하나 봐요. 이거 어떻게 막죠?"

오늘 Step 6 의 정확한 주제입니다. Step 1 의 함정 ② "readValue try-catch 지옥" — 그 부분에 BeanOutputConverter 가 들어와서 코드는 깔끔해졌지만, 모델이 깨뜨려서 보내올 가능성 자체가 0% 가 된 건 아니에요. 그 0% 가 아닌 사건을 어떻게 다룰지가 오늘의 주제입니다.

모델이 JSON 을 깨뜨리는 진짜 사례

먼저 현실 감각을 잡고 갑시다. 실제로 운영 LLM 에서 관찰되는 깨짐 패턴은 이렇게 분류됩니다.

BeanOutputConverter 안의 ResponseTextCleaner 가 마크다운 펜스 같은 흔한 케이스 일부는 자동으로 정리해줘요.

하지만 자유 형식 응답 이나 JSON 자체 깨짐 은 정리할 도리가 없어 그대로 convert() 단계에서 깨집니다.

이때 던져지는 게 RuntimeException(JsonProcessingException) 이에요.

💡 확인하고 싶다면 — Spring AI 1.1.x 의 BeanOutputConverter.convert(String text) 소스를 보면 objectMapper.readValue(...) 호출이 JsonProcessingException 을 잡아 RuntimeException 으로 wrapping 해서 던지고 있어요. 즉 우리는 평범한 RuntimeException 으로 잡으면 됩니다.

복구 전략 3 축

이런 깨짐을 만났을 때 운영 코드가 취할 수 있는 자세는 크게 세 가지예요.

세 전략은 사용자 경험 ↔ 디버깅 가시성 사이의 트레이드오프예요.

• Retry + Fallback 결합 — 사용자에겐 항상 답이 가지만, 가끔 품질이 낮은 답이 갑니다. UX 우선.
• Strict — 사용자에겐 가끔 에러가 보이지만, 운영팀은 문제를 즉시 인지합니다. 운영 우선.

어느 시나리오에 어느 전략?

정리하면 결정 가이드는 이런 표입니다. 실제 면접에서도 자주 나오는 분류예요.

ai-friends 같은 미연시 게임은 첫째 줄에 가까워요. 호감도 변화량이 한 턴 잘못 나와도 게임이 멈추진 않으니 Retry + Fallback 결합 이 자연스러운 선택이에요. 단, 우리가 만든 데모 컨트롤러로 그 패턴을 손에 익혀봅시다.

데모 — recover-retry 엔드포인트

데모 컨트롤러에 메서드 하나를 더 얹어요. 실제 LLM 호출 없이 학습 시뮬레이션으로 가요. 진짜 LLM 호출에서 깨짐을 일관되게 재현하기는 어려워서, 이 시뮬레이션이 패턴을 명료하게 보는 데 더 좋아요.

상수 + 헬퍼

@Slf4j
@RestController
public class StructuredOutputDemoController {

    private static final Quote FALLBACK_QUOTE = new Quote(
            "지금은 명언을 가져올 수 없어요. 잠시 후 다시 시도해주세요.",
            "ai-friends");

    private static final String SIMULATED_VALID_RAW = """
            {"text":"용기는 두려움이 없는 것이 아니라, 두려움을 이겨내는 판단이다.","author":"넬슨 만델라"}
            """;

    private static final String SIMULATED_BROKEN_RAW =
            "이건 JSON 이 아니라 모델이 자유롭게 답해버린 평문입니다. 파싱 실패 시뮬레이션용.";

    // ... (기존 quote / quotes / keyword-counts 생략)
}

Retry → Fallback 결합 메서드

@GetMapping("/api/structured/quote/recover-retry")
public ResponseEntity<ApiResponse<Quote>> recoverWithRetryThenFallback(
        @RequestParam(defaultValue = "2") int simulatedFailures) {
    BeanOutputConverter<Quote> converter = new BeanOutputConverter<>(Quote.class);
    int maxAttempts = 3;

    for (int attempt = 1; attempt <= maxAttempts; attempt++) {
        // simulatedFailures 만큼 초반 시도는 일부러 깨뜨림. 이후엔 정상 응답.
        String simulated = (attempt <= simulatedFailures) ? SIMULATED_BROKEN_RAW : SIMULATED_VALID_RAW;
        try {
            Quote quote = converter.convert(simulated);
            log.info("recover-retry: attempt {}/{} succeeded", attempt, maxAttempts);
            return ResponseEntity.ok(ApiResponse.success(quote));
        } catch (RuntimeException e) {
            log.warn("recover-retry: attempt {}/{} failed: {}", attempt, maxAttempts, e.getMessage());
        }
    }

    log.warn("recover-retry: all {} attempts failed, returning fallback", maxAttempts);
    return ResponseEntity.ok(ApiResponse.success(FALLBACK_QUOTE));
}

핵심을 두 군데로 압축할 수 있어요.

1. for 루프 + try-catch — 한 번 실패해도 다음 시도로 진행. 성공하면 즉시 return.
2. 루프를 빠져나오면 fallback — 모든 attempt 가 실패해야만 fallback 으로 떨어짐. 사용자한테는 항상 200 OK.

💡 왜 @Retryable (Spring Retry) 같은 라이브러리를 안 쓰나요? 의존성 추가 + 어노테이션 + 별도 컨피그가 필요해서 학습 비용이 커요. 또 Spring AI 1.1.x 는 spring.ai.retry.* 자동 설정 으로 ChatModel 레벨에서 RetryTemplate 을 박아주는 길이 따로 있어요 — application.yml 한 줄(예: spring.ai.retry.max-attempts=3) 이면 ChatModel 호출 자체에 재시도가 자동으로 깔립니다. 운영 정책 (써킷브레이커 · Rate Limit · 캐싱) 과 묶이는 본격 학습은 Day 19 Harness 엔지니어링 의 주제예요. 오늘은 그 자동화 뒤에서 어떤 로직이 도는지 손으로 한 번 짜보는 데 의미를 둡니다.

한 번 돌려봅시다 🚀

# 시뮬레이션: 첫 2회 실패 → 3번째 성공
curl "http://localhost:8080/api/structured/quote/recover-retry?simulatedFailures=2"

{
  "success": true,
  "data": {
    "text": "용기는 두려움이 없는 것이 아니라, 두려움을 이겨내는 판단이다.",
    "author": "넬슨 만델라"
  }
}

# 시뮬레이션: 모든 3회 실패 → fallback 으로 떨어짐
curl "http://localhost:8080/api/structured/quote/recover-retry?simulatedFailures=3"

{
  "success": true,
  "data": {
    "text": "지금은 명언을 가져올 수 없어요. 잠시 후 다시 시도해주세요.",
    "author": "ai-friends"
  }
}

두 응답 모두 200 OK + success: true 예요. 사용자한테는 흐름이 끊기지 않고 답이 가는데, 두 번째 응답에선 author 가 ai-friends 로 박혀서 운영팀이 "아, 이건 fallback 이구나" 를 식별할 수 있어요. 로그도 동시에 떨어지죠.

WARN  recover-retry: attempt 1/3 failed: com.fasterxml.jackson.core.JsonParseException: ...
WARN  recover-retry: attempt 2/3 failed: ...
WARN  recover-retry: attempt 3/3 failed: ...
WARN  recover-retry: all 3 attempts failed, returning fallback

운영에선 위 로그 패턴을 모니터링 도구(예: Elastic, Grafana Loki) 에서 "all attempts failed" 로 카운트 잡아서 알림 거는 게 표준이에요. 사용자엔 침묵, 운영엔 신호 — 이 분리가 fallback 정책의 핵심이에요. 🚨

Strict 모드는 어떻게 짜나?

코드는 안 박지만 패턴만 보여드릴게요. Strict 는 try-catch 자체를 걷어내거나, 잡되 즉시 도메인 예외로 변환해서 던지면 끝이에요.

// 의사코드 — 시연 엔드포인트 추가하지 않습니다 (개념만)
public Quote recoverStrict() {
    BeanOutputConverter<Quote> converter = new BeanOutputConverter<>(Quote.class);
    try {
        return converter.convert(maybeBrokenRaw);
    } catch (RuntimeException e) {
        // GlobalExceptionHandler 가 ApiResponse.fail(...) 으로 5xx 응답을 떨어뜨려준다.
        throw new BusinessException(ErrorCode.AI_RESPONSE_INVALID);
    }
}

이 흐름의 응답은 자연스럽게 5xx + ApiResponse.fail 모양이 됩니다.

{
  "success": false,
  "error": {
    "status": 500,
    "code": "...",
    "message": "..."
  }
}

사용자 앱은 에러 화면을 띄우고, 운영팀은 5xx 메트릭으로 즉시 인지해요. 결제·주문·인증 같은 도메인이면 이 정책이 정답에 가깝습니다.

우리 ai-friends 의 정책 결정

자 이제 ai-friends 도메인 (미연시 게임) 의 정책을 어떻게 잡을지 한 번 정리해봅시다.

오늘 우리가 짠 SoulmateChatService.chat(...) 은 첫 줄 시나리오 — 그러니까 retry → fallback 이 가장 자연스러워요. 다만 오늘 그 적용을 손대지 않습니다. 이유는 두 가지.

1. Spring AI 자동 RetryTemplate 으로 한 줄에 깔립니다. application.yml 의 spring.ai.retry.max-attempts=3 한 줄이면 ChatModel 호출 자체에 재시도가 박혀요. 미리 손으로 짜두면 그걸 다시 들어내는 작업이 됩니다.
2. 운영 정책과 묶이는 본격 학습은 Day 19 Harness. retry · 써킷브레이커 · Rate Limit · 캐싱이 한 곳에서 정돈돼요. 손 코딩 retry 가 거기서 어떻게 선언적으로 줄어드는지 직접 비교합니다.

오늘은 데모 트랙 (recover-retry 엔드포인트) 으로 패턴만 익히고, 본 도메인 적용은 위 두 길로 미루는 호흡이에요. 손으로 한 번 짜본 패턴이 한 줄 설정 / 운영 정책 묶음으로 줄어드는 걸 봐야 "역시 자동화·운영 추상화의 가치가 이만큼이구나" 라는 감각이 깊게 박혀요.

💡 튜터의 결론

Step 6 의 한 문장 요약은 이래요.

"BeanOutputConverter 가 들어와도 깨짐의 가능성이 0 이 되진 않는다. 그래서 retry · fallback · strict 의 트레이드오프 위에서 우리 도메인의 정책을 의식적으로 고른다."

오늘 짚은 결정 변수를 한 표로 정리하면:

남은 한 Step (Step 7) 은 가벼워요. 스키마 크기 ↔ 토큰 비용 — record 를 어디까지 풍부하게 만들어도 되는지의 손익분기점 감각. 그리고 마무리. 거의 다 왔습니다.

자, 깨짐의 길까지 정돈했으니 마지막으로 얼마나 풍부하게 만들지 의 감각만 잡으면 끝이에요. Step 7 로 갈까요?

자, Step 5 에서 우리가 만든 AiReply 는 3 필드 였어요 — aiMessage, choices, affectionDelta. 깔끔하죠. 그런데 운영을 시작한 PM 이 또 슬랙을 던집니다.

"튜터님, 한 턴에 캐릭터 표정(emotion), 배경 음악 추천(backgroundMusic), 다음 씬 묘사(sceneDescription), 캐릭터 포즈(characterPose), 대화 종료 신호(shouldEndConversation)... 다 같이 받으면 안 될까요? 한 호출로 다 끝내면 프론트가 정말 깔끔할 것 같은데요."

기능적으로는 가능해요. record 에 필드만 추가하면 되니까. 그런데 이게 그렇게 공짜가 아니에요. 오늘 마지막 Step 은 그 비용 — 스키마가 부풀어 오를수록 매 호출마다 추가로 들어가는 토큰의 비용 — 의 감각을 잡는 시간입니다.

잠깐 — schema 가 비용에 어떻게 잡히는가?

Step 3 에서 봤죠. BeanOutputConverter 는 getFormat() 결과를 사용자 프롬프트 끝에 자동으로 붙여서 LLM 한테 보냅니다. 즉 record 가 만들어내는 JSON Schema 텍스트가 매 호출마다 입력 토큰 으로 들어가요.

| 호출 1 회의 입력 토큰 = | 시스템 프롬프트 + 사용자 메시지 + getFormat() 의 schema 텍스트 |

여기서 schema 텍스트의 크기가 record 의 풍부함에 따라 변합니다. 그리고 입력 토큰은 모델 단가에 따라 직접 비용으로 환산됩니다 — 호출량이 많아질수록 schema 1 byte 가 진짜 돈이 돼요.

직접 비교해보자 — /schema-size 디버그 엔드포인트

데모 컨트롤러에 비교용 record 3 개를 inner 로 박아두고, 한 엔드포인트가 셋의 schema 크기를 한꺼번에 보여주게 했어요. LLM 호출 없는 학습 보조 출력이에요 (Step 3 의 format-debug 와 같은 톤).

public record QuoteMini(String text, String author) { }

public record AiReplyLike(String aiMessage, List<String> choices, int affectionDelta) { }

public record AiReplyBig(
        String aiMessage,
        List<String> choices,
        int affectionDelta,
        String emotion,
        String backgroundMusic,
        List<String> tags,
        int turnNumber,
        String sceneDescription,
        String characterPose,
        boolean shouldEndConversation,
        Map<String, Integer> additionalStats
) { }

@GetMapping(value = "/api/structured/schema-size", produces = MediaType.TEXT_PLAIN_VALUE)
public String schemaSize() {
    StringBuilder sb = new StringBuilder();
    appendSchemaInfo(sb, "QuoteMini  (2 fields)",                     QuoteMini.class);
    appendSchemaInfo(sb, "AiReplyLike (3 fields, incl. List)",        AiReplyLike.class);
    appendSchemaInfo(sb, "AiReplyBig (11 fields, incl. List + Map)",  AiReplyBig.class);
    return sb.toString();
}

private void appendSchemaInfo(StringBuilder sb, String label, Class<?> clazz) {
    BeanOutputConverter<?> converter = new BeanOutputConverter<>(clazz);
    String schema = converter.getJsonSchema();
    int bytes = schema.getBytes().length;
    int approxTokens = (int) Math.ceil(bytes / 4.0);   // 1 token ≈ 4 bytes 휴리스틱
    sb.append("=== ").append(label).append(" ===\n");
    sb.append(schema).append('\n');
    sb.append("length: ").append(bytes).append(" bytes  ≈  ")
            .append(approxTokens).append(" tokens (estimated, English-heavy heuristic)\n\n");
}

bytes / 4.0 은 영어/JSON 위주 텍스트의 거친 토큰 환산 휴리스틱이에요. OpenAI 의 BPE 토크나이저 기준으로 영어는 평균 4 바이트당 1 토큰 정도. 정확한 값은 토크나이저 (Gemini 의 SentencePiece, GPT 의 o200k_base 등) 마다 달라요. 어디까지나 감각 잡기용 근사치예요.

실제 측정 결과

호출해보면 이렇게 떨어져요.

curl http://localhost:8080/api/structured/schema-size

세 개 schema 의 측정값을 표로 정리하면:

핵심 관찰 두 가지.

1. 필드 1 개 → 3 개 (+List) 로 가는 비용은 50% 증가 — 별로 안 큼. 우리 AiReply 정도는 합리적 풍부함이에요.
2. 3 개 → 11 개 (+List + Map) 로 가면 2.5 배 — 매 호출마다 추가로 132 tokens 가 들어가요. 이게 호출 수 × 모델 단가로 곱해지면 슬슬 비용이 보이기 시작해요.

비용으로 환산해보자

매 호출마다 추가되는 132 tokens 를 실제 돈으로 환산해봅시다. 2026 5월 기준 입력 토큰 단가는 이래요.

월 호출량 시나리오로 곱해보면 (유료 단가 기준):

뭔가 작아 보이죠? 그런데 위 숫자는 추가 132 tokens 만 잡은 거예요.

실제론 응답 토큰 (출력) 도 같이 늘고 — record 가 풍부하면 모델이 채워야 할 양도 그만큼 커요 (Gemini 2.5 Flash 의 출력 단가는 $2.50/1M 으로 입력의 8배 가까이 비싸요).

그리고 GPT-4o 보다 훨씬 비싼 프런티어 모델 (Claude 4.x Opus, GPT-4.1 Pro 등) 을 쓰면 단가가 5~10 배 또 뜁니다.

💡 한 줄 직관 — Gemini 2.5 Flash 무료 티어에선 schema 비대화가 별로 안 보이지만, 유료 전환 + 대규모 트래픽 으로 가는 순간 schema 1 byte 가 진짜 비용이 돼요. 우리 ai-friends 같은 학습 단계에선 무료 티어 안에서 여유롭게 키워도 되지만, 운영 단계에선 의식적으로 절제할 줄 알아야 해요.

그럼 어디까지 키워도 되나? 🎯

실무 가이드를 표로 정리하면 이래요.

ai-friends 의 AiReply (3 필드) 는 첫째 줄에 들어가요. 만약 PM 이 위 11 필드 요구를 들고 오면 우리가 "다음 두 가지 중 하나로 분리합시다" 라고 답할 수 있어야 해요.

1. 호출을 두 개로 쪼개기 — aiMessage + choices + affectionDelta 는 매 턴, emotion + backgroundMusic + tags 는 5 턴마다 한 번 같은 식으로
2. lazy 필드 분리 — 매 턴 받는 핵심 응답엔 Mini 만, 추가 정보가 필요할 때 별도 endpoint 호출

이게 운영 감각이에요 — "기능이 가능한가" 가 아니라 "이 비용을 매 호출마다 낼 가치가 있는가" 로 묻는 습관.

모델 응답 품질에도 영향이 있어요 ⚠️

비용 외에 한 가지 더 — schema 가 너무 커지면 모델 응답 품질도 떨어져요. 직관적으론 이상하지만 이유는 명확해요.

1. 모델의 attention 이 분산됨 — 11 개 필드를 채우라고 요구하면 모델이 한 필드당 쓸 수 있는 "주의" 가 그만큼 줄어요. 핵심 필드 (aiMessage) 의 품질이 미세하게 떨어집니다.
2. 모델의 "JSON 채우기 모드" 가 강해짐 — 자유로운 창의성보다 "11 개 필드를 다 채워야 해" 라는 강박이 우세해져서 응답이 형식적이 돼요. 캐릭터 톤이 살짝 무뚝뚝해질 수 있어요.
3. 에러 발생률 미세 증가 — 필드가 많아질수록 모델이 한 필드를 빠뜨리거나 잘못 채울 확률도 누적적으로 증가해요. Step 6 의 retry 정책이 더 자주 작동하게 됨.

이 셋이 합쳐지면 "응답을 풍부하게 받으려고 record 를 키웠는데 오히려 응답이 무뚝뚝해지는" 역설이 일어날 수 있어요. 실측해보지 않으면 못 잡는 함정이에요.

💡 튜터의 결론

Step 7 의 한 문장 요약은 이래요.

"record 의 풍부함은 공짜가 아니다. 매 호출마다 schema 만큼의 입력 토큰이 따라간다. 우리 도메인엔 2~3 필드가 스윗 스팟."

7 단계를 모두 거친 우리의 도구 상자를 한 번 정리해봅시다.

이 7 가지가 손에 다 들어왔다면 오늘 Day 4 의 학습 목표는 모두 달성한 거예요. LLM 응답을 타입 안전한 record 로 받고, 깨짐을 우아하게 복구하고, 비용까지 의식하는 운영 감각 까지 한 번에 꿰뚫어본 하루였어요.

이제 마무리 섹션으로 넘어가서 회고하고, 브랜치를 보존하고, 다음 시간 (Day 5) ChatMemory 의 풍경을 살짝 미리 보여드릴게요. 도구를 다 챙겼으니 이젠 대화의 흐름 을 만들 차례입니다.

오늘의 여정 한눈에

Day 4 의 3 시간을 한 문장으로 요약하면 — "LLM 응답을 String 이 아니라 Record 로 받기 시작한 하루" 였어요.

이 7 개를 다 외우라는 게 아니에요. "record 가 진실의 원본" 과 "풍부함은 공짜가 아니다" 두 문장만 3 개월 뒤에도 기억하시면 오늘 수업은 성공이에요.

Day 5 예고 — "ChatMemory: 대화의 흐름을 만들기"

오늘 우리가 만든 SoulmateChatService.chat(...) 을 다시 한 번 떠올려 봅시다.

public AiReply chat(String anonymizedUserName, String mood, String userMessage) {
    return soulmateChatClient.prompt()
            .system(...)
            .user(userMessage)
            .call()
            .entity(AiReply.class);
}

자, 한 가지 질문 — 이 메서드를 같은 사용자가 두 번 연달아 호출하면 어떻게 될까요?

호출 1) 사용자: "오늘 진짜 별로였어"
모델:  "에이, 무슨 일 있었어? 천천히 얘기해봐."

호출 2) 사용자: "사실 회사에서 일이 있었어"
모델:  ???

모델은 두 번째 호출에서 첫 번째 대화를 전혀 기억하지 못해요. 매 호출이 독립적인 stateless 호출이니까요. "사실 회사에서 일이 있었어" 라는 문장만 받으면 모델은 "어디 회사? 무슨 일? 무엇에 대한 답?" 을 모릅니다. 미연시 게임 도메인에서 이건 치명적이에요. 캐릭터가 매 턴마다 처음 만난 사람처럼 행동하면 게임이 안 되거든요.

Day 5 의 주제가 정확히 이 문제예요 — ChatMemory.

// Day 5 에서 만날 모양 (오늘은 코드에 넣지 않습니다 — 개념 예고)
chatClient.prompt()
        .advisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
        .user(userMessage)
        .call()
        .entity(AiReply.class);

Advisor 라는 새 도구가 등장해요. ChatMemory 가 MessageChatMemoryAdvisor 한 줄로 들어오면서 Day 4 의 .entity(AiReply.class) 패턴이 대화 이력 위에서도 그대로 살아남는 풍경이에요. Day 4 의 도구들이 Advisor 라는 더 큰 추상화 위에 자연스럽게 합류하는 거죠.

💡 Day 5 마무리 시점 예고 — 위 chat(name, mood, msg) 시그니처는 Day 5 Step 5 에서 학습용 lab 으로 conversationId 를 한 인자 더 받게 자라요. 그리고 Day 5 Step 6 에서는 도메인 정합 prod 시그니처 chat(soulmateId, msg) 로 한 번 더 자라요. 그 단계에서 오늘 미뤄둔 GeminiService 30 줄 들어내기 약속도 같이 회수돼요. lab 이 prod 를 흡수하는 수렴 Day 가 다음 시간이에요.

Day 5 에서 다룰 것:

• ChatMemory 인터페이스 + JdbcChatMemoryRepository 영속화 (서버 재시작해도 대화 살아남음)
• MessageWindowChatMemory — sliding window 로 토큰 윈도우 관리
• MessageChatMemoryAdvisor — 대화 이력을 자동으로 프롬프트에 주입
• conversationId 기반 세션 격리 — 사용자별·세션별 대화 분리
• 레거시 GeminiService 의 시스템 프롬프트 + RestClient 수동 호출을 완전히 들어내고 ChatMemory 기반 본 페르소나 서비스로 통합

Day 4 의 빈 공간(레거시 GeminiService 수동 파싱) 을 ChatMemory 와 함께 채우러 갑니다.

Step 6 의 손 코딩 retry 는 별개 트랙 — application.yml 의 spring.ai.retry.* 한 줄로도 즉시 ChatModel 레벨에 깔리고, 운영 정책(써킷브레이커·Rate Limit·캐싱) 과 묶이는 본격 학습은 Day 19 Harness 엔지니어링 의 주제예요.

Day 5 수렴 로드맵 — lab 이 prod 를 흡수하는 마지막 코너

Day 5 예고를 봤으니, 이제 이 lab 이 어디서 끝맺어지는지 못박을 차례입니다.

Day 3 마무리에서 깔아둔 약속을 다시 펴볼게요 — "SoulmateChatController 는 학습용 lab 이고, Day 5 마무리 시점에 기존 AiChatController 의 백엔드를 흡수한다".

Day 4 가 끝난 지금, 그 lab 이 한 단계 더 자랐어요 (AiReply record 반환).

다음 한 코너가 마지막 흡수입니다.

[구현 1] hello-ai/v3 엔드포인트에 구조화 출력 + 복구 전략 적용해보기

배경 시나리오

Day 3 에서 우리는 hello-ai/v3 라는 튜터 페르소나 엔드포인트를 만들었어요. 평문 String 답변을 돌려주는 단순한 형태였죠. 한 달 후 PM 이 또 슬랙을 던집니다.

"튜터님, 학생들이 답변을 받고 나면 '그럼 다음 질문은 뭘 해볼까?' 를 망설이는 데이터가 보여요. 튜터 답변 옆에 추천 후속 질문 2~3 개 도 같이 받을 수 있을까요? 프론트가 그걸 칩(chip) 으로 보여주면 학생이 바로 클릭해서 다음 대화로 이어갈 수 있을 것 같은데요."

전형적인 단일 String → 구조화 record 전환 요구예요. 오늘 Step 5 에서 SoulmateChatService 에 했던 작업을 hello-ai/v3 에도 그대로 굴려보세요.

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

1. 오늘 배운 패턴 굳히기 — .entity(Class<T>) + ApiResponse 래핑 + retry → fallback 까지의 전 과정을 다른 도메인에 한 번 더 적용하면서 패턴이 익숙해집니다.
2. 이전 Day 자산을 부수지 않고 확장 — Day 3 의 tutor-v1.st 외부 프롬프트와 PromptTemplate 슬롯을 그대로 쓰면서 응답 구조만 갈아엎는 경험. "기존 자산 재사용 + 새 도구 도입" 의 실무 호흡을 굳혀요.

✅ 요구사항

1. 새 응답 record 정의 (예: kr.spartaclub.aifriends.hello.dto.TutorReply)
   • 필드: String answer (튜터 답변), List<String> suggestedQuestions (추천 후속 질문 2~3 개)
   • record 위치는 hello/dto/ 패키지로 신설 (chat 의 chat/dto/ 와 동일 패턴)
2. HelloAiV3Controller (또는 같은 자리의 컨트롤러) 수정
   • 반환 타입: String → ResponseEntity<ApiResponse<TutorReply>>
   • ChatClient 호출: .call().content() → .call().entity(TutorReply.class)
3. 시스템 프롬프트 보강
   • tutor-v1.st (또는 같은 위치) 의 Format 섹션에 "답변 후, 학생이 이어서 던질 만한 후속 질문 2~3 개를 함께 제안해" 한두 줄 추가
   • 스키마 자체는 BeanOutputConverter 가 자동 주입하지만, 각 필드를 어떻게 채울지 의 의미는 시스템 프롬프트가 알려줘야 합니다 (Step 5 의 "형식 ↔ 내용 짝" 원칙)
4. retry → fallback 적용
   • 컨트롤러 안에 (또는 helper 메서드로) Step 6 의 recover-retry 패턴 그대로 적용 — 최대 3 회 재시도, 모두 실패하면 fallback TutorReply 반환
   • Fallback 의 answer 는 "지금 답을 만들 수 없어요. 잠시 후 다시 질문해주세요." 같은 솔직한 안내, suggestedQuestions 는 빈 리스트
5. 테스트 갱신
   • 기존 컨트롤러 테스트의 content().string(...) 어설션을 jsonPath("$.data.answer") / jsonPath("$.data.suggestedQuestions") 로 변경
   • retry → fallback 시나리오를 의도적으로 시뮬레이션하는 테스트 1 건 추가 (Step 6 의 임시 dump 테스트 패턴 참고)

확인 방법

./run.sh up

# 정상 호출 — 답변 + 추천 질문이 같이 떨어지는지
curl "http://localhost:8080/api/hello-ai/v3?message=의존성 주입이 뭔가요?"

응답이 다음 형태로 떨어지면 통과예요. ✅

{
  "success": true,
  "data": {
    "answer": "의존성 주입은 객체가 필요한 의존 객체를 직접 만들지 않고 외부에서 받아 쓰는 패턴이에요. ...",
    "suggestedQuestions": [
      "그럼 의존성 주입을 안 쓰면 뭐가 안 좋나요?",
      "Spring 에선 어떻게 자동으로 주입해주나요?",
      "생성자 주입과 필드 주입 중 뭐가 더 좋나요?"
    ]
  }
}

제약 / 금지

• 오늘 안 배운 기술 사용 금지 — Advisor (Day 5), ChatMemory (Day 5), @Retryable, Spring Retry 라이브러리, spring.ai.retry.* 자동 RetryTemplate (Day 19 Harness), Resilience4j (Day 19 Harness) 모두 금지. 오늘 배운 .entity(Class<T>) + 손 코딩 retry/fallback + ApiResponse 만으로 풀어요.
• 시스템 프롬프트의 Format 섹션을 자연어 JSON 명세로 손 조립하지 마세요. record 의 BeanOutputConverter 가 schema 를 자동 주입하니, Format 섹션엔 "각 필드의 의미" 만 자연어로 적습니다.
• 응답을 ApiResponse 로 래핑하지 않고 raw record 로 반환하지 마세요. 본 강의 표준 — 모든 새 컨트롤러는 ApiResponse 래핑.

[구현 2] schema 비대화의 손익분기점 직접 측정해보기

배경 시나리오

Step 7 에서 우리는 QuoteMini (2 필드) → AiReplyBig (11 필드) 사이 schema 가 약 3.7 배 커지는 걸 봤어요. 그런데 "그럼 우리 도메인에선 정확히 어디가 손익분기점인가?" 는 여전히 감각적인 답이었죠. 이번 과제에선 직접 숫자로 그 손익분기점을 그려봅니다.

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

1. 추측을 측정으로 바꾸기 — "응답을 풍부하게 받자" 라는 PM 의 요구에 우리가 "이 비용이 따라옵니다, 표 보세요" 라고 숫자로 답할 수 있어야 합니다. 운영 의사결정의 무게는 측정에서 나와요.
2. trade-off 의 비선형성 체감 — 필드 수와 schema bytes 의 관계는 단순 비례가 아니에요. List, Map, nested record 등이 추가되면 비선형적으로 부풀어 오릅니다. 직접 측정하지 않으면 못 잡는 감각이에요.

✅ 요구사항

1. 5 단계 record 만들기 — 데모 컨트롤러나 별도 학습 패키지에 inner record 5 개 추가
   • Step 1: 2 필드 (String × 2) — Quote 같은 단순체
   • Step 2: 4 필드 (String × 3 + int × 1)
   • Step 3: 8 필드 (String × 5 + int × 2 + boolean × 1)
   • Step 4: 16 필드 (위 + List × 2 + nested record × 2)
   • Step 5: 32 필드 (위 + Map × 2 + enum × 2 — Java 의 enum 으로)
2. 측정 엔드포인트 — GET /api/structured/schema-size-extended 같은 디버그 평문 엔드포인트 (Step 7 의 schema-size 패턴 그대로)
   • 5 단계 record 각각의 getJsonSchema() 길이를 출력
   • 정수 추정 토큰 수도 함께 (Step 7 의 bytes / 4 휴리스틱)
   • Mini 대비 배수도 함께 출력
3. (선택) 실제 LLM 호출 latency 측정 — 5 단계 record 각각으로 동일 사용자 메시지를 LLM 한테 보내고 응답 시간을 측정
   • 각 단계 3 회씩 호출, 평균 지연 시간 기록
   • 모델 호출 비용 발생하니 무료 Gemini Flash 한 모델만 쓰세요. 강의 실습 비용 정책 (CLAUDE.md 3 번) 준수
4. 결과 보고 — markdown 표 한 장 + 짧은 분석 (3 줄 정도)

확인 방법

curl http://localhost:8080/api/structured/schema-size-extended

출력에서 다음 표를 손으로 옮겨 정리하세요.

표 아래에 "우리 도메인의 손익분기점은 X 필드" 같은 결론을 한두 문장으로 적으세요.

제약 / 금지

• 유료 모델 사용 금지 — 측정에 GPT-4o, Claude 4.x Sonnet 같은 유료 모델 쓰지 마세요. Gemini 2.5 Flash 무료 티어로 충분.
• 응답 토큰까지 측정하려고 하지 마세요. 응답 토큰 측정엔 별도 토크나이저 라이브러리가 필요해서 학습 호흡이 깨집니다. schema 입력 토큰의 부풀어 오름 한 가지에만 집중.

이 섹션의 목적 — 정답이 정해져 있지 않은 질문들이에요. 오늘 배운 내용에서 한 발 떨어져 "만약 나라면 어떻게 할까?" 를 스스로 정리해보는 시간. 각 주제마다 5~10 분씩, 가능하면 문장으로 적어보세요. 머릿속 생각과 글로 적은 생각은 다릅니다.

주제 1 — JSON Schema 강제력의 한계, 우리는 어디까지 모델을 신뢰할 것인가?

오늘 Step 3 에서 봤듯이 BeanOutputConverter 는 schema 텍스트를 프롬프트에 자동으로 끼워넣어요. 이건 자연어 instruction 이지 하드 강제 가 아니에요. 즉 모델이 "이번엔 무시하고 자유롭게 답해야겠다" 라고 결정하면 깨질 수 있는 약속이에요.

업계엔 이걸 더 강하게 강제하는 옵션도 있어요.

• OpenAI response_format: { type: "json_schema", strict: true } — API 레벨에서 schema 적합성을 토큰 생성 단계에서 강제. 응답이 schema 를 100% 만족
• Gemini responseMimeType: application/json + responseSchema — 비슷한 강도의 모델 측 강제

🎯 핵심 질문 — 우리 ai-friends 같은 캐주얼 게임 도메인에서 강한 schema 강제 (네이티브 JSON 모드) 와 약한 강제 (BeanOutputConverter 자동 instruction) 중 어느 쪽이 더 적절할까요? 그 결정에 영향을 주는 변수는 무엇일까요?

직관적으론 "강한 강제가 항상 좋은 거 아닌가?" 같지만, 실제론 트레이드오프가 있어요.

• 강한 강제 — 응답 형식의 100% 보장. 다만 모델의 창의성/표현력 미세 저하 가 보고됨. 또 프로바이더에 묶임 (OpenAI 의 strict 와 Gemini 의 responseSchema 형식이 다름 — Day 2 추상화 정신과 충돌)
• 약한 강제 — 형식 보장은 95~99%. 창의성 보존. 프로바이더 중립 (Spring AI 추상화에서 자연스럽게 동작). 깨질 0~5% 를 retry/fallback 으로 흡수

도메인 성격 (캐주얼 vs 트랜잭션) · 깨짐의 비용 · 프로바이더 lock-in 의 부담 · 응답 창의성의 가치 등 여러 변수가 얽혀요. 여러분 도메인에선 어떤 변수가 결정을 뒤집는지 구체적으로 적어보세요.

주제 2 — Fallback 응답의 정직성 — 사용자에게 "이건 fallback" 임을 알려야 하나?

Step 6 의 recover-retry 시연에서 우리는 fallback Quote 의 author 를 "ai-friends" 로 박아둬서 운영팀이 식별할 수 있게 했어요. 그런데 사용자한테는 이 응답이 fallback 이라는 사실을 어떻게 알릴지 (또는 알리지 않을지) 가 별개의 문제예요.

• (A) 위장 fallback — 사용자는 일반 응답과 구분 못 함. UX 끊기지 않음. 단 fallback 이 누적되면 "AI 가 답하는 척만 한다" 는 의심 발생 가능
• (B) 솔직한 fallback — 응답에 명시적 표지 (예: "isFallback": true, "잠시 후 다시 시도해주세요" 라는 안내) 가 박힘. 사용자가 즉시 인지하지만 흐름이 끊김
• (C) 부분 위장 — 사용자에겐 자연스러운 톤으로 보이되, 응답 메타데이터에 fallback flag 박아 운영팀만 식별 가능

🎯 핵심 질문 — 여러분이 운영하는 미연시 게임 (ai-friends) 의 사용자에게 fallback 응답을 어떻게 표현하시겠어요? 그 결정 뒤에 어떤 윤리·UX·운영의 고민이 있나요?

이 주제는 단순한 기술 결정을 넘어 AI 시스템의 신뢰성 정직성 의 영역이에요. 의료·법률·금융 도메인에선 정직한 fallback 이 거의 필수 (틀린 답을 정답처럼 주면 사용자 피해 큼). 반면 추천·엔터테인먼트 도메인에선 위장 fallback 이 더 자연스러울 수 있어요. ai-friends 가 어디 위치하는지부터 정해보세요.

주제 3 — 모델의 자율성 vs schema 의 강제, 균형을 어디에?

Step 7 에서 봤듯이 record 가 풍부할수록 schema 가 부풀어 오르고, 모델의 attention 이 분산돼요. 반대로 record 가 빈약하면 응답이 뭉뚱그려져서 후속 처리가 어려워져요. 풍부함과 빈약함 사이 적정선 이 도메인마다 다르다는 게 오늘 결론이었죠.

이걸 더 깊게 들여다보면 — "모델한테 무엇을 결정하게 둘 것인가" 의 자율성 문제로 이어집니다.

• schema 가 모든 필드를 강제하면 — 모델은 "11 개 빈 칸을 채우는 작업자" 가 됩니다. 자율성 0%. 응답 일관성 ↑, 창의성 ↓
• schema 를 핵심 1~2 필드로만 좁히면 — 모델한테 "어떤 정보를 응답에 담을지" 의 결정권이 일부 넘어갑니다. 자율성 ↑, 응답 일관성 ↓
• 두 응답 모드를 시나리오별로 분기 — 정형 시나리오 (호감도 정산) 는 강한 schema, 자유 대화 (캐주얼 한 턴) 는 약한 schema. 가장 정교하지만 코드 복잡성 증가

🎯 핵심 질문 — 여러분이 LLM 기반 시스템을 설계할 때 "모델한테 자율성을 얼마나 줄 것인가" 의 기준선을 무엇으로 잡으시겠어요? 그 기준선이 도메인별·시나리오별로 어떻게 달라져야 할까요?

이 질문엔 정답이 없어요. 하지만 "의식적으로 결정한 자율성 기준선" 이 있는 시스템은 그렇지 않은 시스템보다 운영 안정성이 항상 더 높습니다. 여러분의 도메인 (ai-friends 든, 본인 사이드 프로젝트든) 에서 이 기준선을 한 번 명시적으로 적어보세요. 적어보지 않으면 무의식 중에 "기본값" 으로 굳어지거든요.