의미론적 검색 (임베딩)

Synapse는 벡터 임베딩을 사용한 의미론적 검색을 지원합니다. FTS5 (키워드 매칭)와 달리 의미론적 검색은 키워드가 일치하지 않더라도 의미로 메모리를 찾습니다.

작동 방식

1. Memory stored → embedding generated → vector stored
2. Search query → embedding generated → vector compared
3. Cosine similarity → top N results returned

임베딩이란?

임베딩은 텍스트의 수치적 벡터 표현입니다. 유사한 의미를 가진 텍스트는 유사한 벡터를 가집니다. Synapse는 각 메모리의 콘텐츠에 대해 벡터 (예: 1536차원)를 생성합니다.

코사인 유사도

의미론적으로 유사한 메모리를 찾기 위해 Synapse는 쿼리 벡터와 각 메모리 벡터 간의 코사인 유사도를 계산합니다. 유사도가 높을수록 더 관련성이 높습니다.

의미론적 검색 사용 시기

의미론적 검색을 사용할 때:

• 저장된 것과 다르게 설명된 "X에 대한 메모리"를 원할 때
• FTS5가 결과를 반환하지 않을 때 (키워드 매칭 없음)
• 개념적 그룹화를 원할 때 (예: 일부가 "release"라고 말하더라도 모든 "deployment" 메모리)
• 쿼리가 질문일 때: "인증은 어떻게 처리합니까?"

FTS5를 사용할 때:

• 정확한 키워드를 알 때
• 불린 로직 (AND, OR, NOT)이 필요할 때
• 서브밀리초 응답이 필요할 때
• 구문 매칭을 원할 때

엔드포인트

GET /memory/semantic-search

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"

응답:

{
  "results": [
    {
      "id": "mem_001",
      "category": "project",
      "key": "project_synapse_deployment",
      "content": "Synapse deployed using Docker Swarm on vps1...",
      "tags": ["docker", "swarm", "deployment"],
      "similarity": 0.89
    },
    {
      "id": "mem_042",
      "category": "fact",
      "key": "kubernetes_cluster",
      "content": "We use Kubernetes for production orchestration...",
      "tags": ["kubernetes", "orchestration"],
      "similarity": 0.84
    }
  ]
}

예시

배포 메모리 찾기

# FTS5 might miss some — semantic catches all
curl .../memory/semantic-search?q=deployment+process

"deployment", "release", "publishing", "rolling out" 등에 대한 메모리를 반환합니다.

인증 패턴 찾기

curl .../memory/semantic-search?q=how+do+users+log+in

login, auth, JWT, session management, OAuth 등에 대한 메모리를 반환합니다.

유사한 메모리 찾기

# Find memories similar to a specific one
curl .../memory/related/mem_001

(공유 태그 및 임베딩 벡터를 통해) 의미론적 유사도를 사용합니다.

임베딩 생성

임베딩은 언제 생성되나요?

• 메모리 저장 시 — 임베딩 서비스가 구성된 경우, 동기적으로 임베딩 생성
• 배치 생성 — POST /memory/embed-batch가 임베딩이 없는 메모리의 임베딩 생성
• 비동기 업데이트 — 콘텐츠가 업데이트되면 임베딩 재생성

임베딩 제공자

Synapse는 구성 가능한 임베딩 제공자를 지원합니다:

• OpenAI (text-embedding-3-small, text-embedding-3-large)
• 로컬 모델 (Ollama 등을 통해)
• 사용자 정의 (임베딩 인터페이스 구현)

환경 변수로 구성:

EMBEDDINGS_PROVIDER=openai
EMBEDDINGS_API_KEY=sk-...
EMBEDDINGS_MODEL=text-embedding-3-small

배치 생성

임베딩이 누락된 메모리가 많은 마인드의 경우:

# Generate embeddings for up to 100 memories
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'

# Check progress
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/memory/embed-batch-status

성능

제한 사항

임베딩 비용

OpenAI를 사용하는 경우, 임베딩 생성에 비용이 듭니다 (text-embedding-3-small의 경우 1M 토큰당 ~$0.02). 평균 100 토큰인 10,000개 메모리의 경우 ~$0.02 — 무시할 수 있는 수준입니다.

콜드 스타트

임베딩이 구성되기 전에 저장된 메모리는 임베딩이 없습니다. POST /memory/embed-batch를 실행하여 백필하십시오.

제공자 의존성

임베딩 제공자가 다운된 경우, 의미론적 검색은 정상적으로 실패합니다 (빈 결과 또는 오류 반환). FTS5는 여전히 작동합니다.

임베딩을 사용할 수 없는 경우

임베딩 서비스가 구성되지 않은 경우:

• GET /memory/semantic-search가 503 Service Unavailable 반환
• POST /memory는 여전히 작동 (임베딩만 생성 안 됨)
• FTS5 검색은 여전히 작동

모범 사례

다음 단계

• FTS5 검색
• Memory API
• 아키텍처