aicasebook.dev 검색에 대해 정리 (rerank, 검색어 분석, 클로드 코드 스킬)
vector + rerank 를 기반으로, 검색어를 분석한 결과의 가중치를 대입해서 검색을 만드는 법
aicasebook.dev 검색 구조
개요
기술 문서 검색 시스템. 바이브 코딩과 LLM 도구 활용에 대한 주제를 주로 다룸.
검색의 목적은 아래와 같다. 주요 요소에 대한 A/B 테스트를 통해 노출 대비 클릭율을 집계함.
1. 자연어 문맥 검색 — 현재 검색어와 키워드가 겹치지 않아도 click 전환이 활발함.
2. 의도 기반 검색 — 특정 회사명, 특정 제품, 컨셉명( harness, codex 등)이 들어오면 관련 리소스를 우선 반환함.
3. 매칭 이유 코멘트 — 각 항목의 매칭 이유에 대한 간단한 코멘트를 검색 결과에 포함
e.g.) "AI 개발 효율화" 검색 → "claude-code-in-action" 반환 시, 카드 아래에 "CI 단계에서 도구를 통한 테스트 자동화"라는 이유를 붙임.
파이프라인
공식 자료, 요약 자료 두개에 대해 검색을 수행.
각각 병렬로 실행후 결과를 sse 로 전송.
검색 파이프라인
│
├─ 1. 검색어 분석 (의도 추출)
│ ├─ 검색 키워드 분석 (ES Percolate)
│ └─ 키워드 매칭 문서 세트 확보
│
├─ 2. 벡터 검색
│ ├─ 공식 문서 검색의 경우 , 청크에 대한 벡터 검색
│ └─ 요약 자료 검색의 경우 , 본문 벡터에 대한 검색
│
├─ 3. Rerank
│ ├─ rerank 풀(검색 대상)을 만들고 , (2) 의 결과 상위권을 포함시킴.
│ ├─ (1) 키워드 보유 문서를 rerank 풀에 포함 시킴.
│ ├─ (1)의 의도 키워드 보유 문서에 가중치 적용
│ ├─ 청크 검색: 문서당 max 3 → 문서 유니크 → top 10
│ └─ → SSE: 정렬된 결과 카드 전송
│
└─ 4. 매칭 이유 생성
├─ 청크 검색 → chunk_summary (1줄 요약)
├─ 문서 검색 → target_audiences 기반 상황 매칭
└─ → SSE: 매칭 이유 전송 (timeout 3.5s, 초과 시 late callback)
→ 요약 문서: 1 → 2(문서, top 30) → 3 → 4(GPT 매칭)
→ 공식 자료: 1 → 2(청크, top 100) → 3(dedup → top 10) → 4(chunk_summary)
- 벡터 검색: OpenAI text-embedding-3-small → ES KNN
- Rerank: Cohere rerank-v3.5
- 매칭 이유 생성 (문서 검색): GPT-5.1-mini
검색어 분석
검색어에서 의도 키워드를 추출하여, 같은 키워드를 보유한 문서를 rerank 대상에 포함시키고 스코어에 가중치를 둠.
가령 "네이버 AI 하네스 구성"이라는 검색어는 "네이버", "하네스"라는 측면에서 타겟이 있는 검색어임.
Percolate 인덱스에 키워드 쿼리를 사전 등록해둠.
// 사전에 intent_keyword 풀을 정의해야함
// 각 문서는 해당 키워드 세트를 만드는 과정이 인덱싱 과정에 포함되어 있어야 함.
{
"keyword_id": "harness",
"display_name": "하네스",
"category": "CONCEPT",
"intent_level": "HIGH",
"boost_weight": 3,
"query": {
"bool": {
"should": [
{ "match": { "search_text": "하네스" } },
{ "match": { "search_text": "harness" } }
],
"minimum_should_match": 1
}
}
}
한/영 표기, 오타, 복합어를 모두 등록해둠. 검색어가 들어오면 Percolate Query로 키워드를 추출하고, 추출된 키워드로 문서 풀에서 같은 키워드가 태깅된 문서를 조회하여 intent-pool을 만듦.
입력: "빅테크 AI 하네스 구축 사례"
Percolate → harness (weight: 3.0)
↓
intent-pool (intent_keywords에 "harness"가 태깅된 문서):
→ "네이버의 AI 하네스 구축 사례" { weight: 3.0 }
→ "AI 하네스 개념과 적용" { weight: 3.0 }
이 문서들은 벡터 검색 결과와 합쳐져서 rerank 대상이 되고, rerank 이후 키워드 가중치가 적용됨.
Percolate Query를 쓰는 이유
키워드로 "네이버 클라우드", "네이버 페이", "네이버"가 등록되어 있을 때, "네이버 클라우드의 운영 환경"으로 검색하면 "네이버 클라우드"만 매칭되어야 함. 일반 match/term query로는 "네이버" 토큰이 공통이기 때문에 세 키워드가 전부 매칭됨.
Percolate Query는 쿼리를 저장한 다음, 입력된 검색어가 각 쿼리에 해당하는지 수행함. 여기서는 "네이버 클라우드" 키워드가 match_phrase로 저장되어 있기 때문에, 검색어에 "네이버 클라우드"라는 구문이 포함되어야만 매칭됨. "네이버 페이"는 구문이 없으므로 매칭되지 않음.
컴퓨팅 비용이 더 높지만, 키워드 수가 제한적이므로 감수함.
매칭 이유 생성
결과 카드에 "왜 이 글이 검색되었는지"를 한 줄로 보여줌.
새로운 도구와 개념이 많은 분야라 가이드를 제공하는 것이 도움이 될 것이라 판단.
청크 검색의 경우
의미 단위로 분할된 청크 중 rerank 스코어가 가장 높은 것이 선택됨. 해당 청크의 1줄 요약은 검색어와의 접점을 가장 잘 드러내므로, 추가 가공 없이 매칭 이유가 됨.
검색어: "claude code 메모리 설정"
매칭 청크:
본문 title: "[클코 공식] 3.3. CLAUDE.md "
청크 넘버 : 3
chunk_summary: "CLAUDE.md와 자동 메모리 중 어떤 것을 쓸지에 대한 기준."
→ 카드에 표시되는 매칭 이유: chunk_summary 내용
요약 문서의 경우
청크 검색은 요약을 그대로 쓰지만, 요약 문서는 문서 안에 관점이 많기 때문에 별도의 매칭 이유 생성이 필요함.
인덱싱 시점에 태깅된 예상 독자 목록(target_audiences)에서 GPT-5.1-mini가 검색어에 가장 가까운 항목을 선택함.
검색어: "LLM으로 데이터 자동 정제"
매칭 문서:
title: "Llama로 하드웨어 부품 탄소 배출량을 자동 분류한 구조"
target_audiences: ["이기종 데이터 LLM 자동 정제", "NLP 유사 부품 매칭", "분류 체계 자동 생성"]
→ 카드에 표시되는 매칭 이유: "이기종 데이터 정제가 고민이라면"
데이터 가공
검색을 위해 인덱싱 시점에 데이터를 추가로 생성/조작함. 아래는 그 작업과 데이터에 대한 간략한 설명. 현재 Claude Code 스킬을 이용해서 주기적으로 실행 중이고, 실행 시점과 스킬 제작은 다음 문서에서 다룸.
intent_keywords
의도 기반 검색용. 사전 정의된 키워드 풀에서 문서에 해당하는 키워드를 태깅함.
title: "네이버의 AI 하네스 구축 사례"
intent_keywords: ["harness", "naver"]
target_audiences
매칭 이유 생성용. 문서 내용을 읽고, 이 글이 도움이 될 상황을 키워드로 추출함.
title: "Llama로 하드웨어 부품 탄소 배출량을 자동 분류한 구조"
target_audiences: ["이기종 데이터 LLM 자동 정제", "NLP 유사 부품 매칭", "분류 체계 자동 생성"]
청크 분할 + chunk_summary
긴 문서를 읽고 의미 단위로 나눔. 문서 크기를 고려하여 2~10개의 청크로 분리하고, 각 청크에 1줄 요약을 붙임.
AiDoc "Claude Code 공식 문서"
│
├─ chunk[0]: "설치 방법" → vector, chunk_summary
├─ chunk[1]: "CLAUDE.md vs 자동 메모리" → vector, chunk_summary
│ ...
└─ chunk[15]: "트러블슈팅" → vector, chunk_summary
본문 제목: "[클코 공식] 3.3. CLAUDE.md "
chunk_title: "CLAUDE.md vs 자동 메모리"
chunk_summary: "CLAUDE.md와 자동 메모리 중 어떤 것을 쓸지에 대한 기준."
chunk_summary는 검색 결과 카드의 매칭 이유로 직접 사용됨.
여담
#v=A 하세요, ab 테스트
현재 a/b 테스트를 진행중이라 검색 퀄리티가 균질하지 않을 수 있음.
/search?q=PR%20코드%20리뷰%20자동화#v=A
/search?q=PR%20코드%20리뷰%20자동화#v=B
#v=A, #v=B 이렇게 직접 태그를 넣으면 입맛에 맞게 검색어를 바꿀 수 있음.
이 글의 독자는 #v=A 이걸로 봤으면 좋겠음. 이게 좋음.
B 버전은 비교 데이터를 위해서 둔 것이라 좀 별로고 곧 내릴 거임.
자료 보강할때 클로드 코드는 진짜 좋은듯.
지금 검색 컨텍스트를 생성할때 skill + agent 엮어서 만든 워크 플로우로 데이터를 보강하고 있음.
api 를 별도로 쓰는 요금제와 비교하면, 문서 당 500원이 넘는 토큰 소모도 클로드 코드 100$ 요금제 안에서 넉넉하게 돌릴 수 있음.
만족