시맨틱 검색(Semantic Search)은 콘텐츠 브라우저에 인공지능(AI) 검색 모드를 추가하는 에디터 플러그인입니다. 에셋 이름과 태그를 그대로 일치시키는 대신, 비주얼 및 컨텍스트 의미에 따라 에셋의 순위를 매길 수 있습니다.
예를 들어, '녹슨 금속 통'을 검색하면 에셋 이름에 해당 단어가 포함되어 있지 않더라도 M_OldOilDrum이라는 이름의 에셋이 반환될 수 있습니다.
작동 원리
이 플러그인은 콘텐츠 브라우저 에셋의 메모리 내 벡터 검색 인덱스를 생성하는 방식으로 작동합니다. 에셋이 인덱싱될 때 플러그인은 에셋에 대한 짧은 AI 생성 설명을 빌드하고, 해당 설명을 벡터로 임베드하고, 키워드 검색과 벡터 검색을 결합한 하이브리드 인덱스에 결과를 저장합니다. 그러면 콘텐츠 브라우저 검색 쿼리는 이 인덱스를 사용하여 시맨틱 매치를 표시합니다.
개괄적으로 설명하면 다음과 같습니다.
플러그인은 지원되는 에셋 데이터를 수집하며, 여기에는 보통 캐시된 섬네일, 에셋 경로, 에셋 클래스 및 선택된 메타데이터가 포함됩니다.
구성된 OpenAI 호환 채팅 완료 엔드포인트는 에셋에 대한 태그와 캡션을 생성합니다.
구성된 OpenAI 호환 임베딩 엔드포인트는 캡션에 대한 벡터 임베딩을 생성합니다.
플러그인은 캡션, 태그 및 임베딩을 파생 데이터 캐시에 저장하고 에셋을 메모리 내 검색 인덱스에 추가합니다.
텍스트 검색은 검색 쿼리를 임베드하고 이를 인덱싱된 에셋 임베딩과 비교합니다. 하이브리드 검색이 활성화된 경우(디폴트 동작), 정확한 키워드 기반 매치가 시맨틱 매치와 융합됩니다.
플러그인 활성화하기
편집(Edit) > 플러그인(Plugins)을 엽니다.
시맨틱 검색(Semantic Search)을 검색합니다.
실험 단계 플러그인(experimental plugins) 목록에서 플러그인을 활성화합니다.
에디터를 재시작합니다.
에디터가 재시작되면 각 콘텐츠 브라우저 검색 창의 오른쪽에 AI 토글이 표시됩니다. 이 버튼을 클릭하면 콘텐츠 브라우저에 대한 AI 검색 모드가 활성화됩니다. AI 모드가 활성화되면 버튼이 청록색으로 바뀝니다.
메인 유저 인터페이스
플러그인은 다음과 같은 에디터 UI를 추가합니다.
| UI | 위치 | 용도 |
|---|---|---|
AI 토글 | 각 콘텐츠 브라우저 검색 창의 오른쪽 | 시맨틱 검색 모드를 켜거나 끕니다. |
인덱스 상태 | AI 모드가 켜져 있을 때 표시되는 콘텐츠 브라우저 탐색 바 | 인덱싱됨, 인덱싱되지 않음, 실패 개수를 인라인 새로고침, 재시도, 취소 버튼과 함께 표시합니다. |
통계 대화 상자 | 툴 > 시맨틱 검색 | 인덱스 통계를 표시하고 인덱스 타입을 플랫 인덱스와 양자화된 인덱스 간에 전환할 수 있습니다. |
세팅(Settings) | 편집 > 에디터 개인설정 > 플러그인 > 시맨틱 검색 | 제공자, 인덱싱, HTTP, 벡터 인덱스 및 검색 동작을 구성합니다. |
유사 항목 찾기 | AI 모드가 켜진 상태에서 콘텐츠 브라우저의 단일 에셋 우클릭 | 선택한 에셋과 비슷한 에셋을 검색합니다. |
제공자 구성
제공자는 플러그인이 에셋 섬네일과 메타데이터를 캡션으로 변환하고, 캡션 또는 검색 텍스트를 임베딩으로 변환하기 위해 호출하는 백엔드 서비스입니다.
편집(Edit) > 에디터 개인설정(Editor Preferences) > 플러그인(Plugins) > 시맨틱 검색(Semantic Search)을 열고 제공자(Provider) 섹션을 구성합니다.
이 플러그인은 현재 OpenAI 호환 API(OpenAI-compatible API)라는 한 가지 제공자 유형과 함께 제공됩니다.
이는 다음을 호출합니다.
에셋 캡셔닝을 위한
/chat/completions텍스트 임베딩을 위한
/embeddings
| 세팅 | 디폴트 | 노트 |
|---|---|---|
제공자 | OpenAI 호환 API | 캡션 및 임베딩에 사용되는 백엔드입니다. |
캡셔닝 베이스 URL | OpenAI 호환 API의 베이스 URL입니다. 플러그인은 <캡셔닝 베이스 URL>/chat/completions에 캡션 요청을 보냅니다. | |
캡셔닝 API 키 | 비어 있음 | 요청 시 Authorization: Bearer <key> 형식으로 전송됩니다. |
캡셔닝 모델 | gpt-5.4-mini | 에셋에 대한 캡션과 태그를 생성하는 데 사용되는 모델입니다. 지원되는 비주얼 에셋은 섬네일이나 스크린샷을 전송하므로 비전 기능이 있어야 합니다. |
임베딩 베이스 URL | 임베딩 요청은 <임베딩 베이스 URL>/embeddings로 전송됩니다. 캡셔닝 URL과 다를 수 있습니다. | |
임베딩 API 키 | 비어 있음 | Authorization: Bearer <key> 형식으로 전송됩니다. 캡셔닝 키와 동일할 수 있습니다. |
임베딩 모델 | text-embedding-3-small | 에셋 캡션 및 검색 쿼리에 대한 임베딩을 생성하는 데 사용되는 모델입니다. |
임베딩 차원 | 512 | 임베딩의 크기입니다. 임베딩 요청에서 dimensions 파라미터로 전송됩니다. |
제공자 세팅은 프로젝트의 에디터 사용자별 세팅 환경설정에 있는 [/Script/SemanticSearch.SemanticSearchSettings]에 저장됩니다.
에디터 필드가 비밀번호 필드로 표시되더라도 API 키는 평문으로 저장됩니다.
제공자 세팅을 변경하면 제공자를 다시 등록하고, 활성 인덱싱을 취소하고, 구성된 치수에서 벡터 인덱스를 플랫으로 다시 빌드합니다. 제공자 값을 변경한 후 다시 인덱싱합니다.
인덱스 빌드
콘텐츠 브라우저를 엽니다.
AI 버튼을 클릭하면 청록색으로 바뀝니다.
콘텐츠 브라우저 탐색 바에서 시맨틱 검색 인덱스(Semantic Search Index):를 찾습니다.
에셋이 인덱싱되지 않은 것으로 나열되면 인덱싱되지 않음 개수 옆의 새로고침 버튼을 클릭합니다.
인덱스 상태 표시줄에는 다음이 표시될 수 있습니다.
| 상태 | 의미 |
|---|---|
| 현재 시맨틱 인덱스에 있는 에셋입니다. 이 수 옆의 새로고침 버튼은 지원되는 모든 에셋을 처음부터 다시 인덱싱합니다. |
| 인덱싱된 경로에서 현재 인덱싱되지 않은 지원되는 에셋입니다. 이 수 옆의 새로고침 버튼은 해당 에셋만 인덱싱합니다. |
| HTTP 오류 또는 속도 제한 등 재시도 가능한 제공자 실패입니다. 이 수 옆의 새로고침 버튼은 실패한 에셋을 다시 시도합니다. |
X 버튼 | 인덱싱이 활성 상태일 때 표시됩니다. 큐 등록된 인덱싱 작업과 대기 중인 제공자 요청을 취소합니다. |
인덱싱은 백그라운드에서 실행되며 진행 알림을 표시합니다. 실행되는 동안에도 에디터에서 계속 작업할 수 있습니다.
캐시되지 않은 인덱싱된 각 에셋에 대해 캡셔닝 요청 하나와 임베딩 요청 하나가 설정된 백엔드로 전송될 것으로 예상됩니다.
지원되는 에셋 타입
현재 다음 에셋 타입만 지원됩니다
스태틱 메시
스켈레탈 메시
머티리얼(Material)
Material Instance
텍스처
블루프린트(연관된 섬네일이 있는 블루프린트만 해당)
이 에셋 타입 중 하나에 속하는 모든 에셋에 대해 에디터에 캐시된 섬네일, 에셋 경로 및 클래스, 일부 메타데이터 태그를 사용하여 에셋에 대한 캡션 요청을 생성합니다.
지원되지 않는 에셋은 인덱싱 중에 무시됩니다.
모든 시맨틱 검색 쿼리의 경우, 인덱싱되지 않았거나 지원되지 않는 에셋은 콘텐츠 브라우저에 정상적으로 표시되더라도 AI 검색 결과에 표시되지 않습니다.
검색
AI 모드가 활성화되고 인덱스가 채워진 상태로 다음 단계를 따릅니다.
콘텐츠 브라우저 검색 창에 자연어 쿼리를 입력합니다.
Enter를 누릅니다.
시맨틱 검색 결과는 쿼리를 제출할 때 가져옵니다. 표준 콘텐츠 브라우저 검색처럼 키를 누를 때마다 계속 업데이트되지 않습니다.
검색 예시:
나무 상자
녹슨 금속 통
빛나는 네온 사인
로우폴리 바위
빨간색 메탈릭 표면
대형 산업용 기계
시맨틱 검색 플러그인은 모든 콘텐츠 브라우저 필터와 호환됩니다. 폴더, 컬렉션 및 클래스 필터는 시맨틱 랭킹이 적용되기 전에 후보 세트를 결정합니다. 일반 콘텐츠 브라우저 필터를 사용하여 검색 범위를 메시, 머티리얼, 텍스처 또는 특정 폴더로 좁힐 수 있습니다.
AI 모드가 켜져 있지만 검색 필드가 비어 있는 경우, 콘텐츠 브라우저가 아이템을 정상적으로 통과시키므로 여전히 폴더를 탐색할 수 있습니다.
유사 항목 찾기
유사 항목 찾기는 임베딩 공간에서 선택한 레퍼런스 에셋에 '가까운' 에셋을 검색합니다.
콘텐츠 브라우저에서 AI 모드를 활성화합니다.
에셋 하나를 우클릭합니다.
유사 항목 찾기(Find Similar)를 선택합니다.
플러그인은 검색 박스를 /find-similar <AssetObjectPath>로 채우고, 시맨틱으로 유사한 인덱싱된 에셋을 반환합니다.
우클릭 메뉴 아이템은 AI 모드가 활성화되어 있고, 정확히 하나의 에셋이 선택되어 있고, 인덱스에 최소 하나의 벡터가 있는 경우에만 표시됩니다. 선택한 에셋 자체가 인덱싱되지 않은 경우 검색 결과가 반환되지 않습니다.
기본적으로 유사 항목 찾기는 현재 폴더 내에서만 유사한 에셋을 찾습니다. 전체 프로젝트에서 비슷한 에셋을 찾으려면 콘텐츠 브라우저 폴더 선택기에서 루트 폴더를 /All로 변경합니다.
인덱싱 경로 제한하기
기본적으로 인덱싱 경로에는 /가 포함되어 있으며, 이는 플러그인이 해당 접두사와 일치하는 모든 콘텐츠 브라우저 패키지 루트를 고려한다는 것을 의미합니다.
인덱싱을 제한하려면 다음 단계를 따릅니다.
편집(Edit) > 에디터 개인설정(Editor Preferences) > 플러그인(Plugins) > 시맨틱 검색(Semantic Search)을 엽니다.
인덱싱(Indexing)에서 / 엔트리를 제거합니다.
/Game/Props/또는/Game/Environments/Forest/와 같은 패키지 경로를 하나 이상 추가합니다.콘텐츠 브라우저 상태 표시줄에서 다시 인덱싱합니다.
인덱싱 경로를 제한하는 것은 인덱싱 시간, 제공자 사용 및 비용을 줄이는 가장 간단한 방법입니다.
인덱스 타입
툴(Tools) > 시맨틱 검색(Semantic Search)을 열어 인덱스 통계를 확인하고 인덱스 타입을 전환합니다.
| 인덱스 타입 | 동작 |
|---|---|
플랫(정확)(Flat (Exact)) | 전체 정밀도 임베딩을 저장하고 정확한 최근접 이웃 벡터 결과를 제공합니다. 간단하고 정확하지만 인덱싱된 에셋 수에 따라 메모리가 선형적으로 증가합니다. |
PQ(압축) | 곱 양자화를 사용하여 압축된 벡터 코드를 저장합니다. 대규모에서 에디터 메모리를 훨씬 적게 사용하며, 일부 재현율 손실이 발생합니다. |
기본적으로 인덱스는 플랫입니다. 소규모에서 중간 규모의 프로젝트의 경우, 플랫이 보통 괜찮으며 약간 더 정확합니다. PQ는 수만~수십만 개의 에셋을 인덱싱할 때 더 유용합니다. 플랫 인덱스에서 PQ 인덱스로 전환하면 인덱스에 이미 있는 벡터를 사용하여 일회성 학습 단계를 수행합니다.
인덱스 타입 전환 외에도 통계 대화 상자에는 다음이 표시됩니다.
인덱스 타입
벡터 개수
BM25 키워드 인덱스 수
임베딩 차원
예상 벡터 메모리
예상 BM25 메모리
현재 인덱스 학습 여부
지원됨, 인덱싱됨, 건너뜀 및 실패 개수
기타 세팅
편집(Edit) > 에디터 개인설정(Editor Preferences) > 플러그인(Plugins) > 시맨틱 검색(Semantic Search)에서 찾을 수 있는 다른 사용 가능한 세팅입니다.
인덱싱
| 세팅 | 디폴트 | 노트 |
|---|---|---|
인덱싱 경로 | / | 인덱스에 포함된 콘텐츠 브라우저 패키지 경로입니다. |
스타트업 시 캐시된 항목 자동 인덱싱 | 꺼짐 | 스타트업 시 DDC에 캐시된 임베딩을 인덱스에 자동으로 로드합니다. |
스타트업 시 캐시되지 않은 항목 자동 인덱싱 | 꺼짐 | 스타트업 시 캐시되지 않은 에셋도 제공자에 전송합니다. 캐시된 항목 스타트업 인덱싱이 켜져 있는 경우에만 의미가 있습니다. |
저장 시 자동 인덱싱 | 켜짐 | 디스크에 에셋을 저장하거나 업데이트하면 에셋이 인덱싱 경로에 있는 경우 해당 에셋을 다시 인덱싱합니다. |
HTTP
| 세팅 | 디폴트 | 노트 |
|---|---|---|
최대 재시도 횟수 | 1 | 429 및 5xx와 같이 재시도 가능한 실패 시 HTTP 캡션/임베드 요청을 재시도합니다. |
재시도 타임아웃(초) | 300 | 한 요청에 대한 최대 실제 시간 재시도 간격입니다. |
최대 동시 캡션 요청 수 | 256 | 진행 중인 캡셔닝 요청을 제한하며, 초과 요청은 로컬에서 대기열에 추가됩니다. |
최대 동시 임베딩 요청 수 | 256 | 진행 중인 임베딩 요청을 제한하며, 초과 요청은 로컬에서 대기열에 추가됩니다. |
제공자가 속도 제한 오류를 반환하는 경우 동시 요청 수를 줄입니다.
검색
| 세팅 | 디폴트 | 노트 |
|---|---|---|
하이브리드 검색 활성화 | 켜짐 | 벡터 검색과 키워드 BM25 랭킹을 결합합니다. |
RRF 상수 | 60 | 역수 랭크 퓨전 튜닝입니다. 값이 높을수록 랭크 차이의 영향이 감소합니다. |
RRF 오버샘플 | 3 | 병합하기 전에 각 검색 소스에서 추가 후보를 가져옵니다. |
BM25 최소 일치 퍼센트 | 75 | 키워드 매치에 포함되어야 하는 쿼리 용어 수를 제어합니다. |
벡터 거리 컷오프 | 1.0 | 벡터 검색을 위한 L2 거리 한계치입니다. 값이 낮을수록 더 엄격해집니다. 결과는 이 시맨틱 한계치를 통과하거나 키워드 매치가 있어야 합니다. |
유사도 거리 컷오프 | 0.5 | 유사한 항목 찾기에서 사용하는 L2 거리 컷오프입니다. 값이 낮을수록 더 엄격해집니다. |
캐싱 및 지속성
캡션 및 임베딩 출력은 파생 데이터 캐시에 저장됩니다. 프로젝트에서 공유된 원격 DDC를 사용하는 경우, 팀은 각 사용자가 동일한 에셋을 다시 캡셔닝 및 임베딩하는 데 비용을 지불하는 대신 생성된 데이터를 재사용할 수 있습니다.
메모리 내 검색 인덱스는 프로젝트의 Saved/SemanticSearch 디렉터리에도 로컬로 저장되며 다음 에디터 스타트업 시 로드됩니다.
비용 및 개인정보처리 관련 참고 사항
인덱싱은 에셋 파생 데이터를 구성된 캡셔닝 제공자에게 전송합니다. 비주얼 에셋 타입의 경우 일반적으로 캐시된 섬네일과 에셋 경로, 클래스 및 선택한 메타데이터가 포함됩니다.
텍스트 검색은 검색 쿼리를 구성된 임베딩 제공자에게 전송합니다. 유사 항목 찾기는 기존 인덱싱된 벡터를 사용하며 검색 시 선택한 에셋을 제공자에게 전송하지 않습니다.
대규모 프로젝트를 인덱싱하기 전에 제공자의 요금과 속도 제한을 확인해 보세요. 대략적인 첫 번째 패스 추정치를 위해 캐시되지 않은 지원되는 에셋당 하나의 캡션 요청과 하나의 임베딩 요청을 계산합니다.
문제 해결
| 증상 | 확인할 사항 |
|---|---|
AI 버튼이 표시되지 않음 | 플러그인이 활성화되어 있는지 확인하고 에디터를 재시작한 후 콘텐츠 브라우저를 다시 엽니다. |
새로고침 후에도 인덱스에 인덱스된 항목이 0개임 | 출력 로그에서 LogSemanticSearch를 확인합니다. 일반적인 원인으로는 API 키 누락, 도달할 수 없는 베이스 URL, OpenAI와 호환되지 않는 서버 등이 있습니다. |
많은 에셋이 실패로 전환 | HTTP 401, 429 또는 5xx 오류를 확인합니다. 캡셔닝 모델이 비전 및 구조화된 JSON 스키마 출력을 지원하고 임베딩 모델이 요청된 차원을 지원하는지 확인합니다. |
인덱싱된 에셋이 있어도 검색 결과가 반환되지 않음 | AI 모드가 켜져 있는지 확인하고, Enter를 눌러 쿼리를 제출하고, 활성 콘텐츠 브라우저 필터를 확인합니다. 덜 엄격한 벡터 거리 컷오프도 시도해 보세요. |
유사 항목 찾기가 아무것도 반환하지 않음 | 선택한 에셋이 인덱싱되지 않았거나 유사도 거리 컷오프가 너무 엄격할 수 있습니다. |
제공자/모델/차원을 변경한 후에도 이전 결과가 표시됨 | 인덱싱된 항목 개수 옆의 새로고침 버튼을 사용하여 모든 에셋을 처음부터 다시 인덱싱합니다. |
인덱싱이 너무 느리거나 비용이 너무 높음 | 인덱싱 경로를 제한하거나, 제공자가 속도를 제한하는 경우 동시성을 낮추거나, 더 저렴하거나 빠른 캡셔닝 및 임베딩 모델을 사용하세요. |
API 키가 환경설정에 표시됨 | 이는 예상된 결과입니다. 적절하게 키를 저장하세요. 키는 에디터 사용자별 세팅 환경설정에 평문으로 작성됩니다. |