DiskANN 확장 활성화 및 사용

2025-05-19

DiskANN은 모든 규모에서 효율적인 벡터 검색을 위한 확장 가능한 근사 최근접 검색 알고리즘입니다. 수십억 개의 데이터 세트에 대해서도 높은 회수, 초당 높은 쿼리 및 낮은 쿼리 대기 시간을 제공합니다. 이러한 특성을 통해 대량의 데이터를 처리할 수 있는 강력한 도구가 됩니다.

DiskANN에 대한 자세한 내용은 DiskANN: 웹 규모 검색 및 권장 사항에 대한 벡터 검색을 참조하세요.

이 확장은 pg_diskann 효율적인 벡터 인덱싱 및 검색을 위해 DiskANN을 사용하기 위한 지원을 추가합니다.

pg_diskann 활성화

Azure Database for PostgreSQL 유연한 서버 인스턴스에서 확장을 사용 pg_diskann 하려면 인스턴스 수준에서 확장을 허용 해야 합니다. 그런 다음 확장에서 제공하는 기능을 사용하려는 각 데이터베이스에 확장을 만들어야 합니다.

pg_diskann 확장은 vector 확장에 대한 종속성을 가지고 있으므로 동일한 데이터베이스에서 허용하고 만들기하여 vector 확장을 실행한 다음 다음 명령을 수행합니다.

CREATE EXTENSION IF NOT EXISTS pg_diskann;

또는 vector 확장을 명시적으로 허용하고 생성하는 단계를 건너뛰고, 대신 CASCADE 절을 추가한 이전 명령을 실행할 수 있습니다. 해당 절에서는 PostgreSQL이 종속된 확장에서 CREATE EXTENSION을 암시적으로 실행하도록 합니다. 이렇게 하려면 다음 명령을 실행합니다.

CREATE EXTENSION IF NOT EXISTS pg_diskann CASCADE;

현재 연결된 데이터베이스에서 확장을 삭제하려면 다음 명령을 실행합니다.

DROP EXTENSION IF EXISTS pg_diskann;

diskann 인덱스 액세스 방법 사용

확장이 설치되면 벡터 데이터가 포함된 테이블 열에 인덱스를 만들 diskann 수 있습니다. 예를 들어 테이블 열 embedding 에 demo 인덱을 만들려면 다음 명령을 사용합니다.

CREATE TABLE demo (
 id INT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 embedding public.vector(3)
 -- other columns
);

-- insert dummy data
INSERT INTO demo (embedding) VALUES
('[1.0, 2.0, 3.0]'),
('[4.0, 5.0, 6.0]'),
('[7.0, 8.0, 9.0]');

-- create a diskann index by using Cosine distance operator
CREATE INDEX demo_embedding_diskann_idx ON demo USING diskann (embedding vector_cosine_ops)

인덱스가 만들어지면 쿼리를 실행하여 가장 가까운 인접 항목을 찾을 수 있습니다.

다음 쿼리는 벡터 [2.0, 3.0, 4.0]에 가장 가까운 5개의 인접 항목을 찾습니다.

SELECT id, embedding
FROM demo
ORDER BY embedding <=> '[2.0, 3.0, 4.0]'
LIMIT 5;

Postgres는 DiskANN 인덱스를 사용할 시기를 자동으로 결정합니다. 인덱스를 사용하기 원하는 시나리오에서 사용하지 않기로 선택된 경우, 다음 명령을 실행합니다.

-- Explicit Transcation block to force use for DiskANN index.

BEGIN;
SET LOCAL enable_seqscan TO OFF;
-- Similarity search queries
COMMIT;

중요함

enable_seqscan을 OFF로 설정하면 사용 가능한 다른 방법이 있는 경우 플래너가 순차적 검사 계획을 사용하는 것을 저해합니다. 명령을 사용하여 SET LOCAL 사용하지 않도록 설정되므로 이 설정은 현재 트랜잭션에만 적용됩니다. COMMIT 또는 ROLLBACK 후에 세션 수준 설정이 다시 적용됩니다. 쿼리에 다른 테이블이 포함된 경우 이 설정은 모든 테이블에서 순차적 검사를 사용하지 않도록 합니다.

