출처: Dev.to

SynapCores 벡터 데이터베이스 - 사용자 문서

문서 날짜: 2025년 9월 1일
버전: 1.0 (공개)
상태: 프로덕션 준비 완료

SynapCores는 고급 인덱싱, 유사도 검색, AI 기반 임베딩 생성을 제공하는 클라우드 네이티브 벡터 데이터베이스 기능을 제공합니다. 이 문서는 의미 검색, 추천 및 AI 기반 기능을 위해 SynapCores를 애플리케이션에 통합하는 방법을 설명합니다.

개요

시작하기

임베딩 생성

거리 메트릭

인덱싱 전략

CRUD 작업

SQL 통합

REST API

모범 사례

일반 사용 사례

SynapCores는 전통적인 SQL 데이터베이스 기능과 네이티브 벡터 연산을 결합하여 다음을 가능하게 합니다.

• 고차원 임베딩 저장 및 검색
• 의미 유사도 검색 수행
• 관계형 데이터와 벡터 데이터를 결합한 하이브리드 쿼리 실행
• 데이터베이스 내에서 직접 임베딩 생성
• 수백만 개의 벡터를 100ms 미만의 쿼리 지연 시간으로 확장

벡터 연산

• 다양한 거리 메트릭 (코사인, 유클리드, 내적, 맨해튼)
• 빠른 근사 검색을 위한 HNSW 기반 고급 인덱싱
• 정확 및 근사 최근접 이웃 검색
• 높은 처리량을 위한 배치 연산

SQL 통합

• 네이티브 벡터 데이터 타입
• SQL 쿼리에서 호출 가능한 AI 함수
• 단일 쿼리에서 벡터와 관계형 데이터 조인
• 벡터 확장이 포함된 표준 SQL 문법

엔터프라이즈 기능

• ACID 트랜잭션
• 자동 데이터 영속성
• 다중 테넌트 격리
• 고가용성

API 자격 증명 발급: https://synapcores.com 에서 회원가입 후 대시보드에서 API 토큰을 생성하세요.

# API 토큰 예시
export SYNAPCORES_TOKEN="sc_live_abc123xyz..."

소켓 연결 (SQL 인터페이스)

# SynapCores 네이티브 프로토콜을 통한 연결
synapcores://username:password@your-instance.synapcores.com:5433/your_database

REST API

# 기본 URL
https://api.synapcores.com/api/v1

연결 방법

• 네이티브 소켓 프로토콜: SQL 쿼리 및 고성능 작업용
• REST API: 언어에 구애받지 않는 HTTP 기반 접근용

SQL 사용 예시

SELECT create_vector_space('products', 384, 'cosine');

REST API 사용 예시

curl -X POST https://api.synapcores.com/api/v1/vectors/collections \
  -H "Authorization: Bearer $SYNAPCORES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "products",
    "dimensions": 384,
    "distance_metric": "cosine",
    "index_type": "hnsw"
  }'

내장 임베딩 생성 (다중 모델 지원)

SQL에서 임베딩 생성

-- 기본 모델 (MiniLM) 사용
SELECT EMBED('wireless headphones');

-- 모델 명시적으로 지정
SELECT EMBED('wireless headphones', 'minilm');
SELECT EMBED('wireless headphones', 'bert-base');
SELECT EMBED('wireless headphones', 'bert-large');

데이터 삽입 시 임베딩 생성

INSERT INTO products (name, description, embedding)
VALUES (
    'Bluetooth Headphones',
    'Premium wireless audio device',
    EMBED('Bluetooth Headphones Premium wireless audio device')
);

배치 처리

-- 기존 데이터에 대한 임베딩 생성
UPDATE products
SET embedding = EMBED(name || ' ' || description)
WHERE embedding IS NULL;

거리 함수 및 사용 예시

코사인 유사도

• 용도: 텍스트 임베딩, 의미 검색, 문서 유사도
• 범위: [-1, 1] (1 = 가장 유사)
• 사용 시점: 문서, 제품, 텍스트 기반 콘텐츠 비교

SELECT COSINE_SIMILARITY(vector1, vector2) AS similarity
FROM comparisons;

예시: 유사한 제품 설명 찾기

유클리드 거리

• 용도: 공간 데이터, 이미지 임베딩
• 범위: [0, ∞] (0 = 동일)
• 사용 시점: 공간 좌표 또는 이미지 특징 비교

