Weaviate Cloud 무료 플랜으로 저사양 EC2 서버에 하이브리드(벡터 + 키워드) 검색 추가하기

월 0원으로 블로그에 자연어 검색 붙이기

블로그 검색창에 "로그인이 자꾸 풀려요"라고 쳐 보면 어떤 글이 나와야 할까요? 저라면 JWT 리프레시 토큰 글을 보여주고 싶어요. 그런데 그 글 어디에도 "자꾸 풀려요"라는 말은 없어요.

이 글에서는 키워드 검색만 되던 개인 블로그에 문장의 의미로 글을 찾는 자연어 검색을 붙인 과정을 정리했어요. 조건은 두 가지였어요. 돈을 쓰지 않을 것, 그리고 지금 쓰는 작은 서버에서 돌릴 것.

키워드 검색으로는 부족했어요

원래 검색은 MySQL FULLTEXT 키워드 검색이었어요. 정확한 단어를 알면 잘 찾지만, 독자는 보통 단어가 아니라 겪고 있는 문제로 검색해요.

"로그인이 자꾸 풀려요" → 찾는 글: JWT 리프레시 토큰 로테이션
"글 저장했는데 화면이 안 바뀜" → 찾는 글: Next.js 캐시 무효화

그래서 문장의 의미가 가까운 글을 찾아주는 검색이 필요했어요.

처음부터 정한 범위가 하나 있어요. 검색 결과는 AI가 쓴 답변이 아니라 관련 글 목록이에요. RAG로 치면 검색(R)까지만 만들고 답변 생성(G)은 하지 않았어요. 이유는 뒤에서 설명할게요.

무료 플랜의 제약이 곧 설계가 됐어요

서버는 이미 한 번 저사양 대응(캐시, 요청 수 제한, 조회수 모아서 쓰기 등)을 거친 작은 서버예요. 벡터 DB를 직접 띄울 여유가 없었어요.

그래서 벡터 DB와 임베딩은 Weaviate Cloud 무료 플랜에 맡겼어요. 무료인 대신 제약이 많았는데, 이 제약 하나하나가 그대로 설계 항목이 됐어요. 문서만 믿지 않고 임시 컬렉션으로 직접 확인했어요.

무료 플랜 제약	확인한 방법	설계에 준 영향
컬렉션 1개	직접 호출해서 429	블로그 검색 전용으로 써요. 실제 클러스터 테스트는 일반 테스트와 분리했어요
GraphQL 사용 불가	직접 호출해서 410	gRPC로만 검색해요. 그래서 프레임워크(Spring AI) 대신 Weaviate Java 클라이언트를 직접 써요
벡터 인덱스는 hfresh만	직접 호출해서 422	컬렉션을 만들 때 명시해요
한국어 형태소 분석기(kagome_kr) 사용 불가	직접 호출해서 422	키워드 검색 쪽은 trigram으로 나눠요
임베딩 하루 2,000건	요금 페이지	결과 캐시, 하루 사용량 제한, 이어서 하는 재색인
7일 안 쓰면 중지, 30일 안 쓰면 삭제, 백업 없음	클러스터 문서	원본은 MySQL이에요. 벡터 저장소는 언제든 다시 만들 수 있는 사본으로 다뤄요

가장 중요한 건 마지막 줄이에요. Weaviate는 언젠가 사라진다고 가정했어요. 그러면 나머지 원칙이 자연스럽게 정해져요.

글의 원본은 항상 MySQL이에요.
벡터 저장소가 비거나 멈춰도 검색은 실패하지 않아야 해요. 이때는 키워드 검색으로 대신해요.
사라진 색인은 관리자 API 한 번으로 다시 만들 수 있어야 해요.

전체 구조

역할을 둘로 나눴어요.

Weaviate는 "이 문장과 의미가 가까운 글이 몇 번 글인지"만 알려줘요. 제목이나 썸네일 같은 카드 정보는 저장하지 않아요.
MySQL은 실제로 보여줄 글을 돌려줘요. 이때 공개 조건(is_deleted = false AND is_edit = false)을 한 번 더 확인해요.

이렇게 하면 벡터 저장소가 조금 늦게 따라와도 비공개 글이나 삭제한 글이 검색에 나오지 않아요. 카드에는 항상 MySQL의 최신 내용이 보여요.

글을 색인하는 방법

글을 1,000자씩 나눠서 넣어요

글 하나를 통째로 임베딩하면 긴 글일수록 중간 내용이 묻혀요. 그래서 글을 조각(청크)으로 나눠서 넣어요.

