Day 16. RAG 심화 — "5 부품 위에 advisor 하나로 자동 RAG 가 도는 첫 시간"

도입부에서 우리가 잡아둔 큰 그림 기억나시죠? Day 15 의 5 부품 위에 advisor 하나가 자동 결합되면 ChatClient 안에서 검색→프롬프트 끼움이 알아서 돈다는 이야기였어요. 이번 Step 에서는 그 "한 장" 이 실제로 어떻게 생겼고, 비즈니스 ChatClient 옆에 어떻게 흘러 들어가는지 확실히 이해할 수 있게 들여다봐요.

오프닝에서 우리가 잡아둔 큰 그림 기억나시죠? Day 15 의 5 부품 위에 advisor 하나가 자동 결합되면 ChatClient 안에서 검색→프롬프트 끼움이 알아서 돈다는 이야기였어요. 이번 Step 에서는 그 "한 장" 이 실제로 어떻게 생겼고, 비즈니스 ChatClient 옆에 어떻게 흘러 들어가는지 확실히 이해할 수 있게 들여다봐요.

흐름은 단순해요. Spring AI 가 제공하는 RAG advisor 가 두 길로 있는데, 우리는 그 중 하나를 prod 에 등록해요. 그 advisor 를 빈으로 정의하고, ChatClient 의 defaultAdvisors 에 합류시키는 룰이에요. 이 두 손짓이 끝나면 SoulmateChatService.chat() 한 줄이 호출될 때 외부 지식이 자동으로 끼워져요.

두 advisor 비교 — Naive RAG vs Modular RAG

Spring AI 1.1 에는 RAG advisor 가 두 종류 들어 있어요. 두 advisor 모두 같은 vectorStore 를 받아서 유사도 검색을 돌리는데, 제공하는 확장점의 갯수가 달라요.

우리는 후자를 prod 에 둬요. 이유는 한 줄 — 다음 시간 MCP 가 같은 advisor 라는 끼움점으로 들어오는데, advisor 가 모듈 합성 구조여야 그 확장이 자연스럽게 열려요. 게다가 Spring AI 공식 문서도 신규 프로젝트는 Modular RAG 쪽을 권장하는 흐름이에요.

spring-ai-rag 의존성 한 줄 — RAG 모듈은 별도 artifact

Day 15 까지는 spring-ai-starter-vector-store-pgvector 하나가 임베딩 모델 자동 구성 + pgvector 빈까지 끌고 와줬어요. 그런데 RAG advisor 와 retriever/augmenter 같은 파이프라인 모듈은 별도 artifact 에 들어 있어요. Spring AI 1.1.0 부터의 정리예요 — 검색 자체와 RAG 파이프라인을 분리해서 의존성 표면을 깔끔하게 가져가는 과정이죠.

// lecture-source-code/ai-friends/build.gradle (L64)
implementation 'org.springframework.ai:spring-ai-rag'

이 한 줄로 RetrievalAugmentationAdvisor · VectorStoreDocumentRetriever · ContextualQueryAugmenter 세 클래스가 한 번에 따라와요. 빌드 도구가 ./gradlew bootRun 직전에 의존성을 한 번 받아주면 다음 단계로 넘어갈 수 있어요.

RagAdvisorConfig — advisor 하나의 실체

이제 advisor 빈을 등록할 차례예요. kr.spartaclub.aifriends.rag.config.RagAdvisorConfig 클래스 에 RAG advisor 의 형태이 다 들어가요. 핵심 빈 메서드를 펼쳐 볼게요.

// kr.spartaclub.aifriends.rag.config.RagAdvisorConfig
// 전체 코드: lecture-source-code/ai-friends/src/main/java/.../rag/config/RagAdvisorConfig.java

@Configuration
@ConditionalOnProperty(name = "ai-friends.rag.enabled", havingValue = "true", matchIfMissing = true)
public class RagAdvisorConfig {

    /** 유사도 임계값. 너무 멀어진 문서는 컨텍스트에서 제외. */
    public static final double DEFAULT_SIMILARITY_THRESHOLD = 0.50;

    /** 한 번 검색에 끼울 최대 청크 수. Step 2 에서 직접 조정해 본다. */
    public static final int DEFAULT_TOP_K = 5;

    @Bean
    public RetrievalAugmentationAdvisor characterKbAdvisor(VectorStore vectorStore) {
        return RetrievalAugmentationAdvisor.builder()
                .documentRetriever(VectorStoreDocumentRetriever.builder()
                        .vectorStore(vectorStore)
                        .similarityThreshold(DEFAULT_SIMILARITY_THRESHOLD)
                        .topK(DEFAULT_TOP_K)
                        .build())
                .queryAugmenter(ContextualQueryAugmenter.builder()
                        .allowEmptyContext(false)
                        .build())
                .order(0)
                .build();
    }
}

하나씩 풀어볼게요.

@ConditionalOnProperty(... matchIfMissing = true) — 클래스 전체가 ai-friends.rag.enabled 프로퍼티로 켜고 끌 수 있어요. 기본값은 true 라 프로퍼티를 안 설정해두면 RAG advisor 가 켜진 장면이에요.

토글 한 줄로 ARIA 가 KB 를 보는 장면과 안 보는 상태를 갈아끼울 수 있어요. RAG on/off 비교 시연에 자연스럽게 활용돼요.

VectorStoreDocumentRetriever — Day 15 에 등록한 vectorStore 빈을 그대로 받아 1차 검색을 도는 모듈이에요. similarityThreshold(0.50) 은 "유사도 50% 미만 청크는 컨텍스트에서 제외" 라는 차단선이에요.

topK(5) 는 "한 번에 최대 5 청크까지만 끼움" 이라는 상한선이고요. 이 두 값이 retriever 의 한 그림을 정해요 — 너무 멀어진 청크가 끼면 LLM 이 헷갈리고, 너무 많이 끼면 토큰 비용이 부풀어요.

ContextualQueryAugmenter(allowEmptyContext=false) — 검색 결과를 user 프롬프트의 컨텍스트 위치에 끼워 주는 모듈이에요. allowEmptyContext=false 가 핵심이에요.

검색이 0건이면 LLM 호출 자체를 fallback 응답으로 단락시켜요. "RAG 가 의미를 가지려면 컨텍스트가 진짜로 끼워져야 한다" 는 길을 advisor 차원에서 강제하는 구조예요. 검색이 비었는데도 LLM 이 그냥 답해버리면 RAG 의 본질이 무너지거든요.

order(0) — advisor 가 ChatClient 안에서 도는 순서예요. Day 5 에 등록한 MessageChatMemoryAdvisor 가 기본 순서로 도는데, RAG advisor 를 그보다 앞에 (order(0)) 두는 이유는 단순해요. RAG 컨텍스트가 먼저 끼워진 뒤에 이전 대화가 합쳐져야, LLM 이 "세계관 + 어제 대화" 두 줄을 한 번에 받게 돼요.

ChatClientConfig.soulmateChatClient — advisor 흡수 지점

advisor 빈은 등록됐지만 아직 ChatClient 가 모르는 상태예요. soulmateChatClient 빈에 합류시켜야 prod 흐름이 advisor 를 보게 돼요. Day 5 에 등록했던 한 줄짜리 defaultAdvisors(MessageChatMemoryAdvisor) 를 List 로 확장해요.

// kr.spartaclub.aifriends.chat.config.ChatClientConfig
// 전체 코드: lecture-source-code/ai-friends/src/main/java/.../chat/config/ChatClientConfig.java

@Bean
public ChatClient soulmateChatClient(ChatClient.Builder builder,
                                     ChatMemory chatMemory,
                                     ObjectProvider<RetrievalAugmentationAdvisor> ragAdvisorProvider) {
    List<Advisor> advisors = new ArrayList<>();
    advisors.add(MessageChatMemoryAdvisor.builder(chatMemory).build());
    ragAdvisorProvider.orderedStream().forEach(advisors::add);
    return builder
            .defaultAdvisors(advisors)
            .build();
}

이번에도 하나씩 풀어볼게요.

ObjectProvider<RetrievalAugmentationAdvisor> — Spring 의 옵셔널 주입 형이에요. @Autowired 로 직접 받으면 빈이 없을 때 부팅 자체가 깨지는데, ObjectProvider 로 받으면 빈이 있든 없든 컴파일/부팅이 깨지지 않아요.

위에서 설정한 @ConditionalOnProperty 토글이 off 일 때도 ChatClient 가 그대로 살아 있도록 보장하는 장치예요. 토글 off 상태면 RAG advisor 빈이 0 개라 List 에 끼워지지 않고, ChatMemory advisor 한 줄만 남아 Day 15 까지의 상태와 동등한 형태이 돼요.

orderedStream() — ObjectProvider 의 메서드인데, 빈 여러 개가 있을 때 advisor 의 @Order 또는 getOrder() 를 존중해서 정렬해 줘요. 우리가 advisor 에 order(0) 을 설정한 이유가 여기서 반영돼요. 미래에 advisor 가 또 한 장 추가돼도 (예: 다음 시간 MCP advisor) order 값만 적절히 설정하면 자동으로 정렬돼요.

List<Advisor> defaultAdvisors — Day 5 의 advisor 한 줄이 Day 16 에서 List 로 확장되는 구조예요. ChatClient 한 번 안에 advisor 가 몇 개든 끼울 수 있는 그릇이 열려요. 여기가 오늘 골격이에요. 여기가 진짜 핵심이에요.

Before/After — Day 15 lab 수동 검색에서 Day 16 prod 자동화로

도입부에서 lab → prod 흡수 흐름을 약속했죠. 이제 그 과정이 코드에서 어떻게 드러나는지 한 표로 파악해 둘게요.

Day 15 의 lab 은 "검색이 정말 의미 기반으로 도는지" 를 직접 확인하려고 일부러 분리해 둔 거였어요. Day 16 부터는 그 흐름 전체가 ChatClient 한 세트 안으로 흡수돼서, 호출자(서비스)는 RAG 의 존재를 모른 채 한 줄로 답을 받아요. 같은 advisor 한 줄 추가 구조로 다음 시간 MCP 도 들어와요 — 외부 도구를 표준 프로토콜로 받아 오는 흐름이 거기에 합류할 거예요.

