선을 넘는 개발 로그

JSON-LD 구조화 데이터: SPA 검색엔진 노출 문제 해결기

개요JSON-LD 구조화 데이터는 페이지 안의 정보를 검색엔진이 그대로 이해하도록 붙이는 표준화된 메타데이터입니다. 그런데 SPA(Single Page Application)는 이 데이터를 심어도 크롤러가 못 읽는 경우가 있습니다. 데이터를 JS가 브라우저에서 받아 그리기 때문에, 크롤러가 처음 받는 HTML에는 아무 콘텐츠도 없기 때문입니다.전국 클래식 공연장의 일정을 모아 보여주는 개인 사이드 프로젝트(클래식 공연 캘린더)에서 이 문제를 겪었습니다. Vite + TypeScript로 만든 SPA라 첫 HTML에는 공연이 하나도 없었고, Search Console에는 색인이 거의 잡히지 않았습니다.이 글은 JSON-LD 구조화 데이터를 빌드 시점에 심어 이 문제를 해결한 과정을 정리합니다. 개념보다는 ..

목차들어가며 1. 증상 — 반쪽만 저장된 데이터2. 코드를 다 뒤졌는데 아무 문제가 없었습니다3. 용의자는 코드가 아니라 실행 환경이었습니다4. 스레드가 들고 있는 것 — 그림 두 장으로 보는 차이5. 왜 로그 한 줄 안 남았을까 — 침묵의 메커니즘6. 추측을 멈추고 자를 만들었습니다7. 실측 — 같은 WAR, 옵션 하나만 토글8. 잔재 지도 — 어디서 터졌느냐에 따라 남는 게 달랐습니다9. 수정은 한 줄이었습니다10. 고치고 나니 새로 생긴 걱정들11. 남은 이야기와 배운 것들어가며@Transactional은 개발하면서 가장 의심을 안 하게 되는 어노테이션 중 하나입니다. 붙여두면 예외가 났을 때 알아서 되돌려주니까요. 저도 그렇게 믿고 몇 년을 살았습니다.그런데 운영에서 이런 데이터가 나오기 시작했습..

들어가며사내 운영 매뉴얼을 자동 생성하고, 그 매뉴얼과 코드·Jira·Confluence를 한 번에 물어볼 수 있는 챗봇을 만들고 있었습니다. 기능은 돌아갔습니다. 문제는 질문 하나에 2분이 걸렸다는 것입니다.2분은 사내 도구로서 사실상 사용 불가입니다. 사람들은 30초를 못 기다립니다. 그래서 "RAG를 붙이면 빨라지지 않을까"라는 이야기가 나왔는데, 저는 이 말이 좀 불편했습니다. RAG는 유행어라 아무 데나 붙이면 좋아진다는 인상이 있지만, 실제로 무엇을 얼마나 줄여주는지 모르는 채 도입하면 그냥 벡터DB 운영 부담만 늘어난 시스템이 됩니다. 그래서 도입 전에 먼저 한 일은 지연을 실측으로 분해하는 것이었습니다. 이 글은 그 실측에서 시작해 RAG를 어디까지 적용했고, 무엇을 일부러 적용하지 않았고..

검색 시스템에서 가장 중요한 질문은 단순합니다.“사용자의 질문에 가장 잘 맞는 문서를 어떻게 위로 올릴 것인가?” BM25나 벡터 검색은 이 질문에 대한 1차 답을 제공합니다. 빠르게 많은 문서 중에서 그럴듯한 후보를 찾아옵니다. 하지만 후보 검색 결과가 항상 완벽한 순서로 정렬되는 것은 아닙니다. 이때 사용하는 것이 Reranker입니다. Reranker는 이미 검색된 후보 문서들을 다시 평가해서, 사용자 질문에 더 잘 맞는 순서로 재정렬하는 모델입니다.사용자 질문 -> BM25 / Vector Search -> 후보 문서 top-k 검색 -> Reranker로 재정렬 -> 최종 상위 문서 반환 예를 들어 사용자가 다음과 같이 질문했다고 가정합니다.퇴직연금 중도 인출 조건은 무엇인가요? 1차 검..

RRF는 Reciprocal Rank Fusion의 약자로, 여러 검색 결과 목록을 하나의 최종 순위로 합치는 랭킹 결합 방법입니다.한국어로는 “역순위 융합” 정도로 이해할 수 있습니다.예를 들어 하나의 검색 시스템에서 다음 두 가지 검색 결과를 동시에 얻었다고 가정합니다.BM25 기반 검색 결과벡터 임베딩 기반 검색 결과BM25는 정확한 키워드 일치에 강하고, 벡터 검색은 의미적 유사성에 강합니다.그렇다면 두 결과를 잘 합치면 키워드 검색과 의미 검색의 장점을 함께 사용할 수 있습니다. 이때 자주 쓰이는 방식이 RRF입니다. 핵심 아이디어 RRF의 핵심은 단순합니다. 여러 검색 결과에서 높은 순위에 자주 등장하는 문서를 더 중요하게 봅니다.즉, 어떤 문서가 BM25 결과에서도 상위권이고, 벡터 검색 결..

