ServBay에서 pgvector PostgreSQL 확장 기능 사용 가이드

pgvector는 PostgreSQL 데이터베이스에 벡터 데이터 타입과 효율적인 벡터 인덱싱 방식을(IVFFlat, HNSW 등) 추가해주는 강력한 서드파티 확장입니다. 이를 통해 PostgreSQL은 벡터 저장 및 유사도 검색을 기본적으로 지원하게 되며, AI 애플리케이션, 추천 시스템, 이미지 인식, 자연어 처리 등 고차원 벡터 데이터를 다루는 데 이상적인 선택지로 자리잡고 있습니다.

ServBay는 통합 로컬 웹 개발 환경으로, PostgreSQL과 pgvector 확장 기능을 이미 내장하고 있어 로컬 환경에서 벡터 데이터베이스를 쉽게 활성화하고 사용할 수 있도록 도와줍니다. 이 문서에서는 ServBay 환경에서 pgvector를 어떻게 활용하는지 상세히 안내드립니다.

pgvector란 무엇이며, 왜 중요한가요?

현대의 다양한 애플리케이션에서는 데이터가 단순한 텍스트나 숫자를 넘어섭니다. AI와 머신러닝 기술의 발전으로 인해 데이터는 흔히 고차원 벡터(임베딩)로 표현됩니다. 벡터는 데이터의 의미, 특징, 예를 들면 이미지의 시각 정보, 텍스트 의미, 사용자 선호도 따위를 포착합니다.

pgvector 확장 기능을 사용하면 PostgreSQL은 이러한 벡터를 직접 저장하고, 효율적인 벡터 유사도 검색(최근접 이웃 검색)을 지원할 수 있습니다. 즉, 익숙한 SQL만으로도 벡터에 기반한 데이터를 검색할 수 있어 별도의 벡터 데이터베이스를 도입할 필요 없이 기술 스택이 한층 단순해집니다.

사전 준비

pgvector를 사용하기에 앞서 다음 조건을 충족해야 합니다:

macOS에서 ServBay가 설치돼 있고 실행 중이어야 합니다.
ServBay의 패키지(“Software Packages”) 리스트에서 PostgreSQL 패키지가 활성화돼 있어야 합니다. 아직 활성화하지 않았다면 ServBay 앱에서 PostgreSQL을 찾아 상태를 “활성화”로 변경하세요.

ServBay의 PostgreSQL에서 pgvector 확장 기능 활성화

ServBay는 PostgreSQL 설치 디렉터리에 pgvector 확장 파일을 미리 포함하고 있습니다. 별도의 다운로드나 빌드가 필요하지 않으며, 사용하려는 특정 데이터베이스에 확장 기능만 활성화하면 됩니다.

ServBay의 PostgreSQL에서 pgvector를 활성화하는 단계는 다음과 같습니다:

PostgreSQL 데이터베이스에 연결 ServBay가 제공하는 PostgreSQL 인스턴스에 psql 명령행 도구를 이용해 연결할 수 있습니다. ServBay의 PostgreSQL은 기본적으로 로컬 연결을 허용하며, 기본 사용자명은 postgres 또는 servbay, 기본 포트는 5432입니다. 환경에 따라 다를 수 있으니 ServBay 데이터베이스 구성 설명서를 참고하세요.
터미널을 열고 아래 명령어로 연결하세요. (사용자명, 데이터베이스명은 환경에 맞게 수정)
bash
```
psql -U servbay -d your_database_name -h localhost -p 5432
```
1
- -U servbay: 사용자명(servbay 또는 postgres) 지정
- -d your_database_name: 연결할 데이터베이스명. 데이터베이스가 없다면 먼저 생성(CREATE DATABASE servbay_demo_db;) 필요
- -h localhost: 호스트는 로컬 서버 지정
- -p 5432: 기본 PostgreSQL 포트(5432) 지정
vector 확장 생성 연결 후, psql 프롬프트에서 아래 SQL 명령으로 pgvector를 활성화하세요:
sql
```
CREATE EXTENSION vector;
```
1
이미 확장 기능이 있다면 존재 알림 메시지가 출력될 수 있습니다.

설치 확인 설치된 확장 기능 목록을 확인하려면 아래 명령을 입력하세요:

sql

\dx

결과에 vector 확장이 버전 정보와 함께 나타나야 합니다.

                           List of installed extensions
   Name   | Version |   Schema   |                         Description