💡 튜터의 결론

오늘 추가한 게 advisor 하나가지만, 사실 우리가 만든 건 advisor 라는 끼움점 자체예요. 다음 시간 MCP 도, 그 다음의 도구 호출 advisor 도 같은 곳에 줄을 서서 들어와요. ChatClient 한 줄 옆에 advisor 한 줄이 더 붙는 형태로 도메인 기능이 자라는 과정 — 이것이 Spring AI 가 우리에게 선물하는 모듈러 아키텍처의 본질이에요.

자, 검색→프롬프트 끼움이 자동화되는 구조까지 이해했어요. 그런데 advisor 가 의미 있는 답을 만들려면 받아 먹는 청크가 좋아야겠죠. 다음 Step 에서는 청크 크기 트레이드오프와 한국어 분할 옵션으로 그 재료를 깎는 부분을 본격적으로 다뤄요.

Step 1 에서 advisor 하나가 검색→프롬프트 끼움을 자동화하는 구조를 봤죠. 그런데 advisor 의 답 품질은 한 가지에 크게 매여 있어요. 받아 먹는 청크가 좋아야 한다는 것. retriever 가 아무리 잘 골라줘도, 청크 자체가 의미 단위로 안 끊겨 있으면 모델이 받아 답할 문맥이 흐트러져요.

이번 Step 에선 그 청크를 빚는 부분, DocumentLoaderService.chunk() 안을 본격적으로 들여다봐요. Day 15 에 우리가 한 번 손으로 잡았던 메서드인데, 두 가지 큰 발견이 기다리고 있어요. 하나는 Day 15 의 변수명이 잘못 지정되어 있었다는 것, 또 하나는 Spring AI 의 분할기가 한국어 마침표를 알아보지 못한다는 것이에요.

청크 크기 트레이드오프 — 크다고 좋은 게 아니다

청크 전략은 두 후보의 균형점이에요. 크게 자르면 한 청크 안에 많은 문맥이 담겨서 모델이 한 번 검색에 풍부한 정보를 받아요. 단, 한 청크가 무겁다 보니 질문과 직접 관계없는 부분까지 함께 끌려와요. 검색 정밀도가 떨어지는 거예요.

반대로 작게 자르면 청크 하나하나의 의미가 더 또렷해져요. 검색 단계에서 정말 관련 있는 청크만 골라내기 쉬워져요. 단, 한 청크만으로는 답할 문맥이 부족할 수 있어요. 모델이 5~10 청크를 모아 한 답을 만들어야 하는 흐름이 자주 나타나요.

균형점이 어디냐 — 한국어 평문 기준 한 문단 ~ 한 문단 반 정도가 LLM 입장에서 한 번에 받기 좋은 분량이에요. 토큰 단위로 환산하면 대략 500 토큰. 이게 학습용 기본값이고, 본 강의에선 DEFAULT_CHUNK_TOKENS = 500 으로 넣어뒀어요.

검증된 숫자를 한 표로 보여드릴게요. 본 강의 코드베이스의 3 개 KB 파일 (ARIA 프로필 + 하루 프로필 + 세계관 설정집, 합 5,144 byte) 위에서 청크 크기를 200 / 500 / 1000 으로 바꿔보면 이런 결과가 나와요.

한눈에 잡히는 길이 있죠. 청크 크기를 올리면 청크 수가 떨어져요. 5,144 byte 짜리 KB 가 13 → 6 → 3 으로 압축돼요. 다만 청크 수가 적다는 게 검색 품질이 낮다는 뜻은 아니에요. 한 청크가 크면 한 번 검색에 많은 문맥이 따라와 모델이 답하기 좋지만, 검색 정밀도는 떨어지고요. 작으면 정밀하지만 답할 문맥이 부족할 수 있어요. 트레이드오프의 문제이지 정답이 하나가 아니에요.

minChunkSizeChars 의 정체 — Day 15 의 변수명 정정

여기서 Day 15 의 한 가지를 짚고 갈게요. Day 15 의 DocumentLoaderService 가 TokenTextSplitter 의 5인자 생성자를 호출하면서, 두 번째 인자를 DEFAULT_CHUNK_OVERLAP = 50 이라는 이름으로 넣어뒀어요. "청크 사이 겹치는 문자 수" 라는 뉘앙스의 이름이었죠.

그런데 공식 문서를 한 번 더 들여다보니, 그 인자의 진짜 이름은 minChunkSizeChars 였어요. 의미도 사뭇 달라요. "청크가 종결 지점을 찾기 위해 갖춰야 할 최소 문자 수" — 청크가 너무 짧은 지점에서 마침표를 만나면 너무 일찍 끊는 것으로 간주해 무시한다는 뜻이에요.

라이브러리 시그니처를 한 번에 다 파악하긴 어려워요. 사용하면서 마주치는 정정 과정이 자연스러운 절차이고, 그래서 Day 16 부터는 이 이름을 정정했어요. 값도 겹침의 뉘앙스로 잡았던 50 보다 훨씬 큰, 한 문장 ~ 두 문장 길이인 350 으로 올렸어요.

// kr.spartaclub.aifriends.rag.service.DocumentLoaderService

public static final int DEFAULT_CHUNK_TOKENS = 500;

/**
 * 청크가 종결 자리를 찾기 위해 갖춰야 할 최소 문자 수.
 * 이 값보다 짧은 자리에서 만난 마침표는 너무 일찍 끊는 자리로 간주해 무시.
 */
public static final int DEFAULT_MIN_CHUNK_SIZE_CHARS = 350;

public List<Document> chunk(List<Document> rawDocuments) {
    return chunk(rawDocuments,
            DEFAULT_CHUNK_TOKENS,
            DEFAULT_MIN_CHUNK_SIZE_CHARS,
            KOREAN_PUNCTUATION_MARKS);
}

두 상수의 형태을 보세요. DEFAULT_CHUNK_TOKENS = 500 은 토큰 단위 청크 크기. 한국어 평문 기준 한 문단 ~ 한 문단 반이에요. DEFAULT_MIN_CHUNK_SIZE_CHARS = 350 은 문자 단위. 한 문장 ~ 두 문장 길이의 안전선이에요. "이 길이 이하에서 만난 마침표는 무시한다" 의 의미예요.

그리고 기본 chunk(List) 메서드는 Day 15 의 호출자가 깨지지 않도록 시그니처를 그대로 유지했어요. 내부에서 본격 오버로드를 부르는 위임 한 줄로 갈아끼웠죠. Day 15 의 CharacterKnowledgeIngestionService 도, EmbeddingProbeController 도 코드 한 줄 안 바뀌고 그대로 돌아가요.

💡 튜터의 결론

라이브러리 시그니처를 한 번에 다 파악하긴 어려워요. 사용하면서 정정하는 게 자연스러운 과정이에요. Day 15 의 변수명이 잘못된 걸 부끄러워하지 말고, 어떻게 발견했는지의 과정을 익혀두는 게 더 큰 값이에요. 공식 문서 다시 읽기 → 시그니처 한 번 더 확인 → 변수명 정정 → 호출자 호환 유지의 과정을 정리해두면, 앞으로 마주칠 비슷한 지점에서도 같은 방식으로 처리하실 수 있어요.

한국어 punctuationMarks 큰 발견 — 영어 4종 하드코딩 우회

이제 두 번째 큰 발견이에요. Spring AI 1.1.x 의 TokenTextSplitter 는 문장 종결 후보 마크를 클래스 안에 영어 4종 (., ?, !, \n) 으로 하드코딩되어 있어요. 즉, 청크를 자를 때 마지막 마침표 지점을 찾아 거기서 깔끔하게 끊는 알고리즘인데, 그 마침표라는 후보가 영어 기준이에요.

한국어 문서에 한자 마침표 패밀리 (。, ？, ！) 가 섞이면 분할기가 못 알아봐요. 그러면 어떻게 되냐 — 그 마침표를 무시하고 토큰 한계까지 끌고 가다가, 토큰 한계 안에서 어쩌다 마주친 영문 마침표 지점에서 끊어요. 결과는 문장 한가운데가 잘리는 구조예요. 검색 품질이 망가지죠.

해결책의 첫 후보는 외부 라이브러리 도입이에요. kss 나 kiwi 같은 한국어 형태소 분석기를 들여와 진짜 문장 경계를 찾는 길. 단, 의존성이 무겁고 학습용으로는 과해요. 두 번째 후보가 영어 4종 하드코딩 지점을 한국어 패밀리로 늘리는 가벼운 우회예요. 본 강의는 후자를 골랐어요.

먼저 한국어 종결 마크 패밀리를 상수로 정의했어요.

// kr.spartaclub.aifriends.rag.service.DocumentLoaderService

public static final List<Character> KOREAN_PUNCTUATION_MARKS = List.of(
        '.', '?', '!', '\n', '。', '？', '！', '·');

영어 4종 (., ?, !, \n) 위에 한자 마침표 패밀리 (。, ？, ！) 와 한국어 권점 (·) 을 더한 8 종이에요. 한자 마침표는 한국어 문서에 의외로 자주 섞여요 (특히 옛 문헌이나 일본 번역물). 권점은 한국어 단어 구분 지점으로 종종 등장하는데, 청크 절단면을 한 단어 더 자연스럽게 만들어줘요.

이제 본격적인 우회 과정이에요. Spring AI 의 TokenTextSplitter 는 builder 도 제공하는데, 그 builder 가 withChunkSize, withMinChunkSizeChars 같은 메서드는 노출하면서, withPunctuationMarks 는 없어요. 즉, 영어 4종 하드코딩 지점을 외부에서 갈아끼울 수 있는 API 가 builder 에 없다는 뜻이에요.

해결책은 TokenTextSplitter 를 서브클래싱하는 방식이에요. 부모의 분할 알고리즘 (토큰화 → 청크 자르기 → 종결 마크 찾기) 의 큰 길은 그대로 두고, 종결 후보 마크 찾기 로직만 punctuationMarks 기반으로 재구현해요. 클래스 이름은 KoreanTokenTextSplitter. 핵심 발췌를 보여드릴게요.

