Qdrant Vektör Verisi (Noktalar)

Noktalar

Noktalar, Qdrant tarafından işlenen temel varlıklardır. Bir nokta, bir vektör ve isteğe bağlı bir yük verisinden oluşan bir kayıttır.

Vektör benzerliğine göre gruplandırılmış noktaları bir koleksiyonda arayabilirsiniz. İşlemin daha detaylı bir açıklaması, Arama ve Filtreleme bölümünde verilmektedir.

Bu bölüm, vektörlerin nasıl oluşturulacağını ve yönetileceğini tanıtır.

Bir noktada yapılan herhangi bir değiştirme işlemi asenkron olarak gerçekleşir ve iki aşamalıdır. İlk aşamada, işlem, bir önceden yazma günlüğüne yazılacaktır.

Bu anda makine güç kaybetsa dahi, hizmet veri kaybetmeyecektir.

İpucu: Noktalar, Qdrant'ta soyut bir kavramdır, onları bir MySQL tablosundaki veri satırı olarak düşünebilirsiniz.

Sonuç Bekleniyor

Eğer API, &wait=false parametresi ile çağrılırsa veya açık bir şekilde belirtilmezse, istemci veri alımı için bir onay mesajı alacaktır:

{
    "result": {
        "operation_id": 123,
        "status": "acknowledged"
    },
    "status": "ok",
    "time": 0.000206061
}

Bu yanıt, verilerin hemen alınmasını garanti etmemektedir. Olaysal tutarlılık biçimini kullanır. Koleksiyonun güncellenmesi sürecinde bazı zaman alabilir. Gerçekte, bu istek nihayetinde başarısız olabilir. Büyük sayıda vektör eklemek gerekiyorsa, boru hattı işlemlerini tam olarak kullanmak için asenkron istemleri kullanmanızı da öneririz.

Eğer uygulama mantığınız, API yanıtından hemen sonra arama için anında kullanılabilirlik gerektiriyorsa, ?wait=true işaretini kullanın. Bu durumda, API yalnızca işlem tamamlandıktan sonra sonucu döndürecektir:

{
    "result": {
        "operation_id": 0,
        "status": "completed"
    },
    "status": "ok",
    "time": 0.000206061
}

Nokta Kimliği

Qdrant, noktalar için 64-bit işaretli tam sayılar ve UUID'leri tanımlayıcı olarak destekler.

UUID dizesi temsillerinin örnekleri aşağıda verilmiştir:

Basit temsil: 936DA01F9ABD4d9d80C702AF85C822A8
Çizgisiz temsil: 550e8400-e29b-41d4-a716-446655440000
URN: urn:uuid:F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4

Bu, her istekte, sayısal kimlikler yerine UUID dizelerinin kullanılabileceği anlamına gelmektedir. Örneğin:

PUT /collections/{koleksiyon_adı}/noktalar

{
    "noktalar": [
        {
            "id": "5c56c793-69f3-4fbf-87e6-c4bf54c28c26",
            "payload": {"renk": "kırmızı"},
            "vektör": [0.9, 0.1, 0.1]
        }
    ]
}

PUT /collections/{koleksiyon_adı}/noktalar

{
    "noktalar": [
        {
            "id": 1,
            "payload": {"renk": "kırmızı"},
            "vektör": [0.9, 0.1, 0.1]
        }
    ]
}

her ikisi de geçerlidir.

Veri Noktalarını Yükleme

Performansı optimize etmek için Qdrant, veri noktalarının toplu yükleme işlemini destekler. Bu, tek bir API çağrısı içinde hizmete birden fazla veri noktası yükleyebileceğiniz anlamına gelir. Toplu yükleme, ağ bağlantılarının getirdiği harici yükü önemli ölçüde azaltabilir.

Qdrant API'si iki toplu oluşturma yöntemini destekler - kayıt odaklı ve sütun odaklı. Dahili olarak, bu seçenekler ayırt edilemez ve sadece etkileşim kolaylığı için vardır.

REST API aracılığıyla veri noktaları oluşturma:

PUT /collections/{collection_name}/points

