컬렉션

컬렉션 (Collections)

출처: Qdrant 공식 문서 — collections

여러분, Qdrant에서 데이터를 다룰 때 가장 처음 만나는 개념이 바로 **컬렉션(Collection)**이에요. 컬렉션은 검색할 수 있는 point(벡터 + payload)들의 이름 붙은 집합이에요. 같은 컬렉션 안의 각 point 벡터는 **동일한 차원(dimensionality)**을 가져야 하고, **단일 메트릭(metric)**으로 비교돼요. 명명된 벡터(Named vectors)를 쓰면 한 point 안에 여러 벡터를 둘 수 있고, 각각 고유한 차원과 메트릭 요구사항을 가질 수 있어요.

거리 메트릭(Distance metrics) 은 벡터 간 유사도를 측정하는 데 쓰여요. 메트릭 선택은 벡터를 얻는 방식, 특히 신경망 인코더의 학습 방법에 따라 달라져요. Qdrant가 지원하는 가장 인기 있는 메트릭은 다음과 같아요:

  • 내적(Dot product): Dot
  • 코사인 유사도(Cosine similarity): Cosine
  • 유클리드 거리(Euclidean distance): Euclid
  • 맨해튼 거리(Manhattan distance): Manhattan

메트릭과 벡터 크기 외에도, 각 컬렉션은 컬렉션 최적화, 인덱스 구축, vacuum을 제어하는 자체 매개변수 집합을 사용해요. 이 설정들은 언제든 해당 요청으로 변경할 수 있어요.

멀티테넌시(Multitenancy) 설정하기

컬렉션을 몇 개 만들어야 할까요? 대부분의 경우에는 payload 기반 파티셔닝을 쓰는 단일 컬렉션만 사용하는 게 좋아요. 이 방식을 멀티테넌시라고 해요. 대부분의 사용자에게 효율적이지만 추가 설정이 필요해요. 설정하는 방법을 살펴보세요.

언제 여러 컬렉션을 만들어야 할까요? 사용자 수가 제한적이고 격리(isolation)가 필요할 때예요. 이 방식은 유연하지만, 컬렉션을 많이 만들면 리소스 오버헤드가 발생해 더 비쌀 수 있어요. 또한 컬렉션들이 성능 측면을 포함해 서로 어떤 식으로든 영향을 주지 않도록 보장해야 해요.

컬렉션 만들기

PUT /collections/{collection_name}
{
    "vectors": {
        "size": 300,
        "distance": "Cosine"
    }
}

curl -X PUT http://localhost:6333/collections/{collection_name} \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "vectors": {
      "size": 100,
      "distance": "Cosine"
    }
  }'

from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://localhost:6333")

client.create_collection(
    collection_name="{collection_name}",
    vectors_config=models.VectorParams(size=100, distance=models.Distance.COSINE),
)

import { QdrantClient } from "@qdrant/js-client-rest";

const client = new QdrantClient({ host: "localhost", port: 6333 });
client.createCollection("{collection_name}", {
  vectors: { size: 100, distance: "Cosine" },
});

필수 옵션 외에도 다음 컬렉션 옵션의 사용자 정의 값을 지정할 수 있어요:

  • hnsw_config — 자세한 내용은 인덱싱(indexing)을 참고해요.
  • wal_config — Write-Ahead-Log 관련 설정. WAL에 대한 자세한 내용은 여기를 참고해요.
  • optimizers_config — 자세한 내용은 옵티마이저를 참고해요.
  • shard_number — 컬렉션이 가질 샤드 수를 정의해요. 분산 배포 섹션을 참고해요.
  • payload.memory — payload 저장의 메모리 티어를 설정해요.
  • quantization_config — 자세한 내용은 양자화(quantization)를 참고해요.
  • strict_mode_config — 자세한 내용은 strict mode를 참고해요.

선택적 컬렉션 매개변수의 기본값은 설정 파일에 정의되어 있어요.

컬렉션과 벡터 매개변수에 대한 자세한 내용은 스키마 정의와 설정 파일을 참고해요.

v1.2.0부터 사용 가능

Qdrant는 항상 벡터를 디스크에 저장해요. 각 벡터에 메모리 티어를 설정해서 그 데이터 중 얼마만큼을 메모리에 함께 둘지 제어할 수 있어요.

여러 벡터를 가진 컬렉션

v0.10.0부터 사용 가능

레코드 하나에 여러 벡터를 둘 수 있어요. 이 기능을 쓰면 컬렉션당 여러 벡터 스토리지를 가질 수 있어요. 한 레코드 안의 벡터들을 구분하려면 각각 고유한 이름(name)을 가져야 해요. 이 모드에서 각 명명된 벡터는 자기만의 거리와 크기를 가져요:

PUT /collections/{collection_name}
{
    "vectors": {
        "image": {
            "size": 4,
            "distance": "Dot"
        },
        "text": {
            "size": 8,
            "distance": "Cosine"
        }
    }
}

from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://localhost:6333")

client.create_collection(
    collection_name="{collection_name}",
    vectors_config={
        "image": models.VectorParams(size=4, distance=models.Distance.DOT),
        "text": models.VectorParams(size=8, distance=models.Distance.COSINE),
    },
)

import { QdrantClient } from "@qdrant/js-client-rest";

const client = new QdrantClient({ host: "localhost", port: 6333 });
client.createCollection("{collection_name}", {
  vectors: {
    image: { size: 4, distance: "Dot" },
    text: { size: 8, distance: "Cosine" },
  },
});

드물지만 벡터 스토리지가 전혀 없는 컬렉션을 만들 수도 있어요.