----------+---------+------------+--------------------------------------------------------------
 plpgsql  | 1.0     | pg_catalog | PL/pgSQL procedural language
 vector   | 0.7.0   | public     | vector data type and ivfflat and hnsw access methods
(2 rows)

(참고: 버전 번호는 ServBay에 포함된 pgvector 버전에 따라 다를 수 있습니다)

pgvector 구성 및 사용

확장 기능을 활성화하면 데이터베이스 내에서 벡터 데이터를 만들고 관리할 수 있습니다.

벡터 데이터를 저장하는 테이블 생성

먼저 벡터 데이터를 담을 테이블을 생성해야 합니다. pgvector는 새로운 데이터 타입인 VECTOR(dimensions)을 제공합니다. 여기서 dimensions는 벡터의 차원 수입니다.

아래는 embeddings라는 테이블(3차원 벡터 저장) 생성 예시입니다:

sql

CREATE TABLE embeddings (
    id SERIAL PRIMARY KEY,
    -- 3차원 벡터 칼럼 정의
    vector VECTOR(3)
);

그 다음, 샘플 벡터 데이터를 삽입합니다:

sql

INSERT INTO embeddings (vector) VALUES
('[0.1, 0.2, 0.3]'),
('[0.4, 0.5, 0.6]'),
('[0.7, 0.8, 0.9]'),
('[0.15, 0.25, 0.35]'),
('[0.6, 0.5, 0.4]'); -- 예시가 더 분명해지도록 데이터를 추가

참고: 벡터 값은 대괄호 []로 감싸고, 각 요소는 쉼표로 구분해야 합니다.

쿼리 성능 향상을 위한 벡터 인덱스 생성

벡터 데이터가 많은 테이블에는 인덱스 생성이 유사도 검색 성능에 매우 중요합니다. pgvector는 IVFFlat, HNSW 두 주요 인덱스를 지원합니다. 인덱스 종류 선택은 용도(속도, 구축 시간, 메모리, 검색 품질 등)에 따라 달라집니다.

IVFFlat (Inverted File Index with Flat compression): 큰 데이터셋이지만 완벽한 검색 품질보다 처리 속도가 중요한 경우 적합, 인덱스 구축이 빠름
HNSW (Hierarchical Navigable Small World): 더 높은 검색 품질과 빠른 쿼리 속도를 제공하지만, 인덱스 구축이 느리고 메모리 사용량이 더 높습니다

아래는 embeddings 테이블의 vector 컬럼에 각각 IVFFlat, HNSW 인덱스를 생성하는 예시입니다:

IVFFlat 인덱스 생성

sql

-- IVFFlat 인덱스 생성 전, ANALYZE로 통계 정보를 수집해야 함
ANALYZE embeddings;

-- IVFFlat 인덱스 생성
-- WITH (lists = 100): 리스트 개수 설정. 테이블 크기에 따라 조정 필요.
-- 리스트 수가 많으면 구축은 느려지고 검색시 더 많은 리스트를 스캔해야 하지만 검색 품질이 향상
-- 공식 권장값은 lists = sqrt(행 개수)
CREATE INDEX idx_ivfflat_vector ON embeddings USING ivfflat (vector) WITH (lists = 100);

HNSW 인덱스 생성

sql

-- HNSW 인덱스 생성
-- WITH (m = 16, ef_construction = 200): HNSW 인덱스 파라미터 설정
-- m: 노드당 연결 개수(연결성/효율/메모리 영향)
-- ef_construction: 인덱스 구축시 탐색 범위. 구축 시간/메모리 및 검색 품질에 영향.
-- 실제 데이터/성능에 맞게 조절 필요
CREATE INDEX idx_hnsw_vector ON embeddings USING hnsw (vector) WITH (m = 16, ef_construction = 200);

참고: 인덱스 파라미터(lists, m, ef_construction)는 성능과 품질에 큰 영향을 줍니다. 최적값 선택은 데이터 특성과 쿼리 패턴을 이해하고 실험하는 과정이 필요합니다. 더 상세한 설명과 튜닝 가이드는 pgvector 공식 문서를 참고하세요.

pgvector로 벡터 쿼리 실행

pgvector는 벡터 간 거리를 계산하는 다양한 연산자를 제공하며, 이를 기반으로 유사도 검색을 수행할 수 있습니다. 주로 사용되는 연산자:

<->: L2 거리(유클리드 거리). 두 벡터 사이의 직선 거리 측정에 사용
<#>: 내적(Inner Product). 코사인 유사도와 관련, 방향상의 유사성 측정에 사용
<=>: 코사인 거리(Cosine Distance), 즉 1 - 코사인 유사도. 벡터 방향의 유사성을 측정하며 벡터 길이에는 영향받지 않음