HTML이 아니라 평문을 써요. 에디터가 저장할 때 마크다운 기호를 뺀 텍스트예요.
1,000자 단위로 나누고 100자씩 겹쳐요. 문장이 경계에서 잘려도 앞뒤 의미가 이어지게 하려고요.
제목도 같이 넣어요. 제목에만 있는 단어로도 찾을 수 있어야 하니까요.
조각마다 article:{글 번호}:{조각 번호}로 만든 고정된 ID를 줘요. 같은 글을 여러 번 다시 넣어도 결과가 같아요.

Weaviate에는 조각마다 이 정보만 저장해요.

속성	용도
articleId, chunkIndex	어느 글의 몇 번째 조각인지, 삭제할 때 찾기
category	카테고리로 거르기
title, content	벡터로 바꾸기 + trigram 키워드 검색

글이 바뀌면 색인도 따라 바뀌어요

글을 쓰거나 고치거나 지우거나 발간 상태를 바꾸면, 저장이 끝난 뒤에 색인을 맞춰요. 이렇게 만든 이유는 네 가지예요.

1. 글 저장은 절대 막지 않아요. 색인은 저장(커밋)이 끝난 뒤 따로 돌아요. Weaviate가 느리거나 멈춰 있어도 글은 저장돼요. 시작할 때부터 "Weaviate 때문에 글 저장이 실패하면 잘못된 설계"라고 정해뒀어요.

2. 색인은 스레드 하나로만 돌려요. 작은 서버라서, 색인 때문에 독자 요청을 처리할 자원이 줄어들면 안 됐어요.

3. 처리할 때 DB를 다시 읽어요. 이벤트에는 글 번호만 담고, 실제 상태는 MySQL에서 다시 확인해요. 이 블로그의 발간 API는 isPublish 값을 그대로 is_edit 컬럼에 넣어요. 이름과 반대로 동작해서 헷갈리기 쉬워요. 그래서 DB에 실제로 저장된 값만 믿기로 했어요.

4. 실패해도 다시 시도하지 않아요. 로그만 남기고, 복구는 재색인에 맡겨요.

참고로 발간 API에는 트랜잭션 없이 호출되는 경로가 있어요. 그래서 리스너에 @TransactionalEventListener(fallbackExecution = true)를 썼어요. 이 옵션이 없으면 그 경로의 이벤트가 사라져요.

어떤 글이 색인됐는지 기록해요

글마다 last_embedded_at 컬럼을 두고 이렇게 써요.

값	뜻
시각	그 시각에 지금 내용으로 색인됐어요
NULL	아직 색인 안 됐거나, 다시 해야 해요

여기서 함정을 두 개 만났어요.

updated_at과 비교하면 안 돼요. 이 컬럼은 조회수나 좋아요만 바뀌어도 자동으로 갱신돼요. 비교했다면 누가 읽기만 한 글도 전부 "다시 색인 필요"로 나왔을 거예요. 그래서 비교하는 대신, 색인이 필요해지는 순간(수정, 발간 전환)에 값을 NULL로 비워요.

색인 시각을 적을 때 updated_at이 바뀌면 안 돼요. updated_at은 "최근 수정순" 정렬 기준이에요. 바뀌면 색인할 때마다 글이 목록 맨 위로 올라가요. 그래서 엔티티를 저장하지 않고, 쿼리로 updated_at을 자기 자신으로 지정했어요.

@Modifying
@Query("UPDATE Article a SET a.lastEmbeddedAt = :at, a.updatedAt = a.updatedAt WHERE a.id = :id")

클러스터가 사라져도 다시 만들 수 있어요

API	하는 일
POST /articles/search-index/reindex	공개 글 중 last_embedded_at이 NULL인 글만 색인해요 (이어서 하기)
POST /articles/search-index/reindex?full=true	컬렉션을 새로 만들고 전부 색인해요
GET /articles/search-index/status	진행 상황, 처리한 개수, 오류를 보여줘요

하루 임베딩 한도에 걸리면 멈춰요. 다음 날 같은 API를 다시 부르면 남은 글부터 이어서 해요. 하루 2,000건 한도를 피하지 않고 그대로 받아들인 설계예요. 관리자 페이지에서는 글마다 색인됐는지도 볼 수 있어요.

검색하는 방법

검색 흐름