{
    "batch": {
        "ids": [1, 2, 3],
        "payloads": [
            {"color": "red"},
            {"color": "green"},
            {"color": "blue"}
        ],
        "vectors": [
            [0.9, 0.1, 0.1],
            [0.1, 0.9, 0.1],
            [0.1, 0.1, 0.9]
        ]
    }
}

Veya kayıt odaklı yaklaşım kullanarak eşdeğer yöntemi kullanın:

PUT /collections/{collection_name}/points

{
    "points": [
        {
            "id": 1,
            "payload": {"color": "red"},
            "vector": [0.9, 0.1, 0.1]
        },
        {
            "id": 2,
            "payload": {"color": "green"},
            "vector": [0.1, 0.9, 0.1]
        },
        {
            "id": 3,
            "payload": {"color": "blue"},
            "vector": [0.1, 0.1, 0.9]
        }
    ]
}

Qdrant'taki tüm API'ler, veri noktası yükleme de dahil olmak üzere idempotenttir. Bu, aynı yöntemi ardışık olarak gerçekleştirmek, tek bir yürütmeyle eşdeğerdir.

Bu senaryoda, aynı kimliğe sahip veri noktalarını tekrar yüklediğinizde, mevcut veri noktaları üzerine yazılacaktır.

İdempotent özelliği, kesin bir tek seferlik garanti sunmayan mesaj kuyruklarını kullanmak için kullanışlıdır. Hatta bu durumda bile, Qdrant veri tutarlılığını sağlar.

V0.10.0 sürümünden itibaren mevcuttur

Oluşturulacak bir koleksiyonda birden fazla vektör bulunuyorsa, her bir vektör için veri sağlayabilirsiniz:

PUT /collections/{collection_name}/points

{
    "points": [
        {
            "id": 1,
            "vector": {
                "image": [0.9, 0.1, 0.1, 0.2],
                "text": [0.4, 0.7, 0.1, 0.8, 0.1, 0.1, 0.9, 0.2]
            }
        },
        {
            "id": 2,
            "vector": {
                "image": [0.2, 0.1, 0.3, 0.9],
                "text": [0.5, 0.2, 0.7, 0.4, 0.7, 0.2, 0.3, 0.9]
            }
        }
    ]
}

V1.2.0 sürümünden itibaren mevcuttur

İsimlendirilmiş vektörler isteğe bağlıdır. Veri noktalarını yüklerken bazı vektörler atlanabilir. Örneğin, yalnızca "görüntü" vektörü olan bir veri noktasını yükleyebilir ve yalnızca "metin" vektörü olan başka bir veri noktasını yükleyebilirsiniz.

Mevcut bir kimliğe sahip bir veri noktasını değiştirirken, mevcut veri noktası önce silinir ve ardından belirtilen vektörle yeniden eklenir. Başka bir deyişle, tüm veri noktası değiştirilecek ve belirtilmeyen vektörler null olarak ayarlanacaktır. Mevcut vektörleri değiştirmeden yalnızca belirtilen vektörleri güncellemek istiyorsanız, lütfen vektörleri güncelleme bölümüne bakınız.

Veri Noktalarını Değiştirme

Bir veri noktasını değiştirmek için, vektörünü veya veri paylaşımlarını değiştirebilirsiniz. Bunun için birkaç yöntem bulunmaktadır.

Vektörleri Güncelleme

Versiyon v1.2.0'dan itibaren kullanılabilir

Bu metod, belirtilen noktalardaki vektörleri günceller. Belirtilmeyen vektörler değişmeyecektir. Verilen tüm noktaların var olduğundan emin olunmalıdır.

REST API (Schema):

PUT /collections/{collection_name}/points/vectors

{
    "points": [
        {
            "id": 1,
            "vector": {
                "image": [0.1, 0.2, 0.3, 0.4]
            }
        },
        {
            "id": 2,
            "vector": {
                "text": [0.9, 0.8, 0.7, 0.6, 0.5, 0.4, 0.3, 0.2]
            }
        }
    ]
}

Noktaları güncellemek ve tüm vektörleri değiştirmek için lütfen yükleme işlemine başvurun.

Vektörleri Silme