양자화를 사용하여 효율적으로 크기 조정(미리 보기)

DiskANN은 PQ(제품 양자화)를 사용하여 벡터의 메모리 공간을 크게 줄입니다. 다른 양자화 기술과 달리 PQ 알고리즘은 벡터를 보다 효과적으로 압축하여 성능을 크게 향상시킬 수 있습니다. PQ를 사용하는 DiskANN은 메모리에 더 많은 데이터를 유지할 수 있으므로 더 느린 스토리지에 액세스할 필요가 줄어들고 압축된 벡터를 비교할 때 더 적은 컴퓨팅을 사용할 수 있습니다. 이렇게 하면 더 많은 양의 데이터(> 100만 행)로 작업할 때 성능이 향상되고 비용이 크게 절감됩니다.

제품 PQ(양자화) 기능에 액세스하려면 미리 보기에 등록하세요.

인덱스 빌드 속도 향상

인덱스 빌드 시간을 개선하는 데 권장되는 몇 가지 방법이 있습니다.

더 많은 메모리 사용

인덱스 만들기 속도를 높이기 위해 인덱스 빌드에 대해 Postgres 인스턴스에 할당된 메모리를 늘릴 수 있습니다. 메모리 사용량은 매개 변수를 maintenance_work_mem 통해 지정할 수 있습니다.

-- Set the parameters
SET maintenance_work_mem = '8GB'; -- Depending on your resources

그런 다음, CREATE INDEX 명령은 사용 가능한 리소스에 따라 지정된 작업 메모리를 사용하여 인덱스를 빌드합니다.

CREATE INDEX demo_embedding_diskann_idx ON demo USING diskann (embedding vector_cosine_ops)

팁 (조언)

인덱스 빌드 중에 메모리 리소스를 확장하여 인덱싱 속도를 개선한 다음 인덱싱이 완료되면 축소할 수 있습니다.

병렬화 사용

인덱스 만들기 속도를 높이기 위해 병렬 작업자를 사용할 수 있습니다. 테이블을 만들 때 parallel_workers 문의 CREATE TABLE 스토리지 매개 변수를 통해 작업자 수를 지정할 수 있습니다. 그리고 SET 명령문의 ALTER TABLE 조항을 사용하여 나중에 조정할 수 있습니다.

CREATE TABLE demo (
	id INT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
	embedding public.vector(3)
) WITH (parallel_workers = 4);
ALTER TABLE demo SET (parallel_workers = 8);

그런 다음, CREATE INDEX 명령은 사용 가능한 리소스에 따라 지정된 수의 병렬 작업자를 사용하여 인덱스를 작성합니다.

CREATE INDEX demo_embedding_diskann_idx ON demo USING diskann (embedding vector_cosine_ops)

중요함

리더 프로세스는 병렬 인덱스 빌드에 참여할 수 없습니다.

병렬 작업자를 사용하여 인덱스를 생성하려면 max_parallel_workers, max_worker_processes, 및 max_parallel_maintenance_workers 매개 변수를 그에 따라 설정해야 합니다. 이러한 매개 변수에 대한 자세한 내용은 리소스 사용 및 비동기 동작을 제어하는 매개 변수를 참조하세요.

이러한 매개 변수는 서로 다른 세분성 수준에서 설정할 수 있습니다. 예를 들어 세션 수준에서 설정하려면 다음 문을 실행할 수 있습니다.

-- Set the parameters
SET max_parallel_workers = 8;
SET max_worker_processes = 8; -- Note: Requires server restart
SET max_parallel_maintenance_workers = 4;