BM25(Best Matching 25)는 검색 시스템에서 문서의 관련도를 계산하는 대표적인 키워드 기반 랭킹 알고리즘입니다. 사용자가 검색어를 입력했을 때, 각 문서가 그 검색어와 얼마나 관련 있는지를 점수로 계산하고, 점수가 높은 문서를 위에 배치합니다. BM25는 오래된 알고리즘입니다. 하지만 지금도 Elasticsearch, OpenSearch, Lucene 같은 검색 엔진에서 기본 랭킹 방식으로 널리 사용됩니다. 딥러닝 기반 검색과 벡터 검색이 보편화된 지금도 BM25가 사라지지 않는 이유는 명확합니다. 빠르고, 단순하고, 설명 가능하며, 여전히 강력하기 때문입니다.핵심 아이디어BM25의 핵심은 “검색어가 문서 안에서 얼마나 중요하게 등장하는가”를 계산하는 것입니다. 이를 위해 BM25는 크게 ..

목차개요RAG 아키텍처와 LangChain4j의 핵심 개념LangChain4j 환경 설정과 기본 구성RAG 파이프라인 단계별 구현심화 — 성능 최적화와 검색 품질 개선운영 환경 적용 시 고려사항맺음말개요문제 배경대형 언어 모델(LLM)은 방대한 지식을 학습했지만, 학습 데이터의 최신성 한계와 특정 도메인 정보의 부재라는 근본적인 제약을 안고 있습니다. 기업 내부 문서, 최신 제품 매뉴얼, 고유한 정책 데이터를 모델이 알고 있다고 기대하기는 어렵습니다. RAG(Retrieval-Augmented Generation) 는 이 문제를 정면으로 해결합니다. 사용자의 질문에 맞는 관련 문서를 동적으로 검색한 후, 그 내용을 프롬프트에 주입해 LLM이 정확하고 근거 있는 답변을 생성하도록 돕는 패턴입니다. Java..

처음 RAG 챗봇을 만들 때는 모든 게 싸 보입니다. OpenAI 임베딩 1만 토큰에 $0.0002, GPT-4o-mini 답변 한 번에 $0.001. "이 정도면 무한히 써도 되겠는데?" 그런데 사용자가 100명, 1,000명, 10,000명으로 늘어나면 다른 세상이 펼쳐집니다.월 청구서를 보고 깜짝 놀랍니다. OpenAI에서 $5,000, Pinecone에서 $800, Cohere Rerank에서 $300. 한 답변이 평균 8초씩 걸려서 사용자 이탈도 늘어납니다. 어디서부터 손을 대야 할까요?이 글은 RAG 챗봇의 비용과 레이턴시를 단계별로 해부하고, 각 단계에서 적용할 수 있는 실무 검증된 최적화 기법을 정리합니다. 막연한 "최적화하세요"가 아니라, 코드와 함께 어디를 어떻게 줄일 수 있는지 구체적..

"우리 사내 매뉴얼 200개를 RAG에 넣었어요. 잘 작동할 거예요." — 이렇게 시작했다가 일주일 후 답변 품질이 형편없는 RAG와 마주치는 것은 거의 모든 RAG 프로젝트의 통과 의례입니다.원인을 추적해 보면 거의 매번 같은 곳에서 막힙니다 — PDF. 모든 사내 문서, 정책서, 계약서, 기술 매뉴얼은 PDF로 되어 있습니다. 그리고 PDF는 RAG가 다루기 가장 어려운 포맷입니다.표는 텍스트로 변환하면 구조가 사라집니다. 이미지 안의 다이어그램은 OCR도 안 됩니다. 멀티 컬럼 레이아웃은 위에서 아래로 읽혀서 의미가 깨집니다. 페이지 헤더/푸터는 모든 청크에 노이즈로 들어갑니다. 한국어 PDF는 더 심합니다 — 글자가 깨지고, 띄어쓰기가 사라집니다.이 글에서는 PDF가 왜 RAG에서 그렇게 어려운지..

목차개요Spring Authorization Server 아키텍처 이해인증 서버 기본 구현JWT 토큰 커스터마이징과 클레임 설계성능 특성과 대안 기술 비교운영 환경 적용 시 고려사항맺음말개요문제 배경현대 분산 시스템 환경에서 OAuth2 인증 서버는 더 이상 선택이 아닌 필수 인프라로 자리잡고 있습니다. 마이크로서비스 아키텍처가 보편화되면서 각 서비스가 독립적으로 사용자 인증을 처리하던 방식은 보안 취약점과 운영 복잡도를 함께 키워 왔습니다. Spring Authorization Server는 이 문제를 해결하기 위해 Spring 생태계 내에서 공식적으로 지원하는 OAuth2 및 OpenID Connect 1.0 인증 서버 구현체입니다.Spring 팀은 오랫동안 커뮤니티에서 광범위하게 사용되던 Sprin..