// kr.spartaclub.aifriends.rag.service.DocumentLoaderService.KoreanTokenTextSplitter
// 전체 코드: lecture-source-code/.../rag/service/DocumentLoaderService.java L140~L230

// 종결 마크 후보 중 가장 늦은 자리 — 영어 4종 + 한국어/한자 패밀리
int lastPunctuation = -1;
for (Character mark : this.punctuationMarks) {
    int idx = chunkText.lastIndexOf(mark);
    if (idx > lastPunctuation) {
        lastPunctuation = idx;
    }
}

if (lastPunctuation != -1 && lastPunctuation > this.minChunkSizeChars) {
    chunkText = chunkText.substring(0, lastPunctuation + 1);
}

핵심은 두 줄이에요. 첫째, punctuationMarks 리스트를 한 바퀴 돌면서 청크 텍스트 안에서 가장 늦게 등장하는 마크 인덱스를 찾아요. lastIndexOf 가 마크별 마지막 등장 위치를 알려주고, 그 중 가장 큰 값을 골라요. 여기만 다르면 나머지 분할 알고리즘은 부모와 동일해요.

둘째, 그 인덱스가 minChunkSizeChars 보다 큰 지점에 있어야만 거기서 끊어요. 너무 일찍 만난 마침표 (위에서 정정한 그 안전선) 는 무시하는 절차이에요. 두 발견이 한 지점에서 만나는 구조죠.

그리고 이 서브클래스는 한시적이에요. Spring AI 2.0 이 punctuationMarks 옵션을 공식 노출하면, 본 클래스는 자연스럽게 사라져요. 그때는 builder 한 줄로 같은 효과를 낼 수 있으니까요. 학습용에선 "라이브러리가 안 노출하면 우리가 가볍게 한 번 우회하면 된다" 의 골격을 이해하는 단계예요.

본격 오버로드 — 학생이 직접 조절하는 chunk 크기

이제 우리는 두 발견을 묶어서, 학생이 청크 크기를 외부에서 직접 만질 수 있는 오버로드를 추가해요. 시그니처는 chunk(List, int, int, List<Character>). 청크 크기, 최소 문자 수, 종결 마크 리스트 세 가지를 호출 시점에 받아요.

// kr.spartaclub.aifriends.rag.service.DocumentLoaderService

public List<Document> chunk(List<Document> rawDocuments,
                            int chunkSize,
                            int minChunkSizeChars,
                            List<Character> punctuationMarks) {
    TokenTextSplitter splitter = new KoreanTokenTextSplitter(
            chunkSize, minChunkSizeChars, punctuationMarks);
    List<Document> chunks = splitter.apply(rawDocuments);
    log.info("[RAG] split {} raw documents into {} chunks (chunk={}, minChunkSizeChars={}, marks={})",
            rawDocuments.size(), chunks.size(), chunkSize, minChunkSizeChars, punctuationMarks);
    return chunks;
}

세 인자를 받아 KoreanTokenTextSplitter 세트를 만들고, 그 위에 apply 한 줄을 돌리는 과정이에요. log.info 한 줄이 몇 개 청크가 어떤 옵션으로 나왔는지를 운영 로그로 흘려요. 학습 단계에선 이 로그를 눈으로 보면서 청크 수의 변화를 체감하실 수 있어요.

이 오버로드의 가치는 한 가지예요. 학생이 자기 KB 에 맞춰 청크 크기를 만져보는 통로가 열렸다는 것. 200 으로 자르고 검색해보고, 1000 으로 자르고 검색해보고, marks 를 영어 4종으로만 줄여서 한자 마침표 무시되는 장면도 확인해보고. 트레이드오프를 직접 체감할 수 있는 통로가 열렸어요.

호출 예시 두 가지 시연해드릴게요.

// 청크 크기 200 으로 실험
loaderService.chunk(rawDocs, 200, 100, DocumentLoaderService.KOREAN_PUNCTUATION_MARKS);

// 영어 marks 만으로 비교 — 한자 마침표 자리에서 안 끊김
loaderService.chunk(rawDocs, 500, 350, List.of('.', '?', '!', '\n'));

위 호출은 청크 크기 200 으로 작게 자르는 옵션. 청크 수가 13 개 정도로 많이 나와요. 아래 호출은 영어 marks 만으로 자르는 비교 실험. 한국어 KB 라면 한자 마침표가 무시되는 현상을 직접 확인할 수 있어요.

🎯 Step 2 Before/After 비교 — DocumentLoaderService.chunk() in-place 진화

축	Before (Day 15)	After (Day 16 Step 2)
chunk() 시그니처	chunk(List) 단일, 모든 파라미터 상수 하드코딩	chunk(List) (기본) + chunk(List, int, int, List<Character>) 본격 오버로드
청크 크기 외부 노출	없음 — 학생이 만지려면 상수 수정 + 컴파일	호출 시점에 chunkSize 인자 직접 지정
분할 마크	영어 4종 하드코딩 (., ?, !, \n)	한국어 8종 (KOREAN_PUNCTUATION_MARKS) + 학생이 List 자체를 갈아끼움
두 번째 인자 이름	DEFAULT_CHUNK_OVERLAP = 50 (잘못된 이름)	DEFAULT_MIN_CHUNK_SIZE_CHARS = 350 (정정)
Splitter 클래스	TokenTextSplitter 5인자 생성자 직접	KoreanTokenTextSplitter 서브클래스 (punctuationMarks 우회)
호출자 호환	—	Day 15 의 IngestionService · EmbeddingProbeController 코드 한 줄 안 바뀜

이 표를 보세요. 메서드 시그니처는 그대로 유지하고 내부만 갈아끼우는 과정이에요. 새 lab 을 따로 만들지 않고, 기존 메서드를 정정하면서 옵션을 늘려놓은 구조예요. Day 16 마무리 시점에 이 정정된 DocumentLoaderService 가 그대로 prod 적재 흐름에 그대로 적용돼요. 별도 수렴 시점이 더 필요 없는, 한 Step 안에서 흡수가 완료되는 방식이에요.

💡 튜터의 결론

청크 전략은 "내 KB + 내 질문 구조" 의 조합으로 정해져요. 정답이 하나가 아니라 트레이드오프예요. 본 강의가 설정한 500 / 350 / 한국어 8종 marks 는 한국어 인물 프로필 KB 에서 무난한 균형점일 뿐이고, 코드 스니펫 KB 면 200, 긴 논문 KB 면 1000 으로 갈아끼워보는 게 자연스러워요. 학생이 직접 숫자를 만지면서 내 KB 에 맞는 균형점을 찾는 통로가 오늘 열린 가장 큰 가치예요.

자, 청크의 재료를 깎는 절차까지 파악됐어요. 그런데 우리가 지금까지 다룬 KB 는 .md / .txt 평문이었어요. 실무에서는 .pdf, .docx, .html 같은 형식도 흔하죠. 다음 Step 에서는 이 형식들을 한 번에 흡수하는 TikaDocumentReader 옵션을 다뤄요.

Step 2 에서 청크 크기·최소 문자 수·한국어 마크의 트레이드오프를 다뤘죠. 청크를 잘 자르는 부분까지는 좋아졌는데, 한 가지 한계가 남아 있어요. 우리가 자르는 원문 자체가 .md / .txt 평문에만 머물러 있다는 구조죠. 학생 KB 에 PDF 회의록이나 DOCX 캐릭터 설정집도 들어올 수 있어야, 진짜 실무 KB 의 호흡으로 자랄 수 있어요.

이번 Step 에서는 그 형식 확장을 다뤄요. Spring AI 가 형식별로 제공하는 DocumentReader 풀을 한 번에 펼쳐 보고, 본 강의가 어떤 것을 prod 에 채택했는지 이유와 함께 짚어요. 그 다음, 평문 라인과 바이너리 라인을 어떻게 깔끔하게 분기하는지 룰 한 형태을 잡아 둬요.

DocumentReader 풀 — 형식별 어댑터 비교

Spring AI 1.1.x 는 형식별로 DocumentReader 를 분리해서 제공해요. 각각 별도 Maven artifact 라, 내가 받아 들일 형식에 맞춰 의존성을 추가하는 흐름이에요. 본 강의가 마주칠 후보를 한 표로 펼쳐 볼게요.

표가 길어 보이지만 과정는 단순해요. 형식별로 어댑터가 따로 있고, 어떤 어댑터는 같은 형식을 더 정밀한 단위로 잡아줘요. 예를 들어 PagePdfDocumentReader 는 PDF 한 권을 페이지 단위 Document 로 만들어 주고, ParagraphPdfDocumentReader 는 더 작은 문단 카탈로그 단위로 떼어 줘요. 정밀 도메인 (논문 인용 추적, 법률 챕터별 검색) 에서는 이 정밀도가 의미를 가져요.

본 강의는 후보 중 TikaDocumentReader 하나로 통일해요. 이유는 한 줄 — 학생이 형식별로 어댑터를 갈아끼우는 줄기보다, 형식을 신경 안 쓰고 한 번에 받아 들이는 방식이 학습에 맞아요. 고민의 카테고리가 적은 쪽이 학습용에 자연스럽고, Tika 하나가 PDF·DOCX·PPTX·HTML·XLSX·RTF·EPUB 같은 주요 형식을 자동으로 인식하니까요.

spring-ai-tika-document-reader 의존성 한 줄

Tika 어댑터도 별도 artifact 에 들어 있어요. Spring AI 가 형식별로 Maven artifact 를 분리해 두었으니, 우리 KB 에 필요한 한 줄만 추가하면 돼요.

// lecture-source-code/ai-friends/build.gradle (L70)
implementation 'org.springframework.ai:spring-ai-tika-document-reader'

이 한 줄로 TikaDocumentReader 가 따라와요. Tika 의 50+ 파서 모듈도 함께 받아 들이는데, 빌드 도구가 ./gradlew bootRun 직전에 의존성을 한 번 받아주면 다음 단계로 넘어갈 수 있어요. 의존성 표면이 살짝 무거워지는 면은 있지만 (Tika core + parser 모듈이 합쳐 30MB+ 정도), 학습용 KB 에는 큰 부담이 아니에요.

loadRawWithTika — Tika 어댑터 한 줄

