01 / 09 · 표지
OPENSEARCH TUTORIAL · SEMANTIC & HYBRID SEARCH · STEP-BY-STEP ANALYSIS

시맨틱·하이브리드
튜토리얼 학습자료

OpenSearch 공식 튜토리얼 「Getting started with semantic and hybrid search」를 단계별 전문 분석했다 — 5개 문서·3가지 검색 방식으로 같은 질의 「wild west」를 날려, 키워드가 뭘 놓치고 시맨틱이 뭘 바꾸고 하이브리드가 뭘 이어 붙이는지 실제 응답 점수표로 확인하는 실습이다.

준비클러스터 설정 2값 Step 1모델 선택(768차) Step 2등록·배포(비동기) Step 3수집 3단(파이프라인·인덱스·문서) Step 4검색 3방식 대조 정리Clean up 6삭제 이 학습자료의 약속 튜토리얼의 요청·응답·점수는 원문 그대로 — 해설과 판정(프로젝트 실측 대조)은 8번 시트에서 분리 표기
768
튜토리얼 임베딩 차원 — msmarco-distilbert-base-tas-b(영어 문장 변환기)
5개
Flickr 이미지 설명 문서 — 로데오·야생 말 테마 샘플
3방식
같은 질의를 match·neural·hybrid로 날려 순위 대조
match(키워드)neural(시맨틱) hybrid(결합)min_max + arithmetic_mean 0.3/0.7 27체크·266MB 모델 자동 분할비동기 등록 task_id→model_id
건설도면프로젝트 · 학습자료 SEQ 22 (양식: 17 템플릿 준수 — kikum.xyz/physical-ai-motion 팔레트)출처: docs.opensearch.org tutorials/vector-search/neural-search-tutorial/ 전문 분석(2026-11-17) · 이론편: SEQ 21
02 / 09 · 준비
UNIT 01 · COMPONENTS & PREREQUISITES

튜토리얼이 쓰는 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 원문)

PUT _cluster/settings { "persistent": { "plugins.ml_commons.only_run_on_ml_node": "false", "plugins.ml_commons.native_memory_threshold": "99" } }

전용 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으로 만든 것을 모두 지운다.

건설도면프로젝트 · 시맨틱·하이브리드 튜토리얼 학습자료 SEQ 22근거: neural-search-tutorial/ 본문 — Components·Prerequisites·Advanced 절 인용
03 / 09 · Step 1~2
STEP 1-2 · CHOOSE · REGISTER · DEPLOY

모델 고르고, 비동기로 등록·배포하기

튜토리얼은 벤치마크 성적이 좋았던 DistilBERT 문장 변환기를 고른다 — 이름·버전·차원 3개 정보만 있으면 등록이 끝난다.

Step 1 — 모델 정보 3개 (공식)

· 이름: huggingface/sentence-transformers/msmarco-distilbert-base-tas-b
· 버전: 1.0.3
· 차원: 768 — 사전학습 모델 표의 config_url에서 확인(공식 안내 경로)
· 대안(Advanced): 다른 pretrained 모델 / 커스텀 로컬 모델 업로드 / 외부 원격 모델 연결

POST /_plugins/_ml/models/_register?deploy=true { "name": "huggingface/sentence-transformers/msmarco-distilbert-base-tas-b", "version": "1.0.3", "model_format": "TORCH_SCRIPT" } → { "task_id": "aFeif4oB5Vm0Tdw8yoN7", "status": "CREATED" }
등록 요청(deploy=true) 응답: task_id · CREATED 다운로드·분할 저장 10MB 청크 × 27개(총 266MB) Get ML Task API 폴링 GET /_plugins/_ml/tasks/{id} COMPLETED → model_id task_id와 다른 별개 ID(공식 주의) 배포 = 인스턴스 생성·메모리 캐시 Test it: GET models/{id} → DEPLOYED

공식 응답 예시의 실제 값 — model 콘텐츠 266,357,253바이트·total_chunks 27·embedding_dimension 768·space_type innerproduct·pooling CLS. Models Profile API(GET /_plugins/_ml/profile/models)로 클러스터의 배포 모델 전체 통계도 볼 수 있다(공식).

공식 주의 — 등록은 비동기 작업이다. 등록 즉시 쓰면 안 되고 Get ML Task API로 상태가 COMPLETED가 될 때까지 확인한 뒤, 응답의 model_id(task_id와 다름)를 이후 단계 전부에 쓴다. 배포는 모델 인스턴스를 만들어 노드 메모리에 캐시하는 절차(공식).
건설도면프로젝트 · 시맨틱·하이브리드 튜토리얼 학습자료 SEQ 22근거: Step 1~2 원문·등록/조회 예제 응답(체크 27개·268MB·768차) 인용
04 / 09 · Step 3
STEP 3 · INGEST DATA (A→B→C)

