pgvector 설치 및 AI 서버 구동 문서

1. PostgreSQL에 pgvector 설치

macOS

brew install pgvector

Ubuntu

sudo apt update
sudo apt install postgresql-server-dev-14  # PostgreSQL 버전에 따라 수정
git clone https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install

Docker

FROM postgres:14
RUN apt-get update && apt-get install -y postgresql-server-dev-14 git make gcc
RUN git clone https://github.com/pgvector/pgvector.git && cd pgvector && make && make install

PostgreSQL 접속 후

CREATE EXTENSION IF NOT EXISTS vector;

---

2. 임베딩 테이블 생성

블로그 본문 청크 테이블

CREATE TABLE post_chunks (
  post_id     BIGINT     NOT NULL,
  chunk_index INT        NOT NULL,
  content     TEXT       NOT NULL,
  embedding   VECTOR(1536) NOT NULL,
  PRIMARY KEY (post_id, chunk_index),
  FOREIGN KEY (post_id)
    REFERENCES blog_post(id)
    ON DELETE CASCADE
);

CREATE INDEX idx_post_chunks_embedding
  ON post_chunks
  USING hnsw (embedding vector_cosine_ops);

블로그 제목 임베딩 테이블

CREATE TABLE post_title_embeddings (
  post_id   BIGINT       NOT NULL,
  embedding VECTOR(1536) NOT NULL,
  FOREIGN KEY (post_id)
    REFERENCES blog_post(id)
    ON DELETE CASCADE
);

CREATE INDEX idx_post_title_embeddings_embedding
  ON post_title_embeddings
  USING hnsw (embedding vector_cosine_ops);

---

3. HNSW 인덱스란?

• ANN (Approximate Nearest Neighbor) 그래프 기반 인덱스 구조
• 빠른 탐색, 높은 정확도
• 소규모 데이터셋에서도 ivfflat보다 우수한 성능
• PostgreSQL에서는 pgvector v0.5.0+부터 지원 (USING hnsw)
• 데이터량 많아지면 ivfflat으로 변경 고려

---

4. AI 서버 작동

.env 파일 작성 (루트 디렉토리 BUBBLOG_AI에 위치)

---

5. 텍스트 검색 인덱스 (pg_trgm)

하이브리드 검색의 키워드/부분일치 성능 향상을 위해 pg_trgm 확장 및 GIN 인덱스를 추가합니다.

5.1 확장 및 인덱스 생성 스크립트

프로젝트에 제공된 스크립트를 사용하세요:

docs/migrations/2025-01-pgtrgm.sql

내용:

CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE INDEX IF NOT EXISTS idx_pc_content_trgm ON post_chunks USING gin (content gin_trgm_ops);
CREATE INDEX IF NOT EXISTS idx_bp_title_trgm   ON blog_post   USING gin (title   gin_trgm_ops);

5.2 적용 방법

• 환경변수 DATABASE_URL이 설정된 경우:

psql "$DATABASE_URL" -f docs/migrations/2025-01-pgtrgm.sql

• 또는 npm 스크립트 사용:

npm run db:migrate:pgtrgm

• 또는 수동 실행(PostgreSQL 쉘 접속 후):

\i docs/migrations/2025-01-pgtrgm.sql

주의: 인덱스는 쓰기 비용과 디스크 사용량을 증가시킵니다. 텍스트 검색에 사용하는 컬럼(post_chunks.content, blog_post.title)에만 생성하세요.

---

6. Redis 기반 임베딩 워커

임베딩 생성 작업을 Redis 큐에 적재한 뒤 Node.js 워커가 안전하게 처리하도록 구성할 수 있습니다.

6.1 환경 변수

.env 또는 배포 환경 변수를 통해 다음 값을 설정하세요 (필요 시 기본값 사용 가능).

# Redis 연결 (예: 외부 매니지드 인스턴스)
REDIS_URL=redis://username:password@your-redis-host:6379
# 또는 REDIS_HOST/REDIS_PORT 조합 사용 (둘 중 하나만 설정)

# 큐 이름
EMBEDDING_QUEUE_KEY=embedding:queue
EMBEDDING_FAILED_QUEUE_KEY=embedding:failed

# 워커 재시도 설정 (선택)
EMBEDDING_WORKER_MAX_RETRIES=3
EMBEDDING_WORKER_BACKOFF_MS=5000

6.2 로컬 실행

npm run build               # TypeScript 컴파일
npm run start               # Express API
npm run worker              # 프로덕션 워커 (빌드 후)
# 또는 개발용 실시간 실행
npm run worker:dev

6.3 Docker Compose

docker-compose.yml 에는 API와 워커 서비스가 정의되어 있습니다. 외부 Redis 에 접속하도록 .env 의 REDIS_URL 을 설정한 뒤 아래 명령으로 기동하세요.

docker compose up --build

로컬에서 자체 Redis 컨테이너가 필요하다면 compose 파일에 Redis 서비스를 별도로 추가한 뒤 REDIS_URL 또는 REDIS_HOST/PORT 를 해당 컨테이너로 지정하세요.

필요 시 워커만 스케일링할 수도 있습니다.

docker compose up --build --scale worker=3

Redis 큐 상태는 redis-cli 또는 LLEN embedding:queue 같은 명령으로 확인하세요.