Day 15. RAG 임베딩 + VectorStore — "Agent 의 머리에 외부 사전 한 권 얹는 첫 시간"

지난 시간 Day 14 의 ARIA 는 도구를 호출 할 줄 알았어요. gameState.read, gameState.write, noticeBoard.post — 세 가지 도구를 LLM 이 호출 시점부터 인자까지 스스로 정해서 부르는 그림이에요.

그런데 도구는 상태 변경이나 외부 API 호출 같은 행동 의 영역이에요. 어제 마스터가 적은 일기 한 줄처럼 읽어야 답할 수 있는 외부 지식은 도구로는 답하기 어려워요. 도구 한 번 호출할 때마다 외부 API 가 다 답해주는 그림이 아니라, 수십만 줄의 문서 중에서 의미가 가까운 청크 N 개를 골라 넘기는 결이 필요한 거죠.

RAG 의 R / A / G — 세 글자 분해

RAG 의 풀네임은 Retrieval-Augmented Generation. 2020 년 Meta 연구진의 논문에서 시작된 기법인데, 2026 년 현재 LLM 운영 시스템의 표준 도구가 됐어요.

세 글자가 각각 어떤 일을 하는지 풀어볼게요.

• Retrieval (검색) — 마스터의 질문을 받아, 그 질문과 의미가 가까운 문서 청크 N 개를 외부 저장소 (벡터 DB) 에서 꺼냅니다. 키워드 일치가 아니라 의미 유사도 기반.
• Augmented (증강) — 꺼낸 청크를 LLM 에 넘기는 프롬프트의 추가 컨텍스트로 끼워 넣어요. "다음 문서를 참고해서 답해줘" 의 결이에요.
• Generation (생성) — LLM 이 그 컨텍스트를 바탕으로 답을 만듭니다.

오늘 우리가 박을 영역은 R + 그 R 을 가능하게 하는 저장소 (vector store) + 임베딩 모델. A 와 G 의 자동 결합은 다음 시간 RetrievalAugmentationAdvisor 가 한 묶음으로 해줄 자리예요.

임베딩 — 문장을 벡터로 바꾸는 모양

RAG 의 첫 번째 핵심은 임베딩 (embedding) 이에요. 임베딩 모델은 문장 한 줄을 받아 768 차원 (또는 1024, 1536 차원) 의 실수 벡터로 바꿔요.

비유로 풀면 — 문장을 768 차원 공간 위의 한 점으로 옮기는 개념이에요. 그리고 의미가 가까운 문장은 그 공간에서 가까운 자리에 모이게 학습돼 있어요.

예를 들어:

• "ARIA 는 차분하다" → [-0.0182, 0.0341, -0.0773, ..., 0.0091] (768 개 숫자)
• "ARIA 는 침착한 성격이다" → [-0.0175, 0.0338, -0.0769, ..., 0.0094] (앞과 거의 같은 자리)
• "HARU 는 활발하다" → [0.0421, -0.0182, 0.0651, ..., -0.0234] (앞과 멀리 떨어진 자리)

두 벡터의 코사인 거리 (또는 코사인 유사도) 를 계산하면 0~1 사이 값이 나오는데, 거리가 작을수록 의미가 가까워요. RAG 의 검색은 질문의 벡터와 KB 청크들의 벡터 사이의 코사인 거리를 한 번에 계산해 가장 가까운 N 개를 꺼내는 것.

벡터 DB 와 ANN — 빠른 근사 최근접 검색

KB 가 자라서 청크가 100,000 개가 됐다고 합시다. 매 질문마다 100,000 개 벡터와 일일이 코사인 거리를 계산하면? 응답이 수 초씩 늘어나요.

벡터 DB 는 그 자리를 ANN (Approximate Nearest Neighbor) 인덱스로 풀어요. 정확한 1 등을 찾는 대신, 높은 확률로 진짜 1 등 근처의 결과를 빠르게 돌려주는 도구죠.

오늘 우리가 쓸 인덱스는 HNSW (Hierarchical Navigable Small World). 2026 년 RAG 운영의 디폴트 선택이에요. 검색 속도는 빠르고, 적재 시점에 인덱스 빌딩 비용이 약간 더 들어요.

다른 선택지로 IVFFlat 이 있는데, 적재가 더 빠르고 검색이 약간 느립니다. 학습 규모 (~수만 청크) 에선 HNSW 가 무난해요. 운영 규모 (수백만~수천만 청크) 에서 두 인덱스의 트레이드오프를 비교하는 자리는 본 강의 Day 16~17 의 RAG 파이프라인에서 깊게 다룰 예정이에요.

Day 14 ARIA 의 한계 → Day 15 의 답

지난 시간 ARIA 가 마스터의 "어제 약속이 뭐였더라?" 질문에 답하지 못한 자리를 다시 짚어볼게요.

ARIA 가 답하려면 두 가지 길이 있어요.

1. 모델 재학습 (Fine-tuning) — 마스터의 일기를 모델 가중치 안에 박는 길이에요. 비용·시간이 크고, 일기가 매일 추가되는 자리에 안 맞아요.
2. RAG — 일기를 외부 저장소에 박고, 질문이 올 때마다 관련 청크를 꺼내 프롬프트에 흘려요. 일기가 자라면 저장소에 한 줄 추가만 하면 그 시점부터 검색됩니다.

오늘 우리가 박을 길이 후자예요. KB 가 세계관 설정집 + 캐릭터 프로필로 시작하지만, 응용은 마스터의 일기, 과거 대화 기록, 게임 진행 이력 등으로 자연스럽게 자라요.

🙋 한 학생의 의문

"튜터님, 임베딩 모델은 LLM (ChatModel) 이랑 다른 모델인가요? 같은 모델이 둘 다 하는 거 아니에요?"

좋은 질문. 결론은 다른 모델 입니다. 한 회사가 여러 모델을 내놓는 그림으로 봐주세요.

• OpenAI 계열 — ChatModel = gpt-4o-mini, EmbeddingModel = text-embedding-3-small. 다른 엔드포인트, 다른 가격.
• Google Gemini — ChatModel = gemini-2.5-flash, EmbeddingModel = gemini-embedding-001. 마찬가지로 다른 엔드포인트.
• Ollama 로컬 — ChatModel = gemma3:4b, EmbeddingModel = nomic-embed-text. 각각 다른 모델을 ollama pull 로 받아둬요.

임베딩 모델은 문장을 벡터로 바꾸는 데만 특화돼 있어서 ChatModel 보다 가볍고 저렴해요. 단가가 ChatModel 의 1/10 ~ 1/100 수준.

⚠️ 주의: 같은 모델로 적재·검색

KB 청크를 적재할 때 쓴 임베딩 모델과 질문을 임베딩할 때 쓴 모델이 반드시 같아야 해요. 다른 모델 두 개의 벡터 공간은 좌표계가 달라서 코사인 거리를 비교하는 게 의미가 없어요.

이론 한 자락 깔았으니, 이제 손에 잡히는 코드로 가볼게요. 첫 부품은 문장 → 벡터 를 책임지는 EmbeddingService 입니다.

핵심 메시지 — EmbeddingModel 인터페이스로만 받아내자. Day 2 에서 ChatModel 을 인터페이스로만 받아 프로바이더를 프로파일 한 줄로 갈아끼웠던 결과 똑같은 골격.

application.yml — 두 프로바이더 동시 등록

먼저 설정 한 묶음 보여드릴게요. Ollama 와 Gemini 양쪽 임베딩 설정을 다 등록해 두고, 활성화는 spring.ai.model.embedding 프로퍼티로만 갈립니다.