아래에 주요 벡터 쿼리 예시를 소개합니다:

최근접 이웃 쿼리(Nearest Neighbor Search)

지정한 쿼리 벡터와 가장 유사한(거리가 가장 가까운) 벡터를 검색합니다. 보통 ORDER BY와 거리 연산자, LIMIT을 함께 사용합니다.

벡터 [0.2, 0.3, 0.4]와 L2 거리가 가장 가까운 5개 벡터 검색

sql

SELECT
    id,
    vector,
    -- 쿼리 벡터와의 L2 거리 계산
    vector <-> '[0.2, 0.3, 0.4]' AS distance
FROM
    embeddings
ORDER BY
    distance -- 거리가 가까운 순(유사도가 높은 순)으로 정렬
LIMIT 5;

벡터 유사도 쿼리(Similarity Search)

최근접 쿼리와 유사하지만, 유사도 점수를 함께 표시하는 경우에 활용됩니다.

벡터 [0.2, 0.3, 0.4]와 코사인 거리가 가장 가까운 5개 벡터 검색 후 점수 표시

sql

SELECT
    id,
    vector,
    -- 쿼리 벡터와의 코사인 거리 계산
    vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance
FROM
    embeddings
ORDER BY
    cosine_distance -- 거리가 가까운 순(유사도가 높은 순)으로 정렬
LIMIT 5;

벡터 데이터 시각화(선택 사항)

고차원 벡터 데이터를 시각화하면 데이터 분포와 클러스터링을 이해하는 데 도움이 됩니다. 2D, 3D 벡터라면 바로 산점도를 그릴 수 있고, 그 이상의 차원은 PCA, t-SNE 같은 차원 축소 기법을 이용해 2D/3D로 투영해 시각화합니다.

아래는 Python과 Matplotlib 라이브러리를 이용해 3차원 벡터 데이터를 시각화하는 기본 예시입니다.

Python 환경 준비 ServBay 외부 혹은 내부에서 Python 환경을 세팅해야 합니다. ServBay의 Python 패키지를 사용할 경우 활성화 상태를 확인하세요. PostgreSQL과 연결하는 라이브러리(psycopg2)와 그래프 라이브러리(matplotlib)가 필요합니다:
bash
```
# 시스템 기본 Python 혹은 별도 설치한 경우
pip install psycopg2 matplotlib

# ServBay Python 사용시, ServBay 명령행이나 pip 실행 경로 이용
# /Applications/ServBay/패키지/python/bin/pip install psycopg2 matplotlib
```
1
2
3
4
5
환경 경로에 맞게 pip 명령어를 조정하세요.

Python 스크립트 작성 파일명(visualize_vectors.py)을 생성하고 아래 코드를 복사해 붙여넣기. ServBay PostgreSQL 환경에 맞게 dbname, user, password, host, port를 수정하세요.

python

import psycopg2
import matplotlib.pyplot as plt
from mpl_toolkits.mplot3d import Axes3D # 3D 산점도 생성 모듈

# 데이터베이스 연결 설정 – ServBay 환경에 맞게 수정
db_params = {
    "dbname": "your_database_name", # 데이터베이스명으로 변경
    "user": "servbay",              # ServBay PostgreSQL 사용자명(일반적으로 servbay 또는 postgres)
    "password": "",                 # 데이터베이스 비밀번호(로컬 연결시 비어 있을 수도 있음)
    "host": "localhost",            # ServBay PostgreSQL은 주로 localhost에서 동작
    "port": "5432"                  # 기본 포트
}

conn = None
cur = None