수집 3단 — 파이프라인, 벡터 인덱스, 문서

모델이 준비됐으면 수집 파이프라인→벡터 인덱스→문서 순으로 쌓는다. 문서가 들어갈 때 임베딩 필드가 자동 추가되는 것이 핵심 장면이다.

(a) 수집 파이프라인

PUT /_ingest/pipeline/nlp-ingest-pipeline { "processors": [ { "text_embedding": { "model_id": "aVeif4oB…", "field_map": { "text": "passage_embedding" } } } ] }

field_map — 원본 텍스트 필드(text)→임베딩이 기록될 필드(passage_embedding). Test it: GET /_ingest/pipeline(공식).

(b) 벡터 인덱스

PUT /my-nlp-index { "settings": { "index.knn": true, "default_pipeline": "nlp-ingest-pipeline" }, "mappings": { "properties": { "passage_embedding": { "type": "knn_vector", "dimension": 768, "space_type": "l2" }, "text": { "type": "text" } } } }

인덱스에 기본 파이프라인을 묶어 두면 문서마다 지정할 필요가 없다(공식). 차원 768은 Step 1의 모델 차원과 반드시 일치.

(c) Flickr 샘플 5문서

공식이 Flickr 이미지 데이터셋에서 가져온 이미지 설명 5개 — 로데오·야생 말 테마:
· 1 WV 대학 여자농구 경기장
· 2 들판을 달리는 야생동물
· 3 Freemont 광고판 줄·카우보이 승마
· 4 로데오에서 야생말 타는 남자
· 5 모자 쓴 카우보이 낙마 순간

수집 직후 — 문서에 임베딩 필드가 붙어 나온다

PUT 문서 { text, id } 예: 로데오 카우보이 설명 nlp-ingest-pipeline text_embedding → 모델 추론 passage_embedding 자동 추가 [0.0449, −0.3410, 0.0368, …] my-nlp-index 색인 원문+벡터 함께 보관
공식 설명 — 문서가 색인될 때 text_embedding 프로세서가 임베딩 필드를 새로 만들어 문서에 덧붙인다. GET _doc/1로 확인하면 _source에 원본 text·id와 passage_embedding이 함께 있다(공식 응답 예시의 벡터 첫 값들: 0.04491629·−0.34105563·0.036822468·−0.14139028…).
건설도면프로젝트 · 시맨틱·하이브리드 튜토리얼 학습자료 SEQ 22근거: Step 3(a)(b)(c) 원문·예제 JSON — 파이프라인/인덱스/문서 5개 전문
05 / 09 · Step 4-1
STEP 4 · SEARCH #1 — KEYWORD (match)

첫 번째 검색 — 키워드(match)는 무엇을 놓치나

질의는 「wild west」 하나로 고정. match 쿼리는 키워드가 포함된 문서만 돌려주고, 의미는 보지 않는다 — 그 결과가 아래 표다(공식 응답 원문 수치).

GET /my-nlp-index/_search { "_source": { "excludes": ["passage_embedding"] }, "query": { "match": { "text": { "query": "wild west" } } } }
1 · WV 대학 농구 경기장
0.8127 — 1위
2 · 들판의 야생동물
0.2641 — 2위
5 · 모자 쓴 카우보이 낙마
0.2510 — 3위
4 · 로데오 야생말 기수
0.2450 — 4위
3 · Freemont 광고판+카우보이
응답에 없음 — 누락

took 647ms(공식 응답 값). 문서 3은 질의 키워드(wild·west)가 없어 아예 반환되지 않았다 — 공식 해설: 로데오·카우보이 문서는 의미가 고려되지 않아 낮은 점수를 받는다.

이 장면이 말하는 것

· 1위가 농구 경기장 문서라는 점에 주목 — "West Virginia"의 West가 질의의 west와 충돌했다(키워드 일치만 보면 농구 문서가 이긴다)
· 진짜 주제(카우보이·로데오·야생마)는 전부 하위권 — 의미를 모르면 순위가 뒤집힌다
· 문서 3은 키워드가 한 개도 안 겹쳐 목록 밖 — 재현 불가능한 누락(재점수화로도 살릴 수 없다)

프로젝트 접점(실측)

건설도면 코퍼스에서도 BM25는 태그 exact 질의(P101 등)에 강하고, 「최신 개정」 같은 표현 변화에는 약하다는 대응 관계가 06호 실측·18호 단원 3에 기록되어 있다 — 공식 튜토리얼의 이 장면이 그 원리의 교과서적 예시다.