Azure Database for PostgreSQL 유연한 서버에서 이러한 매개 변수를 구성하는 다른 옵션에 대해 알아보려면 서버 매개 변수 구성을 참조하세요.

참고

max_worker_processes 매개 변수를 적용하려면 서버를 다시 시작해야 합니다.

해당 매개 변수의 구성과 서버에서 사용 가능한 리소스가 병렬 작업자 시작을 허용하지 않는 경우 PostgreSQL은 자동으로 뒤로 물러나 비할 데 없는 모드에서 인덱스를 만듭니다.

구성 매개 변수

인덱스 만들기 시 diskann 다양한 매개 변수를 지정하여 동작을 제어할 수 있습니다.

인덱스 매개 변수

max_neighbors: 그래프의 노드당 최대 가장자리 수입니다(기본값은 32). 값이 높을수록 특정 시점까지 회수가 향상될 수 있습니다.
l_value_ib: 인덱스 빌드 중 검색 목록의 크기입니다(기본값은 100). 값이 높을수록 빌드 속도가 느려지지만 인덱스의 품질은 높아집니다.
pq_param_num_chunks: 제품 정량화의 청크 수입니다(기본값은 0). 0은 포함 차원에 따라 자동으로 결정됨을 의미합니다. 원래 포함 차원의 1/3을 사용하는 것이 좋습니다.
pq_param_training_samples: PQ 피벗 테이블을 학습시킬 벡터 수입니다(기본값은 0). 0은 테이블 크기에 따라 자동으로 결정됩니다.

CREATE INDEX demo_embedding_diskann_custom_idx ON demo USING diskann (embedding vector_cosine_ops)
WITH (
 max_neighbors = 48,
 l_value_ib = 100,
 pq_param_num_chunks = 0,
 pq_param_training_samples = 0
 );

확장 매개 변수

diskann.iterative_search: 검색 동작을 제어합니다.

구성: diskann.iterative_search
- relaxed_order (기본값): diskann에서 diskann.l_value_is 절로 제한될 수 있는 원하는 튜플 수가 생성될 때까지 그래프를 LIMIT 배치로 검색할 수 있습니다. 결과가 순서가 다를 수 있습니다.
- strict_order: relaxed_order과(와) 같이 원하는 튜플 수가 생성될 때까지 diskann에서 그래프를 반복적으로 검색할 수 있습니다. 그러나 결과가 거리별로 정렬된 엄격한 순서로 반환되도록 합니다.
- off: 비반복 검색 기능을 사용하여 한 단계에서 diskann.l_value_is 튜플을 가져오려고 시도합니다. 반복적이지 않은 검색은 쿼리와 일치하는 절 diskann.l_value_is 또는 튜플 수에 관계없이 최대 LIMIT 벡터만 반환할 수 있습니다.
검색 동작을 strict_order 변경하려면 현재 세션에서 실행된 모든 쿼리에 대해 다음 문을 실행합니다.
```
SET diskann.iterative_search TO 'strict_order';
```
현재 트랜잭션에서 실행된 모든 쿼리에만 영향을 주도록 변경하려면 다음 문을 실행합니다.
```
BEGIN;
SET LOCAL diskann.iterative_search TO 'strict_order';
-- All your queries
COMMIT;
```
diskann.l_value_is: 인덱스 검색에 대한 L 값입니다(기본값은 100). 값을 늘리면 회수가 향상되지만 쿼리 속도가 느려질 수 있습니다.

인덱스 검색에 대한 L 값을 20으로 변경하려면 현재 세션에서 실행된 모든 쿼리에 대해 다음 문을 실행합니다.
```
SET diskann.l_value_is TO 20;
```
현재 트랜잭션에서 실행된 모든 쿼리에만 영향을 주도록 변경하려면 다음 문을 실행합니다.
```
BEGIN;
SET LOCAL diskann.l_value_is TO 20;
-- All your queries
COMMIT;
```

매개 변수의 권장 구성