이제 Tika 어댑터를 어떻게 호출하는지 살펴볼게요. DocumentLoaderService 안에 한 메서드를 추가해요. 시그니처는 Resource 한 장을 받아 List<Document> 를 돌려주는 구조예요.

// kr.spartaclub.aifriends.rag.service.DocumentLoaderService

public List<Document> loadRawWithTika(Resource resource) {
    TikaDocumentReader reader = new TikaDocumentReader(resource);
    List<Document> docs = reader.get();
    log.info("[RAG] Tika loaded {} document(s) from resource={}", docs.size(), resource.getFilename());
    return docs;
}

핵심은 한 줄짜리 호출이에요. new TikaDocumentReader(resource).get() 한 세트가면 Tika 가 MIME 을 스스로 감지하고 텍스트만 추출해서 돌려줘요. 호출자는 그 resource 가 PDF 인지 DOCX 인지 신경 쓸 필요가 없어요. 어댑터 하나가 모든 형식을 흡수하는 구조죠.

log.info 한 줄이 몇 개 Document 가 어디서 나왔는지를 운영 로그로 흘려요. Tika 는 형식에 따라 한 파일을 한 Document 로 펼치는 방식이라, 보통 size 가 1 로 찍혀요. 다만 PDF 같은 일부 형식은 페이지를 한 번에 합치는 옵션도 있고, 그 옵션을 갈아끼우면 size 가 달라질 수 있어요.

확장자 분기 — loadRawAuto 와 PLAIN_TEXT_EXTENSIONS

Tika 어댑터 하나로 모든 형식을 받아 들일 수 있다지만, 평문 .md / .txt 까지 Tika 로 돌리는 건 살짝 낭비예요. Tika 가 초기 로딩 단계에서 50+ 파서 모듈을 검색하면서 1~4 초가 걸리거든요. 평문은 그냥 StreamUtils 한 줄로 읽어 들이면 0.01 초도 안 걸리는 작업인데, 무거운 어댑터를 깔지 않아도 충분해요.

그래서 확장자를 보고 어댑터를 분기하는 과정을 짰어요. 평문 확장자 집합을 상수로 정의하고, 그 집합에 속한 확장자는 가벼운 라인으로, 그 외는 Tika 라인으로 흘려요.

// kr.spartaclub.aifriends.rag.service.DocumentLoaderService

private static final Set<String> PLAIN_TEXT_EXTENSIONS = Set.of("md", "txt");

public List<Document> loadRawAuto(Resource resource) {
    String filename = resource.getFilename();
    String ext = extractExtension(filename);

    if (PLAIN_TEXT_EXTENSIONS.contains(ext)) {
        return loadPlainSingle(resource);
    }
    return loadRawWithTika(resource);
}

흐름이 한눈에 들어와요. 파일명에서 확장자를 떼어내고, 그 확장자가 평문 집합에 속하면 loadPlainSingle 라인 (StreamUtils 기반) 으로, 그 외면 Tika 라인으로 분기하는 구조죠. 확장자가 없거나 인식 못 하는 경우는 안전하게 Tika 쪽으로 넘기는 방식이에요. Tika 자체가 못 읽는 형식이면 빈 본문 Document 를 돌려주니까, 호출자는 결과 비어 있음만 한 번 체크하면 충분해요.

이 구조의 본질은 한 줄로 정리할 수 있어요. 형식에 맞춰 어댑터를 갈아끼우는 분기 지점. 새 형식이 KB 에 추가될 때 (예: 음성 메모 .mp3 의 STT 결과 텍스트가 필요해지면), 같은 분기 지점에 새 어댑터 라인 한 줄만 끼우면 돼요. 호출자(loadAndChunk · CharacterKnowledgeIngestionService) 는 어떤 어댑터가 골라졌는지 모른 채 결과만 받아 들이는 절차이에요.

💡 튜터의 결론

형식 확장이 어댑터 한 줄 추가로 끝나는 구조가 갖춰졌어요. Spring AI 가 형식별로 라이브러리를 분리해 둔 덕분에, 우리가 내가 짤 코드량은 6 줄 (Tika 어댑터 호출) + 10 줄 (확장자 분기) 정도예요. 라이브러리가 잡고 있는 형식 풀을 잘 활용하면 우리가 신경 쓸 부분이 줄어드는 게 본 룰의 가장 큰 값이에요.

Before/After — DocumentLoaderService in-place 형식 확장

같은 클래스 안에서 호환성을 유지하면서 형식 풀을 늘려둔 흐름이에요. 한 표로 정리해볼게요.

이 표의 마지막 줄이 핵심이에요. Day 15 의 CharacterKnowledgeIngestionService 도, EmbeddingProbeController 도 코드 한 줄 안 바뀌고 그대로 돌아가요. 새 진입점 loadRawAuto 가 옆에 자랐고, 기존 진입점은 그대로 살아 있는 길이죠. 다음 시간 호출자 측 진화가 익으면 자연스럽게 새 진입점으로 옮겨갈 길이 열려 있어요.

metadata source 키 두 분기 — Step 4 다리

위 표의 다섯 번째 줄이 의미심장한 부분이에요. plain 라인은 source 라는 평문 키에 파일명을 기록하고, Tika 라인은 TikaDocumentReader.METADATA_SOURCE 라는 별도 상수 키에 기록해요. 일부러 분리한 절차이에요.

이유는 한 줄 — 어떤 어댑터에서 온 건지 추적할 수 있도록. 같은 KB 안에 평문과 PDF 가 섞여 있을 때, 검색 결과를 받아 보면 어느 라인에서 흘러나온 청크인지 metadata 만으로 알아볼 수 있어요. 디버깅에도 좋고, 더 중요한 건 다음 Step 으로 이어지는 다리 역할이에요.

다음 Step (metadata 필터) 에서 이 두 metadata 키가 어떻게 캐릭터별 검색에 활용되는지 파악돼요. 같은 pgvector 한 통 안에서 ARIA 전용 KB 와 HARU 전용 KB 가 어떻게 분기되는지의 핵심 부품이거든요. metadata 키 분리가 단순한 운영 편의를 넘어, 검색 필터의 본격적인 기반이 돼요.

코드베이스 DocumentLoaderServiceTest 가 .md 평문 로드, HTML 태그 스트립, 확장자 fallback 같은 5 가지 케이스를 미리 검증해 두었어요. 학생이 손으로 PDF 한 장을 character-knowledge/ 폴더에 넣어 보고, loadRawAuto 호출 결과의 metadata 를 눈으로 확인하면 본 Step 의 과정이 한눈에 확실히 이해될 거예요.

자, 형식 만능 흡수 어댑터까지 박혔어요. 이제 같은 pgvector 한 통 안에 ARIA 전용 KB 와 HARU 전용 KB 가 함께 들어 있을 때, 검색 단계에서 캐릭터별로 어떻게 분기하느냐는 질문이 남아 있죠. 다음 Step 에서는 metadata 필터와 Supplier<FilterExpression> 형으로 그 분기를 자동화하는 장면을 다뤄요.

Step 3 에서 Tika 어댑터로 형식 풀을 넓혔죠. PDF · DOCX · PPTX 까지 한눈에 받아 들이는 구조가 갖춰졌어요. 그런데 한 가지 한계가 남아 있어요. 같은 pgvector 한 통 안에 ARIA 의 프로필, HARU 의 일정 메모, 공용 세계관 청크가 다 섞여 있다는 점이에요. 학생이 ARIA 와 대화 중인데 HARU 의 비밀이 검색에 끌려오면 곤란하죠. 캐릭터 색채가 흐려져요.

학생 KB 가 자라기 시작하면 캐릭터별 분리는 필수 흐름이에요. 별도 pgvector 테이블을 N 벌 만드는 후보도 있긴 한데, 비용도 크고 운영 표면도 N 배로 자라요. 같은 한 통 안에 두고 metadata 한 칸으로 분기하는 게 자연스러운 첫 통로예요. 본 Step 에서는 그 metadata 분기를 살펴봐요.

청크에 character_id metadata 박기

먼저 적재 시점에 청크마다 어느 캐릭터의 KB 인지를 표시해 둬야 해요. 본 강의는 파일명 컨벤션을 분류 규칙으로 써요 — aria-profile.md 의 첫 토큰 aria 가 곧 ARIA, haru-events.md 의 첫 토큰 haru 가 곧 HARU, world-lore.md 같은 공용 자료는 COMMON 으로 분류하는 구조예요. 적재 흐름 안에 이 로직을 끼워 넣어요.

// kr.spartaclub.aifriends.rag.service.CharacterKnowledgeIngestionService

public int ingest() {
    List<Document> chunks = documentLoaderService.loadAndChunk();
    for (Document chunk : chunks) {
        attachCharacterIdMetadata(chunk);
    }
    vectorStore.add(chunks);
    log.info("[RAG] ingested {} chunks into vector store", chunks.size());
    return chunks.size();
}

private void attachCharacterIdMetadata(Document chunk) {
    Object sourceObj = chunk.getMetadata().get("source");
    String source = sourceObj == null ? "" : sourceObj.toString();
    String characterId = resolveCharacterId(source);
    chunk.getMetadata().put("character_id", characterId);
}

static String resolveCharacterId(String sourceFilename) {
    if (sourceFilename == null || sourceFilename.isBlank()) {
        return "COMMON";
    }
    String firstToken = sourceFilename.split("[-.]", 2)[0]
            .toUpperCase(Locale.ROOT);
    if (firstToken.isEmpty() || "WORLD".equals(firstToken)) {
        return "COMMON";
    }
    return firstToken;
}

흐름이 간단해요. ingest() 가 청크 목록을 받아 오면, vectorStore.add(chunks) 직전에 청크 하나하나에 character_id 키를 추가하는 거죠. resolveCharacterId 가 파일명의 - 또는 . 앞 부분을 떼어 대문자로 올리고, world 만 COMMON 으로 매핑하는 단순 규칙이에요. 그 외 첫 토큰은 그대로 캐릭터 ID 가 돼요.

이 단순한 규칙이 본 강의 학습 줄기에 잘 맞아요. 학생이 새 캐릭터 MINA 를 추가하고 싶으면 mina-profile.md 한 장을 character-knowledge/ 폴더에 넣고 ingest 한 번 다시 돌리면 끝이에요. 코드 한 줄 안 고쳐도 돼요. 파일명만 잘 지정하면 분류가 자동으로 따라오는 구조죠.