검색어를 확인해요. 2자 이상, 최대 100자예요.
같은 검색어(와 카테고리)로 만든 순위 목록이 캐시에 있는지 봐요. 있으면 임베딩을 쓰지 않고 바로 4번으로 가요.
없으면 오늘 쓸 수 있는 양이 남았는지 확인하고 Weaviate에서 검색해요(벡터 75% + 키워드 25%, 후보 100개, 2초 제한). 조각 단위 결과를 글 단위로 합쳐서 최대 50개 순위 목록을 만들고 10분 동안 캐시해요.
커서 위치부터 필요한 만큼 글 번호를 잘라 MySQL에서 가져와요. 공개 조건을 다시 확인하고 순위는 그대로 유지해요.
기존 키워드 검색과 똑같은 형식으로 응답해요.

벡터와 키워드를 섞었어요

벡터 검색은 의미는 잘 잡지만, 고유명사나 정확한 용어에는 약해요. 그래서 벡터 75%, 키워드 25%를 섞었어요(alpha = 0.75). 키워드 쪽은 한국어 형태소 분석기를 쓸 수 없어서 trigram으로 나눠요.

페이지는 서버에서 직접 나눠요

한 글의 조각 여러 개가 상위권을 차지할 수 있어요. 그러면 Weaviate에 "다음 10개"를 요청할 때 같은 글이 또 나오거나 빠져요. 그래서 글 단위 순위 목록을 서버가 직접 만들어 캐시해 두고, 커서로 잘라서 보내요.

덕분에 독자가 다음 페이지를 넘겨도 임베딩을 다시 쓰지 않아요. 정확도와 비용을 한 번에 잡은 부분이에요. 결과는 50개까지만 보여줘요. 그 아래는 관련도가 낮아서 의미가 크지 않았어요.

프론트는 거의 바꾸지 않았어요

응답 형식을 기존 키워드 검색과 똑같이 맞췄어요. 그래서 검색 결과 화면은 그대로예요. 프론트에서 바꾼 건 세 가지예요.

관리자용 색인 관리 페이지를 만들었어요. 글마다 색인 여부를 보고 재색인을 실행할 수 있어요.
검색창 문구를 "자연어 검색 (최대 100자)"로 바꾸고, 검색 결과에 "벡터 + 키워드 하이브리드" 안내를 넣었어요.
검색어를 100자로 제한했어요. 자연어 질문은 대부분 10~50자예요. 그보다 길면 대개 오류 로그를 붙여넣은 경우인데, 서버가 특수문자를 지우고 나면 의미 없는 문자열만 남아요. 서버에서도 200자에서 한 번 더 잘라요.

장애가 나도 검색은 돼요

무료 클라우드는 느려질 수도, 멈출 수도, 사라질 수도 있어요. 그래서 어떤 경우에도 검색 API가 서버 오류(5xx)를 내지 않게 만들었어요.

Weaviate를 못 쓰면 키워드 검색으로 대신해요

요청	Weaviate 상태	결과
첫 페이지	실패, 2초 초과, 오늘 사용량 초과	키워드 검색 첫 페이지를 보여줘요
첫 페이지	정상인데 결과 0건	키워드 검색 첫 페이지를 보여줘요
다음 페이지, 캐시 있음	상관없음	캐시로 이어서 보여줘요
다음 페이지, 캐시 없음	정상	다시 검색해서 같은 위치부터 보여줘요
다음 페이지, 캐시 없음	실패	목록을 여기서 끝내요

마지막 줄은 일부러 이렇게 했어요. 키워드 검색 첫 페이지로 넘기면 독자가 이미 본 글이 또 나와요. 그보다는 목록을 끝내는 게 낫다고 판단했어요.

결과가 0건일 때 키워드 검색으로 넘기는 데도 이유가 있어요. AI, 토큰 같은 2글자 검색어는 trigram으로 찾을 수 없어요. 그대로 두면 예전에는 찾히던 글이 안 찾혀요.

작은 서버를 지키는 장치

검색은 2초까지만 기다려요. 넘으면 바로 키워드 검색으로 넘어가고, 다시 시도하지 않아요.
연결이 안 되면 잠시 쉬어요. 30초부터 시작해 최대 6시간까지 다시 연결하지 않아요. 클러스터가 잠들었을 때 모든 요청이 2초씩 기다리는 일을 막아줘요. 재색인을 실행하면 바로 다시 연결해요.
첫 호출만 한 번 더 시도해요. 서버가 막 켜졌을 때 첫 gRPC 호출은 준비 시간 때문에 2초를 넘기기 쉬워요. 그래서 다시 해도 결과가 같은 쓰기 작업만 한 번 더 시도해요.
하루 사용량을 나눠 써요. 검색 API는 누구나 부를 수 있어요. 누군가 검색어를 계속 바꿔 넣으면 하루 임베딩 한도가 바닥나고, 색인까지 멈춰요. 그래서 검색은 하루 1,900건까지만 쓰고 100건은 색인 몫으로 남겨요. 캐시에서 바로 찾은 검색은 세지 않아요. 사용량을 세는 Redis가 멈추면 검색은 막지 않고 그대로 진행해요.

