Configuration

AkasicDB를 안정적으로 운영하기 위한 주요 설정과 관리 방법을 정리합니다.

1. 그래프 모듈 관련 GUC 파라미터

AkasicDB의 그래프 분석 모듈인 GraphOn의 GUC 파라미터로 질의 계획을 조정할 수 있습니다.

파라미터	설명	기본값
`enable_graphplan`	쿼리 플래너의 그래프 특화 연산자 사용 여부 (`true`/`false`)	`false`

-- 예시: 세션 단위로 그래프 특화 연산자 사용 여부 조정
SET enable_graphplan = on;
-- 그래프 특화 연산자를 사용할 경우, indexonlyscan을 비활성화해야 함
SET enable_indexonlyscan = off;

AkasicDB에서 제공하는 그래프 특화 연산자의 효율성은 그래프 질의의 복잡도와 데이터의 규모, 그리고 데이터의 특성에 따라 차이가 있을 수 있습니다.

2. 벡터 모듈 관련 GUC 파라미터

AkasicDB의 벡터 인덱스 및 질의 모듈인 VectorOn의 GUC 파라미터로 런타임 탐색·인덱싱 동작을 미세 조정할 수 있습니다.

2.1. 파라미터 일람

파라미터	설명	기본값
`vectoron.enable_index`	쿼리 플래너의 벡터 인덱스 사용 여부 (`true`/`false`)	`true`
`vectoron.hnsw_ef_search`	HNSW 탐색 깊이 (그래프 레벨)	`100`
`vectoron.ivf_nprobe`	IVF 검색 시 스캔할 리스트 수	`10`
`vectoron.pgvector_compatibility`	pgvector 호환 모드 활성화 (`true`/`false`)	`false`
`vectoron.search_mode`	검색 모드 (`"vbase"` 또는 `"basic"`)	`"vbase"`
`vectoron.vamana_l_search`	Vamana 탐색 최대 홉(hop) 수	`100`

-- 예시: 세션 단위로 HNSW 탐색 깊이 조정
SET vectoron.hnsw_ef_search = 128;

2.2 양방향 트레이드오프

파라미터	↑ 설정 시	↓ 설정 시
`hnsw_ef_search`	Recall↑ · 지연↑	지연↓ · Recall↓
`vamana_l_search`	Recall↑ · 지연↑	지연↓ · Recall↓
`ivf_nprobe`	Recall↑ · I/O↑	I/O↓ · Recall↓

3. 벡터 인덱스 관련 파라미터

3.1 백그라운드 최적화 & 세그먼트 크기

인덱스 생성 후 백그라운드에서 세그먼트를 병합·최적화할 때 사용할 워커 스레드 수와
쓰기 버퍼 및 인덱싱 세그먼트의 임계 크기를 조정합니다.

[segment]
max_growing_segment_size = 200000   # 비인덱싱(쓰기) 세그먼트 최대 벡터 개수 (기본: 1,000,000)
max_sealed_segment_size  = 1000000  # 인덱싱(읽기) 세그먼트 최대 벡터 개수 (기본: 4,000,000,000)

[optimizing]
delete_threshold        = 0.1       # 세그먼트 병합/최적화 트리거 삭제 비율 (기본: 0.2)
optimizing_secs         = 1000      # 다음 최적화 시도까지 대기 시간 (초) (기본: 600)
optimizing_threads      = 8         # 병합·최적화 워커 수 (기본: 4, 추천: CPU 코어 수의 √)
sealing_secs            = 30        # 임계값 도달 후 새 세그먼트 분리까지 대기 시간 (초)
sealing_size            = 1000000   # 쓰기 버퍼 → 성장 세그먼트 전환 임계값 (벡터 개수)

max_growing_segment_size: 아직 인덱싱되지 않은 쓰기 세그먼트의 최대 크기
max_sealed_segment_size: 이미 인덱싱된 세그먼트의 최대 크기
delete_threshold: 최적화/병합이 되기 위한 세그먼트 내 삭제된 벡터의 임계값 비율
optimizing_secs: 최적화 시도가 완료된 후 다음 작업을 시도할 때까지의 최소 대기 시간 (초)
optimizing_threads: 백그라운드 병합·최적화에 사용할 스레드 수
sealing_secs: 임계 도달 후 세그먼트 분리 대기 시간
sealing_size: 쓰기 버퍼 크기 임계값

3.2. 인덱스별 파라미터

HNSW

[hnsw]
m               = 16        # 노드당 최대 연결 수 (기본 12)
ef_construction = 200       # 인덱스 구축 시 탐색 폭 (기본 300)

m 값을 크게 할수록 검색 그래프 연결 밀도가 높아지는 대신, 메모리 사용량 및 인덱스 빌드 시간이 늘어납니다.
ef_construction 값을 크게 할수록 인덱스 빌드 품질은 좋아지지만, 인덱스 빌드 시간이 늘어납니다.

Vamana

[vamana]
alpha    = 1.2    # 품질 vs 속도 균형 파라미터  
r        = 32     # 유지할 이웃 노드 수  
l_search = 64     # 검색 시 최대 탐색 홉 수  

alpha 값을 크게 할수록 더 정교한 그래프가 만들어집니다.
r 값을 크게 할수록 메모리 사용량 및 인덱스 빌드 시간이 늘어납니다.
l_search 값을 크게 할수록 검색 품질은 좋아지지만, 검색 지연이 늘어납니다.

IVF

[ivf]
nlist    = 1024     # 클러스터 센터 개수  

nlist 값을 크게 할수록 검색 정확도는 높아지지만, 디스크 및 메모리 사용량이 늘어납니다.

3.3 `CREATE INDEX` 에서 옵션 지정 예시

인덱스 생성 시 WITH (options = $$ … $$) 블록 안에 직접 TOML 스타일 키를 넣어 튜닝할 수 있습니다.

-- 백그라운드 최적화 스레드를 16개로 설정
CREATE INDEX ON items
  USING vectoron (embedding vector_l2_ops)
  WITH (options = $$
    optimizing.optimizing_threads = 16
  $$);

-- 세그먼트 최대 성장 크기를 200,000으로 제한
CREATE INDEX ON items
  USING vectoron (embedding vector_l2_ops)
  WITH (options = $$
    segment.max_growing_segment_size = 200000
  $$);

3.4 양방향 트레이드오프

파라미터	↑ 설정 시	↓ 설정 시
`m` / `r`	Recall↑ · 메모리↑	Recall↓ · 메모리↓
`ef_construction`	빌드 품질↑ · 느림	빌드 속도↑ · 품질↓
`optimizing_threads`	병합 속도↑	병합 속도↓

위 설정과 절차를 따라 AkasicDB를 튜닝·모니터링·업그레이드하면, 안정적이고 효율적인 검색 서비스를 운영하실 수 있습니다. 워크로드·하드웨어 특성에 맞춰 설정을 조정하여, 소규모 테스트를 통해 최적의 파라미터 조합을 찾기를 권장드립니다.