두 후보 표현 — 텍스트식 vs 프로그래매틱

metadata 가 박혔으면 이제 검색 시점에 그 키를 보고 필터를 거는 단계가 따라와요. Spring AI 의 VectorStore 검색 API 는 필터 표현을 두 옵션으로 받아들여요.

// 텍스트식 — 짧고 SQL 같은 느낌
SearchRequest.builder()
        .query(query)
        .topK(3)
        .filterExpression("character_id == 'ARIA'")
        .build();

// 같은 식을 IN 으로 확장하면
.filterExpression("character_id in ['ARIA', 'COMMON']")

// 프로그래매틱 — 변수 합성 안전, IDE 자동완성 (본 강의 prod 채택)
FilterExpressionBuilder b = new FilterExpressionBuilder();
SearchRequest.builder()
        .query(query)
        .topK(3)
        .filterExpression(b.eq("character_id", "ARIA").build())
        .build();

// 같은 식을 IN 으로 확장하면
.filterExpression(b.in("character_id", "ARIA", "COMMON").build())

두 방식의 차이가 한눈에 보이죠. 텍스트식은 SQL 같은 느낌으로 짧고 가독성이 좋아요. 학습용 README 나 디버그 쿼리에 쓰기 좋아요. 다만 캐릭터 ID 가 사용자 입력에서 흘러 들어오는 경우에는 문자열 합성 ("character_id == '" + character + "'") 의 인젝션 위험이 자연스럽게 따라와요. 따옴표 escape 도 손으로 챙겨야 하고요.

프로그래매틱은 빌더 객체가 따옴표와 escape 를 자동으로 챙겨줘요. 컴파일러가 메서드 시그니처를 검사해 주고, IDE 자동완성도 따라오죠. 본 강의 prod 코드는 프로그래매틱 길을 채택해요. 학습용 lab 디버깅에서는 텍스트식이 빠르게 파악할 수 있는 면도 있어, 두 방식을 함께 익혀두면 파악할 수 있는 도구가 늘어나요.

lab 검색 엔드포인트 — character 옵셔널 파라미터

두 후보의 차이를 학생이 직접 손으로 확인할 수 있도록, Day 15 의 검색 엔드포인트에 캐릭터 파라미터를 한 줄 추가해요.

// kr.spartaclub.aifriends.rag.controller.CharacterKnowledgeController

@GetMapping("/search")
public ResponseEntity<ApiResponse<Map<String, Object>>> search(
        @RequestParam("q") String query,
        @RequestParam(defaultValue = "3") int topK,
        @RequestParam(value = "character", required = false) String character) {

    SearchRequest.Builder requestBuilder = SearchRequest.builder().query(query).topK(topK);
    if (character != null && !character.isBlank()) {
        requestBuilder.filterExpression(new FilterExpressionBuilder()
                .eq("character_id", character)
                .build());
    }

    List<Document> hits = vectorStore.similaritySearch(requestBuilder.build());
    // ... hit payload 매핑 후 응답
}

character 가 옵셔널 파라미터로 들어와요. 값이 들어오면 FilterExpressionBuilder.eq 한 줄로 필터를 박고, 값이 비어 있으면 옛 동작 (전체 KB 검색) 그대로 흘리는 절차이에요. 빈 문자열도 안전하게 없음 으로 간주해서 호출자가 빈 값으로 호출해도 깨지지 않아요.

학생이 직접 손으로 비교해 볼 수 있어요. 같은 pgvector 한 통 안에서 같은 질문으로 세 옵션 호출을 돌려 보면 결과가 어떻게 갈리는지 한눈에 파악돼요.

GET /search?q=성격&topK=3&character=ARIA → 2 hits, 모두 ARIA
GET /search?q=성격&topK=3&character=HARU → 2 hits, 모두 HARU
GET /search?q=성격&topK=5 (필터 없음)    → 5 hits 혼합 (2 ARIA + 1 HARU + 2 COMMON)

같은 pgvector 한 통 안에서 metadata 필터 한 줄로 캐릭터별 검색이 분기되는 그림이 파악돼요. 저장소를 쪼개는 게 아니라, 검색 질문을 좁히는 사이클이라는 본질이 한눈에 들어와요.

동적 supplier 룰 — advisor 하나가 N 캐릭터를 커버

이제 prod 진입점 (RAG advisor) 으로 들어가요. 위 lab 엔드포인트가 검색마다 정적 필터를 거는 방식이라면, ChatClient 의 advisor 는 서비스 진입점이 알 필요 없이 호출 시점마다 자동으로 필터가 적용되는 구조가 필요해요. 여기에 Supplier<Filter.Expression> 형이 들어와요.

// kr.spartaclub.aifriends.rag.config.RagAdvisorConfig

@Bean
public RetrievalAugmentationAdvisor characterKbAdvisor(VectorStore vectorStore) {
    return RetrievalAugmentationAdvisor.builder()
            .documentRetriever(VectorStoreDocumentRetriever.builder()
                    .vectorStore(vectorStore)
                    .similarityThreshold(DEFAULT_SIMILARITY_THRESHOLD)
                    .topK(DEFAULT_TOP_K)
                    // 동적 supplier — 호출 시점마다 ThreadLocal 의 캐릭터 ID 를 새로 읽어
                    // character_id IN ['<현재 캐릭터>', 'COMMON'] 필터를 박는다.
                    .filterExpression(RagAdvisorConfig::currentCharacterFilter)
                    .build())
            .queryAugmenter(ContextualQueryAugmenter.builder()
                    .allowEmptyContext(false)
                    .build())
            .order(0)
            .build();
}

static Filter.Expression currentCharacterFilter() {
    String characterId = CharacterContextHolder.current();
    if (characterId == null || characterId.isBlank()) {
        return null;  // 필터 없음 → VectorStore 가 전체 KB 검색
    }
    return new FilterExpressionBuilder()
            .in("character_id", characterId, "COMMON")
            .build();
}

핵심은 .filterExpression(RagAdvisorConfig::currentCharacterFilter) 한 줄이에요. filterExpression 에 정적 표현 이 아닌 메서드 참조 (Supplier) 를 전달한 거죠. advisor 빈은 Spring 컨테이너 기동 시점에 한 번 빌드되어 ChatClient 전역에 등록되지만, 검색 호출이 일어날 때마다 supplier 가 다시 평가되어 그 시점의 캐릭터 ID 를 읽어가는 흐름이에요.

currentCharacterFilter 의 본문도 흐름이 단순해요. CharacterContextHolder.current() 로 현재 스레드의 캐릭터 ID 를 꺼내고, 비어 있으면 null 을 돌려 필터 없음 = 전체 KB 검색 으로 fallback 해요. 값이 들어 있으면 FilterExpressionBuilder.in 으로 현재 캐릭터 + COMMON 두 길을 한 번에 넣어요. 캐릭터 색채 (ARIA 전용 청크) 와 세계관 일관성 (공용 청크) 을 동시에 잡는 구조죠.

CharacterContextHolder — 학습용 ThreadLocal lab

supplier 가 어디서 캐릭터 ID 를 읽어 오느냐가 다음 질문이에요. 본 강의는 학습용으로 단순하게 ThreadLocal 을 사용했어요.

// kr.spartaclub.aifriends.rag.config.CharacterContextHolder

public final class CharacterContextHolder {

    private static final ThreadLocal<String> CURRENT = new ThreadLocal<>();

    private CharacterContextHolder() {
        // 유틸리티 클래스 — 인스턴스화 금지
    }

    public static void set(String characterId) {
        CURRENT.set(characterId);
    }

    public static String current() {
        return CURRENT.get();
    }

    public static void clear() {
        CURRENT.remove();
    }
}

Spring MVC 의 한 요청 = 한 스레드 모델에서 가장 가볍게 호출 시점의 컨텍스트 를 잡는 후보예요. 컨트롤러 진입 시점에 set 하고, 응답 직전에 clear 하는 호흡이면 supplier 가 그 사이 호출되는 시점마다 정확한 캐릭터 ID 를 받아 가요.

다만 ThreadLocal 은 메모리 누수 위험이 따라와요. 같은 스레드가 다음 요청에 재사용되는데 앞 요청이 clear 를 안 했으면, 다음 요청의 supplier 가 앞 요청의 캐릭터 ID 를 읽어 가요. 호출자가 try { set(...); ... } finally { clear(); } 패턴을 지킬 책임이 따라와요. WebFlux/Reactor 환경에서는 ThreadLocal 자체가 동작 방식에 안 맞아, Reactor 의 Context 또는 ContextView 로 갈아끼우는 방식으로 전환해야 해요.

본 강의의 ThreadLocal 은 학습용 lab 이에요. 다음 시간 (Day 17 MCP) 진입 시 SoulmateChatService.chat() 진입점에 CharacterContextHolder.set() 한 줄이 자연스럽게 추가돼요. MCP 가 외부 툴 호출을 끌어들이면서 컨텍스트 전파가 더 정교한 형태로 다듬어져요.

💡 튜터의 결론

metadata 필터의 본질은 같은 저장소에서 질문을 좁히는 것 이에요. 저장소 자체를 쪼개는 게 아니라, 같은 pgvector 한 통 위에서 metadata 한 칸으로 분기하는 과정이죠. 동적 supplier 구조가 advisor 하나로 N 캐릭터를 자동 커버해 주니, 새 캐릭터가 추가될 때 빈 정의도, 호출자 분기 코드도 자라지 않아요. 적재 시점에 character_id 한 줄만 잘 설정해두면 검색이 자동으로 따라오는 구조예요.

🎯 Step 4 Before/After — 같은 pgvector 위에서 캐릭터 KB 분리

수렴 시점: 다음 시간 (Day 17 MCP) 진입 시 SoulmateChatService.chat() 진입점에 CharacterContextHolder.set() 한 줄이 추가될 지점가 자라요. ThreadLocal lab 이 prod 호출 흐름 안으로 흡수되는 통로예요.