v1.1.1부터 사용 가능

각 명명된 벡터에 대해 hnsw_config나 quantization_config를 선택적으로 지정해서 컬렉션 설정과 다르게 할 수 있어요. 벡터 수준에서 검색 성능을 미세 조정할 때 유용해요.

v1.2.0부터 사용 가능

Qdrant는 항상 벡터를 디스크에 저장해요. 벡터별로 메모리 티어를 설정해서 그 데이터 중 얼마만큼을 메모리에 함께 둘지 제어할 수 있어요.

벡터 데이터 타입 (Vector Datatypes)

v1.9.0부터 사용 가능

기본적으로 Qdrant는 각 벡터 차원을 32비트 부동소수점(float)으로 저장해요. 메모리와 저장 공간은 차원 수에 따라 선형으로 늘어나기 때문에, 큰 벡터에서는 금방 커져요. 이 비용을 줄이거나 이미 낮은 정밀도로 된 벡터를 저장하려면 다른 데이터 타입을 설정할 수 있어요: float16(반정밀도), uint8(부호 없는 8비트 정수), turbo4(4비트).

예를 들어 uint8 임베딩으로 컬렉션을 만들려면:

PUT /collections/{collection_name}
{
    "vectors": {
        "size": 1024,
        "distance": "Cosine",
        "datatype": "uint8"
    }
}

from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://localhost:6333")

client.create_collection(
    collection_name="{collection_name}",
    vectors_config=models.VectorParams(
        size=1024,
        distance=models.Distance.COSINE,
        datatype=models.Datatype.UINT8,
    ),
)

import { QdrantClient } from "@qdrant/js-client-rest";

const client = new QdrantClient({ host: "localhost", port: 6333 });
client.createCollection("{collection_name}", {
  vectors: {
    image: { size: 1024, distance: "Cosine", datatype: "uint8" },
  },
});

데이터 타입 전체 선택지와 trade-off는 데이터 타입(Datatypes) 문서를 참고해요.

희소 벡터를 가진 컬렉션

v1.7.0부터 사용 가능

Qdrant는 희소 벡터(sparse vector)를 일급 시민(first-class citizen)으로 지원해요.

희소 벡터는 각 단어가 별개의 차원으로 표현되는 텍스트 검색에 유용해요.

컬렉션은 일반적인 밀집 벡터와 함께 희소 벡터를 추가 명명된 벡터로 포함할 수 있어요.

밀집 벡터와 달리 희소 벡터는 반드시 이름을 가져야 해요. 그리고 희소 벡터와 밀집 벡터는 컬렉션 안에서 서로 다른 이름을 가져야 해요.

PUT /collections/{collection_name}
{
    "sparse_vectors": {
        "text": { }
    }
}

from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://localhost:6333")

client.create_collection(
    collection_name="{collection_name}",
    vectors_config={},
    sparse_vectors_config={
        "text": models.SparseVectorParams(),
    },
)

import { QdrantClient } from "@qdrant/js-client-rest";

const client = new QdrantClient({ host: "localhost", port: 6333 });
client.createCollection("{collection_name}", {
  sparse_vectors: { text: { } },
});

고유한 이름 외에는 희소 벡터에 필수 설정 매개변수가 없어요.

희소 벡터의 거리 함수는 항상 Dot이고 지정할 필요가 없어요.

다만 기본이 되는 희소 벡터 인덱스를 조정하는 선택적 매개변수가 있어요.

다른 컬렉션에서 컬렉션 만들기

다른 컬렉션에서 컬렉션을 만들려면 Migration Tool을 사용해요. 같은 Qdrant 인스턴스 안에서 컬렉션을 복사하거나, 다른 인스턴스로 복사할 수 있어요.

예를 들어 로컬 인스턴스의 컬렉션을 Qdrant Cloud 인스턴스로 복사하려면:

docker run --net=host --rm -it registry.cloud.qdrant.io/library/qdrant-migration qdrant \
    --source.url 'http://localhost:6334' \
    --source.collection 'source-collection' \
    --target.url 'https://example.cloud-region.cloud-provider.cloud.qdrant.io:6334' \
    --target.api-key 'qdrant-key' \
    --target.collection 'target-collection' \
    --migration.batch-size 64

컬렉션 존재 확인

v1.8.0부터 사용 가능

GET /collections/{collection_name}/exists

curl -X GET http://localhost:6333/collections/{collection_name}/exists

client.collection_exists(collection_name="{collection_name}")

client.collectionExists("{collection_name}");

메타데이터를 가진 컬렉션

v1.14.0부터 사용 가능

컬렉션을 만들 때 컬렉션 메타데이터를 지정할 수 있어요:

client.create_collection(
    collection_name="{collection_name}",
    vectors_config=models.VectorParams(size=100, distance=models.Distance.COSINE),
    metadata={"my-metadata-field": "value-1", "another-field": 123},
)

client.createCollection("{collection_name}", {
  vectors: { size: 100, distance: "Cosine" },
  metadata: { "my-metadata-field": "value-1", "another-field": 123 },
});

또한 이후에 업데이트할 수도 있어요:

PATCH /collections/{collection_name}
{
    "metadata": {
        "my-metadata-field": {
            "key-a": "value-a",
            "key-b": 42
        }
    }
}

client.update_collection(
    collection_name="{collection_name}",
    metadata={"my-metadata-field": {"key-a": "value-a", "key-b": 42}},
)

client.updateCollection("{collection_name}", {
  metadata: { "my-metadata-field": { "key-a": "value-a", "key-b": 42 } },
});

더 알아보기 (Learn more)