Versiyon v1.2.0'dan itibaren kullanılabilir

Bu metod, yalnızca belirtilen vektörleri belirtilen noktalardan siler. Diğer vektörler değişmeyecektir. Noktalar silinmeyecektir.

REST API (Schema):

POST /collections/{collection_name}/points/vectors/delete

{
    "points": [0, 3, 100],
    "vectors": ["text", "image"]
}

Payload Ayarlama

Verilen payload değerlerini noktalara ayarlayın.

REST API (Schema):

POST /collections/{collection_name}/points/payload

{
    "payload": {
        "property1": "string",
        "property2": "string"
    },
    "points": [
        0, 3, 100
    ]
}

Değiştirilecek noktanın kimliğini bilmek gerekli değildir. Başka bir yol da filtreleri kullanmaktır.

POST /collections/{collection_name}/points/payload

{
    "payload": {
        "property1": "string",
        "property2": "string"
    },
    "filter": {
        "must": [
            {
                "key": "color",
                "match": {
                    "value": "red"
                }
            }
        ]
    }
}

Payload Üzerine Yazma

Mevcut payload'ı verilen payload ile tamamen değiştirin.

REST API (Schema):

PUT /collections/{collection_name}/points/payload

{
    "payload": {
        "property1": "string",
        "property2": "string"
    },
    "points": [
        0, 3, 100
    ]
}

Payload Ayarlama ile benzer şekilde, değiştirilecek noktanın kimliğini bilmek gerekli değildir. Başka bir yol da filtreleri kullanmaktır.

Payload Anahtarlarını Silme

REST API (Schema):

POST /collections/{collection_name}/points/payload/delete

{
    "keys": ["color", "price"],
    "points": [0, 3, 100]
}

Alternatif olarak, noktalardan payload anahtarlarını silmek için filtreleri kullanabilirsiniz.

POST /collections/{collection_name}/points/payload/delete

{
    "keys": ["color", "price"],
    "filter": {
        "must": [
            {
                "key": "color",
                "match": {
                    "value": "red"
                }
            }
        ]
    }
}

Payload Temizleme

Bu metod, belirtilen noktalardan tüm payload anahtarlarını kaldırır.

REST API (Schema):

POST /collections/{collection_name}/points/payload/clear

{
    "points": [0, 3, 100]
}

Noktaları Silme

REST API (Şema):

POST /collections/{collection_name}/points/delete

{
    "points": [0, 3, 100]
}

Silinecek noktaları belirtmenin başka bir yolu da filtreyi kullanmaktır:

POST /collections/{collection_name}/points/delete

{
    "filter": {
        "must": [
            {
                "key": "color",
                "match": {
                    "value": "red"
                }
            }
        ]
    }
}

Bu örnek koleksiyondan { "color": "red" } özelliğine sahip tüm noktaları siler.

Noktaları Getirme

ID'lerine göre noktaları almak için yöntem:

REST API (Şema):

POST /collections/{collection_name}/points

{
    "ids": [0, 3, 100]
}

Bu yöntemin with_vectors ve with_payload adında ek parametreleri bulunmaktadır. Bu parametreleri kullanarak ihtiyacınız olan nokta sonuçlarının bölümlerini seçebilirsiniz. Dışarda bırakılarak gereksiz veri transferi önlenmiş olur.

API üzerinden tek bir noktayı almak da mümkündür:

REST API (Şema):

GET /collections/{collection_name}/points/{point_id}

Kaydırma

Bazı durumlarda, ID'lerini bilmeden tüm depolanan noktaları almak veya filtreleme koşullarını karşılayan noktalar arasında dolaşmak gereklidir.

REST API (Şema):

POST /collections/{collection_name}/points/scroll

{
    "filter": {
        "must": [
            {
                "key": "color",
                "match": {
                    "value": "red"
                }
            }
        ]
    },
    "limit": 1,
    "with_payload": true,
    "with_vector": false
}

color=red eşleşen tüm noktaları döndürür:

{
    "result": {
        "next_page_offset": 1,
        "points": [
            {
                "id": 0,
                "payload": {
                    "color": "red"
                }
            }
        ]
    },
    "status": "ok",
    "time": 0.0001
}

