콘텐츠로 이동

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를 사용)
  • 질의 벡터의 차원이 인덱스가 생성된 벡터 컬럼의 차원과 동일한지
  • 질의 플래너가 인덱스 탐색을 선호할 만큼 테이블에 데이터(행)가 충분히 있는지
  • 인덱스를 생성하거나 데이터를 대량으로 로드한 후 안정적인 벤치마크 테스트가 필요할 때 vectoron_index_stat에서 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)를 적용하여 성능을 측정하시는 것을 권장합니다.

필터 조건이 포함된 벡터 질의에서는 필터 조건 컬럼에 일반 PostgreSQL 인덱스를 추가합니다.

CREATE INDEX items_category_idx ON items (category_id);

그래프 질의 실패 또는 예기치 않은 결과 반환

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

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

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

  • akasicdb.cypher()에 전달한 그래프 이름이 실제 그래프 정의와 일치하는지
  • akasicdb.create_graph(...)를 실행하기 전에 정점 및 간선 정의를 먼저 생성했는지
  • akasicdb.cypher() 호출의 AS 절에 정의한 컬럼이 그래프 질의의 RETURN 절에서 생성되는 결과 컬럼과 개수 및 순서 면에서 일치하는지
  • 그래프 질의 문자열을 $$...$$ 또는 $query$...$query$ 형식의 달러 인용 문자열로 작성했는지(작은따옴표로 묶은 일반 문자열은 사용할 수 없음)
  • akasicdb.cypher()를 FROM 절에서 호출했는지(SELECT akasicdb.cypher(...) 등은 동작하지 않음)

질의할 그래프가 정상적으로 존재하고 akasicdb.cypher()를 올바르게 사용하고 있다면 SQL/GQL 사용 시 유의사항에서 지원 문법과 제한 사항을 확인해 주세요.

그래프 토폴로지 복구

이전에 생성한 그래프의 토폴로지가 일관되지 않거나 손상되어 그래프를 질의할 수 없다면, 기존 그래프 데이터를 기반으로 정점 및 간선 토폴로지를 다시 빌드하세요.

SELECT akasicdb.recover_graph_topology('retail_graph');

함수 시그니처

akasicdb.recover_graph_topology(graph_name NAME) RETURNS void

graph_name은 akasicdb.create_graph(...)로 생성한 기존 그래프의 이름입니다.

현재 그래프 정의가 존재하고 그래프를 생성할 때 사용한 정의와 일치하며, 그래프 카탈로그 및 속성 데이터가 온전한 경우에만 토폴로지를 복구할 수 있습니다.

그래프 정의가 변경되었다면 토폴로지 복구를 사용할 수 없습니다. 변경된 정의를 적용하려는 경우이며 그래프 DML 변경 사항이 사라져도 되는 경우에만 akasicdb.create_graph(..., replace_if_exists := true)로 그래프를 재생성하세요. 자세한 내용은 Graph DML의 경고를 참조하세요. 필수 그래프 데이터나 식별자 컬럼이 없다면 먼저 이를 복원한 후 토폴로지 복구를 실행해야 합니다.

Warning

토폴로지를 다시 빌드하는 동안 그래프 데이터가 잠깁니다. 그래프가 변경되지 않는 유지보수 시간에 실행하세요. 이 함수는 그래프의 현재 속성 데이터를 기반으로 토폴로지를 복구하며, 누락된 속성 데이터나 그래프 정의 및 카탈로그 메타데이터는 복원하지 않습니다.