4주차 스터디
database: postgres, pgvector
data: [IMDB](https://developer.imdb.com/non-commercial-datasets/)
docker, fastapi
dash board: streamlit
- 기본 틀 정도만 구성
- 도커 띄우기
- 데이터셋 샘플 임포트 (전체는 양이 굉장히 많음, 모두 체크는 못해봤으나 한 테이블은 9천만행 이상
프로토타입을 바이브코딩으로 만들어보려다 진행을 제대로 못해서… 맥락이 다르긴 하지만 바이브코딩을 어떤 식으로 해보았는지로 남길게요.
-
[Task-master](https://www.task-master.dev/) 활용 (스펙문서를 바탕으로 태스크로 나누어주고 태스크를 티켓처럼 관리할 수 있는 mcp)
-
[무엇이고 왜 필요한지?에 대한 참고 영상](https://www.youtube.com/watch?v=ktr-4JjDsU0) (0:15 - 2:05)
-
PRD 문서
<context> # Overview 이 프로젝트는 자연어를 SQL로 변환해 PostgreSQL DB를 조회할 수 있는 **Text2SQL 데모 시스템**을 만드는 것을 목표로 합니다. - **문제**: 비기술 사용자나 분석가들이 데이터베이스 구조를 몰라 SQL 작성에 어려움을 겪는다. - **대상**: 사내 데이터 분석가, 비개발자, 혹은 SQL 작성에 익숙하지 않은 사용자. - **가치**: 자연어 질의로 DB를 탐색해 데이터 접근성을 높이고, LLM 및 벡터 검색 기반 구조를 학습·검증할 수 있다. # Core Features 1. **자연어 → SQL 변환** - **무엇을 하는가**: OpenAI LLM을 사용해 사용자의 자연어 입력을 SQL로 변환 - **중요성**: SQL을 모르는 사용자도 데이터 조회 가능 - **동작 방식**: pgvector에 저장된 스키마/예제 쿼리 임베딩을 RAG로 불러와 프롬프트를 구성 후 LLM 호출 2. **쿼리 실행 및 결과 반환** - **무엇을 하는가**: 생성된 SQL을 PostgreSQL에 실행하고 결과를 반환 - **중요성**: 사용자가 실제 데이터를 즉시 확인 - **동작 방식**: FastAPI가 DB 연결 및 실행 처리 → Streamlit이 테이블 형식으로 결과 표시 3. **유사 쿼리/스키마 검색 (pgvector)** - **무엇을 하는가**: 기존 쿼리/스키마를 임베딩 후 유사 질의 시 참조 - **중요성**: LLM의 SQL 생성 정확도 향상 - **동작 방식**: OpenAI Embedding API로 스키마/쿼리 임베딩 생성 → pgvector 검색 4. **Streamlit UI** - **무엇을 하는가**: 사용자 입력·결과를 시각적으로 보여줌 - **중요성**: 비기술 사용자가 쉽게 접근 가능 - **동작 방식**: FastAPI API를 호출해 SQL과 결과를 가져옴 # User Experience - **User Persona** - 데이터 분석팀 신입: DB 구조 이해가 부족하지만 조회 필요 - 비즈니스 매니저: SQL 작성 없이 데이터 확인 - **Key User Flow** 1. Streamlit 웹페이지 접속 2. 자연어 질의 입력 3. LLM이 SQL 생성 → FastAPI API 반환 4. 결과 테이블 확인 및 SQL 미리보기 - **UI/UX Considerations** - SQL 미리보기 및 수정 가능 - 결과 테이블 페이지네이션 - 에러 발생 시 명확한 메시지 표시 </context> <PRD> # Technical Architecture - **System Components** - **Frontend/UI**: Streamlit - **Backend API**: FastAPI (SQL 생성/DB 연결) - **Database**: PostgreSQL + pgvector - **LLM/Embeddings**: OpenAI API - **Data Models** - PostgreSQL: 예제 테이블(employees, orders) - pgvector: - 테이블/컬럼 설명 임베딩 - 사용자 질의 및 SQL 히스토리 임베딩 - **APIs & Integrations** - OpenAI API (LLM + Embedding) - FastAPI Endpoints: - `/generate_sql` (자연어→SQL) - `/execute_sql` (SQL 실행) - `/search_schema` (유사 스키마 검색) - **Infrastructure Requirements** - Docker Compose로 PostgreSQL + pgvector + FastAPI 컨테이너 구성 - Streamlit은 별도 컨테이너 또는 로컬 실행 - .env 파일로 OpenAI API Key 관리 # Development Roadmap - **MVP Requirements** - PostgreSQL+pgvector 세팅 - FastAPI 기본 API (generate_sql, execute_sql) - OpenAI LLM 연동 - Streamlit UI (질의 입력·결과 표시) - **Future Enhancements** - SQL 미리보기 및 수정 - 사용자 히스토리 기반 추천 - 스키마 자동 업데이트 및 임베딩 리프레시 - 권한 관리/로그인 - 데이터 시각화 (차트/그래프) # Logical Dependency Chain 1. **기반 구축** - Docker Compose로 PostgreSQL+pgvector+FastAPI 기본 구조 - DB 스키마/테이블 정의 및 초기 데이터 2. **LLM 연동** - OpenAI API 연결, 프롬프트 엔지니어링 - 임베딩 생성·pgvector 저장 3. **기본 UI 구축** - Streamlit에서 질의 입력→FastAPI 호출→결과 표시 4. **RAG/유사 검색 추가** - pgvector 검색 기반 프롬프트 개선 5. **고급 기능** - SQL 미리보기/수정 - 사용자 히스토리 관리 # Risks and Mitigations - **Technical Challenges**: LLM이 올바른 SQL 생성하지 못할 수 있음 → pgvector로 스키마 제공, 프롬프트 개선 - **MVP 정의**: 범위를 좁혀 초기에는 단일 DB·단일 사용자 대상 → 이후 확장 - **Resource Constraints**: OpenAI API 비용 → GPT-3.5 우선 사용, 샘플 데이터 최소화 # Appendix - **Research Findings** - pgvector는 PostgreSQL 확장으로 설치 및 관리 간단 - OpenAI Embedding API는 1k 토큰당 저렴, 빠른 임베딩 생성 가능 - **Technical Specifications** - Python 3.11 - FastAPI 0.110+ - Streamlit 1.35+ - PostgreSQL 15+ / pgvector 0.5+ - Docker Compose로 로컬 환경 구축 </PRD>
-
- 프론트: streamlit
- 스키마, 데이터 설정
- 구현 공유
Vanna 같은 경우는 DB 구조(DDL), 문서(Documentation), 예제 쿼리를 사전에 만들거나 계속 추가해 RAG 방식으로 검색해서 찾는 구조
-
필요한 (메타)데이터
DB의 테이블, 컬럼, 데이터 타입 등 구조 설명
-
CREATE TABLE, ALTER TABLE 등 DDL 문 자체를 그대로 입력
textvn.train(ddl="CREATE TABLE customer (id INT PRIMARY KEY, name TEXT, signup_date DATE, age INT);") vn.train(ddl="CREATE TABLE order (id INT, customer_id INT, order_date DATE, total INT);")
- 모든 주요 테이블의 CREATE 문
- PK/FK, 인덱스, 데이터 타입 등 연결관계
- 실제 인증/이력 테이블까지 세부적으로 입력하면 베스트
업무 용어/비즈니스 규칙/도메인 용어, 사용 설명서 등
-
해당 컬럼이 뭘 의미하는지, 용도, 기준, 통계 규칙 등 한글/영문 설명
textvn.train(documentation="고객 한 명은 여러 개 주문을 할 수 있다. 주문 테이블의 customer_id는 customer 테이블의 id를 가리킨다.") vn.train(documentation="order 테이블의 total 컬럼은 부가세가 포함된 최종 결제 금액이다.")
- 중요한 비즈니스 룰(예: VIP 등급 기준)
- 테이블 간 관계 및 실무적 해석
- 주요 집계·통계 계산 방식
- 자주 쓰는 코드 예시도 한 줄 코멘트로 남기면 효과적
회사에서 자주 쓰거나 실무적 의미가 있는 SQL과 그에 해당하는 자연어 질문/설명
-
질문-SQL 쌍을 직접 추가
textvn.train(question="지난달 신규 고객 수는?", sql="SELECT COUNT(*) FROM customer WHERE signup_date >= '2025-08-01' AND signup_date < '2025-09-01';") vn.train(question="VIP 고객의 이름과 전화번호 가져와", sql="SELECT name, phone FROM customer WHERE vip_status = 'Y';")
- 자주 쓰는 KPI/매출/통계형 쿼리
- 헷갈리는 조건/분기별 집계 등 까다로운 쿼리
- 다양한 DB의 조인/필터/집계 예시
- DDL(테이블/컬럼/관계/타입)
- 도메인 설명(비즈니스 용어/규칙/설명)
- 실전 질문-SQL 쌍(업무별, 팀별, 역할별 주요 질의 쿼리)
-
사내에서 쓸꺼면 데이터 관리부서에서 자주쓰는 내용들만 해줘도 어느정도 커버가 될꺼라고는 생각함
하지만 B2B 서비스나 모르는 데이터를 연결하려고 했을 때는 저 정보들이 하나도 없기 때문에 사실상 못 씀
두가지 고객의 유형이 있을꺼라고 생각
- DB가 없거나 단순한 유형
- DB가 복잡한 유형
첫 번째 유형 같은 경우는 개발자가 직접 데이터를 보고 분석하거나 LLM이 분식 및 판단해도 크게 무리가 없음
두 번째 유형은 크고 복잡한 DB를 바로 연결하고자 한 경우는 고객사(IT 관리자)한테 위의 (메타)데이터를 다 받아서 진행해야함
→ 이 과정을 앞단에서 정규화해서 처리할 수 있는 과정을 통해 안정적으로 확보
- 구현 공유
- 사례 공유
database: postgres, pgvector
api: openai chatgpt 4o-mini, embedding-3-small
data: e-commerce data(회사거), dvd_rental
dash board: streamlit
- 벡터에서 문서 참조는 꼭 n 개가 필요하지 않은 것 같다. 오히려 방해요소. 임베딩 유사도에 임계치를 두면 어떨까?
- 질의 벡터와 문서간 벡터간의 유사도는 JOIN 이 들어가는 순간 참조 테이블들은 대부분 무시되며 할루시네이션 발생 빈도 증가.
- 기초적인 문법에 잘 작동. 메타베이스 정의문 작성과 SQL 예시문을 충분히 주면 어떨까?
- 질의에 들어가는 단어는 컬럼을 선택하는 중요한 요소. 질의를 분석해 필요한 테이블과 컬럼을 명시할 수 없을까?
- snowflake
next)
- 데이터: dvdrental
- 데이터베이스: postgres
- 벡터 데이터베이스: pgvector
- 데이터베이스 관리: Dbeaver
- llm openai
구현하고. 과정 중에 겪었던 일. 생각했던 것들. ->> 공유!!! 구현하신분들은 JOIN 한 번 도전! 해보면서 추석을 보내면 좋을 것 같습니다.