# 의미론적 검색 (임베딩)
SUMMARY: 벡터 임베딩을 사용한 개념적 메모리 검색 — 키워드뿐만 아니라 의미로 찾습니다.

의미론적 검색 (임베딩)
Synapse는 벡터 임베딩을 사용한 의미론적 검색을 지원합니다. FTS5 (키워드
매칭)와 달리 의미론적 검색은 키워드가 일치하지 않더라도 의미로
메모리를 찾습니다.
작동 방식
[CODE BLOCK]
임베딩이란?
임베딩은 텍스트의 수치적 벡터 표현입니다. 유사한 의미를 가진 텍스트는
유사한 벡터를 가집니다. Synapse는 각 메모리의 콘텐츠에 대해 벡터 (예:
1536차원)를 생성합니다.
코사인 유사도
의미론적으로 유사한 메모리를 찾기 위해 Synapse는 쿼리 벡터와 각 메모리
벡터 간의 코사인 유사도를 계산합니다. 유사도가 높을수록 더 관련성이
높습니다.
의미론적 검색 사용 시기
의미론적 검색을 사용할 때:
- 저장된 것과 다르게 설명된 "X에 대한 메모리"를 원할 때
- FTS5가 결과를 반환하지 않을 때 (키워드 매칭 없음)
- 개념적 그룹화를 원할 때 (예: 일부가 "release"라고 말하더라도 모든 "deployment" 메모리)
- 쿼리가 질문일 때: "인증은 어떻게 처리합니까?"
FTS5를 사용할 때:
- 정확한 키워드를 알 때
- 불린 로직 (AND, OR, NOT)이 필요할 때
- 서브밀리초 응답이 필요할 때
- 구문 매칭을 원할 때
엔드포인트
GET /memory/semantic-search
[CODE BLOCK]
응답:
[CODE BLOCK]
예시
배포 메모리 찾기
[CODE BLOCK]
"deployment", "release", "publishing", "rolling out" 등에 대한 메모리를
반환합니다.
인증 패턴 찾기
[CODE BLOCK]
login, auth, JWT, session management, OAuth 등에 대한 메모리를 반환합니다.
유사한 메모리 찾기
[CODE BLOCK]
(공유 태그 및 임베딩 벡터를 통해) 의미론적 유사도를 사용합니다.
임베딩 생성
임베딩은 언제 생성되나요?
- 메모리 저장 시 — 임베딩 서비스가 구성된 경우, 동기적으로 임베딩 생성
- 배치 생성 — 가 임베딩이 없는 메모리의 임베딩 생성
- 비동기 업데이트 — 콘텐츠가 업데이트되면 임베딩 재생성
임베딩 제공자
Synapse는 구성 가능한 임베딩 제공자를 지원합니다:
- OpenAI (, )
- 로컬 모델 (Ollama 등을 통해)
- 사용자 정의 (임베딩 인터페이스 구현)
환경 변수로 구성:
[CODE BLOCK]
배치 생성
임베딩이 누락된 메모리가 많은 마인드의 경우:
[CODE BLOCK]
성능
| 작업 | 지연 시간 |
|-----------|---------|
| 임베딩 생성 (OpenAI) | 100-200ms |
| 의미론적 검색 (1k 메모리) | 50-100ms |
| 의미론적 검색 (10k 메모리) | 200-500ms |
| 배치 생성 (100 메모리) | 10-20s |
> [!NOTE]
> 의미론적 검색은 벡터 계산으로 인해 FTS5보다 느립니다. 알려진 키워드에는
> FTS5를, 개념적 쿼리에는 의미론적 검색을 사용하십시오.
제한 사항
임베딩 비용
OpenAI를 사용하는 경우, 임베딩 생성에 비용이 듭니다 (text-embedding-3-small의
경우 1M 토큰당 $0.02). 평균 100 토큰인 10,000개 메모리의 경우
$0.02 — 무시할 수 있는 수준입니다.
콜드 스타트
임베딩이 구성되기 전에 저장된 메모리는 임베딩이 없습니다. 를 실행하여 백필하십시오.
제공자 의존성
임베딩 제공자가 다운된 경우, 의미론적 검색은 정상적으로 실패합니다 (빈
결과 또는 오류 반환). FTS5는 여전히 작동합니다.
임베딩을 사용할 수 없는 경우
임베딩 서비스가 구성되지 않은 경우:
- 가 503 Service Unavailable 반환
- 는 여전히 작동 (임베딩만 생성 안 됨)
- FTS5 검색은 여전히 작동
모범 사례
> [!TIP]
> - 개념적 쿼리에 의미론적 검색 사용 — "X를 어떻게 처리합니까?"
> - 특정 용어에 FTS5 사용 — "docker swarm"
> - 정기적으로 임베딩 백필 — 
> - 제공자 상태 모니터링 — 의미론적 검색은 이에 의존
> - 태그와 결합 — 의미론적 + 태그 필터가 결과를 좁힘
다음 단계
- FTS5 검색
- Memory API
- 아키텍처