SELECT EUCLIDEAN_DISTANCE(vector1, vector2) AS distance
FROM comparisons;

예시: 유사 이미지 찾기

내적 (점곱)

• 용도: 추천 시스템
• 범위: (-∞, ∞)
• 사용 시점: 정규화된 벡터로 관련 점수 계산

SELECT INNER_PRODUCT(vector1, vector2) AS score
FROM comparisons;

예시: 사용자‑아이템 추천

맨해튼 거리

• 용도: 희소 고차원 데이터
• 범위: [0, ∞]
• 사용 시점: 희소 특징 벡터 작업

SELECT MANHATTAN_DISTANCE(vector1, vector2) AS distance
FROM comparisons;

특징 요약

• 100% 리콜 보장 (정확한 결과)
• 모든 벡터를 탐색 (브루트 포스)
• 작은 데이터셋에 최적

복합 쿼리 예시

SELECT
    'product_id' AS product_id,
    v.metadata->>'category' AS category,
    COSINE_SIMILARITY(v.values, EMBED('wireless headphones')) AS similarity
FROM vector_spaces.products v
WHERE COSINE_SIMILARITY(v.values, EMBED('wireless headphones')) > 0.7
ORDER BY similarity DESC
LIMIT 10;

REST API 예시

curl -X POST https://api.synapcores.com/api/v1/vectors/collections/products/search \
  -H "Authorization: Bearer $SYNAPCORES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query_text": "wireless headphones",
    "k": 10,
    "threshold": 0.7,
    "include_metadata": true
  }'

응답 예시

{
  "status": "success",
  "data": [
    {
      "id": "prod_12345",
      "score": 0.95,
      "metadata": {
        "product_id": "12345",
        "category": "electronics"
      }
    },
    {
      "id": "prod_67890",
      "score": 0.87,
      "metadata": {
        "product_id": "67890",
        "category": "electronics"
      }
    }
  ],
  "total_results": 2,
  "query_time_ms": 12
}

의미 검색 + 전통 SQL 필터 결합

SELECT
    p.product_id,
    p.name,
    p.price,
    COSINE_SIMILARITY(p.embedding, EMBED('noise cancelling headphones')) AS similarity
FROM products p
WHERE
    p.category = 'electronics'
    AND p.price BETWEEN 50 AND 200
    AND p.in_stock = true
    AND COSINE_SIMILARITY(p.embedding, EMBED('noise cancelling headphones')) > 0.7
ORDER BY similarity DESC, p.price ASC
LIMIT 20;

curl -X POST https://api.synapcores.com/api/v1/vectors/collections/products/search \
  -H "Authorization: Bearer $SYNAPCORES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query_text": "wireless headphones",
    "k": 20,
    "threshold": 0.7,
    "filter": {
      "category": "electronics",
      "in_stock": true
    }
  }'

벡터 업데이트 (SQL)

UPDATE vector_spaces.products
SET
    values = EMBED('Updated product description'),
    metadata = JSON_BUILD_OBJECT(
        'product_id', '12345',
        'category', 'audio',
        'updated_at', CURRENT_TIMESTAMP
    )
WHERE id = 'prod_12345';

벡터 업데이트 (REST API)

curl -X PUT https://api.synapcores.com/api/v1/vectors/collections/products/vectors/prod_12345 \
  -H "Authorization: Bearer $SYNAPCORES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "values": [0.1, 0.2, ...],
    "metadata": {
      "category": "audio",
      "updated_at": "2025-09-01T10:00:00Z"
    }
  }'

벡터 삭제 (SQL)

-- ID로 삭제
DELETE FROM vector_spaces.products
WHERE id = 'prod_12345';

-- 조건으로 삭제
DELETE FROM vector_spaces.products
WHERE metadata->>'category' = 'discontinued';

벡터 삭제 (REST API)

# 단일 벡터 삭제
curl -X DELETE https://api.synapcores.com/api/v1/vectors/collections/products/vectors/prod_12345 \
  -H "Authorization: Bearer $SYNAPCORES_TOKEN"

# 배치 삭제
curl -X POST https://api.synapcores.com/api/v1/vectors/collections/products/delete_batch \
  -H "Authorization: Bearer $SYNAPCORES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids":