시맨틱·하이브리드
튜토리얼 학습자료
OpenSearch 공식 튜토리얼 「Getting started with semantic and hybrid search」를 단계별 전문 분석했다 — 5개 문서·3가지 검색 방식으로 같은 질의 「wild west」를 날려, 키워드가 뭘 놓치고 시맨틱이 뭘 바꾸고 하이브리드가 뭘 이어 붙이는지 실제 응답 점수표로 확인하는 실습이다.
튜토리얼이 쓰는 6개 구성요소 + 시작 전 설정
공식 튜토리얼은 BM25가 키워드에 강하지만 질의어의 의미를 잡지 못한다고 출발한다 — 그래서 6개 부품을 조립한다. 모르는 부품이 있어도 튜토리얼이 차례로 설명한다는 것이 공식 안내 문구다.
① 사전학습 언어 모델
OpenSearch가 제공하는 pretrained 모델 — 텍스트→벡터. 이 실습은 Hugging Face의 DistilBERT 계열을 쓴다.
② 수집 파이프라인
인덱스에 들어가기 전 문서 필드를 변형하는 프로세서 모음 — 여기선 text_embedding 하나.
③ k-NN 벡터 필드
임베딩을 저장하는 특수 필드 타입(knn_vector) — 차원·거리 공간을 명시한다.
④ 검색 파이프라인
검색 시점에 결과를 가로채 처리하는 파이프라인 — hybrid의 결합 무대.
⑤ normalization processor
여러 질의 절의 점수를 정규화·결합하는 search phase results processor(이론: SEQ 21 4·5번 시트).
⑥ hybrid 쿼리
match(키워드)와 neural(시맨틱)을 queries 배열 하나로 묶는 복합 쿼리.
시작 전 클러스터 설정 (Prerequisites 원문)
전용 ML 노드가 없는 기본 클러스터에서 실습을 돌리기 위한 2값(공식) — ML을 어떤 노드에서든 돌리고, 네이티브 메모리 임계를 99%로 올려 모델 캐시가 시작되도록 한다.
Advanced — 운영 전환 시 공식 주의
· 커스텀 모델 URL 등록에는 allow_registering_model_via_url: true가 추가로 필요
· 운영은 전용 ML 노드 분리가 모범 관행 — 그 경우 only_run_on_ml_node: true
· URL 등록은 신뢰한 소스만 — 미신뢰 모델 로딩은 보안 위험(공식: PyTorch 보안 가이드 링크)
· 세부 설정은 ML Commons cluster settings 문서로
실행 방법: 명령줄 또는 OpenSearch Dashboards Dev Tools 콘솔(공식 — 두 경로 모두 안내됨). 일부 단계에는 선택형 Test it 섹션이 있어 성공을 즉시 확인할 수 있고, 마지막에는 Clean up으로 만든 것을 모두 지운다.
모델 고르고, 비동기로 등록·배포하기
튜토리얼은 벤치마크 성적이 좋았던 DistilBERT 문장 변환기를 고른다 — 이름·버전·차원 3개 정보만 있으면 등록이 끝난다.
Step 1 — 모델 정보 3개 (공식)
· 이름: huggingface/sentence-transformers/msmarco-distilbert-base-tas-b
· 버전: 1.0.3
· 차원: 768 — 사전학습 모델 표의 config_url에서 확인(공식 안내 경로)
· 대안(Advanced): 다른 pretrained 모델 / 커스텀 로컬 모델 업로드 / 외부 원격 모델 연결
공식 응답 예시의 실제 값 — model 콘텐츠 266,357,253바이트·total_chunks 27·embedding_dimension 768·space_type innerproduct·pooling CLS. Models Profile API(GET /_plugins/_ml/profile/models)로 클러스터의 배포 모델 전체 통계도 볼 수 있다(공식).
수집 3단 — 파이프라인, 벡터 인덱스, 문서
모델이 준비됐으면 수집 파이프라인→벡터 인덱스→문서 순으로 쌓는다. 문서가 들어갈 때 임베딩 필드가 자동 추가되는 것이 핵심 장면이다.
(a) 수집 파이프라인
field_map — 원본 텍스트 필드(text)→임베딩이 기록될 필드(passage_embedding). Test it: GET /_ingest/pipeline(공식).
(b) 벡터 인덱스
인덱스에 기본 파이프라인을 묶어 두면 문서마다 지정할 필요가 없다(공식). 차원 768은 Step 1의 모델 차원과 반드시 일치.
(c) Flickr 샘플 5문서
공식이 Flickr 이미지 데이터셋에서 가져온 이미지 설명 5개 — 로데오·야생 말 테마:
· 1 WV 대학 여자농구 경기장
· 2 들판을 달리는 야생동물
· 3 Freemont 광고판 줄·카우보이 승마
· 4 로데오에서 야생말 타는 남자
· 5 모자 쓴 카우보이 낙마 순간
수집 직후 — 문서에 임베딩 필드가 붙어 나온다
text_embedding 프로세서가 임베딩 필드를 새로 만들어 문서에 덧붙인다. GET _doc/1로 확인하면 _source에 원본 text·id와 passage_embedding이 함께 있다(공식 응답 예시의 벡터 첫 값들: 0.04491629·−0.34105563·0.036822468·−0.14139028…).첫 번째 검색 — 키워드(match)는 무엇을 놓치나
질의는 「wild west」 하나로 고정. match 쿼리는 키워드가 포함된 문서만 돌려주고, 의미는 보지 않는다 — 그 결과가 아래 표다(공식 응답 원문 수치).
took 647ms(공식 응답 값). 문서 3은 질의 키워드(wild·west)가 없어 아예 반환되지 않았다 — 공식 해설: 로데오·카우보이 문서는 의미가 고려되지 않아 낮은 점수를 받는다.
이 장면이 말하는 것
· 1위가 농구 경기장 문서라는 점에 주목 — "West Virginia"의 West가 질의의 west와 충돌했다(키워드 일치만 보면 농구 문서가 이긴다)
· 진짜 주제(카우보이·로데오·야생마)는 전부 하위권 — 의미를 모르면 순위가 뒤집힌다
· 문서 3은 키워드가 한 개도 안 겹쳐 목록 밖 — 재현 불가능한 누락(재점수화로도 살릴 수 없다)
프로젝트 접점(실측)
건설도면 코퍼스에서도 BM25는 태그 exact 질의(P101 등)에 강하고, 「최신 개정」 같은 표현 변화에는 약하다는 대응 관계가 06호 실측·18호 단원 3에 기록되어 있다 — 공식 튜토리얼의 이 장면이 그 원리의 교과서적 예시다.
두 번째 검색 — 시맨틱(neural)은 무엇을 바꾸나
같은 질의 「wild west」를 neural 쿼리로 — 수집 때 쓴 같은 모델로 질의 텍스트를 벡터로 만드는 것이 공식 요건이다. 결과는 5건 전부, 순서도 뒤집힌다.
took 25ms(공식). 5건 전부 반환 — 문서 3이 돌아왔다. 농구 문서는 4위로 내려왔다.
이 장면이 말하는 것
· 공식 해설 그대로: 의미를 고려해 문서 순서까지 개선됐다 — 카우보이·로데오·야생마 문서(4·5·3)가 의미적으로 상위로
· 점수 눈금이 완전히 다르다: 최고점이 0.0158 — 키워드의 0.8127과 비교 불가(내적(innerproduct) 유사도의 특성). 이것이 결합 전 정규화가 필요한 이유(SEQ 21의 12.4 vs 0.87 예시와 같은 원리)
· 공식 요건: 질의 임베딩도 수집과 같은 model_id로 생성 — 모델을 바꾸면 벡터 공간이 어긋난다
프로젝트 접점(실측)
· 「문서·질의 모두 같은 임베딩 모델」은 7.2절 요건으로 프로젝트에도 그대로 적용(06호 운영 메모)
· 한국어 코퍼스 실측에서는 bge-m3(1024차) 5/5 vs nomic 3/5 — 모델 선택 자체가 실험 대상(18호 단원 3)
세 번째 검색 — 하이브리드, 그리고 3방식 순위 대조
검색 파이프라인(min_max + arithmetic_mean, weights 0.3/0.7)을 만들고 hybrid 쿼리로 match 「cowboy rodeo bronco」+ neural 「wild west」를 묶는다.
3방식 최종 대조표 — 공식 응답 점수·순위 그대로
| 문서 | 키워드 match — 점수(순위) | 시맨틱 neural — 점수(순위) | 하이브리드 — 점수(순위) |
|---|---|---|---|
| 5 카우보이 낙마 | 0.2510 (3위) | 0.0152 (3위) | 0.8648 (1위) |
| 4 로데오 야생말 | 0.2450 (4위) | 0.0159 (1위) | 0.7003 (2위) |
| 2 들판의 야생동물 | 0.2641 (2위) | 0.0157 (2위) | 0.6840 (3위) |
| 3 Freemont 광고판+카우보이 | 누락 (순위 없음) | 0.0113 (5위) | 0.3007 (4위) |
| 1 WV 대학 농구 경기장 | 0.8127 (1위) | 0.0133 (4위) | 0.2992 (5위) |
took 27ms(공식). 공식 해설 — wild west의 의미에 맞는 문서가 돌아오는 데서 그치지 않고, wild west 테마 관련 단어(cowboy·rodeo·bronco)가 든 문서도 상대적으로 높아진다. 1위는 농구 문서(키워드 함정)도 카우보이 단독(시맨틱)도 아닌 카우보이 낙마 문서 5 — 두 신호가 모두 강한 문서다. 문서 3은 시맨틱 절 덕에 목록에 복귀했다.
요청마다 파이프라인 지정이 귀찮다면(공식)
PUT /my-nlp-index/_settings { "index.search.default_pipeline": "nlp-search-pipeline" } — 인덱스 기본 검색 파이프라인으로 지정하면 요청 파라미터가 필요 없다. 이후 가중치·정규화·결합 기법을 자유롭게 실험하라고 공식이 안내한다(SEQ 21 5번 시트 기법 카탈로그로 확장).
수치 해설은 분리(R3)
took의 격차(647→25→27ms)는 공식이 원인 해설을 하지 않는다 — 첫 요청의 캐시·워밍업 가능성 등 원인 추정은 기록하지 않는다. 점수·순위·건수만이 원문 사실이며, 프로젝트 적용 판단은 다음 시트의 대조로 별도 표기한다.
Clean up 6단계 + 프로젝트 적용 대조
공식은 실습 끝에 만든 것을 정확한 역할 순서로 지우도록 안내한다 — 지우는 순서까지 학습 내용이다.
Clean up — 공식 삭제 순서
① DELETE 인덱스(my-nlp-index)
② DELETE 검색 파이프라인(nlp-search-pipeline)
③ DELETE 수집 파이프라인(nlp-ingest-pipeline)
④ POST 모델 undeploy → ⑤ DELETE 모델
⑥ DELETE 모델 그룹(model_group_id 필요 — Step 2 조회 응답에서 회수)
심화(Advanced): 질의를 search template으로 매개변수화하면 중첩이 줄어 복잡도가 내려간다(공식).
Further reading(공식 2편)
· 시맨틱 검색 기초 — 「Building a semantic search engine in OpenSearch」
· 결합·기법·벤치마크 — 「The ABCs of semantic search: Architectures, benchmarks, and combination strategies」
· 다음 단계: AI search 개요 · workflow template(semantic-search-using-a-local-model)로 모델·수집 파이프라인·벡터 인덱스를 요청 한 번에 생성
| 항목 | 공식 튜토리얼 | 건설도면 실측(06·10·18호) |
|---|---|---|
| 임베딩 모델 | DistilBERT(영어, 768차, innerproduct·CLS pooling) | bge-m3(한국어 우수, 1024차) 채택 권장 — 5/5 vs 3/5 실측 |
| 모델 등록 | 클러스터가 URL에서 다운로드(비동기 27체크) | 로컬은 Docker 임베딩(ollama bge-m3/nomic) — ml-commons URL 등록 경로는 미검증 |
| 하이브리드 조합 | min_max + arithmetic_mean(0.3/0.7) | 동일 조합 실측 동작 — 단, kNN 단독 5/5 > 하이브리드 4/5 역전 사례 기록 |
| 가중치 | 0.3/0.7 고정 예시 | 평가셋 스윕 [0.3/0.5/0.7]로 결정하는 프로토콜(고정값 복사 금지) |
| Clean up | 삭제 6단계 안내 | 에뮬레이터는 중지 시 메모리 소멸 — 대신 로컬 OS 데이터(/opt/seachdog/data)는 수동 관리 |
| 적용 가능 판정 | — | 요청 형식(hybrid·neural·파이프라인)은 로컬 2.13과 호환(SEQ 21 매트릭스) — pretrained 모델 다운로드 경로만 미실측, 필요 시 실측 후 기록 |
튜토리얼이 참조하는 공인 문서 20편
본문 연결 링크를 전부 추출해 2026-11-17 기준 접속(canonical·끝 슬래시)을 검증했다 — 학습 확장 순서대로 정렬.
본문 01Getting started with semantic and hybrid search — 분석 대상 튜토리얼docs.opensearch.org/latest/tutorials/vector-search/neural-search-tutorial/ 구성요소Pretrained language models — 모델 표·config_url(768차 확인처)docs.opensearch.org/latest/ml-commons-plugin/pretrained-models/ 구성요소Ingest pipeline — 수집 파이프라인 APIdocs.opensearch.org/latest/api-reference/ingest-apis/index/ 구성요소k-NN vector 필드 타입 — knn_vector·차원·공간docs.opensearch.org/latest/mappings/supported-field-types/knn-vector/ 구성요소Search pipelines — 검색 파이프라인 개요docs.opensearch.org/latest/search-plugins/search-pipelines/index/ 구성요소Normalization processor — 정규화·결합 레퍼런스(SEQ 21 5번 시트 원전)docs.opensearch.org/latest/search-plugins/search-pipelines/normalization-processor/ 구성요소Hybrid 쿼리 DSL — queries 배열docs.opensearch.org/latest/query-dsl/compound/hybrid/ 설정ML Commons cluster settings — only_run_on_ml_node 등docs.opensearch.org/latest/ml-commons-plugin/cluster-settings/ APIGet ML Task API — 비동기 상태 폴링·응답 형식docs.opensearch.org/latest/ml-commons-plugin/api/tasks-apis/get-task/ APIModels Profile API — 배포 모델 통계docs.opensearch.org/latest/ml-commons-plugin/api/profile/ 심화Using ML models — 커스텀 모델 등록 설정docs.opensearch.org/latest/ml-commons-plugin/using-ml-models/ 심화Custom local models — 자체 모델 업로드docs.opensearch.org/latest/ml-commons-plugin/custom-local-models/ 심화Search templates — 질의 매개변수화(Advanced)docs.opensearch.org/latest/search-plugins/search-template/ 도구Dev Tools 콘솔 — 명령줄 대안 실행 환경docs.opensearch.org/latest/dashboards/dev-tools/run-queries/ 다음Workflow templates — semantic-search-using-a-local-model(한 번에 생성)docs.opensearch.org/latest/vector-search/ai-search/workflows/workflow-templates/ 다음AI search 개요 — 확장 학습 방향docs.opensearch.org/latest/vector-search/ai-search/index/ 공식 블로그Building a semantic search engine in OpenSearch(기초)opensearch.org/blog/semantic-search-solutions/ 공식 블로그The ABCs of semantic search — 아키텍처·벤치마크·결합 전략opensearch.org/blog/semantic-science-benchmarks/ 보안PyTorch security guidelines — 미신뢰 모델 로딩 주의(Advanced 절 참조)github.com/pytorch/pytorch/blob/main/SECURITY.md 데이터Flickr image dataset — 튜토리얼 샘플 5문서의 출전kaggle.com/datasets/hsankesara/flickr-image-dataset