건설도면프로젝트 · 시맨틱·하이브리드 튜토리얼 학습자료 SEQ 22근거: Step 4 keyword 절 — 요청·응답 JSON 원문(4건·max_score 0.8126553·took 647)
06 / 09 · Step 4-2
STEP 4 · SEARCH #2 — SEMANTIC (neural)

두 번째 검색 — 시맨틱(neural)은 무엇을 바꾸나

같은 질의 「wild west」를 neural 쿼리로 — 수집 때 쓴 같은 모델로 질의 텍스트를 벡터로 만드는 것이 공식 요건이다. 결과는 5건 전부, 순서도 뒤집힌다.

GET /my-nlp-index/_search { "_source": { "excludes": ["passage_embedding"] }, "query": { "neural": { "passage_embedding": { "query_text": "wild west", "model_id": "aVeif4oB…", "k": 5 } } } }
4 · 로데오 야생말 기수
0.01585 — 1위
2 · 들판의 야생동물
0.01575 — 2위
5 · 모자 쓴 카우보이 낙마
0.01518 — 3위
1 · WV 대학 농구 경기장
0.01327 — 4위
3 · Freemont 광고판+카우보이
0.01135 — 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)

건설도면프로젝트 · 시맨틱·하이브리드 튜토리얼 학습자료 SEQ 22근거: Step 4 semantic 절 — 요청·응답 JSON 원문(5건·max_score 0.01585195·took 25)
07 / 09 · Step 4-3 · 총정리
STEP 4 · SEARCH #3 — HYBRID + FULL COMPARISON

세 번째 검색 — 하이브리드, 그리고 3방식 순위 대조

검색 파이프라인(min_max + arithmetic_mean, weights 0.3/0.7)을 만들고 hybrid 쿼리로 match 「cowboy rodeo bronco」+ neural 「wild west」를 묶는다.

PUT /_search/pipeline/nlp-search-pipeline { "phase_results_processors": [ { "normalization-processor": { "normalization": { "technique": "min_max" }, "combination": { "technique": "arithmetic_mean", "parameters": { "weights": [0.3, 0.7] } } } } ] }
GET /my-nlp-index/_search?search_pipeline=nlp-search-pipeline { "query": { "hybrid": { "queries": [ { "match": { "text": { "query": "cowboy rodeo bronco" } } }, { "neural": { "passage_embedding": { "query_text": "wild west", "model_id": "aVeif4oB…", "k": 5 } } } ] } } }

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)는 공식이 원인 해설을 하지 않는다 — 첫 요청의 캐시·워밍업 가능성 등 원인 추정은 기록하지 않는다. 점수·순위·건수만이 원문 사실이며, 프로젝트 적용 판단은 다음 시트의 대조로 별도 표기한다.

건설도면프로젝트 · 시맨틱·하이브리드 튜토리얼 학습자료 SEQ 22근거: Step 4 hybrid 절 — 파이프라인·hybrid 요청·응답 5건 점수 원문(max_score 0.86481035)
08 / 09 · 마무리·대조
CLEAN UP · ADVANCED · OUR CONTEXT

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 모델 다운로드 경로만 미실측, 필요 시 실측 후 기록
학습 순서 권장 — 이 튜토리얼(실습) → SEQ 21(이론·기법 카탈로그·버전 판정) → 06호(한국어 실측). 튜토리얼의 0.3/0.7은 예시값이지 최적값이 아니라는 점이 공식의 반복 강조다(「자유롭게 실험하라」).
건설도면프로젝트 · 시맨틱·하이브리드 튜토리얼 학습자료 SEQ 22근거: Clean up·Further reading·Next steps 원문 — 대조표의 실측은 06·10·18호(출처 분리 표기)
09 / 09 · 출처·연결
SOURCES · ALL PAGES REFERENCED BY THE TUTORIAL

튜토리얼이 참조하는 공인 문서 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

프로젝트 문서 연결

21 · 하이브리드 이론편(기법 카탈로그·2.13 판정) 19 · A2 모션 학습 지도(단원 3=검색) 06 · 한국어 임베딩 실측(bge-m3) 20 · 데이터엔지니어링 구성환경
판정 표기 원칙 — 튜토리얼 인용 수치(점수·순위·took·체크 수)는 원문 그대로, 프로젝트 비교·가능/불가 판정은 8번 시트에서 출처(06·10·18·21호)와 함께 분리 표기한다. 링크는 모두 2026-11-17 canonical 접속 검증을 통과했다(soft-404 마커 검사 포함).