Qdrant Edge 퀵스타트

Qdrant Edge 퀵스타트 (edge-edge-quickstart)

Qdrant Edge 설치하기 (Install Qdrant Edge)

먼저 Python Bindings for Qdrant Edge 또는 Rust 크레이트를 설치해 주세요.

스토리지 디렉터리 만들기 (Create a Storage Directory)

Qdrant Edge 샤드는 데이터를 디스크의 로컬 디렉터리에 저장해요. 아직 디렉터리가 없다면 만들어 주세요:

from pathlib import Path

SHARD_DIRECTORY = "./qdrant-edge-directory"

Path(SHARD_DIRECTORY).mkdir(parents=True, exist_ok=True)

const SHARD_DIRECTORY: &str = "./qdrant-edge-directory";

fs_err::create_dir_all(SHARD_DIRECTORY)?;

Edge 샤드 구성하기 (Configure the Edge Shard)

Edge 샤드는 Qdrant 컬렉션을 구성하는 것과 유사하게, Edge 샤드에 저장할 수 있는 밀집·희소 벡터의 정의로 구성돼요.

EdgeConfig 인스턴스를 만들어 구성을 설정해 주세요. 예를 들어:

from qdrant_edge import (
    Distance,
    EdgeConfig,
    EdgeVectorParams,
)

VECTOR_NAME="my-vector"
VECTOR_DIMENSION=4

config = EdgeConfig(
    vectors={
        VECTOR_NAME: EdgeVectorParams(
            size=VECTOR_DIMENSION,
            distance=Distance.Cosine,
        )
    }
)

const VECTOR_NAME: &str = "my-vector";
const VECTOR_DIMENSION: usize = 4;

let config = EdgeConfig {
    on_disk_payload: true,
    vectors: HashMap::from([(
        VECTOR_NAME.to_string(),
        EdgeVectorParams {
            size: VECTOR_DIMENSION,
            distance: Distance::Cosine,
            on_disk: Some(true),
            quantization_config: None,
            multivector_config: None,
            datatype: None,
            hnsw_config: None,
        },
    )]),
    sparse_vectors: HashMap::new(),
    hnsw_config: Default::default(),
    quantization_config: None,
    optimizers: Default::default(),
};

Edge 샤드 초기화하기 (Initialize the Edge Shard)

이제 스토리지 디렉터리와 구성을 전달해 EdgeShard.create(Python) 또는 EdgeShard::new(Rust)로 새 EdgeShard를 만들 수 있어요:

from qdrant_edge import EdgeShard

edge_shard = EdgeShard.create(SHARD_DIRECTORY, config)

let edge_shard = EdgeShard::new(
    Path::new(SHARD_DIRECTORY),
    config,
)?;

스토리지 디렉터리에 데이터가 이미 있으면 create와 new가 실패한다는 점에 유의해 주세요. 기존 데이터로 Edge 샤드를 초기화하려면 디스크에서 기존 Edge 샤드 로드(Load Existing Edge Shard from Disk)를 참고해 주세요.

포인트 작업하기 (Work with Points)

Edge 샤드는 포인트를 다루는 여러 메서드가 있어요. 포인트를 추가하려면 update 메서드를 사용해 주세요:

from qdrant_edge import (
    Point,
    UpdateOperation
)

point = Point(
    id=1,
    vector={VECTOR_NAME: [0.1, 0.2, 0.3, 0.4]},
    payload={"color": "red"}
)

edge_shard.update(UpdateOperation.upsert_points([point]))

let points: Vec<PointStructPersisted> = vec![
    PointStruct::new(
        1u64,
        Vectors::new_named([(VECTOR_NAME, vec![0.1f32, 0.2, 0.3, 0.4])]),
        json!({"color": "red"}),
    )
    .into(),
];

edge_shard.update(UpdateOperation::PointOperation(
    PointOperations::UpsertPoints(
        PointInsertOperations::PointsList(points),
    ),
))?;

ID로 포인트를 검색하려면 retrieve 메서드를 사용해 주세요:

records = edge_shard.retrieve(
    point_ids=[1],
    with_payload=True,
    with_vector=False
)

let retrieved = edge_shard.retrieve(
    &[PointId::NumId(1)],
    Some(WithPayloadInterface::Bool(true)),
    Some(WithVector::Bool(false)),
)?;

페이로드 인덱스 만들기 (Create a Payload Index)

페이로드 필드에 대한 필터링 및 패싯(faceting) 같은 연산을 최적화하려면, 먼저 이런 연산에 사용할 필드에 페이로드 인덱스를 만들어 주세요:

from qdrant_edge import PayloadSchemaType

edge_shard.update(UpdateOperation.create_field_index("color", PayloadSchemaType.Keyword))

edge_shard.update(UpdateOperation::FieldIndexOperation(
    FieldIndexOperations::CreateIndex(
        CreateIndex {
            field_name: "color".try_into().unwrap(),
            field_schema: Some(PayloadFieldSchema::FieldType(
                PayloadSchemaType::Keyword,
            )),
        },
    ),
))?;

포인트 쿼리하기 (Query Points)

Edge 샤드에서 포인트를 쿼리하려면 query 메서드를 사용해 주세요:

from qdrant_edge import Query, QueryRequest