try:
    # PostgreSQL 연결
    conn = psycopg2.connect(**db_params)
    cur = conn.cursor()

    # 벡터 데이터 쿼리
    # psycopg2는 생성한 Vector 타입을 '[x, y, z]' 문자열로 반환함
    # 구버전에서는 수동 파싱 필요, 최신 pgvector 및 psycopg2에서 자동 변환 지원할 수 있음
    # 아래는 문자열 처리 예제
    cur.execute("SELECT vector FROM embeddings")
    vectors_raw = cur.fetchall()

    # 벡터 문자열 파싱 후 숫자 배열로 변환
    vectors = []
    for row in vectors_raw:
        # 대괄호 제거, 쉼표로 분할 후 실수 변환
        vec_str = row[0].strip('[]')
        coords = [float(c) for c in vec_str.split(',')]
        vectors.append(coords)

    if not vectors:
        print("쿼리에서 벡터 데이터를 찾지 못했습니다.")
        exit()

    # 벡터 좌표 추출 – 모든 벡터가 3차원이어야 함
    if any(len(v) != 3 for v in vectors):
         print("경고: 차원이 3이 아니거나 일치하지 않아 3D 그래프를 그릴 수 없습니다.")
         exit()


    x = [v[0] for v in vectors]
    y = [v[1] for v in vectors]
    z = [v[2] for v in vectors]

    # 3D 산점도 생성
    fig = plt.figure()
    ax = fig.add_subplot(111, projection='3d')
    ax.scatter(x, y, z)

    ax.set_xlabel('Dimension 1')
    ax.set_ylabel('Dimension 2')
    ax.set_zlabel('Dimension 3')
    ax.set_title('3D 벡터 시각화')

    plt.show()

except psycopg2.Error as e:
    print(f"데이터베이스 연결 또는 쿼리 오류: {e}")
except Exception as e:
    print(f"에러 발생: {e}")
finally:
    # 데이터베이스 연결 해제
    if cur:
        cur.close()
    if conn:
        conn.close()

스크립트 실행 터미널에서 다음 명령어로 Python 스크립트를 실행합니다:
bash
```
python visualize_vectors.py
```
1
스크립트가 PostgreSQL에서 벡터를 읽어 Matplotlib으로 3D 산점도 창을 표시합니다.

자주 묻는 질문(FAQ)

Q: \dx 명령 결과에 vector 확장이 보이지 않습니다. A: 우선 CREATE EXTENSION vector; 명령을 제대로 실행했는지, 에러가 없는지 확인하세요. 그래도 없다면 ServBay PostgreSQL 패키지 설치 및 활성화 상태를 재점검하시고, pgvector 확장 파일이 PostgreSQL의 share/extension 폴더에 있는지 확인하세요. 파일 유실 시 ServBay의 PostgreSQL 패키지를 재설치 또는 업그레이드해야 할 수 있습니다.
Q: 데이터베이스 연결시 인증 실패 오류가 발생합니다. A: psql 명령 또는 Python 스크립트의 사용자명, 비밀번호, 호스트, 포트가 ServBay PostgreSQL 구성과 일치하는지 확인하세요. 로컬 연결은 기본적으로 servbay 또는 postgres 계정이며, 비밀번호가 비어 있는 경우가 있습니다.
Q: 벡터 인덱스 파라미터(lists, m, ef_construction)는 어떻게 선택하나요? A: 파라미터는 성능/검색 품질에 크게 영향을 미치므로 일률적 최적값이 없습니다. 데이터 크기, 차원 수, 쿼리 지연 허용 범위, 목표 검색 품질에 따라 실험과 조율이 필수입니다. 자세한 정보는 pgvector 공식 문서에서 확인할 수 있습니다.

요약

pgvector는 강력한 벡터 데이터베이스 기능을 안정적인 PostgreSQL 시스템에 통합해, 개발자가 로컬 환경에서 AI 및 벡터 기반 애플리케이션 개발을 훨씬 쉽게 할 수 있게 합니다. ServBay는 pgvector를 기본 제공함으로써 설치 및 환경 세팅 과정을 크게 단순화해줍니다.

이 가이드에 따라 ServBay PostgreSQL에서 pgvector 활성화, 벡터 데이터 테이블 생성, 인덱스를 통한 빠른 쿼리, 다양한 벡터 유사도 검색을 간편하게 실행할 수 있습니다. ServBay가 제공하는 기타 개발 도구, 환경과 결합해 현대 웹 프로젝트와 데이터 집약적 애플리케이션을 더욱 효율적으로 구축 및 테스트하세요.

ServBay에서 pgvector PostgreSQL 확장 기능 사용 가이드 ​

pgvector란 무엇이며, 왜 중요한가요? ​

사전 준비 ​

ServBay의 PostgreSQL에서 pgvector 확장 기능 활성화 ​

pgvector 구성 및 사용 ​

벡터 데이터를 저장하는 테이블 생성 ​

쿼리 성능 향상을 위한 벡터 인덱스 생성 ​

pgvector로 벡터 쿼리 실행 ​

최근접 이웃 쿼리(Nearest Neighbor Search) ​

벡터 유사도 쿼리(Similarity Search) ​

벡터 데이터 시각화(선택 사항) ​

자주 묻는 질문(FAQ) ​

요약 ​