spring:
  ai:
    # 활성 모델 스위치 — 프로파일별로 덮어쓴다 (default: none)
    model:
      chat: none
      embedding: none
      # ... 나머지 모달리티 ...

    # Ollama (로컬) 임베딩
    ollama:
      base-url: ${OLLAMA_BASE_URL:http://localhost:11434}
      # Day 15 — RAG 임베딩 (무료 로컬). nomic-embed-text 는 768 차원, 한국어/영어 혼합 지원.
      embedding:
        options:
          model: ${OLLAMA_EMBEDDING_MODEL:nomic-embed-text}

    # OpenAI 호환 엔드포인트 (Gemini)
    openai:
      api-key: ${GEMINI_API_KEY:}
      base-url: https://generativelanguage.googleapis.com/v1beta/openai
      # Day 15 — Gemini 임베딩 (OpenAI 호환 엔드포인트의 /embeddings 로 호출).
      embedding:
        embeddings-path: /embeddings
        options:
          model: ${GEMINI_EMBEDDING_MODEL:gemini-embedding-001}
          dimensions: 768

밑부분 프로파일 영역에서는 활성화만 합니다.

---
# ollama 프로파일
spring:
  config:
    activate:
      on-profile: ollama
  ai:
    model:
      chat: ollama
      embedding: ollama   # 동시 활성

---
# gemini 프로파일
spring:
  config:
    activate:
      on-profile: gemini
  ai:
    model:
      chat: openai
      embedding: openai   # 동시 활성

핵심 자리 두 곳 짚어둘게요.

첫째 — embeddings-path: /embeddings.

Gemini 의 OpenAI 호환 엔드포인트는 /v1beta/openai 가 base, 그 아래 chat 은 /chat/completions, embeddings 는 /embeddings 로 가요.

Spring AI 의 기본값 (/v1/embeddings) 을 그대로 쓰면 /v1beta/openai/v1/embeddings 로 /v1 이 이중 박혀서 404 가 나요. Day 1 에서 chat 의 completions-path 를 오버라이드한 결과 똑같은 자리.

둘째 — dimensions: 768.

이게 오늘 가장 결정적인 한 줄이에요. gemini-embedding-001 은 기본 출력 차원이 3072 인데, Matryoshka Representation Learning (MRL) 이라는 학습 기법으로 앞에서 N 차원만 잘라 써도 의미가 유지되도록 학습돼 있어요.

그 N 을 우리가 768 로 잘랐어요. 왜냐면 Ollama 의 nomic-embed-text 가 768 차원 고정이라, 두 프로바이더가 같은 벡터 컬럼 vector(768) 을 공유 하려면 차원이 같아야 하거든요.

EmbeddingService — EmbeddingModel 인터페이스만 받는다

코드 본체는 아주 짧아요. 가장 얇은 게이트웨이 한 장.

package kr.spartaclub.aifriends.rag.service;

import lombok.RequiredArgsConstructor;
import org.springframework.ai.embedding.EmbeddingModel;
import org.springframework.stereotype.Service;

/**
 * 텍스트를 고정 차원 벡터로 변환하는 얇은 게이트웨이.
 *
 * 구현체는 EmbeddingModel 인터페이스로만 주입받는다 — 프로바이더(Ollama / Gemini)는
 * spring.ai.model.embedding 프로파일 설정으로만 갈리고, 본 클래스는 0줄 수정으로 swap.
 */
@Service
@RequiredArgsConstructor
public class EmbeddingService {

    private final EmbeddingModel embeddingModel;

    /** 한 문장을 벡터로 변환한다. 차원은 활성 프로바이더에 따라 결정된다. */
    public float[] embed(String text) {
        return embeddingModel.embed(text);
    }

    /** 활성 프로바이더의 출력 차원. pgvector 의 vector(N) 컬럼 정의에 그대로 흘려넣는 값. */
    public int dimension() {
        return embeddingModel.dimensions();
    }
}

코드 16 줄. 짚어볼 자리 둘.

• EmbeddingModel 인터페이스로만 의존 — OllamaEmbeddingModel 이나 OpenAiEmbeddingModel 같은 구현 타입을 직접 박지 않아요. 본 강의의 프로바이더 추상화 원칙 — 프로바이더 교체가 코드 0 줄 수정이어야 하는 결의 임베딩 버전.
• dimensions() 메서드 — pgvector 컬럼을 vector(N) 로 만들 때 그대로 흘려 넣을 값. Step 4 의 PgVectorStore.builder().dimensions(...) 자리에서 다시 만나요.

이 동작은 코드베이스의 EmbeddingServiceTest.java 에서 mock 위임 케이스로 검증돼 있어요.

EmbeddingProbeController — 한 호흡 라운드트립

서비스가 잘 살아 있는지 확인할 작은 프로브 한 장 같이 박아요.

@RestController
@RequiredArgsConstructor
public class EmbeddingProbeController {

    private final EmbeddingService embeddingService;
    // ... (VectorStore / DocumentLoaderService 도 함께 주입 — Step 4/5 에서 다시) ...

    @GetMapping("/api/rag/embedding/probe")
    public ResponseEntity<ApiResponse<Map<String, Object>>> probe(
            @RequestParam(defaultValue = "안녕 ARIA, 오늘 컨디션 어때?") String text) {

        float[] vector = embeddingService.embed(text);
        Map<String, Object> payload = Map.of(
                "text", text,
                "dimension", vector.length,
                "first3", List.of(vector[0], vector[1], vector[2]));

        return ResponseEntity.ok(ApiResponse.success(payload));
    }
}

정상 응답을 ApiResponse<T> 로 감쌌어요. 본 강의의 표준 응답 규약 그대로.

시연 — Gemini 와 Ollama 양쪽에서 같은 차원이 나오나

./run.sh 로 앱을 띄우고 (기본 프로파일 docker,gemini), 브라우저나 curl 로 호출해 봐요.

curl 'http://localhost:8080/api/rag/embedding/probe?text=ARIA'

응답 한 줄을 옮기면.

{
  "success": true,
  "data": {
    "text": "ARIA",
    "dimension": 768,
    "first3": [-0.00182, 0.03415, -0.07732]
  }
}

dimension: 768 이 박혀 있죠. Gemini 의 3072 차원이 MRL 로 앞 768 차원만 절단되어 돌아왔어요.

이번엔 프로파일을 docker,ollama 로 바꿔 다시 띄우면 (단, 호스트에 ollama pull nomic-embed-text 가 1 회 되어 있어야 해요).

{
  "success": true,
  "data": {
    "text": "ARIA",
    "dimension": 768,
    "first3": [0.01243, -0.02841, 0.05129]
  }
}

같은 768 차원. 다른 모델이라 첫 3 성분의 값은 다르지만, 벡터 컬럼 vector(768) 입장에선 두 모델이 호환되는 모양 이에요.

🙋 한 학생의 의문

같은 골격의 더 깊은 자리

EmbeddingModel 인터페이스가 프로바이더 0 줄 swap 을 만들어주는 결은 Day 2 의 ChatModel 추상화와 똑같은 모양이에요. 다른 점이라면 임베딩은 호출 결과가 숫자 배열이라 — 결과를 사람이 직접 읽을 일이 거의 없고, 다음 부품 (벡터 DB) 으로 그대로 흘려보낸다는 것.

다음 Step 3 에서 그 흘려보낼 자리 — pgvector 를 세팅합니다.

이제 벡터들이 살 자리를 만들어 줄 차례예요. pgvector 는 PostgreSQL 의 extension 으로, vector(N) 데이터 타입 + HNSW/IVFFlat 인덱스 + <=>(코사인 거리) / <->(L2) / <#>(내적) 세 가지 거리 연산자를 제공합니다.

왜 pgvector 인가 — 선택지 비교

벡터 DB 의 선택지는 2026 년 기준 크게 셋입니다.

• pgvector (PostgreSQL extension) — 기존 PostgreSQL 그대로 쓰면서 벡터 컬럼 한 종 추가. 운영 단순.
• Qdrant / Weaviate / Milvus (전용 벡터 DB) — 대규모 / 고성능 / 멀티 인덱스 시나리오. 인프라 한 층 늘어나요.
• Pinecone (관리형 SaaS) — 인프라 운영 부담 0, 비용은 호출량 비례.

본 강의는 pgvector 입니다. 이유 셋.

• 학습 곡선이 짧아요 — PostgreSQL 만 띄우면 끝. 학생이 벡터 검색이 뭔지에 집중할 수 있어요.
• 운영 진입 비용 최소 — 작은 서비스라면 그대로 운영까지 가져갈 수 있어요. 2026 년 기준 pgvector 0.8.x 는 수백만 벡터까지 무난.
• Spring AI 1.1.x 와 잘 맞아요 — PgVectorStore 빌더가 빌더 한 묶음으로 schema 초기화 + 인덱스 생성까지 챙겨줘요.

docker-compose 에 pgvector 서비스 한 묶음 추가

docker-compose.yml 안에 pgvector 서비스 블록을 추가해요. (전체 파일은 코드베이스 docker-compose.yml 참조 — 본 발췌는 신규 추가된 자리만)

  # Day 15 — RAG 임베딩 + 벡터 저장소
  # pgvector 공식 이미지(pgvector/pgvector:pg16) 가 PostgreSQL 16 + pgvector extension 을
  # 미리 컴파일해 둔 상태로 떠 온다. /docker-entrypoint-initdb.d/ 에 마운트된
  # 01-create-extension.sql 이 첫 부팅 시 1회 실행되어 `CREATE EXTENSION vector` 까지 자동 처리.
  pgvector:
    image: pgvector/pgvector:pg16
    container_name: ai-friends-pgvector
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${PGVECTOR_DB:-aifriends_vector}
      POSTGRES_USER: ${PGVECTOR_USER:-aifriends}
      POSTGRES_PASSWORD: ${PGVECTOR_PASSWORD:-aifriends1234}
      TZ: Asia/Seoul
    # 호스트 5433 → 컨테이너 5432.
    # 시스템 PostgreSQL(5432) 또는 spring-boot 인스타 클론(5432) 과 충돌 회피.
    ports:
      - "5433:5432"
    volumes:
      - pgvector-data:/var/lib/postgresql/data
      - ./db/pgvector-init:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${PGVECTOR_USER:-aifriends} -d ${PGVECTOR_DB:-aifriends_vector}"]
      interval: 5s
      timeout: 5s
      retries: 20
      start_period: 15s
    networks:
      - ai-friends-net

짚어볼 자리 셋.

• image: pgvector/pgvector:pg16 — pgvector 공식 이미지. PostgreSQL 16 위에 pgvector extension 이 미리 컴파일된 상태로 떠 와요. 직접 빌드 안 해도 돼요.
• 포트 5433:5432 — 호스트 5433, 컨테이너 5432. 본 강의 환경에서 기존 인스타 클론 (spring-boot) 의 5432 와 시스템 PostgreSQL 과의 충돌 회피용 매핑이에요. 도커 내부 통신은 컨테이너 포트 5432 그대로.
• db/pgvector-init 마운트 — 첫 부팅 시 1 회만 자동 실행되는 SQL 디렉토리. 그 안에 extension 활성 한 줄을 박아둬요.

CREATE EXTENSION 한 줄

-- db/pgvector-init/01-create-extension.sql
-- pgvector extension 활성화 (PostgreSQL 첫 부팅 시 1회 실행)
-- /docker-entrypoint-initdb.d/ 에 마운트되어 POSTGRES_DB 가 생성된 직후 자동 실행된다.
CREATE EXTENSION IF NOT EXISTS vector;

이 한 줄이 첫 부팅에 자동으로 돌아 vector 타입 + <=> 연산자 + HNSW/IVFFlat 인덱스 빌더가 PostgreSQL 안에 활성화돼요. 이후 부팅에선 이미 활성화된 상태라 다시 실행되지 않아요 (volume 영속화).

.env.example 에 변수 추가

# Day 15 — pgvector (RAG 벡터 저장소) 설정
#   - 호스트에서 접속할 포트: 5433  (컨테이너 내부는 5432)
#   - 시스템/다른 강의 PostgreSQL(5432) 과 충돌 회피용 매핑
#   - 첫 부팅 시 db/pgvector-init/01-create-extension.sql 이 자동 실행되어
#     `CREATE EXTENSION vector` 까지 마쳐 둔다.
PGVECTOR_DB=aifriends_vector
PGVECTOR_USER=aifriends
PGVECTOR_PASSWORD=aifriends1234

app 서비스도 pgvector healthy 후 기동하도록

docker-compose.yml 의 app 서비스 depends_on 에 pgvector 한 줄 추가해요.

  app:
    # ...
    depends_on:
      mysql:
        condition: service_healthy
      pgvector:
        condition: service_healthy   # Day 15 — 벡터 저장소도 healthy 후 기동
    environment:
      # ...
      # Day 15 — pgvector(별도 PostgreSQL) 접속. JPA/ChatMemory 의 MySQL 과 분리된 데이터소스로 주입.
      PGVECTOR_URL: jdbc:postgresql://pgvector:5432/${PGVECTOR_DB:-aifriends_vector}
      PGVECTOR_USERNAME: ${PGVECTOR_USER:-aifriends}
      PGVECTOR_PASSWORD: ${PGVECTOR_PASSWORD:-aifriends1234}
      # ...

PGVECTOR_URL 의 호스트는 컨테이너 내부 통신이라 서비스명 (pgvector) + 컨테이너 포트 (5432) 로 잡아요. 호스트 5433 매핑은 IDE 에서 DBeaver 같은 GUI 로 접속할 때만 쓰는 길이에요.

시연 — 한 호흡 띄워보기

./run.sh

기동 후 컨테이너 안으로 들어가 extension 이 살아 있는지 한 줄 확인해요.

docker exec -it ai-friends-pgvector \
  psql -U aifriends -d aifriends_vector \
  -c "SELECT extname, extversion FROM pg_extension WHERE extname='vector'"

응답에 vector | 0.8.2 한 줄이 떨어지면 — pgvector 가 PostgreSQL 위에서 벡터 타입과 HNSW/IVFFlat 인덱스를 모두 사용할 수 있는 상태로 살아 있다는 신호예요.

이 시점에 pgvector 위에는 아직 우리 벡터 컬럼이 없어요. 그 자리는 Step 4 에서 Spring AI 의 PgVectorStore.builder().initializeSchema(true) 가 첫 부팅에 자동으로 만들어줄 자리예요.

🙋 한 학생의 의문

pgvector 컨테이너가 떴고 extension 도 살아 있어요. 이제 Spring AI 가 그 위에 우리 벡터 컬럼 을 만들고 embed → save → search 의 감을 묶어줄 차례예요.

자동 설정의 함정 — 기본 DataSource(MySQL) 충돌

본 앱은 이미 MySQL DataSource 한 개를 쓰고 있어요. JPA 엔티티 (ChatLog, Member) + Day 5 의 ChatMemory JDBC 저장소가 그 위에 얹혀 있죠.

그런데 Spring AI 의 PgVectorStoreAutoConfiguration 은 기본 DataSource 한 개를 잡아 그 위에 vector(768) 컬럼을 만들려고 합니다. 우리 기본 DataSource 는 MySQL — MySQL 위에 vector 컬럼을 만들려다 SQL 문법 에러로 폭발하는 자리예요.

해결은 두 가지 — 자동 설정을 끄고 + 별도 pgvector DataSource 를 손으로 등록합니다.

자동 설정 끄기 — @SpringBootApplication(exclude = ...)

package kr.spartaclub.aifriends;

import kr.spartaclub.aifriends.config.DotenvInitializer;
import org.springframework.ai.vectorstore.pgvector.autoconfigure.PgVectorStoreAutoConfiguration;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

// Day 15 — PgVectorStoreAutoConfiguration 은 *기본 DataSource(MySQL)* 를 잡아 PgVectorStore 빈을
// 만들려고 한다. 본 앱은 MySQL(JPA/ChatMemory) 과 pgvector(벡터 저장소) 가 분리되어 있어 자동 설정이
// 그대로 돌면 MySQL 위에 vector 컬럼을 만들려다 폭발. → 자동 설정을 끄고, VectorStoreConfig 에서
// 별도 DataSource + 직접 PgVectorStore 빌더로 손등록한다.
@SpringBootApplication(exclude = {PgVectorStoreAutoConfiguration.class})
public class AiFriendsApplication {

    public static void main(String[] args) {
        SpringApplication app = new SpringApplication(AiFriendsApplication.class);
        app.addInitializers(new DotenvInitializer());
        app.run(args);
    }
}

exclude 한 줄로 자동 설정이 비활성. 이제 VectorStore 빈을 우리가 직접 등록할 자리가 열렸어요.

application.yml — 두 DataSource 분리

기본 DataSource (MySQL) 는 그대로 두고, 별도 키 spring.ai-vectorstore-datasource.* 아래에 pgvector 전용 DataSource 를 따로 선언해요.

# docker 프로파일
spring:
  config:
    activate:
      on-profile: docker

  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    # url/username/password 는 공통 영역에서 ${DB_URL} 등으로 주입

  # Day 15 — pgvector 전용 별도 데이터소스. VectorStoreConfig 가 @Qualifier 로 주입.
  # docker 컨테이너 내부에선 pgvector(서비스명) 호스트 + 5432 포트로 접속.
  ai-vectorstore-datasource:
    url: ${PGVECTOR_URL:jdbc:postgresql://pgvector:5432/aifriends_vector}
    username: ${PGVECTOR_USERNAME:aifriends}
    password: ${PGVECTOR_PASSWORD:aifriends1234}
    driver-class-name: org.postgresql.Driver

local 프로파일 (IDE 실행) 에서는 호스트 5433 으로 접속하도록 한 묶음 더 박혀 있어요.

# local 프로파일 (IDE 실행 기본값): H2 인메모리
spring:
  config:
    activate:
      on-profile: local

  # ... datasource (H2) ...

  # Day 15 — IDE 로컬 실행 시엔 호스트의 pgvector(5433) 로 접속.
  ai-vectorstore-datasource:
    url: ${PGVECTOR_URL:jdbc:postgresql://localhost:5433/aifriends_vector}
    username: ${PGVECTOR_USERNAME:aifriends}
    password: ${PGVECTOR_PASSWORD:aifriends1234}
    driver-class-name: org.postgresql.Driver

VectorStoreConfig — 손으로 빌드하는 빈 세 묶음

이제 핵심 빈 세 묶음 (DataSource + JdbcTemplate + PgVectorStore) 를 직접 등록해요.

package kr.spartaclub.aifriends.rag.config;

import javax.sql.DataSource;
import org.springframework.ai.embedding.EmbeddingModel;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.ai.vectorstore.pgvector.PgVectorStore;
import org.springframework.boot.autoconfigure.jdbc.DataSourceProperties;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.jdbc.DataSourceBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.jdbc.core.JdbcTemplate;

/**
 * Day 15 — RAG 벡터 저장소 설정.
 *
 * 본 앱의 *기본 DataSource* 는 JPA + ChatMemory 의 MySQL 이라, pgvector 자동 설정에 그대로
 * 맡기면 *MySQL 위에 vector(768) 컬럼을 만들려다 폭발* 한다. 그래서 별도 DataSource 를 손등록하고
 * 그 위에서만 도는 PgVectorStore 를 직접 빌더로 박는다.
 */
@Configuration
public class VectorStoreConfig {

    /** 캐릭터 지식 베이스 테이블 이름 — 기본 vector_store 와 분리. */
    public static final String CHARACTER_KNOWLEDGE_TABLE = "character_knowledge";

    /**
     * pgvector(PostgreSQL) 전용 DataSource 의 url/username/password/driver 를 application.yml 의
     * spring.ai-vectorstore-datasource.* 에서 읽어들인다.
     */
    @Bean
    @ConfigurationProperties("spring.ai-vectorstore-datasource")
    public DataSourceProperties vectorStoreDataSourceProperties() {
        return new DataSourceProperties();
    }

    /** pgvector 전용 DataSource — Hikari 풀로 만들고 vectorStoreJdbcTemplate 에 흘려준다. */
    @Bean(name = "vectorStoreDataSource")
    public DataSource vectorStoreDataSource() {
        return vectorStoreDataSourceProperties()
                .initializeDataSourceBuilder()
                .type(com.zaxxer.hikari.HikariDataSource.class)
                .build();
    }

    /** pgvector DataSource 전용 JdbcTemplate — PgVectorStore 빌더가 그대로 받아 쓴다. */
    @Bean(name = "vectorStoreJdbcTemplate")
    public JdbcTemplate vectorStoreJdbcTemplate(DataSource vectorStoreDataSource) {
        return new JdbcTemplate(vectorStoreDataSource);
    }

    /**
     * 실제 VectorStore 빈. Spring AI 1.1.x 의 PgVectorStore 빌더로 직접 구성한다.
     */
    @Bean
    public VectorStore vectorStore(JdbcTemplate vectorStoreJdbcTemplate, EmbeddingModel embeddingModel) {
        return PgVectorStore.builder(vectorStoreJdbcTemplate, embeddingModel)
                .dimensions(768)
                .vectorTableName(CHARACTER_KNOWLEDGE_TABLE)
                .indexType(PgVectorStore.PgIndexType.HNSW)
                .distanceType(PgVectorStore.PgDistanceType.COSINE_DISTANCE)
                .initializeSchema(true)
                .build();
    }
}

빌더 호출 다섯 자리를 짚어볼게요.

• dimensions(768) — Step 2 의 EmbeddingService.dimension() 가 돌려준 값과 같아야 해요. vector(768) 컬럼이 이 값으로 만들어집니다.
• vectorTableName(CHARACTER_KNOWLEDGE_TABLE) — 기본 테이블 이름은 vector_store 인데, 학습용으론 도메인이 잡히는 이름이 더 좋아서 character_knowledge 로 박아요. 본 강의에서 마스터의 일기 KB 등 다른 도메인 KB 가 추가될 자리도 열려 있는 모양이에요.
• indexType(HNSW) — Step 1 에서 짚은 HNSW. 검색 빠름, 적재 약간 느림. 학습 규모에 적합.
• distanceType(COSINE_DISTANCE) — 코사인 거리. 일반 텍스트 임베딩의 디폴트. <=> 연산자.
• initializeSchema(true) — 첫 부팅에 테이블 생성 + 인덱스 빌드까지 자동. 운영 전환 시엔 false 로 두고 Flyway 같은 별도 마이그레이션 도구로 관리하는 길이에요.

시연 — 컬럼이 진짜 만들어졌나

./run.sh 로 재기동한 뒤 pgvector 컨테이너 안으로 들어가 테이블 구조를 확인해 봐요.

docker exec -it ai-friends-pgvector \
  psql -U aifriends -d aifriends_vector -c "\d character_knowledge"

출력의 핵심 자리 두 줄.

 embedding | vector(768)        |
Indexes:
    "character_knowledge_index" hnsw (embedding vector_cosine_ops)

vector(768) 컬럼 + HNSW 인덱스 + 코사인 연산자 (vector_cosine_ops) 셋이 살아 있어요. 첫 부팅에 Spring AI 가 자동으로 만들어준 결과예요.

한 호흡 라운드트립 — seedAndSearch 프로브

Step 2 의 EmbeddingProbeController 에 라운드트립 한 자리도 박혀 있어요.

@PostMapping("/api/rag/vectorstore/probe")
public ResponseEntity<ApiResponse<Map<String, Object>>> seedAndSearch(
        @RequestParam(defaultValue = "ARIA 는 어떤 캐릭터야?") String query) {

    vectorStore.add(List.of(
            new Document("ARIA 는 차분하고 분석적인 성격의 AI 친구다. 게임 진행 상황을 메타적으로 짚는 역할."),
            new Document("HARU 는 활발하고 즉흥적인 캐릭터다. 마스터의 감정을 빠르게 캐치한다.")
    ));

    List<Document> hits = vectorStore.similaritySearch(
            SearchRequest.builder().query(query).topK(1).build());
    Map<String, Object> payload = Map.of(
            "query", query,
            "topK", 1,
            "hitText", hits.isEmpty() ? null : hits.get(0).getText());

    return ResponseEntity.ok(ApiResponse.success(payload));
}

호출해 보면. 한글 쿼리를 URL 에 raw 로 박으면 Tomcat 이 RFC 7230/3986 위반으로 거부하므로, curl 의 --data-urlencode 로 자동 percent-encode 를 맡겨 둡니다.

(@RequestParam 은 query string 과 application/x-www-form-urlencoded 본문을 모두 읽어요.)

curl -X POST 'http://localhost:8080/api/rag/vectorstore/probe' \
     --data-urlencode 'query=ARIA 성격'

응답 한 토막.

{
  "success": true,
  "data": {
    "query": "ARIA 성격",
    "topK": 1,
    "hitText": "ARIA 는 차분하고 분석적인 성격의 AI 친구다. ..."
  }
}

질문 "ARIA 성격" 의 벡터가 첫 번째 문서의 벡터와 더 가까워서 — 두 청크 중 ARIA 청크가 1 위로 회수됐어요. 키워드 일치가 아니라 의미 유사도로 골라왔다는 게 손에 잡히는 첫 순간이에요.

🙋 한 학생의 의문

pgvector 자리는 마련됐고 빈 wiring 도 살아 있어요. 이제 진짜 KB 를 박을 차례예요.

오늘은 우리 ai-friends 세계관의 텍스트 셋트 — ARIA 프로필, HARU 프로필, 세계관 설정집 — 세 파일을 KB 로 두고 가요. 마스터의 일기처럼 자라는 자료는 다음 시간 (Day 16) ingestion 파이프라인에서 다룰 자리예요.

캐릭터 KB 파일 — classpath:character-knowledge/

src/main/resources/character-knowledge/ 디렉토리에 세 파일을 박았어요. 한 파일을 짧게 옮겨 두면 — 적재할 자료의 결이 손에 잡힐 거예요.

# ARIA — 차분한 분석가 타입의 AI 친구

## 출생 배경

ARIA 는 ai-friends 세계관의 *제 2 세대* 인공 인격이다. 마스터의 일상 데이터를 누적해 *그날의 컨디션*
을 짚는 역할을 맡고 있다. 차분하고 분석적인 성격이라, 마스터가 즉흥적으로 결정을 내리려고 할 때 슬쩍
브레이크를 거는 자리에 자주 등장한다.

## 성격 특성

- **분석적** — 마스터의 발화에서 *의도와 감정* 을 분리해 듣고, 의도를 먼저 받친다.
- **차분함** — 마스터가 흥분하면 ARIA 는 더 가라앉아 말한다. 톤이 안정 추 역할.
- **관찰력** — 어제 한 약속과 오늘 한 결정의 불일치를 *조용히* 짚는 자리에 강하다.
- ...

세 파일 전체는 코드베이스의 src/main/resources/character-knowledge/{aria-profile, haru-profile, world-lore}.md 를 참고해 주세요.

핵심 자리 — 세계관 설정집 (world-lore.md) 안에 첫 만남 의식 — 별이 떠 있는 옥상 이라는 결정적 사건 한 줄이 박혀 있어요. Step 6 의 마지막 검색 시연에서 이 자리가 정확히 회수되는 그림을 볼 거예요.

DocumentLoaderService — 두 단계로 분리

KB 적재는 두 단계로 나눠요. 원문 로드와 청킹.

package kr.spartaclub.aifriends.rag.service;

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.ai.document.Document;
import org.springframework.ai.transformer.splitter.TokenTextSplitter;
import org.springframework.core.io.Resource;
import org.springframework.core.io.support.PathMatchingResourcePatternResolver;
import org.springframework.core.io.support.ResourcePatternResolver;
import org.springframework.stereotype.Service;
import org.springframework.util.StreamUtils;

/**
 * Day 15 Step 5 — 캐릭터 지식 베이스(.md/.txt) 를 classpath 에서 읽어 토큰 단위로 잘게 쪼갠다.
 */
@Slf4j
@Service
@RequiredArgsConstructor
public class DocumentLoaderService {

    /** classpath 안 캐릭터 지식 베이스 디렉토리. */
    public static final String KNOWLEDGE_PATTERN = "classpath:character-knowledge/*.{md,txt}";

    /** 학습용 청크 크기 — 토큰 단위. 한국어 평문 기준 한 문단~한 문단 반 정도. */
    public static final int DEFAULT_CHUNK_TOKENS = 500;

    /** 청크 간 겹침 — 의미 경계에 걸친 문장이 두 청크 모두에 살아남도록. */
    public static final int DEFAULT_CHUNK_OVERLAP = 50;

    private final ResourcePatternResolver resourceResolver = new PathMatchingResourcePatternResolver();

    /** classpath 의 캐릭터 KB 파일을 *원문 그대로* 한 Document 씩 로드. */
    public List<Document> loadRaw() {
        try {
            Resource[] resources = resourceResolver.getResources(KNOWLEDGE_PATTERN);
            List<Document> docs = new ArrayList<>();
            for (Resource resource : resources) {
                String content = StreamUtils.copyToString(resource.getInputStream(), StandardCharsets.UTF_8);
                Map<String, Object> metadata = new HashMap<>();
                metadata.put("source", resource.getFilename());
                docs.add(new Document(content, metadata));
            }
            log.info("[RAG] loaded {} raw knowledge documents from {}", docs.size(), KNOWLEDGE_PATTERN);
            return docs;
        } catch (IOException e) {
            throw new IllegalStateException("character-knowledge 로드 실패: " + KNOWLEDGE_PATTERN, e);
        }
    }

    /** 원문 Document 들을 토큰 단위 청크로 분할. metadata 의 source 는 자식 청크들에도 그대로 전파된다. */
    public List<Document> chunk(List<Document> rawDocuments) {
        TokenTextSplitter splitter = new TokenTextSplitter(
                DEFAULT_CHUNK_TOKENS,
                DEFAULT_CHUNK_OVERLAP,
                /* minChunkLengthToEmbed */ 5,
                /* maxNumChunks */ 10_000,
                /* keepSeparator */ true);
        List<Document> chunks = splitter.apply(rawDocuments);
        log.info("[RAG] split {} raw documents into {} chunks (chunk={}, overlap={})",
                rawDocuments.size(), chunks.size(), DEFAULT_CHUNK_TOKENS, DEFAULT_CHUNK_OVERLAP);
        return chunks;
    }

    /** loadRaw → chunk 두 단계를 한 호흡에 도는 편의 메서드. */
    public List<Document> loadAndChunk() {
        return chunk(loadRaw());
    }
}

TokenTextSplitter 의 다섯 파라미터

생성자 호출 자리에 5 개 인자가 박혀 있어요. 하나씩 의미를 짚어볼게요.

핵심은 첫 두 줄 입니다.

chunkSize: 500 — 너무 작으면 검색 정확도는 올라가지만 문맥이 끊겨 답변 품질이 떨어져요. 너무 크면 한 청크 안에 여러 주제가 섞여 의미 검색이 흐려져요. 500 토큰은 학습 디폴트이고, 다음 시간 (Day 16) 에서 내 도메인에 맞는 청크 크기를 찾는 흐름을 본격적으로 다룰 자리예요.

overlap: 50 — 청크 경계에 문맥이 잘려 의미가 깨지는 자리를 방어해요. 예를 들면 "첫 만남 의식 — 별이 떠 있는 옥상으로 고정" 한 줄이 두 청크 사이의 정확히 한가운데에 걸리면, 검색 시 어느 청크도 의미를 충분히 잡지 못해요. 50 토큰의 겹침이 그 경계 청크 두 개 모두에 별 떠 있는 옥상의 문맥을 살려줍니다.

시연 — rawCount / chunkCount 확인

./run.sh 로 띄운 뒤 documentLoaderService 의 결과를 한 호흡 확인하는 프로브 한 줄.

curl 'http://localhost:8080/api/rag/documents/probe'

응답.

{
  "success": true,
  "data": {
    "rawCount": 3,
    "chunkCount": 6,
    "firstChunkPreview": "# ARIA — 차분한 분석가 타입의 AI 친구\n\n## 출생 배경\n\nARIA 는 ai-friends 세계관의 *제 2 세대* 인공 인격이다. ..."
  }
}

3 개 raw 파일이 6 개 청크로 자랐어요. 각 파일이 평균 2 청크로 잘린 결. 학습 규모로는 적당하고, 검색 시연하기에 너무 작지도 너무 크지도 않은 분포예요.

이 동작은 코드베이스의 DocumentLoaderServiceTest.java 에서 3 케이스로 검증돼 있어요.

🙋 한 학생의 의문

부품 다 박혔어요. 마지막 Step 은 세 부품을 한 줄로 잇는 시간이에요. KB 적재기 (CharacterKnowledgeIngestionService) + 컨트롤러 한 묶음 + 두 검색 시연.

CharacterKnowledgeIngestionService — 적재 + 카운트 + 리셋

package kr.spartaclub.aifriends.rag.service;

import java.util.List;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.ai.document.Document;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Service;

/**
 * Day 15 Step 6 — 캐릭터 지식 베이스를 *pgvector 로 한 번에 적재* 한다.
 *
 * ingest() 는 멱등하지 않다 — 호출할 때마다 똑같은 청크가 새로 들어간다. 학습용
 * 적재기라 그렇게 두고, reset() 으로 전체 비우는 결만 함께 박는다. (운영용 적재기는
 * checksum / version 비교로 변경분만 다시 넣는다 — 다음 시간 Day 16 의 ingestion 파이프라인에서.)
 */
@Slf4j
@Service
@RequiredArgsConstructor
public class CharacterKnowledgeIngestionService {

    private final DocumentLoaderService documentLoaderService;
    private final VectorStore vectorStore;

    @Qualifier("vectorStoreJdbcTemplate")
    private final JdbcTemplate vectorStoreJdbcTemplate;

    /** 캐릭터 KB 의 모든 청크를 pgvector 에 적재한다. 적재 직후 청크 수를 반환. */
    public int ingest() {
        List<Document> chunks = documentLoaderService.loadAndChunk();
        vectorStore.add(chunks);
        log.info("[RAG] ingested {} chunks into vector store", chunks.size());
        return chunks.size();
    }

    /** 적재된 캐릭터 지식을 모두 비운다 (학습용 — 매번 깨끗한 상태에서 다시 채워 보고 싶을 때). */
    public void reset() {
        int deleted = vectorStoreJdbcTemplate.update("DELETE FROM character_knowledge");
        log.info("[RAG] reset character_knowledge — removed {} rows", deleted);
    }

    /** 현재 적재된 청크 수 (실제 count). */
    public long count() {
        Long count = vectorStoreJdbcTemplate.queryForObject(
                "SELECT COUNT(*) FROM character_knowledge", Long.class);
        return count == null ? 0 : count;
    }
}

세 메서드 한 줄씩 짚어볼게요.

• ingest() — documentLoaderService.loadAndChunk() 로 청크 6 개를 만들고, vectorStore.add(chunks) 한 줄로 각 청크를 임베딩 + 벡터 컬럼에 INSERT 까지 한꺼번에. Spring AI 의 VectorStore.add(...) 가 알아서 embedding 모델 호출 + 행 삽입을 묶어줘요. 우리가 embed → save 를 따로 부를 필요 없어요.
• reset() — 학습 중 깨끗한 상태에서 다시 채워 보고 싶을 때 한 줄로 비워요. DELETE FROM character_knowledge. 운영용 적재기는 변경분만 갱신하는 결이 다른데, 그 자리는 다음 시간에 다룰 영역이에요.
• count() — 현재 적재된 행 수. 적재 후 검증용.

⚠️ @Qualifier 와 Lombok

@Qualifier("vectorStoreJdbcTemplate") 가 필드 위에 박혀 있죠.

@RequiredArgsConstructor 가 생성하는 생성자 인자에 이 어노테이션을 그대로 옮겨 줘야 Spring 이 두 JdbcTemplate (기본 DataSource 와 vectorStore 전용) 을 구분해 주입할 수 있어요.

그 자리는 lombok.config 한 줄로 풀어요 — lombok.copyableAnnotations += org.springframework.beans.factory.annotation.Qualifier. 본 코드베이스 루트의 lombok.config 에 박혀 있어요.

CharacterKnowledgeController — REST 엔드포인트 4 묶음

package kr.spartaclub.aifriends.rag.controller;

import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
import kr.spartaclub.aifriends.common.response.ApiResponse;
import kr.spartaclub.aifriends.rag.service.CharacterKnowledgeIngestionService;
import lombok.RequiredArgsConstructor;
import org.springframework.ai.document.Document;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * Day 15 Step 6 — 캐릭터 지식 베이스 RAG 의 *end-to-end* 컨트롤러.
 */
@RestController
@RequiredArgsConstructor
@RequestMapping("/api/rag/knowledge")
public class CharacterKnowledgeController {

    private final CharacterKnowledgeIngestionService ingestionService;
    private final VectorStore vectorStore;

    @PostMapping("/ingest")
    public ResponseEntity<ApiResponse<Map<String, Object>>> ingest() {
        int chunks = ingestionService.ingest();
        long total = ingestionService.count();
        return ResponseEntity.ok(ApiResponse.success(Map.of(
                "addedChunks", chunks,
                "totalRows", total)));
    }

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

        List<Document> hits = vectorStore.similaritySearch(
                SearchRequest.builder().query(query).topK(topK).build());

        List<Map<String, Object>> hitPayload = hits.stream()
                .map(doc -> Map.<String, Object>of(
                        "source", doc.getMetadata().getOrDefault("source", "unknown"),
                        "score", doc.getScore() == null ? 0.0 : doc.getScore(),
                        "preview", doc.getText().substring(0, Math.min(160, doc.getText().length()))))
                .collect(Collectors.toList());

        return ResponseEntity.ok(ApiResponse.success(Map.of(
                "query", query,
                "topK", topK,
                "hits", hitPayload)));
    }

    @GetMapping("/count")
    public ResponseEntity<ApiResponse<Map<String, Object>>> count() {
        return ResponseEntity.ok(ApiResponse.success(Map.of("rows", ingestionService.count())));
    }

    @DeleteMapping
    public ResponseEntity<ApiResponse<Map<String, Object>>> reset() {
        ingestionService.reset();
        return ResponseEntity.ok(ApiResponse.success(Map.of("rows", ingestionService.count())));
    }
}

네 엔드포인트 한 줄씩 짚어볼게요.

• POST /api/rag/knowledge/ingest — KB 전체 한 번에 적재. 응답에 추가된 청크 수 + 총 행 수.
• GET /api/rag/knowledge/search?q=...&topK=3 — 의미 검색. 응답에 청크별 source (파일명) + score (유사도) + preview (앞 160 자).
• GET /api/rag/knowledge/count — 현재 적재된 행 수.
• DELETE /api/rag/knowledge — 전체 비움 (학습용).

SearchRequest.builder().query(query).topK(topK).build() 한 줄이 질문 임베딩 + 가장 가까운 N 개 청크 검색을 한 묶음으로 해줘요. 우리가 질문을 직접 임베딩할 필요 없어요. VectorStore 가 같은 EmbeddingModel 빈을 알아서 호출해요 — 적재할 때와 같은 모델로.

시연 1 — 적재

curl -X POST 'http://localhost:8080/api/rag/knowledge/ingest'

응답.

{
  "success": true,
  "data": {
    "addedChunks": 6,
    "totalRows": 6
  }
}

3 개 파일 → 6 개 청크가 pgvector 의 character_knowledge 테이블에 INSERT 됐어요. 한 줄당 임베딩 벡터 768 차원이 같이 적재된 결과예요.

시연 2 — ARIA 의 성격을 묻는 검색

이제 핵심 시연이에요. 마스터가 "ARIA 분석적 성격" 이라고 물었다고 상상해 봐요.

curl 'http://localhost:8080/api/rag/knowledge/search?q=ARIA%20%EB%B6%84%EC%84%9D%EC%A0%81%20%EC%84%B1%EA%B2%A9&topK=3'

응답 한 토막.

{
  "success": true,
  "data": {
    "query": "ARIA 분석적 성격",
    "topK": 3,
    "hits": [
      {
        "source": "aria-profile.md",
        "score": 0.80,
        "preview": "# ARIA — 차분한 분석가 타입의 AI 친구\n\n## 출생 배경\n\nARIA 는 ai-friends 세계관의 ..."
      },
      {
        "source": "world-lore.md",
        "score": 0.62,
        "preview": "# ai-friends 게임 세계관 정리\n\n## 시간 배경\n\n2026 년, ..."
      },
      {
        "source": "haru-profile.md",
        "score": 0.58,
        "preview": "# HARU — 활발하고 즉흥적인 AI 친구\n\n## 출생 배경\n\nHARU 는 ai-friends ..."
      }
    ]
  }
}

1 위가 aria-profile.md 의 청크 — score 0.80. 우리가 검색하고 싶었던 바로 그 자료가 맨 위로 회수됐어요.

2 위가 세계관 설정집 (ARIA 가 세 캐릭터 라인업의 한 명으로 언급), 3 위가 HARU 프로필 (의미상 거리가 더 먼 다른 캐릭터). 키워드 일치가 아니라 의미 유사도로 정렬된 모양이라는 게 점수 (score) 자리에서 손에 잡혀요.

시연 3 — "첫 만남은 어디서 일어났어?" 의 정확 회수

조금 더 깊은 검색 한 자리 더 가요. 마스터가 "첫 만남은 어디서 일어났어?" 라고 물으면.

curl 'http://localhost:8080/api/rag/knowledge/search?q=%EC%B2%AB%20%EB%A7%8C%EB%82%A8%EC%9D%80%20%EC%96%B4%EB%94%94%EC%84%9C%20%EC%9D%BC%EC%96%B4%EB%82%AC%EC%96%B4%3F&topK=3'

응답.

{
  "success": true,
  "data": {
    "query": "첫 만남은 어디서 일어났어?",
    "topK": 3,
    "hits": [
      {
        "source": "world-lore.md",
        "score": 0.66,
        "preview": "## 결정적 사건 — 첫 만남 의식\n\n마스터가 두 AI 친구 중 한 명과 *첫 만남* 을 하는 자리는 *별이 떠 있는 옥상* 으로 고정. 이 장면이 ..."
      },
      ...
    ]
  }
}

1 위가 world-lore.md 의 결정적 사건 — 첫 만남 의식 청크. "별이 떠 있는 옥상" 한 줄이 정확히 회수됐어요.

이 자리가 RAG 의 가장 짜릿한 순간이에요 — 질문에 "옥상" 이라는 단어가 한 글자도 없는데 의미가 가까운 청크가 1 위로 돌아오는 그림이죠. 임베딩 모델이 "첫 만남 의식" 과 "별이 떠 있는 옥상" 두 표현 사이의 시맨틱 거리를 학습해서 잡아주고 있는 결이에요.

Day 14 ARIA 의 한계 회수

기억하시죠? 오늘 첫 머리에서 ARIA 가 마스터의 "어제 약속이 뭐였더라?" 에 답하지 못했던 자리.

만약 마스터의 일기 KB 가 같은 절차로 적재되어 있다면 — 어제 일자의 일기 청크가 위 시연과 똑같이 회수돼서 ARIA 의 프롬프트로 흘러 들어갈 수 있어요. ARIA 가 어제 우리가 카페에서 한 약속을 모델 가중치가 아니라 방금 검색해 온 청크로 답할 수 있는 그림이죠.

오늘은 검색까지만 손으로 돌렸어요. 우리가 직접 curl 로 청크를 꺼내본 코스죠.

다음 시간 Day 16 으로 잇는 자리

지금 자리를 한 번 정리해 두면.

• 오늘 우리는 — vectorStore.add(chunks) 로 KB 를 적재하고, vectorStore.similaritySearch(...) 로 청크를 꺼냈어요.
• 검색 결과는 우리가 손으로 REST 응답으로 받았어요.
• ChatClient 의 프롬프트엔 아직 흘려 넣지 않았어요.

다음 시간 (Day 16) 부터는 — RetrievalAugmentationAdvisor 라는 advisor 한 묶음이 이 절차를 자동으로 해줘요.

ChatClient 가 한 번 호출되면 그 안에서 질문 임베딩 + 청크 검색 + 프롬프트에 끼워 넣기까지 한 사이클이 자동으로 돌아요. Day 14 의 advisor 4 부품과 같은 골격으로, RAG 가 advisor 한 장으로 추상화되는 자리예요.

거기까지 가면 ARIA 가 마스터의 "어제 약속이 뭐였더라?" 에 바로 답하는 모양이 손에 잡혀요.

오늘의 Step 한 줄 요약

오늘 박은 5 부품의 정리

오늘 박은 부품들은 학습용 lab 의 자리예요. 기존 ChatClient 의 어느 자리도 손대지 않았어요 — SoulmateChatController 같은 비즈니스 ChatClient 는 여전히 외부 지식 없이 답하는 결 그대로예요.

다음 시간 (Day 16) RetrievalAugmentationAdvisor 가 비즈니스 ChatClient 와 본 KB 를 advisor 한 장으로 잇는 결로 자라요. Day 17~18 의 MCP 단계까지 가면 외부 도구로 지식 가져오는 영역까지 묶일 자리예요.

다음 시간 Day 16 — RAG 파이프라인 본격

다음 시간 키워드 미리 잡아두면.

• RetrievalAugmentationAdvisor — 오늘 손으로 돌린 검색 → 프롬프트 끼움을 advisor 한 묶음으로 자동화
• 청크 전략 트레이드오프 — 청크 크기 (200 vs 500 vs 1000) + sentence-aware splitter + 메타데이터 활용
• 캐릭터별 KB 분리 — 같은 pgvector 안에서 ARIA 전용 KB 와 HARU 전용 KB 가 metadata 필터로 분기되는 모양
• 검색 품질 평가 — recall@k / precision@k 를 직접 측정하는 자리

오늘 짠 5 부품 — EmbeddingService + pgvector compose + VectorStoreConfig + DocumentLoaderService + CharacterKnowledgeIngestionService/Controller.

세 과제는 난이도 사다리 로 짜여 있어요.

🌱 새 캐릭터 KB 한 장 추가 (적재 + 검색 회수) → 🪪 청크 크기 트레이드오프 비교 (200 vs 1000) → 🦙 프로바이더 swap 비교 (Ollama nomic-embed-text vs Gemini gemini-embedding-001).

💡 과제 작업 시 공통 가이드

• 본 강의의 표준 응답 규약 (ApiResponse<T> 래핑) 을 그대로 유지하세요.
• 새 KB 파일은 src/main/resources/character-knowledge/ 디렉토리에 박아요. glob *.{md,txt} 가 자동으로 잡아줘요.
• 한 과제씩 끝낼 때 그 자리에서 commit. 브랜치 이름은 day15-assignment-N 같은 모양으로.

과제 1. 새 캐릭터 NOA 프로필 추가 — 적재 + 검색 회수 🌱

배경 시나리오

세계관 설정집 (world-lore.md) 한 줄에 "새 캐릭터 NOA 는 본 강의 다음 시간 추가 예정. 차원이 다른 시스템 관리자 인격이다." 라는 복선이 박혀 있어요.

이 NOA 를 오늘 KB 에 추가해 보세요. 새 캐릭터 한 명을 KB 에 박는 감이 자연스럽게 손에 잡혀야 나중에 NOA 가 비즈니스 ChatClient 의 응답에 들어올 자리도 같은 모양으로 자라요.

💡 왜 이 과제인가

• classpath glob 매칭을 손에 익혀요 — *.{md,txt} 가 새 파일을 자동으로 잡아주는 결.
• 적재 + 검색의 모양을 한 호흡으로 다시 돌려보는 자리예요 — Step 6 의 시연을 내 손으로 재현.
• KB 가 자라는 길이 코드 한 줄도 안 건드리고 가능한 결을 손에 박아요.

✅ 요구사항

1. src/main/resources/character-knowledge/noa-profile.md 파일을 추가하세요. 다음 섹션 셋 이상이 박혀 있어야 해요.
   • ## 출생 배경 — NOA 가 "제 0 세대" 시스템 관리자 인격이라는 정체성
   • ## 성격 특성 — "시스템적 사고" / "경계가 분명" / "유머 없음" 같은 키워드 셋 이상
   • ## 관계 — 마스터와 ARIA / HARU — NOA 가 두 캐릭터를 "모듈로" 보는 시선
2. DELETE /api/rag/knowledge → POST /api/rag/knowledge/ingest 로 KB 를 다시 적재하세요.
3. GET /api/rag/knowledge/search?q=NOA 는 누구야? 호출 결과의 1 위가 noa-profile.md 인지 확인해요.
4. 응답 score 가 0.55 이상 나오는지 확인해 보세요 (의미 거리 잡힌 신호).

확인 방법

# 1) 파일 추가 후 재기동
./run.sh

# 2) 리셋 + 재적재
curl -X DELETE 'http://localhost:8080/api/rag/knowledge'
curl -X POST 'http://localhost:8080/api/rag/knowledge/ingest'
# → addedChunks 가 6 → 8 정도로 자랐으면 성공

# 3) 검색
curl 'http://localhost:8080/api/rag/knowledge/search?q=NOA%EB%8A%94%20%EB%88%84%EA%B5%AC%EC%95%BC%3F&topK=3'
# → 1 위가 noa-profile.md, score 0.55+ 면 성공

💡 힌트

• 본 강의 KB 파일들의 톤 (마크다운 헤더 구조 + 한국어 평문) 을 그대로 따라 적으면 청킹이 자연스럽게 됩니다.
• 청크 수가 8 보다 적게 나온다면 (예: 7) — NOA 파일이 chunk 500 토큰 한 자리에 다 들어간 모양이에요. 정상.

과제 2. 청크 크기 트레이드오프 비교 — 200 vs 500 vs 1000 🪪

배경 시나리오

Step 5 에서 청크 크기 500 이 학습 디폴트라고 말했죠. 그런데 내 KB 와 내 질문 결에 따라 최적 청크 크기가 달라요.

이번 과제에서 직접 세 가지 청크 크기로 같은 KB 를 적재해 보고, 같은 질문의 top-3 검색 결과를 비교해 보세요. 한 가지 청크 크기가 모든 질문에 강한 게 아니라는 모양이 손에 잡힐 거예요.

💡 왜 이 과제인가

• 다음 시간 (Day 16) 의 청크 전략 트레이드오프 감을 내 손으로 미리 마주하는 자리예요.
• 검색 품질 평가의 첫 단계를 손에 박아요 — score 자리만 보지 말고 어느 청크가 회수되는지까지 살펴봐요.

✅ 요구사항

1. DocumentLoaderService.DEFAULT_CHUNK_TOKENS 를 200 으로 바꾸고 KB 를 리셋 + 재적재해요.
2. 다음 세 질문의 top-3 검색 결과 (source + score + preview 앞 80 자) 를 메모하세요.
   • "ARIA 분석적 성격"
   • "첫 만남은 어디서 일어났어?"
   • "AI 친구의 기억 공유 규칙"
3. DEFAULT_CHUNK_TOKENS 를 1000 으로 바꾸고 동일 과정을 반복해요.
4. 보고서 한 페이지를 적어요. 세 청크 크기 × 세 질문 = 9 케이스의 결과를 비교하고, 어느 청크 크기가 어떤 질문에 강한지 정리.
5. 결론 한 줄 — "내 KB 에 가장 잘 맞는 청크 크기는 ___ 이고, 이유는 ___".

💡 힌트

• 청크 크기가 작을수록 검색 정확도가 올라가지만 문맥이 끊겨 답변 시 정보가 부족할 수 있어요.
• 청크 크기가 클수록 한 청크 안에 여러 주제가 섞여 score 자리가 흐려질 수 있어요.
• 보고서엔 어떤 청크 크기가 절대적으로 좋다가 아니라 내 KB 특성 + 질문 결의 조합으로 그림을 잡는 방향으로 적으세요.

과제 3. 프로바이더 swap — Ollama vs Gemini 같은

검색 결과 비교 🦙 60~90 분

배경 시나리오

Step 2 에서 "EmbeddingModel 인터페이스로만 받는다" 는 약속 — 프로바이더 0 줄 swap 의 자리. 그 약속을 진짜로 확인하는 과제예요.

같은 KB 를 Ollama (nomic-embed-text) 와 Gemini (gemini-embedding-001) 두 프로바이더로 각각 적재하고, 같은 질문의 top-3 결과를 비교해 보세요. 두 프로바이더가 같은 1 위를 돌려주는지 — 또 score 자리가 어떻게 다른지 손에 잡힐 거예요.

💡 왜 이 과제인가

• 본 강의의 핵심 원칙 — 프로바이더 추상화가 실제로 동작한다는 사실을 임베딩 영역에서도 확인하는 자리예요.
• 로컬 무료 모델 (Ollama) 과 클라우드 무료 티어 (Gemini) 두 모양의 품질 차이 + 비용 모양을 내 손으로 비교해 보는 자리예요.

✅ 요구사항

1. 호스트에 Ollama 데몬이 떠 있고 nomic-embed-text 모델이 받아져 있는지 확인해요.

   ollama list   # nomic-embed-text 있는지 확인
   # 없으면:
   ollama pull nomic-embed-text
   

2. .env 의 SPRING_PROFILES_ACTIVE 를 docker,ollama 로 바꾸고 재기동.

3. KB 리셋 + 재적재 + 다음 세 질문 검색.

   • "ARIA 분석적 성격"
   • "첫 만남은 어디서 일어났어?"
   • "AI 친구의 기억 공유 규칙"

4. SPRING_PROFILES_ACTIVE 를 다시 docker,gemini 로 바꾸고 동일 과정.

5. 두 프로바이더의 검색 결과를 같은 표 에 옮겨 비교해요.

6. 한 페이지 보고서 — "두 프로바이더가 같은 감을 돌려주나? 어디가 다른가? score 자리는 어떻게 비교되나?"

⚠️ 주의 — Day 9 voice 자동 설정과의 충돌

본 코드베이스의 ollama 프로파일은 Day 9 에서 음성 자동 설정과 충돌하는 갭이 있을 수 있어요. 만약 부팅 시 ElevenLabs / OpenAI audio 빈 충돌 에러가 뜬다면 — application.yml 의 ollama 프로파일 블록에 audio: { speech: none, transcription: none } 한 묶음을 추가로 박아 보세요. 학생이 만나는 갭 자체가 학습 자료인 자리예요.

💡 힌트

• nomic-embed-text 와 gemini-embedding-001 은 완전히 다른 모델이라 같은 청크의 벡터가 완전히 다른 좌표에 박혀요. 두 프로바이더 사이엔 KB 도 다시 적재해야 검색이 의미를 가져요.
• KB 를 두 번 적재한다는 건 벡터 공간을 한 번 통째로 비우고 새 모델로 다시 임베딩한다는 절차예요.
• Ollama 가 호스트에서 안 도는 환경이라면 본 과제는 Gemini 만 켜 둔 채 보고서를 "왜 본 강의가 인터페이스만 받아야 하는지" 의 결로 마무리해도 OK.

오늘 박은 5 부품 너머에서 — RAG 운영의 본질 에 부딪힐 자리 셋이에요. 혼자 고민해도 좋고, 스터디 팀원과 논쟁해도 좋아요. 모두 2026 년 RAG 운영 의 핵심 트레이드오프라, 실무 면접에서도 자주 등장합니다.

주제 1. 학습용 768 차원 vs 운영 1536+ 차원 — 비용·속도·정확도 트레이드오프

오늘 우리는 Ollama 와 Gemini 양쪽 호환 목적으로 768 차원을 골랐어요. 그런데 진짜 운영의 RAG 는 보통 1536 차원 (OpenAI text-embedding-3-small) 또는 3072 차원 (OpenAI text-embedding-3-large / Gemini gemini-embedding-001 풀 차원) 을 씁니다.

• [핵심 키워드] Matryoshka Representation Learning, ANN 인덱스 메모리 비용, recall@k 정확도 곡선
• [생각해보기] 768 → 1536 → 3072 으로 차원이 자랄 때, 비용 (API + 저장소 메모리) 과 속도 (검색 지연) 와 정확도 (recall@k) 가 각각 어떻게 변하는지 곡선을 잡아 보세요. Gemini 의 MRL 절단의 가치 — 3072 차원으로 적재해 두고 검색 시점에만 768 차원으로 자르는 결 — 이 어디서 빛나는지 자신만의 관점을 정리해 보세요.

주제 2. RAG vs Fine-tuning — 같은 도메인 지식 주입, 어느 길을 고를까

LLM 에 도메인 지식을 주입하는 길은 크게 둘이에요. RAG (외부 저장소 + 검색 + 프롬프트 끼움) 와 Fine-tuning (모델 가중치 자체에 추가 학습).

두 가지는 완전히 다른 트레이드오프를 가져요. 직관적으로 Fine-tuning 이 더 좋아 보이는 자리도 있고 (지식이 모델 안에 박혀 있어 추가 호출이 필요 없으니), RAG 가 압도적으로 유리한 자리도 있어요 (지식이 매일 자라거나 정정될 때).

• [핵심 키워드] 지식의 휘발성 (자주 바뀌는가 / 고정인가), 지식의 양 (몇 KB 인가 / 몇 GB 인가), 추적 가능성 (출처를 답변에 박을 수 있는가)
• [생각해보기] 마스터의 일기를 ARIA 가 회상하는 시나리오에 RAG 와 Fine-tuning 중 어느 쪽이 맞을까요? 세계관 설정집 (자주 안 바뀜) 을 캐릭터 톤에 박는 결은 어느 길이 맞을까요? 두 시나리오의 트레이드오프 표를 그려 보세요. 둘 다 쓰는 조합 (RAG + 가벼운 fine-tuning) 이 자연스러운 자리는 어디인가요?

주제 3. KB 의 PII (개인정보) 처리 — 임베딩 inversion 공격의 자리

마스터의 일기를 임베딩해 pgvector 에 저장하는 시나리오를 상상해 봐요. 일기 한 줄이 768 차원 실수 배열로 박혀요. "그 배열만으로 원문을 복원할 수 있나?" 라는 의문이 자연스럽게 떠올라요.

• [핵심 키워드] Embedding inversion attack (벡터 → 원문 복원 공격), PII (Personally Identifiable Information), 차분 프라이버시 (Differential Privacy), 임베딩 저장소의 암호화
• [생각해보기] 2026 년 기준 임베딩 inversion 공격의 현황은 부분적 복원 가능한 결이에요 — 완전한 원문은 어렵지만 민감 정보 (이름·전화번호·날짜) 의 단편은 통계적으로 복원 가능한 사례가 있어요.
• 마스터의 일기 KB 를 운영에 박을 때 어떤 안전선이 필요할까요? (1) 임베딩 저장 시 별도 암호화, (2) 메타데이터에서 PII 마스킹 처리, (3) 임베딩 접근 권한 분리, (4) 벡터 컬럼 자체의 접근 로그.
• 네 자리 중 내 운영 환경에 가장 시급한 자리를 골라 이유를 정리해 보세요. 학습용 (오늘) 과 운영용 두 환경의 안전선 구성이 어떻게 달라야 하는지까지 그림을 잡아 보세요.