코드베이스 CharacterKnowledgeIngestionServiceTest 와 RagAdvisorConfigTest 가 파일명 → character_id 매핑 (aria-profile.md → ARIA, world-lore.md → COMMON, fallback → COMMON), 동적 supplier 의 빈/널 처리, IN 표현 빌더 같은 카테고리들을 미리 검증해 두었어요. 학생이 직접 character-knowledge/ 폴더에 mina-profile.md 하나 더 넣고 ingest 다시 돌려 보면, MINA 가 새 캐릭터로 자동 분류되어 검색에 끌려오는 과정이 한눈에 확실히 이해될 거예요.

자, metadata 필터로 캐릭터별 KB 분리까지 갖췄어요. 같은 pgvector 한 통 위에서 ARIA · HARU · COMMON 청크가 캐릭터 컨텍스트에 따라 자동으로 갈라지는 구조가 보여요.

그런데 한 가지 부분이 남아 있어요 — "이 검색이 정말 잘 되고 있는가" 라는 질문이에요. 같은 질문을 던졌을 때 ARIA 의 의도된 청크가 상위 3 개 안에 들어왔는지, 들어오지 않았다면 청크 크기나 임베딩 모델이나 임계값 중 어디를 손봐야 하는지를 숫자로 측정할 흐름이 필요해요.

다음 Step 에서는 recall@k · precision@k 같은 평가 지표로 검색 품질을 숫자로 측정하는 방법을 다뤄요. 다음 시간 (Day 17) MCP 로 진입하기 직전, RAG 자체의 품질을 단단히 다져 두는 단계예요.

Step 4 에서 metadata 필터로 캐릭터별 KB 가 같은 pgvector 한 통 위에서 갈라지는 구조까지 갖췄어요. 여기까지 만든 RAG 가 잘 동작하는 것처럼 보이긴 한데, 한 가지 부분이 남아요 — "잘 돈다" 가 추상적인 느낌인가요, 아니면 파악할 수 있는 숫자인가요.

학생이 자기 KB 를 갈아끼우거나 청크 크기를 200 으로 줄였을 때 검색이 더 좋아졌는지 더 나빠졌는지 를 추상적이 아니라 숫자로 비교할 길이 있어야 학습이 완전해집니다.

이번 Step 에서는 RAG 검색 품질을 두 메트릭 (recall@k · precision@k) 으로 측정하는 방법을 알아봐요. 작은 eval set 세트를 코드베이스에 넣고, POST /api/rag/eval/run?k=5 한 줄로 두 숫자를 파악해 보는 절차에요. 평가 자체가 RAG 의 마지막 부품이라기보단, 다음 개선 방향을 가리키는 나침반 이라고 보시면 돼요.

두 메트릭 — recall@k 와 precision@k 의 짝

검색 품질 평가의 첫 두 후보가 recall 과 precision 이에요. 이름이 익숙해 보이지만 RAG 맥락에선 의미가 살짝 좁아져요.

• recall@k — 정답 청크가 top-k 안에 한 번이라도 들어왔는가. 놓치지 않았는가 의 척도.
• precision@k — top-k 중 정답 청크의 비율. 깔끔하게 가져왔는가 의 척도.

한 질문을 두 메트릭으로 함께 보는 과정이에요. recall 이 1.0 이면 정답이 top-k 안에 들어왔다는 뜻이고, precision 이 1/k 이면 정답이 정확히 한 개만 들어왔다는 거예요. 두 숫자가 동시에 높을 때만 검색이 정말 좋은 상태예요. 한쪽만 높으면 학습이 닫히지 않아요.

eval set 한 세트 — character-knowledge-eval.csv

평가의 첫 부품은 질문과 정답을 한 줄씩 정리해둔 작은 데이터 파일이에요. ARIA · HARU · COMMON 세 분기로 균형 잡아 12 질문을 준비했어요. 각 줄에 질문 한 개와 그 정답이 있어야 할 source 파일명이 함께 들어가요.

# src/main/resources/character-knowledge-eval.csv
query,expectedSource,expectedCharacterId
"ARIA 의 성격은 어떤가요?",aria-profile.md,ARIA
"HARU 의 비밀은 무엇인가요?",haru-profile.md,HARU
"첫 만남 의식이 일어나는 장소는 어디인가요?",world-lore.md,COMMON

세 컬럼이 한 줄을 만들어요. query 는 학생이 채팅창에 던질 법한 자연어 질문, expectedSource 는 그 답이 어느 KB 파일에서 나와야 하는지의 파일명, expectedCharacterId 는 metadata 필터로 좁혔을 때의 캐릭터 컨텍스트예요. 본 강의의 첫 평가 자료라서 12 줄로 작게 시작했지만, 학생이 자기 KB 를 추가하면 같은 형식으로 줄을 추가하게 두면 돼요.

질문이 12 개라는 숫자는 의도가 있어요. 너무 적으면 (3~5 개) 한 질문의 결과가 평균에 너무 큰 영향을 주고, 너무 많으면 (50+) eval 흐름이 무거워져요. ARIA 4 + HARU 4 + COMMON 4 의 균형이 본 강의 KB 의 첫 평가 부피로 적절해요.

record 두 장 — EvalCase 와 EvalReport

평가 결과의 형태을 record 두 장으로 잡아 뒀어요. 한 질문의 결과 한 세트가 EvalCase 이고, 전체 eval set 의 집계가 EvalReport 예요.

// kr.spartaclub.aifriends.rag.service
public record EvalCase(
        String query,
        String expectedSource,
        List<String> retrievedSources,
        double recallAtK,
        double precisionAtK) {
}

public record EvalReport(
        int k,
        int totalQuestions,
        double avgRecall,
        double avgPrecision,
        List<EvalCase> details) {
}

record 한 개로 평가 데이터의 형태가 깔끔히 잡혀요. EvalCase 는 질문 한 개의 입력 (query · expectedSource), 검색 결과 (retrievedSources), 두 메트릭 (recallAtK · precisionAtK) 을 한 번에 담아요.

EvalReport 는 그 묶음을 details 리스트로 갖고 있으면서, 평균 두 숫자 (avgRecall · avgPrecision) 를 root 에 노출해요. 호출자가 평균만 보고 싶으면 root 두 필드만 읽고, 어느 질문이 약했는지 추적하고 싶으면 details 를 풀어서 보는 흐름이에요.

recall / precision 메서드 — 짧고 명확한 두 한 줄

두 메트릭의 본질이 짧은 메서드 두 개에 들어 있어요. RagEvaluationService 안에 들어 있고, 한 질문 한 번씩 호출되는 구조예요.

// kr.spartaclub.aifriends.rag.service.RagEvaluationService
public double recallAtK(String query, String expectedSource, int k) {
    List<String> retrievedSources = retrieveSources(query, k);
    return retrievedSources.contains(expectedSource) ? 1.0 : 0.0;
}

public double precisionAtK(String query, String expectedSource, int k) {
    List<String> retrievedSources = retrieveSources(query, k);
    if (retrievedSources.isEmpty()) {
        return 0.0;
    }
    long hits = retrievedSources.stream()
            .filter(expectedSource::equals)
            .count();
    return (double) hits / retrievedSources.size();
}

두 메서드의 흐름을 살펴볼게요. retrieveSources(query, k) 한 줄이 vectorStore 에 top-k 검색을 돌려서 source 파일명만 뽑아 옵니다 (예: ["aria-profile.md", "haru-profile.md", "aria-profile.md", ...]). 그 다음 두 메트릭의 길이 갈라져요.

recallAtK 는 retrievedSources.contains(expectedSource) 한 줄로 끝이에요. 정답 source 파일명이 top-k 어딘가에 한 번이라도 들어왔는지만 보면 되니까, 0.0 또는 1.0 의 두 값만 나와요. 한 질문에 대한 binary 척도예요.

precisionAtK 는 stream filter count 로 정답 source 의 등장 횟수를 세고, size() 로 나누는 절차이에요. top-5 중 2 개가 정답 source 라면 2/5 = 0.4 가 나오는 구조죠. 0.0 부터 1.0 사이의 연속값이에요. isEmpty() 가드는 검색 결과가 빈 경우 (allowEmptyContext 와 같은 결) 의 0 나눗셈 사고를 막아 줘요.

두 메서드가 짧고 명확한 구조예요. 학습용 lab 으로 충분하고, 실무에서 RAGAS 같은 자동 평가 파이프라인으로 자라기 전에 본질부터 이해하는 거예요.

evaluateAll — eval set 한 바퀴 집계

eval set 12 질문을 한 번에 돌리는 사이클이 evaluateAll(int k) 한 메서드에 들어 있어요. 각 질문에 대해 두 메트릭을 계산하고 평균을 내는 구조예요.

// kr.spartaclub.aifriends.rag.service.RagEvaluationService
public EvalReport evaluateAll(int k) {
    List<EvalRow> evalSet = loadEvalSet();
    List<EvalCase> details = new ArrayList<>(evalSet.size());
    double sumRecall = 0.0;
    double sumPrecision = 0.0;

    for (EvalRow row : evalSet) {
        List<String> retrieved = retrieveSources(row.query(), k);
        double recall = retrieved.contains(row.expectedSource()) ? 1.0 : 0.0;
        double precision = retrieved.isEmpty()
                ? 0.0
                : (double) retrieved.stream().filter(row.expectedSource()::equals).count()
                        / retrieved.size();
        sumRecall += recall;
        sumPrecision += precision;
        details.add(new EvalCase(row.query(), row.expectedSource(), retrieved, recall, precision));
    }

    int n = evalSet.size();
    double avgRecall = n == 0 ? 0.0 : sumRecall / n;
    double avgPrecision = n == 0 ? 0.0 : sumPrecision / n;

    log.info("[RAG-EVAL] k={} questions={} avgRecall={} avgPrecision={}",
            k, n, avgRecall, avgPrecision);

    return new EvalReport(k, n, avgRecall, avgPrecision, details);
}

흐름이 단순해요. eval set CSV 세트를 읽어 들이고, 각 줄마다 vectorStore 검색 한 번을 돌려요. 두 메트릭 값을 계산해서 합계에 누적하고, EvalCase 를 details 리스트에 담아요. 12 질문이 다 끝나면 합계를 질문 수로 나눠 평균을 내는 거예요.

