Troubleshooting¶

이 섹션에서는 AkasicDB 설치, 확장 프로그램 초기화, 그래프 쿼리, 벡터 인덱스 관련 문제 발생 시 가장 먼저 확인해야 할 사항과 일반적인 복구 절차를 설명합니다.

기본 진단 정보 수집¶

가장 먼저 PostgreSQL 버전, 활성화된 확장 프로그램, 현재 AkasicDB 설정, 그리고 최근 서버 로그를 확인합니다. 문제를 보고할 때는 이 정보들을 비롯해 정확한 SQL 구문이나 애플리케이션 오류 메시지를 함께 첨부해 주시기 바랍니다.

SELECT version();

SELECT extname, extversion FROM pg_extension WHERE extname = 'akasicdb';

SHOW enable_graphplan;
SHOW vectoron.enable_index;
SHOW vectoron.search_mode;

만약 위의 명령을 수행하는 도중 오류가 발생한다면 Installation 섹션을 참고하여 extension을 다시 활성화해 보시기 바랍니다.

서버 로그는 docker logs(Docker 배포판) / pg_ctl -l 옵션에 지정했던 로그 파일(binary 배포판)에서 확인하실 수 있습니다.

라이선스 파일을 찾을 수 없음¶

라이선스 파일 경로가 잘못되었거나, 마운트가 누락되었거나, 환경 변수가 잘못되는 등 여러 이유로 라이선스 관련 문제가 발생할 수 있습니다.

Docker 환경에서는 라이선스 디렉터리 또는 라이선스 파일을 마운트해야 합니다.

-v {directory-with-akasicdb_license.json}:/license
# or
-v {path-to-license-file}:/license/akasicdb_license.json

PostgreSQL 프로세스를 실행하는 사용자가 파일을 읽고 쓸 수 있도록 권한이 부여되어 있어야 합니다. 파일이 읽기 전용으로 설정되었을 경우 오류가 발생할 수 있습니다.

바이너리 설치 환경에서는 PostgreSQL을 시작하기 전에 AKASICDB_LICENSE_PATH 환경 변수가 라이선스 파일을 정확히 가리키고 있는지 확인해야 합니다.

export AKASICDB_LICENSE_PATH=$HOME/.license/akasicdb_license.json

라이선스 경로나 마운트된 디렉터리를 변경했다면, 서버나 컨테이너를 재시작하여 프로세스가 업데이트된 설정을 반영할 수 있게 해야 합니다.

확장 프로그램 초기화 실패¶

AkasicDB는 데이터베이스 내에서 슈퍼유저 권한으로 한 번 활성화해 주어야 합니다.

CREATE EXTENSION IF NOT EXISTS akasicdb;

SELECT akasicdb_admin.initialize();

이 과정이 실패할 경우:

클라이언트 메시지가 아닌 서버 로그를 확인합니다.
바이너리 설치 환경이라면 PostgreSQL을 시작하는 세션의 PATH, LD_LIBRARY_PATH, AKASICDB_LICENSE_PATH 등 환경 변수가 올바른지 확인합니다.

벡터 쿼리가 인덱스를 사용하지 않음¶

AkasicDB의 벡터 검색은 PostgreSQL의 ORDER BY ... LIMIT 패턴을 사용합니다. 사용할 수 있는 벡터 인덱스가 없거나 쿼리 플래너가 인덱스를 선택하지 않을 경우, 쿼리가 전체 탐색(exact search)으로 전환될 수 있습니다.

EXPLAIN
SELECT id
  FROM items
 ORDER BY embedding <-> '[0.1,0.2,0.3]'::vector
 LIMIT 10;

다음 사항들을 확인해 보세요:

vectoron.enable_index 설정이 on으로 되어 있는지
쿼리에 ORDER BY embedding <연산자> query_vector 구문과 LIMIT 절이 모두 포함되어 있는지
연산자 패밀리(operator family)가 인덱스의 연산자 클래스(opclass)와 일치하는지 (예: <-> 연산자에는 vector_l2_ops를 사용)
쿼리 벡터의 차원이 인덱스가 생성된 벡터 컬럼의 차원과 동일한지
쿼리 플래너가 인덱스 탐색을 선호할 만큼 테이블에 데이터(행)가 충분히 있는지
인덱스를 생성하거나 데이터를 대량으로 로드한 후 안정적인 벤치마크 테스트가 필요할 때 idx_indexing 값이 false로 설정되어 있는지

정확한 성능 비교를 위해 전체 탐색(exact search)을 실행해 보려면, 별도의 세션에서 벡터 인덱스 사용을 비활성화하면 됩니다.

SET vectoron.enable_index = off;

비교 테스트가 끝난 후에는 새로운 세션을 열거나 원래 설정값으로 다시 되돌려 놓으시기 바랍니다.

벡터 검색이 느리거나 재현율(Recall)이 예상보다 낮음¶

인덱스 생성 옵션을 변경하기 전에, 먼저 쿼리 실행 시의 검색 파라미터를 조정해 보시기 바랍니다.

BEGIN;
SET LOCAL vectoron.hnsw_ef_search = 200;
SET LOCAL vectoron.vamana_l_search = 200;
SET LOCAL vectoron.ivf_nprobe = 20;

SELECT id
  FROM items
 ORDER BY embedding <-> '[0.1,0.2,0.3]'::vector
 LIMIT 10;
COMMIT;

탐색 범위를 넓히면 재현율이 높아질 수 있지만, 쿼리 응답 시간(latency)과 CPU 사용량도 함께 증가할 수 있습니다. 실제 서비스와 유사한 필터 조건, 벡터 차원, 결과 제한 수(limit)를 적용하여 성능을 측정하시는 것을 권장합니다.

CREATE INDEX items_category_idx ON items (category_id);

그래프 쿼리 실패 또는 예기치 않은 결과 반환¶

그래프 쿼리의 경우, 그래프 준비 과정이 제대로 완료되었는지부터 확인해야 합니다. 그래프 정의를 생성한 후 akasicdb.create_graph(...) 함수까지 실행해야만 실제로 사용 가능한 그래프가 생성됩니다.

akasicdb.create_graph(...) 함수를 실행하기 전에 필요한 정점(vertex)과 간선(edge) 정의가 모두 그래프에 설정되어 있어야 합니다.

만약 그래프 질의가 실패한다면 다음 사항들을 확인해 보세요:

akasicdb.cypher()에 전달한 그래프 이름이 실제 그래프 정의와 일치하는지
akasicdb.create_graph(...)를 실행하기 전에 정점 및 간선 정의를 먼저 생성했는지
akasicdb.cypher() 호출 시 출력될 컬럼명과 SQL 타입이 명시된 AS 절이 포함되어 있는지
GQL 쿼리 문자열을 $$ 기호로 올바르게 감싸서(dollar-quoted) 작성했는지 (작은따옴표로 감싸면 오류 발생)
akasicdb.cypher()를 FROM 절에서 호출했는지(SELECT akasicdb.cypher(...) 등은 동작하지 않음)

만약 질의할 그래프가 정상적으로 존재하고 akasicdb.cypher()를 올바르게 사용하고 있다면 SQL/GQL 사용 시 유의사항 섹션을 확인하시기 바랍니다.