데이터 세트 크기(행)	매개 변수 형식	이름	권장 값
<1백만	인덱스 빌드	`l_value_ib`	100
<1백만	인덱스 빌드	`max_neighbors`	32
<1백만	쿼리 시간	`diskann.l_value_is`	100

1M-50M	인덱스 빌드	`l_value_ib`	100
1M-50M	인덱스 빌드	`max_neighbors`	64
1M-50M	쿼리 시간	`diskann.l_value_is`	100

>50M	인덱스 빌드	`l_value_ib`	100
>50M	인덱스 빌드	`max_neighbors`	96
>50M	쿼리 시간	`diskann.l_value_is`	100

참고

이러한 매개 변수는 특정 데이터 세트 및 사용 사례에 따라 달라질 수 있습니다. 사용자는 특정 시나리오에 대한 최적의 설정을 찾기 위해 다른 매개 변수 값을 실험해야 할 수 있습니다.

CREATE INDEX 및 REINDEX 진행률

PostgreSQL 12 이상에서는 CREATE INDEX 또는 REINDEX 작업의 진행률을 확인하는 데 사용할 pg_stat_progress_create_index 수 있습니다.

SELECT phase, round(100.0 * blocks_done / nullif(blocks_total, 0), 1) AS "%" FROM pg_stat_progress_create_index;

CREATE INDEX 또는 REINDEX 작업이 진행되는 가능한 단계에 대한 자세한 내용은 CREATE INDEX 단계를 참조하세요.

인덱스 액세스 함수 선택

벡터 형식을 사용하면 저장된 벡터에서 세 가지 유형의 검색을 수행할 수 있습니다. 데이터베이스에서 쿼리를 실행할 때 인덱스를 고려할 수 있도록 인덱스에 대한 올바른 액세스 함수를 선택해야 합니다.

pg_diskann 는 다음 거리 연산자를 지원합니다.

vector_l2_ops: <-> 유클리드 거리
vector_cosine_ops: <=> 코사인 거리
vector_ip_ops: <#> 내부 제품

문제 해결

오류: assertion left == right failed left: 40 right: 0:

DiskANN GA 버전 인 v0.6.x에서는 인덱스 메타데이터 형식의 주요 변경 내용을 소개합니다 . v0.5.x로 만든 인덱스는 v0.6.x 삽입 작업과 정방향 호환되지 않습니다. 오래된 인덱스가 있는 테이블에 삽입하려고 하면 인덱스가 유효한 것처럼 보이는 경우에도 오류가 발생합니다.
이 오류가 발생하면 다음을 통해 해결할 수 있습니다.
- 옵션 1: 인덱스에서 REINDEX 또는 REDINDEX CONCURRENTLY 문을 실행합니다.
- 옵션 2: 인덱스 다시 작성
```
DROP INDEX your_index_name;
CREATE INDEX your_index_name ON your_table USING diskann(your_vector_column vector_cosine_ops);
```

오류: diskann index needs to be upgraded to version 2...:

이 오류가 발생하면 다음을 통해 해결할 수 있습니다.
- 옵션 1: 인덱스에서 REINDEX 또는 REDINDEX CONCURRENTLY 문을 실행합니다.
- 옵션 2: 시간이 오래 걸릴 수 있으므로 REINDEX 확장은 가능한 경우 인덱스를 더 빠르게 업그레이드하는 사용자 정의 함수도 upgrade_diskann_index()제공합니다.
  
  인덱스 업그레이드를 수행하려면 다음 문을 실행합니다.
```
SELECT upgrade_diskann_index('demo_embedding_diskann_custom_idx');
```
  데이터베이스의 모든 diskann 인덱스를 현재 버전으로 업그레이드하려면 다음 문을 실행합니다.
```
SELECT upgrade_diskann_index(pg_class.oid)
FROM pg_class
JOIN pg_am ON (pg_class.relam = pg_am.oid)
WHERE pg_am.amname = 'diskann';
```