Data Vektor Qdrant (Poin)

Poin

Poin adalah entitas inti yang dimanipulasi oleh Qdrant. Sebuah poin merupakan catatan yang terdiri dari vektor dan payload opsional.

Anda dapat mencari poin yang dikelompokkan dalam sebuah koleksi berdasarkan kesamaan vektor. Deskripsi lebih detail tentang proses ini disediakan di bagian Pencarian dan Penyaringan.

Bagian ini memperkenalkan bagaimana cara membuat dan mengelola vektor.

Setiap operasi modifikasi pada sebuah poin bersifat asinkron dan terbagi menjadi dua tahap. Pada tahap pertama, operasi akan ditulis ke dalam log tulis-dahulu.

Pada saat ini, bahkan jika mesin kehilangan daya, layanan tidak akan kehilangan data.

Tip: Poin adalah konsep abstrak dalam Qdrant, Anda dapat menganggapnya sebagai baris data dalam tabel MySQL.

Menunggu Hasil

Jika API dipanggil dengan parameter &wait=false, atau tidak secara eksplisit ditentukan, klien akan menerima pesan konfirmasi untuk penerimaan data:

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

Respon ini tidak menjamin pengambilan data secara langsung. Ini menggunakan bentuk konsistensi eventual. Proses aktual pembaruan koleksi mungkin memerlukan waktu. Pada kenyataannya, permintaan ini pada akhirnya mungkin gagal. Jika ingin menyisipkan sejumlah besar vektor, kami juga menyarankan untuk menggunakan permintaan asinkron untuk memanfaatkan operasi pipeline sepenuhnya.

Jika logika aplikasi Anda memerlukan ketersediaan segera setelah respons API, gunakan flag ?wait=true. Dalam hal ini, API akan mengembalikan hasil hanya setelah operasi selesai:

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

ID Poin

Qdrant mendukung penggunaan bilangan bulat tak bertanda 64-bit dan UUID sebagai identifikasi untuk poin.

Contoh representasi string UUID adalah sebagai berikut:

Representasi sederhana: 936DA01F9ABD4d9d80C702AF85C822A8
Representasi dengan tanda hubung: 550e8400-e29b-41d4-a716-446655440000
URN: urn:uuid:F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4

Ini berarti bahwa dalam setiap permintaan, string UUID dapat digunakan sebagai ganti ID numerik. Misalnya:

PUT /collections/{nama_koleksi}/points

{
    "points": [
        {
            "id": "5c56c793-69f3-4fbf-87e6-c4bf54c28c26",
            "payload": {"color": "red"},
            "vector": [0.9, 0.1, 0.1]
        }
    ]
}

dan

PUT /collections/{nama_koleksi}/points

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

keduanya valid.

Mengunggah Titik Data

Untuk mengoptimalkan kinerja, Qdrant mendukung pengunggahan berkelompok dari titik data. Ini berarti Anda dapat memuat beberapa titik data ke dalam layanan dalam satu panggilan API tunggal. Memuat berkelompok dapat secara signifikan mengurangi overhead koneksi jaringan.

API Qdrant mendukung dua metode penciptaan berkelompok - berorientasi rekaman dan berorientasi kolom. Secara internal, opsi-opsi ini tidak dapat dibedakan dan hanya untuk kenyamanan dalam interaksi.

Membuat titik data menggunakan REST API:

PUT /collections/{nama_koleksi}/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]
        ]
    }
}

Atau gunakan metode setara dengan pendekatan berorientasi rekaman:

PUT /collections/{nama_koleksi}/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]
        }
    ]
}

Semua API dalam Qdrant, termasuk pengunggahan titik data, bersifat idempoten. Ini berarti bahwa melakukan metode yang sama secara berurutan sama dengan satu eksekusi tunggal.

Dalam skenario ini, ini berarti bahwa saat mengunggah kembali titik data dengan id yang sama, titik data yang ada akan ditimpa.

Sifat idempoten berguna untuk menggunakan antrean pesan yang tidak memberikan jaminan tepat sekali. Bahkan dalam kasus ini, Qdrant memastikan konsistensi data.

Tersedia sejak v0.10.0

Jika koleksi yang sedang dibuat memiliki beberapa vektor, Anda dapat memberikan data untuk setiap vektor dengan menamai vektor-vektor tersebut:

PUT /collections/{nama_koleksi}/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]
            }
        }
    ]
}

Tersedia sejak v1.2.0

Vektor-vektor yang diberi nama bersifat opsional. Saat mengunggah titik data, beberapa vektor mungkin diabaikan. Misalnya, Anda dapat mengunggah titik data hanya dengan vektor image dan lainnya hanya dengan vektor text.

Saat memodifikasi titik data dengan ID yang sudah ada, titik data yang ada akan terlebih dahulu dihapus dan kemudian dimasukkan kembali dengan vektor yang ditentukan. Dengan kata lain, seluruh titik data akan digantikan, dan vektor-vektor yang tidak ditentukan akan diset ke nol. Jika Anda ingin menjaga vektor-vektor yang ada tidak berubah dan hanya memperbarui vektor-vektor yang ditentukan, silakan merujuk ke pembaruan vektor.

Memodifikasi Titik Data

Untuk memodifikasi titik data, Anda dapat memodifikasi vektornya atau payload-nya. Ada beberapa metode untuk mencapainya.

Memperbarui Vektor

Tersedia mulai dari versi v1.2.0

