🚀 FastAPI 기반 로컬 LLM + RAG 챗봇 만들기 – Docker를 활용한 PostgreSQL 및 pgvector 설정

🚀 FastAPI 기반 로컬 LLM + RAG 챗봇 만들기 – 2.3.2 Docker를 활용한 PostgreSQL 및 pgvector 설정

이번 글에서는 Docker를 사용하여 PostgreSQL 및 pgvector를 설치하고 설정하는 방법을 다룹니다.
✅ Docker로 PostgreSQL + pgvector 컨테이너 실행 → PostgreSQL 환경 설정 → FastAPI에서 PostgreSQL 연결 순서로 진행됩니다.

---

📌 1. Docker를 활용하는 이유

PostgreSQL 및 pgvector를 Docker로 실행하면 다음과 같은 장점이 있습니다.

✅ 빠른 설치 및 실행 → 시스템에 직접 설치하지 않아도 간편하게 컨테이너 실행
✅ 환경 격리 → 개발 환경과 운영 환경을 분리하여 충돌 방지
✅ 손쉬운 유지보수 → 데이터베이스를 쉽게 삭제, 재설정 및 백업 가능

💡 Docker를 활용하면 PostgreSQL과 pgvector를 쉽고 빠르게 설정할 수 있습니다! 🚀

---

📌 2. Docker Compose를 활용한 PostgreSQL + pgvector 실행

반응형

✅ 1️⃣ docker-compose.yml 파일 생성

📌 프로젝트 루트 디렉터리에 docker-compose.yml 파일을 생성합니다.

version: '3.8'

services:
  postgres:
    image: ankane/pgvector:latest  # pgvector가 포함된 PostgreSQL 이미지
    container_name: pgvector_db
    restart: always
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: password
      POSTGRES_DB: rag_db
    ports:
      - "5432:5432"
    volumes:
      - ./pgvector_data:/var/lib/postgresql/data

volumes:
  pgvector_data:

✅ 설정 설명:

• image: ankane/pgvector:latest → pgvector가 포함된 PostgreSQL 이미지 사용
• POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB → 데이터베이스 사용자 및 기본 설정
• ports: "5432:5432" → 호스트와 컨테이너 간 포트 연결
• volumes → 데이터베이스 데이터를 지속적으로 저장 (컨테이너 삭제 시에도 유지)

---

📌 3. Docker 컨테이너 실행 및 상태 확인

✅ 1️⃣ PostgreSQL 컨테이너 실행

docker-compose up -d

✅ 2️⃣ 실행된 컨테이너 확인

docker ps

📌 정상적으로 실행되었다면 pgvector_db 컨테이너가 활성화 상태로 표시됩니다.

✅ 3️⃣ PostgreSQL 접속 테스트

docker exec -it pgvector_db psql -U admin -d rag_db

✅ 4️⃣ pgvector 확장 기능 활성화

PostgreSQL 내부에서 다음 명령어를 실행하여 pgvector 확장을 활성화합니다.

CREATE EXTENSION IF NOT EXISTS vector;

📌 pgvector 확장이 정상적으로 설치되었는지 확인하려면 다음 명령어를 실행합니다.

SELECT * FROM pg_extension WHERE extname = 'vector';

✅ 결과가 출력되면 pgvector가 정상적으로 활성화된 것입니다! 🚀

---

📌 4. FastAPI에서 PostgreSQL 연결 설정

FastAPI에서 PostgreSQL에 연결하기 위해 SQLAlchemy와 psycopg 라이브러리를 사용합니다.

✅ 1️⃣ 필수 라이브러리 설치

pip install sqlalchemy psycopg[binary] psycopg2-binary

---

✅ 2️⃣ .env 환경 변수 설정

📌 프로젝트 루트 디렉터리에 .env 파일을 생성하고 데이터베이스 정보를 추가합니다.

DATABASE_URL=postgresql://admin:password@localhost:5432/rag_db

✅ 이제 FastAPI에서 .env 파일을 로드하여 PostgreSQL에 연결할 수 있습니다!

---

✅ 3️⃣ database.py 파일 생성 (FastAPI에서 PostgreSQL 연결)

📌 app/core/database.py 파일을 생성하고 SQLAlchemy 설정을 추가합니다.

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base
import os
from dotenv import load_dotenv

# 환경 변수 로드
load_dotenv()

DATABASE_URL = os.getenv("DATABASE_URL")

# 데이터베이스 엔진 생성
engine = create_engine(DATABASE_URL)

# 세션 팩토리 생성
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

# Base 클래스 생성 (모든 모델이 이 클래스를 상속받음)
Base = declarative_base()

# DB 세션 종속성 함수
def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

✅ 이제 FastAPI에서 get_db()를 사용하여 PostgreSQL 세션을 주입할 수 있습니다! 🚀

---

📌 5. FastAPI에서 데이터베이스 연결 테스트

📌 app/api/v1/endpoints/db_test.py 파일을 생성하고 데이터베이스 연결을 확인하는 API를 추가합니다.

from fastapi import APIRouter, Depends
from sqlalchemy.orm import Session
from app.core.database import get_db

router = APIRouter()

@router.get("/test-db")
async def test_db_connection(db: Session = Depends(get_db)):
    return {"message": "Database connection successful!"}

✅ FastAPI에 라우터 등록 (app/main.py 수정)

from fastapi import FastAPI
from app.api.v1.endpoints import db_test

app = FastAPI(title="FastAPI LLM Chatbot")

app.include_router(db_test.router, prefix="/api/v1", tags=["database"])

✅ FastAPI 서버 실행 및 API 테스트

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

✅ 테스트 API 호출 (curl 사용)

curl -X GET "http://localhost:8000/api/v1/test-db"

📌 정상 응답 (200 OK)이 반환되면 PostgreSQL 연결이 성공적으로 설정된 것입니다. 🚀

---

📌 6. 오류 해결 및 디버깅

🔥 1️⃣ could not connect to server: Connection refused 오류

✅ 원인: PostgreSQL 컨테이너가 실행되지 않음
✅ 해결 방법:

docker-compose up -d

---

🔥 2️⃣ relation "pg_extension" does not exist 오류

✅ 원인: pgvector 확장이 활성화되지 않음
✅ 해결 방법:

CREATE EXTENSION IF NOT EXISTS vector;

---

🔥 3️⃣ No module named 'sqlalchemy' 오류

✅ 원인: SQLAlchemy 패키지가 설치되지 않음
✅ 해결 방법:

pip install sqlalchemy

---

📌 7. 결론 및 다음 단계

✅ Docker로 PostgreSQL 및 pgvector 컨테이너 실행 완료!
✅ pgvector 확장 활성화 및 FastAPI에서 데이터베이스 연결 설정!
✅ FastAPI를 사용하여 PostgreSQL 연결을 확인하는 API 테스트 성공! 🚀

🚀 다음 글에서는 "2.3.3 벡터 임베딩 저장 및 검색 구현"을 작성합니다!