PostgreSQL + pgvector 기반의 벡터 검색 실험을 한 흐름으로 따라갈 수 있는 실용 가이드입니다. 설치부터 데이터 준비, 인덱스 생성·평가, 그리고 PostgreSQL 튜닝까지 필요한 스크립트와 절차를 정리했습니다.
- PostgreSQL과 pgvector를 직접 빌드하고 확장까지 설치하는 방법
- Hugging Face/ANN-Benchmarks 데이터를 활용해
.fbin/.ibin포맷을 만드는 데이터셋 준비법 - 테이블 스키마 예시와 대량 적재 스크립트
- IVFFlat/HNSW 인덱스 생성과 recall–QPS 기반 평가 워크플로우
- 대규모 적재·인덱싱 환경을 위한 PostgreSQL 핵심 튜닝 파라미터
docs/00_overview.md: 프로젝트 개요와 목적docs/01_install_pgvector.md: PostgreSQL·pgvector 소스 빌드 및 초기화docs/02_create_dataset.md: Hugging Face/ANN-Benchmarks 데이터 준비와.fbin생성docs/03_create_index.md: 테이블 생성, 데이터 적재, IVFFlat/HNSW 인덱스 예제docs/04_evaluation.md: ground truth 생성, 쿼리 실행, recall/QPS 계산과 시각화docs/05_monitoring_sql.md: 대용량 적재·인덱싱 시 유용한 PostgreSQL 파라미터 튜닝 가이드
(추가 모니터링/튜닝 팁을 여기에 확장 예정)
- 데이터셋 생성:
scripts/02_create_dataset/01_huggingface_to_fbin.py
Hugging Face 데이터셋을.fbin(train/query)으로 변환. - 데이터 적재:
scripts/03_create_index/01_fbin_to_pgvector.py
.fbin을 읽어COPY바이너리로 pgvector 테이블에 삽입. - 평가 준비:
scripts/04_evaluation/01_fbin_to_ibin.py
train/query.fbin으로 DiskANN 스타일.ibinground truth 생성. - 쿼리 실행:
scripts/04_evaluation/02_run_test.py
PostgreSQL에 recall@k, QPS 측정 쿼리를 반복 수행. - 결과 시각화:
scripts/04_evaluation/03_plot_result.py
recall–QPS 곡선 예제 플롯.
- PostgreSQL & pgvector 설치
docs/01_install_pgvector.md의 빌드/초기화 절차를 따라CREATE EXTENSION vector;까지 완료합니다. - 데이터 준비
Hugging Face 예시:python scripts/02_create_dataset/01_huggingface_to_fbin.py에서 경로/차원 등을 수정 후 실행 →*-train.fbin,*-query.fbin생성 (docs/02_create_dataset.md참고). - 테이블 생성 & 적재
CREATE TABLE vectors (id integer, embedding VECTOR(<dim>));실행 후scripts/03_create_index/01_fbin_to_pgvector.py의 파일 경로와 테이블명을 맞춰 실행 (docs/03_create_index.md). - 인덱스 생성
예:CREATE INDEX ON vectors USING hnsw (embedding vector_cosine_ops) WITH (m=24, ef_construction=200);
필요 시 IVFFlat/bit_hamming 예제를 문서에서 선택. - 성능 평가
- Ground truth:
python scripts/04_evaluation/01_fbin_to_ibin.py --base train.fbin --query query.fbin --out neighbors.ibin --k 100 --metric l2 - 쿼리/recall 측정:
scripts/04_evaluation/02_run_test.py에서 파일 경로, 테이블명, 포트 등을 설정 후 실행 - 그래프:
scripts/04_evaluation/03_plot_result.py의 데이터 포인트를 수정해 플롯
- Ground truth:
- 튜닝
docs/05_monitoring_sql.md의shared_buffers,maintenance_work_mem, 병렬 파라미터 등을 환경에 맞게 적용.
- Python 3.10+ 와 주요 패키지:
numpy,datasets,scikit-learn,psycopg,pgvector,matplotlib - PostgreSQL 소스 빌드 환경, pgvector 소스
- 실험용 DB: 예시에서는
dbname=ann,user=ann,port=5434를 사용
이슈/제안/PR 환영합니다. 실험 중 얻은 설정 팁이나 추가 스크립트가 있다면 공유해주세요.