Metode ini memperbarui vektor yang spesifik pada titik yang diberikan. Vektor yang tidak ditentukan akan tetap tidak berubah. Semua titik yang diberikan harus ada.

REST API (Schema):

PUT /collections/{nama_koleksi}/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]
            }
        }
    ]
}

Untuk memperbarui titik dan mengganti semua vektor, silakan merujuk ke operasi unggah titik.

Hapus Vektor

Tersedia mulai dari versi v1.2.0

Metode ini hanya menghapus vektor yang spesifik dari titik yang diberikan. Vektor lainnya akan tetap tidak berubah. Titik tidak akan dihapus.

REST API (Schema):

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

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

Atur Payload

Atur nilai payload yang diberikan pada titik-titik.

REST API (Schema):

POST /collections/{nama_koleksi}/points/payload

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

Anda tidak perlu mengetahui id dari titik yang akan dimodifikasi. Cara lain adalah dengan menggunakan penyaring.

POST /collections/{nama_koleksi}/points/payload

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

Ganti Payload

Ganti seluruh payload yang ada dengan payload yang diberikan.

REST API (Schema):

PUT /collections/{nama_koleksi}/points/payload

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

Sama seperti Atur Payload, Anda tidak perlu mengetahui id dari titik yang akan dimodifikasi. Cara lain adalah dengan menggunakan penyaring.

Hapus Kunci Payload

REST API (Schema):

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

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

Atau, Anda bisa menggunakan penyaring untuk menghapus kunci payload dari titik.

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

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

Bersihkan Payload

Metode ini menghapus semua kunci payload dari titik-titik yang spesifik.

REST API (Schema):

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

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

Menghapus Titik-Titik

REST API (Skema):

POST /collections/{collection_name}/points/delete

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

Cara lain untuk menentukan titik-titik yang akan dihapus adalah dengan menggunakan filter:

POST /collections/{collection_name}/points/delete

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

Contoh ini menghapus semua titik dengan { "color": "red" } dari koleksi.

Mengambil Titik-Titik

Metode untuk mengambil titik berdasarkan ID mereka:

REST API (Skema):

POST /collections/{collection_name}/points

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

Metode ini memiliki parameter tambahan with_vectors dan with_payload. Dengan menggunakan parameter ini, Anda dapat memilih bagian dari hasil titik-titik yang Anda butuhkan. Pengkecualian membantu menghindari pemborosan transfer data pada data yang tidak perlu.

Juga mungkin untuk mengambil satu titik melalui API:

REST API (Skema):

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

Scroll

Terkadang diperlukan untuk mengambil semua titik yang tersimpan tanpa mengetahui ID mereka, atau untuk beriterasi melalui titik-titik yang memenuhi kondisi penyaringan.

REST API (Skema):

POST /collections/{collection_name}/points/scroll

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

Mengembalikan semua titik yang cocok dengan color=red:

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

API Scroll akan mengembalikan semua titik yang cocok dengan filter secara berpaginasi.

Semua titik hasil diurutkan berdasarkan ID. Untuk mengambil halaman berikutnya, Anda perlu menentukan ID maksimum yang ditemukan di bidang offset. Untuk kenyamanan, ID ini juga dikembalikan dalam bidang next_page_offset. Jika nilai bidang next_page_offset adalah null, itu berarti halaman terakhir telah tercapai.

Menghitung Titik-Titik

Tersedia mulai dari versi v0.8.4

Terkadang, penting untuk hanya mengetahui berapa banyak titik yang cocok dengan kondisi penyaringan tanpa benar-benar melakukan pencarian.

Misalnya, ini dapat berguna dalam skenario berikut:

Menaksir ukuran hasil untuk pencarian fasit
Menentukan jumlah halaman untuk penomoran
Debugging kecepatan eksekusi query

REST API (Skema):

POST /collections/{collection_name}/points/count

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

Mengembalikan jumlah titik yang cocok dengan kondisi penyaringan yang diberikan:

{
    "count": 3811
}

Pembaruan Massal

Tersedia sejak v1.5.0

Anda dapat melakukan operasi massal pada beberapa titik. Ini termasuk menyisipkan, memperbarui, dan menghapus titik, vektor, dan muatan.

Permintaan pembaruan massal terdiri dari serangkaian operasi yang dieksekusi secara berurutan. Operasi yang dapat dijadwalkan termasuk:

Menyisipkan atau memperbarui titik: upsert atau UpsertOperation
Menghapus titik: delete_points atau DeleteOperation
Memperbarui vektor: update_vectors atau UpdateVectorsOperation
Menghapus vektor: delete_vectors atau DeleteVectorsOperation
Menetapkan muatan: set_payload atau SetPayloadOperation
Menimpa muatan: overwrite_payload atau OverwritePayload
Menghapus muatan: delete_payload atau DeletePayloadOperation
Menghapus muatan: clear_payload atau ClearPayloadOperation

Potongan kode contoh berikut menggunakan semua operasi.

REST API (Skema):

POST /collections/{nama_koleksi}/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]}}
    ]
}

Untuk menggunakan titik batch dengan satu jenis operasi, gunakan fitur batch langsung dalam operasi tersebut.

Poin

Menunggu Hasil

ID Poin

Mengunggah Titik Data

Memodifikasi Titik Data

Memperbarui Vektor

Hapus Vektor

Atur Payload

Ganti Payload

Hapus Kunci Payload

Bersihkan Payload

Menghapus Titik-Titik

Mengambil Titik-Titik

Scroll

Menghitung Titik-Titik

Pembaruan Massal

Tutorial Terkait