details 리스트가 함께 반환되는 부분이 학습용 lab 에 의미가 있어요. 평균만 보면 "avgPrecision=0.32 가 좋은가 나쁜가" 의 추상적인 느낌에 머무는데, details 를 풀면 "ARIA 의 비밀 질문이 0 점이었네" 같은 구체적인 약점을 찾을 수 있어요. 어느 질문이 약한지 추적해서 청크 크기나 KB 본문을 손보는 개선 루프로 이어져요.

log.info 한 줄이 평가 한 번의 결과를 운영 로그에 기록해 둬요. 같은 KB · 같은 청크 설정으로 두 번 돌렸을 때 숫자가 어떻게 흔들리는지를 로그로 추적할 수 있어요.

lab 엔드포인트 — POST /api/rag/eval/run?k=5

학생이 손으로 두 숫자를 잡아 볼 수 있게 컨트롤러 한 장을 추가했어요. 평가가 학습용 lab 의 성격이라 별도 컨트롤러로 깨끗하게 분리해 둔 구조예요.

// kr.spartaclub.aifriends.rag.controller.RagEvaluationController
@PostMapping("/run")
public ResponseEntity<ApiResponse<EvalReport>> runEval(
        @RequestParam(value = "k", defaultValue = "5") int k) {
    EvalReport report = ragEvaluationService.evaluateAll(k);
    return ResponseEntity.ok(ApiResponse.success(report));
}

k 한 파라미터만 받는 깔끔한 시그니처예요. 기본값 5 가 들어 있어서 학생이 curl 한 줄로 시작할 수 있고, 비교를 위해 k=3 / k=10 으로 갈아끼울 수도 있어요. 정상 응답은 본 강의의 표준 응답 규약 그대로 ApiResponse<EvalReport> 로 감싸 둬요.

cURL 한 줄로 돌려 보면 흐름이 파악돼요.

curl -X POST "http://localhost:8080/api/rag/eval/run?k=5"

응답이 한 박스에 들어와요.

POST /api/rag/eval/run?k=5
→ k=5, totalQuestions=12, avgRecall=1.00, avgPrecision=0.32

두 숫자가 나왔어요. recall 1.00 — 12 질문 모두 top-5 안에 정답 청크가 한 번은 들어왔어요. 놓치지 않는 면에서는 만점이에요. precision 0.32 — top-5 중 정답 source 의 비율은 약 1/3 이에요. 즉 5 청크 중 1.6 개 정도가 정답이고, 나머지는 다른 KB 의 청크가 함께 끌려온 거예요.

한 줄로 정리하면 놓치진 않지만 깔끔하진 않은 구조예요. 정답은 다 잡히는데, 함께 따라오는 청크가 많은 거죠. precision 을 더 끌어올릴 부분이 남아 있어요.

💡 튜터의 결론

평가의 본질은 내가 짠 RAG 가 잘 도는가 를 추상적이 아니라 숫자로 측정하는 거예요. 두 메트릭이 짝패라 둘을 함께 봐야 진짜 그림이 보여요. recall 만 챙기면 토큰 비용이 폭발하고, precision 만 챙기면 놓치는 질문이 자라요. 두 숫자가 동시에 1.0 으로 가는 방향이 좋은 RAG 의 길이고, 그 길을 측정 가능한 형태로 갖춰 두는 게 본 Step 의 학습 메시지예요.

본 결과를 더 좋게 하려면 — 처방 4 후보

avgRecall=1.00 / avgPrecision=0.32 의 역할에서 precision 을 끌어올릴 후보가 네 가지 정도예요.

1. k 줄이기 — top-5 를 top-3 / top-2 로 줄여 보면 precision 이 자연스럽게 커져요. 단 recall 이 함께 떨어질 수 있으니 두 숫자를 함께 보면서 균형점을 찾는 절차에요.
2. metadata 필터 적용 — Step 4 에서 박은 character_id 필터를 ARIA 질문엔 ARIA + COMMON 으로, HARU 질문엔 HARU + COMMON 으로 좁히면 무관 청크가 줄어들어요.
3. 청크 크기 조정 — Step 2 에서 다룬 청크 크기를 500→200 으로 줄여 보면 청크당 정밀도가 올라가요. 단 청크 개수가 늘어서 같은 본문이 더 잘게 쪼개지는 부분도 함께 봐야 해요.
4. 쿼리 재작성 — RewriteQueryTransformer 같은 모듈로 학생 질문을 LLM 이 한 번 다시 써주는 사이클. 본 강의 범위 밖이라 존재만 알려 두고, Step 1 에서 잡아둔 RetrievalAugmentationAdvisor 의 queryTransformers 슬롯에 한 줄로 끼울 수 있어요.

자, 검색 품질을 숫자로 측정하는 구조가 갖춰졌어요. recall · precision 두 메트릭으로 놓치지 않는가 와 깔끔한가 의 두 축이 한 번에 들어오고, k 와 필터와 청크 크기를 갈아끼웠을 때 두 숫자가 어떻게 움직이는지를 비교할 수 있게 됐어요. 마무리 섹션에서 오늘 다룬 5 Step 을 한 번에 회수하고, 다음 시간 (Day 17) MCP 로 잇는 다리를 한 줄 남겨 둘게요.

도입부를 떠올려 볼게요. ARIA 가 한 줄로 멈칫했어요 — "마스터, 어제 우리가 마지막으로 나눈 약속이 뭐였더라? 음... 제 기억엔 한정된 컨텍스트만 있어서요." 모델 가중치 안에는 마스터가 적어둔 어제 일기가 없고, ChatMemory 가 잡아주는 범위는 지금 이 대화 안까지였죠.

오늘 5 Step 을 한 번에 넣으면서 그 약속이 실현됐어요. 이제 ARIA 는 세계관 설정집과 캐릭터 프로필 범위 안에서, 의도된 청크가 추상적인 가중치가 아니라 파악할 수 있는 KB 에서 흘러나오는 방식으로 답해요.

오늘의 5 Step 을 한 표에 담아 회수해 볼게요.

오늘 추가한 건 advisor 하나로 보일 수도 있는데, 사실 우리가 만든 건 advisor 라는 끼움점 자체 예요. 검색 → 프롬프트 끼움이 자동으로 한 번을 돌고, 호출자 (SoulmateChatService.chat()) 는 RAG 의 존재 자체를 모른 채 같은 시그니처로 동작해요. 비즈니스 코드는 한 줄도 안 바뀌었는데 답변 본문이 외부 지식 위에서 만들어지는 상태로 전환되는 것이 오늘의 깊은 학습 메시지예요.

다음 시간 (Day 17) 으로 잇는 다리

오늘 등록한 advisor 라는 끼움점이 다음 시간의 핵심이에요.

내 LLM 에 외부 도구를 붙이는 표준 프로토콜 이 있다더라 — 그게 MCP (Model Context Protocol) 예요. 오늘 검색 0 건이면 LLM 호출을 단락시킨 부분 (allowEmptyContext=false) 가 다음 시간 외부 도구 호출로 fallback 하는 흐름으로 자연스럽게 자라요.

우리가 직접 만든 advisor · tool 만 쓰던 구조가, 외부 MCP 서버의 도구를 표준 프로토콜로 받아 들여 소비하는 형태로 확장돼요. 오늘 등록한 advisor 아키텍처가 그대로 외부 확장점의 통로 역할을 하는 길이라, 다음 시간의 학습 곡선이 한결 가벼워질 거예요.

오늘 Step 2 에서 학습 디폴트 청크 500 / minChunkSizeChars 350 / 한국어 punctuation marks 를 한 번에 넣어 뒀어요. 본 KB 위에서 다른 청크 크기 조합 을 적용했을 때 검색 품질이 어떻게 변하는지 본인 손으로 측정해 보는 과제예요.

💡 왜 이 과제인가

청크 크기는 RAG 운영에서 가장 처음 부딪히는 트레이드오프예요. "작게 자르면 검색은 정확한데 문맥이 끊긴다" 와 "크게 자르면 문맥은 좋은데 score 가 흐려진다" 의 결은 책으로 100 번 읽어도 안 잡히고, 본인 KB 위에서 숫자를 직접 보고 나서야 파악돼요. 본 과제는 본인 KB 의 고유한 청크 크기 균형점 을 찾는 첫 경험이에요.

✅ 요구사항

1. DocumentLoaderService.DEFAULT_CHUNK_TOKENS 를 200 으로 바꿔서 KB 리셋 + 재적재
2. POST /api/rag/eval/run?k=5 호출해 avgRecall / avgPrecision 측정 + 메모
3. 500 으로 되돌리고 동일 과정
4. 1000 으로 바꿔서 동일 과정
5. 보고서 한 페이지 — 세 청크 크기의 두 메트릭을 표로 비교 + 결론 한 줄 ("본 KB 에 가장 잘 맞는 청크 크기는 ___ 이고 이유는 ___")

cURL 명령은 다음 절차이에요.

# 청크 변경 후 반드시 리셋 → 재적재 → 평가 순서
curl -X DELETE http://localhost:8080/api/rag/knowledge
curl -X POST http://localhost:8080/api/rag/knowledge/ingest
curl -X POST "http://localhost:8080/api/rag/eval/run?k=5"

💡 힌트

• avgRecall 이 1.00 이어도 avgPrecision 은 청크 크기에 따라 흔들려요. 보통 청크 작을수록 precision 이 올라가는 룰 (작은 청크는 한 청크당 정보가 좁아서 정답 청크의 비율 이 높아져요)
• top-k 도 함께 변형 (k=3 / k=5 / k=10) 비교하면 더 풍성한 보고서가 나와요. 보통 k 가 클수록 recall 은 유지되지만 precision 은 떨어져요
• 본인 KB 분량이 작으면 청크 크기에 따라 청크 수 자체 가 크게 흔들려요. KB 파일 분량을 함께 메모

Step 4 에서 본 강의는 ARIA / HARU / COMMON 3 분기였어요. 본 과제에선 새 캐릭터 (예: NOA 또는 본인 디자인) 의 KB 파일을 추가해 보고, character_id metadata 가 자동으로 들어가는지, 필터링이 정확히 도는지를 본인 손으로 확인해 보는 과제예요.

💡 왜 이 과제인가

