본문으로 건너뛰기

[가이드] PostgreSQL pgvector를 활용한 Open WebUI RAG 환경 구축

등록일: 2026-05-04

본 문서는 홈서버(5825U) 환경에서 PostgreSQL 18 기반으로 pgvector 확장을 적용하고, Open WebUI의 벡터 데이터를 외부 DB로 관리하기 위한 일련의 과정을 정리함.

1. 개요​

  • 목적: Open WebUI의 벡터 데이터를 내장 DB(Chroma) 대신 외부 PostgreSQL(pgvector)에 저장하여 데이터 독립성 및 확장성을 확보함.
  • 환경: 8코어 16스레드 CPU(5825U), Ubuntu 기반 Docker 환경.

2. Docker Compose 설정 업데이트​

2.1 PostgreSQL (pgvector 이미지 교체)​

기존 postgres:18 이미지를 pgvector/pgvector:pg18으로 교체함. 기존의 한글 로케일 생성 로직은 그대로 유지하여 한글 처리 능력을 보존함.

services:
  postgres:
    image: pgvector/pgvector:pg18
    container_name: postgres
    restart: unless-stopped
    command: >
      bash -c "apt-get update && apt-get install -y locales 
      && sed -i 's/^# ko_KR.UTF-8 UTF-8/ko_KR.UTF-8 UTF-8/' /etc/locale.gen 
      && locale-gen 
      && exec docker-entrypoint.sh postgres"
    environment:
      - POSTGRES_USER=sleepzz
      - POSTGRES_PASSWORD=********
      - TZ=Asia/Seoul
      - LANG=ko_KR.UTF-8
      - LC_ALL=ko_KR.UTF-8
    volumes:
      - /data001/postgresql:/var/lib/postgresql
    ports:
      - "5432:5432"
    networks:
      - serverzz-net

2.2 Open WebUI (환경 변수 설정)​

Open WebUI가 외부 PostgreSQL을 바라보도록 벡터 DB 관련 환경 변수를 추가함.

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    restart: always
    ports:
      - "8083:8080"
    volumes:
      - /data001/open-webui/data:/app/backend/data
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      - "OLLAMA_BASE_URL=https://ollama-api.sleepzz.xyz"
      # 벡터 DB 설정 추가
      - "VECTOR_DB=pgvector"
      - "PGVECTOR_DB_URL=postgresql://sleepzz:********@postgres:5432/postgres"
    networks:
      - serverzz-net

3. 데이터베이스 내 확장(Extension) 활성화​

컨테이너를 다시 시작한 후, PostgreSQL에 접속하여 vector 확장을 직접 활성화해야 함.

-- PostgreSQL 접속 후 (DBeaver 또는 CLI)
-- 사용할 데이터베이스에서 아래 명령 실행
CREATE EXTENSION IF NOT EXISTS vector;

-- 설치 확인
SELECT * FROM pg_extension WHERE extname = 'vector';

4. 작동 확인 및 테스트​

4.1 테이블 생성 확인​

Open WebUI에서 파일을 업로드하거나 대화를 시도하면 다음과 같은 테이블이 자동으로 생성됨을 확인함.

  • document_chunk 등

4.2 데이터 적재 확인​

실제로 임베딩 데이터가 들어갔는지 쿼리를 통해 확인함.

-- 문서 조각 및 벡터 데이터 조회
SELECT * FROM document_chunk LIMIT 5;
  • embedding 컬럼에 숫자 배열(Vector)이 정상적으로 들어가 있다면 설정 완료됨.

5. 결론 및 향후 활용​

  • 관리 편의성: 모든 데이터가 PostgreSQL 한곳에 모여 관리가 용이함.
  • API 연동: 추후 'Nexus' 프로젝트 등 외부 API 서비스에서도 동일한 DB를 조회하여 RAG 구현이 가능함.
  • 성능: 5825U의 멀티코어를 활용하여 인덱싱 처리가 원활하게 수행됨.