Kaydırma API, filtreyle eşleşen tüm noktaları sayfalı olarak döndürür.

Tüm sonuç noktalar ID'ye göre sıralanmıştır. Bir sonraki sayfayı sorgulamak için, offset alanına en büyük keşfedilmiş ID'yi belirtmeniz gerekir. Kolaylık sağlamak için bu ID aynı zamanda next_page_offset alanında da döndürülür. next_page_offset alanının değeri null ise, son sayfaya ulaşıldığı anlamına gelir.

Noktaları Sayma

V0.8.4 sürümünden itibaren kullanılabilir

Bazı durumlarda, sorgu gerçekleştirme olmaksızın filtrelendirme koşullarına uyan noktaların sayısını bilmek faydalı olabilir.

Örneğin, bu durumlar şunlardır:

Fasetli arama için sonuç boyutunu tahmin etme
Sayfalama için sayfa sayısını belirleme
Sorgu yürütme hızını hata ayıklama

REST API (Şema):

POST /collections/{collection_name}/points/count

{
    "filter": {
        "must": [
            {
                "key": "color",
                "match": {
                    "value": "red"
                }
            }
        ]
    },
    "exact": true
}

Verilen filtrelendirme koşullarına uyan noktaların sayısını döndürür:

{
    "count": 3811
}

Toplu Güncelleme

V1.5.0'dan itibaren kullanılabilir

Birden fazla noktada toplu işlemler gerçekleştirebilirsiniz. Bu işlemler arasında noktaları, vektörleri ve yükleri ekleme, güncelleme ve silme işlemleri bulunmaktadır.

Toplu güncelleme isteği, sıralı olarak yürütülen bir dizi işlemden oluşur. Toplu işleme tabi tutulabilecek işlemler şunları içerir:

Noktaları ekle veya güncelle: upsert veya UpsertOperation
Noktaları sil: delete_points veya DeleteOperation
Vektörleri güncelle: update_vectors veya UpdateVectorsOperation
Vektörleri sil: delete_vectors veya DeleteVectorsOperation
Yükü ayarla: set_payload veya SetPayloadOperation
Yükü üzerine yaz: overwrite_payload veya OverwritePayload
Yükü sil: delete_payload veya DeletePayloadOperation
Yükü temizle: clear_payload veya ClearPayloadOperation

Aşağıdaki örnek kod parçacığı tüm işlemleri kullanmaktadır.

REST API (Şema):

POST /collections/{collection_name}/points/batch

{
    "operations": [
        {
            "upsert": {
                "points": [
                    {
                        "id": 1,
                        "vector": [1.0, 2.0, 3.0, 4.0],
                        "payload": {}
                    }
                ]
            }
        },
        {
            "update_vectors": {
                "points": [
                    {
                        "id": 1,
                        "vector": [1.0, 2.0, 3.0, 4.0]
                    }
                ]
            }
        },
        {
            "delete_vectors": {
                "points": [1],
                "vector": [""]
            }
        },
        {
            "overwrite_payload": {
                "payload": {
                    "test_payload": "1"
                },
                "points": [1]
            }
        },
        {
            "set_payload": {
                "payload": {
                    "test_payload_2": "2",
                    "test_payload_3": "3"
                },
                "points": [1]
            }
        },
        {
            "delete_payload": {
                "keys": ["test_payload_2"],
                "points": [1]
            }
        },
        {
            "clear_payload": {
                "points": [1]
            }
        },
        {"delete": {"points": [1]}}
    ]
}

Yalnızca tek bir türde işlemle toplu işlem yapmak için, o işlem içinde doğrudan toplu özelliğini kullanabilirsiniz.

Noktalar

Sonuç Bekleniyor

Nokta Kimliği

Veri Noktalarını Yükleme

Veri Noktalarını Değiştirme

Vektörleri Güncelleme

Vektörleri Silme

Payload Ayarlama

Payload Üzerine Yazma

Payload Anahtarlarını Silme

Payload Temizleme

Noktaları Silme

Noktaları Getirme

Kaydırma

Noktaları Sayma

Toplu Güncelleme

İlgili Rehberler