매일 클러스터를 깨워요. "7일 안 쓰면 중지"를 피하려고 매일 새벽에 가벼운 호출을 보내요. 다만 이 호출이 실제로 중지를 막는지는 아직 확인하지 못했어요.
스위치로 켜고 끌 수 있어요. SEMANTIC_SEARCH_ENABLED로 색인은 켜둔 채 독자 검색만 끌 수 있어요. 재색인이 끝나기 전에 일부 글만 검색되는 일을 막고, 실제 글로 기준을 맞춘 뒤에 켜려고 만들었어요. Weaviate 설정이 아예 없으면 서버는 정상으로 켜지고 키워드 검색만 써요.

비용은 이렇게 아꼈어요

돈이 드는 곳	아낀 방법
벡터 DB 서버	직접 띄우지 않고 Weaviate Cloud 무료 플랜을 써요
임베딩 API	Weaviate에 들어 있는 임베딩을 무료 한도 안에서 써요
같은 검색어 반복	순위 목록을 10분 동안 캐시해요
다음 페이지	캐시된 목록을 잘라 써서 임베딩을 쓰지 않아요
한도를 바닥내는 요청	하루 1,900건까지만 써요
재색인	아직 안 된 글만 이어서 해요
AI 답변 생성	만들지 않았어요. 결과는 글 목록이에요

직접 해보고 알게 된 것

무료 플랜과 클라이언트 라이브러리에는 문서와 다른 부분이 있었어요. 임시 컬렉션으로 직접 확인한 내용이에요.

alpha 값을 꼭 적어야 해요. 빼먹으면 한국어 질문의 결과가 비어 있었어요.
alpha=1이 순수 벡터 검색이에요. 점수 설명(explainScore)으로 확인했어요. 쓰고 있는 Java 클라이언트 문서에는 반대로 적혀 있어요.
무료 플랜에서는 GraphQL(410), 한국어 분석기(422), 두 번째 컬렉션(429)이 막혀 있어요. 문서만 보고 설계했다면 구현하다가 다시 짜야 했을 거예요.
넣자마자 검색하면 결과가 비어 있던 적이 한 번 있어요. 다시 재현되지는 않았어요. 그래서 테스트에서는 넣은 직후의 결과를 바로 확인하지 않아요.
관련 있는 글과 없는 글의 경계가 생각보다 흐려요. 실험에서 관련 있는 글의 거리는 0.57~~0.75였는데, 관련 없는 질문의 1등 결과도 0.71~~0.80이었어요. 그래서 기준은 "아주 먼 결과만 자르는" 느슨한 값(기본 0.95)으로 두고, 실제 글로 맞춰가기로 했어요.

왜 AI 답변은 만들지 않았을까요

요즘 "블로그 + AI 검색"이라고 하면 보통 질문하면 AI가 답해주는 RAG 챗봇을 떠올려요. 이번에는 일부러 검색까지만 만들었어요.

비용 때문이에요. 검색할 때마다 답변 생성 비용이 붙어요. 무료 한도 안에서 돌린다는 목표와 맞지 않았어요.
블로그답게 하고 싶었어요. 개인 블로그의 가치는 "내가 쓴 글"이에요. AI 요약보다 그 글로 바로 데려가는 게 낫다고 생각했어요.
나중에 쉽게 붙일 수 있어요. 글 → 조각 → 벡터 색인 흐름이 이미 있어요. 관련 글 추천이나 AI 답변을 붙일 때 그대로 다시 쓰면 돼요.

마치며

이번 작업에서 가장 크게 배운 건 기술보다 순서였어요. 제약을 먼저 직접 확인하고, 그 제약을 설계로 바꾸는 것이요. 무료 플랜이 돌려준 429, 410, 422 하나하나가 결국 캐시, 사용량 제한, 대체 검색, 재색인 설계로 이어졌어요.

이제 검색창에 단어 대신 문장을 넣어 보세요. "로그인이 자꾸 풀려요"처럼요.

사용한 기술: Spring Boot · MySQL · Redis · Caffeine · Weaviate Cloud (text2vec-weaviate, 하이브리드 검색, gRPC Java 클라이언트 client6) · Next.js