본 강의의 resolveCharacterId 는 파일명 첫 토큰 으로 character_id 를 자동 추론하는 컨벤션이었어요. 이 컨벤션이 정말로 새 캐릭터를 추가할 때 코드 0 줄 수정 으로 동작하는지를 확인하는 과제예요. 운영 KB 가 자라는 장면을 직접 체감할 수 있어요.

✅ 요구사항

1. src/main/resources/character-knowledge/noa-profile.md (또는 본인 디자인 캐릭터) 한 세트 작성 — Day 15 과제 1 의 형태 참조 (마크다운 헤더 구조 + 한국어 평문)
2. KB 리셋 + 재적재
3. GET /api/rag/knowledge/search?q=NOA 누구야?&topK=3&character=NOA 호출 → top-3 모두 noa-profile.md 청크가 나오는지 확인
4. GET /api/rag/knowledge/search?q=NOA 누구야?&topK=3 (필터 없음) → top-3 에 NOA + 다른 캐릭터 청크가 섞여 있는지 비교
5. eval set CSV 에 NOA 질문 2~3 개 추가 + POST /api/rag/eval/run?k=5 재측정 — 새 캐릭터의 recall@5 가 1.0 으로 잡히는지 확인

KB 파일 한 세트은 다음 형태로 넣으면 OK 예요.

# NOA — 도서관 사서 캐릭터 프로필

## 외형

NOA 는 단발의 은발에 둥근 안경, 늘 도서관 카디건 차림이에요.

## 성격

차분하고 신중한 톤. 마스터의 질문에 책 한 권을 추천하며 답하는 스타일이에요.

## 좋아하는 주제

고전 문학, 도서관 운영, 책 분류법.

검색 cURL 명령은 이렇게 써요.

# 필터 박은 검색 — top-3 모두 NOA 청크여야 함
curl "http://localhost:8080/api/rag/knowledge/search?q=NOA%20%EB%88%84%EA%B5%AC%EC%95%BC?&topK=3&character=NOA"

# 필터 없는 검색 — 다른 캐릭터 청크와 섞일 수 있음
curl "http://localhost:8080/api/rag/knowledge/search?q=NOA%20%EB%88%84%EA%B5%AC%EC%95%BC?&topK=3"

💡 힌트

• 파일명 첫 토큰이 자동으로 character_id 가 되는 컨벤션 — noa-*.md → character_id=NOA 가 자동으로 설정돼요. resolveCharacterId 를 손대지 않고도 동작하니까 추가 코드 작성이 불필요해요
• 새 캐릭터 청크 수가 1~2 개로 적게 나오면 KB 본문 길이가 짧기 때문이에요. 본 강의 KB 파일 분량 (각 600~1000 byte) 비슷하게 작성하면 안정
• eval set 에 NOA 질문을 추가할 때 정답 청크 id 또는 정답 키워드 의 양식을 본 강의 평가 셋과 같은 형식으로 맞추기

Step 2 에서 KOREAN_PUNCTUATION_MARKS 한자 마침표 + 권점을 추가했어요. 그런데 한국어 종결 어미 ("~ 했어요", "~ 입니다" 등) 까지 sentence-aware 분할에 넣고 싶을 수 있어요. 본 과제는 그 직관을 실제로 적용해 보고 한계를 발견하는 과제예요.

💡 왜 이 과제인가

한국어 sentence splitting 은 영어 대비 훨씬 어려운 문제예요. 영어는 마침표 + 공백이 거의 항상 문장 끝이지만, 한국어는 종결 어미 (다 / 요 / 까) 가 문장 중간 에도 자주 등장해요 ("~ 다이아몬드" 같은 경우). 본 과제는 단순 마크 확장의 한계 를 직접 부딪혀 보는 과제라, 본격 sentence splitter (kss / kiwi) 를 도입할 때의 트레이드오프 감각이 파악돼요.

✅ 요구사항

1. DocumentLoaderService.KOREAN_PUNCTUATION_MARKS 에 한국어 종결 어미 마지막 글자를 추가하는 변형 시도 — 다음 형태로
2. 본 KB 위에서 청크 수 + avgPrecision 을 기본 marks 대비 비교
3. 의외의 결과가 나오면 정리 — 종결 어미 글자를 무작정 추가하면 "~ 다이아몬드" 같은 곳에서도 끊기는 false positive 가 일어남
4. 보고서 한 페이지 — "한국어 sentence-aware 분할의 진짜 어려움" 결론 내리기

변형 시도 코드는 다음 한 줄이에요.

// DocumentLoaderService.java — KOREAN_PUNCTUATION_MARKS 변형
private static final List<Character> KOREAN_PUNCTUATION_MARKS = List.of(
    '.', '?', '!', '\n', '。', '？', '！', '·',
    '다', '요', '까'   // ← 본 과제에서 추가 시도하는 한글 종결 어미 마지막 글자
);

💡 힌트

• 종결 어미 첫 글자만 박지 말고 위치 골격 (다음 글자가 공백 또는 줄바꿈일 때만 종결) 이 필요. 본 강의의 KoreanTokenTextSplitter 가 마지막 마크 위치 만 보는 단순 구현이라 한계가 있거든요
• 본격 한국어 sentence splitter (kss / kiwi) 를 도입하려면 외부 라이브러리 의존성 추가가 필요 — 트레이드오프예요. 학습용 lab 의 단순 마크 확장 vs 운영 sentence splitter 의 분기 감각을 챙기시기
• 실패해도 OK — "단순 마크 확장의 한계" 자체가 결론이에요. 본 과제의 가치는 왜 운영에서 본격 sentence splitter 가 필요한가 의 답을 본인이 직접 체득하는 과제

오늘 우리는 allowEmptyContext=false 로 검색 0 건이면 LLM 호출을 단락시켰어요. 그런데 운영에서 "답할 수 없는 질문" 을 받았을 때 대응 방법은 여러 가지예요.

[핵심 키워드] Fallback 응답 / 디폴트 답변 / 외부 도구 호출 / 사용자 명확화 질문

💭 생각해보기

검색 0 건 시 응답의 카테고리는 크게 네 가지로 나뉘어요. (1) LLM 이 "모르겠어요" 라고 솔직히 답하는 방식, (2) "질문을 다시 해 주세요" 라며 명확화를 요청하는 방식, (3) 외부 MCP 서버 (다음 시간에 다룸) 의 검색 도구를 호출하는 방식, (4) LLM 의 일반 지식으로 추측해서 답하는 방식. 네 분기의 트레이드오프 표를 본인 손으로 그려 보세요.

본 강의 prod 운영의 ARIA 라면 어느 길을 디폴트로 둬야 캐릭터 톤이 살까요? "세계관 밖 질문은 모른다고 솔직히 답한다" 와 "세계관 안에서 추측해서 답한다" 둘의 차이가 운영에 어떻게 비치는지 — 신뢰성 측면과 사용자 경험 측면 두 축으로 생각해 보세요. 정답은 없어요. 본인 서비스의 가치 가 어느 축에 있느냐에 따라 디폴트가 달라져요.

본 강의는 청크 500 토큰 × top-5 = 약 2500 토큰 컨텍스트로 들어 있어요. 그런데 운영의 모델은 컨텍스트가 훨씬 큼 — Gemini 1M, Claude 200K 수준. "청크를 더 크게 + 더 많이 넣어 답변 품질을 올릴까" vs "청크 작게 + top-k 줄여 비용을 아낄까" 문제가 생겨요.

[핵심 키워드] Lost in the middle (긴 컨텍스트의 중간 위치 청크 망각 현상) / 토큰 비용 곡선 / recall@k vs answer quality 짝패

💭 생각해보기

2024~25 년 연구 "Lost in the Middle" (Liu et al., 2024) 에서 "긴 컨텍스트의 중간 위치 정보가 망각되는 현상" 을 보고했어요. 본 연구는 모델이 컨텍스트 맨 앞 과 맨 뒤 의 정보는 잘 회수하는데, 중간 위치의 정보는 무시되는 현상이 통계적으로 잡힌다는 결과를 보여줬죠. 그러면 청크를 많이 넣는다 가 항상 답변 품질을 올리는 건 아니라는 의문이 생겨요.

본 강의 prod 운영 시 청크 200 / 500 / 1000 × top-3 / 5 / 10 의 어느 조합이 답변 품질 × 비용 의 균형점일지 본인 직관과 데이터를 함께 생각해 보세요. 답변 품질 평가 는 본 강의 Step 5 의 검색 메트릭과 다른 차원 — 생성된 응답 의 정확성 평가 (LLM-as-judge 룰) 가 필요한 부분이에요. 본 강의가 설정한 recall@k / precision@k 는 검색 의 품질이지 답변 의 품질은 아니라는 점을 이해해두세요.

본 강의 Step 4 는 파일명 첫 토큰 으로 character_id 를 자동 추론하는 컨벤션이에요. 학습용 lab 으론 단순 + 깔끔하지만 운영에서는 명시적 manifest (예: manifest.yml 또는 frontmatter) 가 더 안전해요.

[핵심 키워드] Convention over configuration / 명시성 / 운영 변경 가능성 / 다국적 KB

💭 생각해보기

파일명 컨벤션의 장점은 "파일만 잘 지정하면 자동 분류" 의 과정이에요. 단점은 "파일명을 잘못 지으면 잘못 분류" 와 "한 파일에 여러 캐릭터가 등장하는 경우" 같은 모호한 상황이에요. 본 강의의 NOA (학생 추가 캐릭터) 와 NOA 와 ARIA 가 함께 등장하는 에피소드 같은 자료는 어느 character_id 로 분류해야 할까요?

운영 안전성 vs 학습용 단순성의 차이에서 본 강의의 어디까지를 자동 추론으로 가고, 어디부터 명시적 manifest 로 넘어가야 하는지 본인의 방향을 잡아 보세요. 가능한 길은 — (1) 모든 KB 가 단일 캐릭터 전용일 때만 파일명 컨벤션, (2) 다중 캐릭터 자료는 frontmatter character_id: [NOA, ARIA] 로 명시, (3) 모든 자료에 manifest.yml 강제 — 의 세 가지. 본인 서비스의 KB 자라는 속도 와 오류 비용 위에서 방향을 정해 보세요.