results = edge_shard.query(
    QueryRequest(
        query=Query.Nearest([0.2, 0.1, 0.9, 0.7], using=VECTOR_NAME),
        limit=10,
        with_vector=False,
        with_payload=True
    )
)

let results = edge_shard.query(
    QueryRequest {
        prefetches: vec![],
        query: Some(ScoringQuery::Vector(QueryEnum::Nearest(
            NamedQuery {
                query: vec![0.2f32, 0.1, 0.9, 0.7].into(),
                using: Some(VECTOR_NAME.to_string()),
            }
        ))),
        filter: None,
        score_threshold: None,
        limit: 10,
        offset: 0,
        params: None,
        with_vector: WithVector::Bool(false),
        with_payload: WithPayloadInterface::Bool(true),
    }
)?;

포인트 필터링하기 (Filter Points)

페이로드 필드를 기준으로 포인트를 필터링할 수도 있어요:

from qdrant_edge import FieldCondition, Filter, MatchValue

results = edge_shard.query(
    QueryRequest(
        query=Query.Nearest([0.2, 0.1, 0.9, 0.7], using=VECTOR_NAME),
        filter=Filter(
            must=[
                FieldCondition(
                    key="color",
                    match=MatchValue(value="red"),
                )
            ]
        ),
        limit=10,
        with_vector=False,
        with_payload=True
    )
)

let filter = Filter {
    should: None,
    min_should: None,
    must: Some(vec![Condition::Field(
        FieldCondition::new_match(
            "color".try_into().unwrap(),
            Match::Value(MatchValue { value: ValueVariants::String("red".to_string()) }),
        ),
    )]),
    must_not: None,
};

let results = edge_shard.query(
    QueryRequest {
        prefetches: vec![],
        query: Some(ScoringQuery::Vector(QueryEnum::Nearest(
            NamedQuery {
                query: vec![0.2f32, 0.1, 0.9, 0.7].into(),
                using: Some(VECTOR_NAME.to_string()),
            }
        ))),
        filter: Some(filter),
        score_threshold: None,
        limit: 10,
        offset: 0,
        params: None,
        with_vector: WithVector::Bool(false),
        with_payload: WithPayloadInterface::Bool(true),
    }
)?;

패싯 만들기 (Create Facets)

페이로드 필드에 대한 패싯을 만들려면 facet 메서드를 사용해 주세요.

from qdrant_edge import FacetRequest

facet_response = edge_shard.facet(
    FacetRequest(
        key="color",
        limit=10,
        exact=False,
    )
)

let facet_response = edge_shard.facet(
    FacetRequest {
        key: "color".try_into().unwrap(),
        limit: 10,
        filter: None,
        exact: false,
    }
)?;

Edge 샤드 최적화하기 (Optimize the Edge Shard)

최적화는 삭제 대상으로 표시된 데이터를 제거하고, 세그먼트를 병합하며, 인덱스를 만드는 과정이에요. Qdrant Edge에는 백그라운드 옵티마이저가 없어요. 대신 애플리케이션은 optimize 메서드를 호출해 트래픽이 적은 시간이나 일괄 업데이트 후처럼 적절한 시점에 최적화를 동기적으로 실행할 수 있어요.

edge_shard.optimize()

edge_shard.optimize()?;

옵티마이저는 Edge 샤드를 초기화할 때 EdgeConfig의 optimizers 파라미터로 구성할 수 있어요. 예를 들어:

from qdrant_edge import EdgeOptimizersConfig

config = EdgeConfig(
    vectors={
        VECTOR_NAME: EdgeVectorParams(
            size=VECTOR_DIMENSION,
            distance=Distance.Cosine,
        )
    },
    optimizers=EdgeOptimizersConfig(
        deleted_threshold=0.2,
        vacuum_min_vector_number=100,
        default_segment_number=2,
    ),
)

let config = EdgeConfig {
    on_disk_payload: true,
    vectors: HashMap::from([(
        VECTOR_NAME.to_string(),
        EdgeVectorParams {
            size: VECTOR_DIMENSION,
            distance: Distance::Cosine,
            on_disk: Some(true),
            quantization_config: None,
            multivector_config: None,
            datatype: None,
            hnsw_config: None,
        },
    )]),
    sparse_vectors: HashMap::new(),
    hnsw_config: Default::default(),
    quantization_config: None,
    optimizers: EdgeOptimizersConfig {
        deleted_threshold: Some(0.2),
        vacuum_min_vector_number: Some(100),
        default_segment_number: Some(2),
        ..Default::default()
    },
};

Edge 샤드 닫기 (Close the Edge Shard)

애플리케이션을 종료할 때는 모든 데이터가 디스크에 플러시되도록 Edge 샤드를 닫아 주세요. 데이터는 디스크에 저장되며 Edge 샤드를 다시 여는 데 사용할 수 있어요.

edge_shard.close()

drop(edge_shard);

Edge 샤드를 닫은 후에는 load 메서드로 디스크에서 데이터와 구성을 로드해 다시 열 수 있어요:

edge_shard = EdgeShard.load(SHARD_DIRECTORY)

let edge_shard = EdgeShard::load(Path::new(SHARD_DIRECTORY), None)?;

더 많은 예제 (More Examples)

Qdrant GitHub 저장소에는 Python과 Rust로 Qdrant Edge API를 사용하는 예제가 포함되어 있어요.

더 알아보기 (Learn more)

출처: Qdrant 공식문서 - Quickstart