داده‌های برداری کیودرانت (نقاط)

امتیازها

امتیازها موجودیت‌های اصلی‌ای هستند که توسط Qdrant کنترل می‌شوند. یک امتیاز یک رکورد است که از یک بردار و یک بارگذاری اختیاری تشکیل شده است.

شما می‌توانید براساس شباهت بردارها برای امتیازها در یک مجموعه جستجو کنید. توضیحات دقیق‌تر این فرایند در بخش جستجو و فیلتر مشخص شده است.

این بخش، چگونگی ایجاد و مدیریت بردارها را معرفی می‌کند.

هر عملیات تغییر در یک امتیاز به صورت ناهمزمان است و به دو مرحله تقسیم می‌شود. در مرحله اول، عملیات به یک log write-ahead نوشته می‌شود.

در این لحظه، حتی اگر دستگاه قدرت را از دست بدهد، سرویس داده‌ای خود را از دست نخواهد داد.

نکته: امتیازها یک مفهوم انتزاعی در Qdrant هستند، می‌توانید به آن‌ها به عنوان یک ردیف داده در یک جدول MySQL فکر کنید.

انتظار نتایج

اگر API با پارامتر &wait=false فراخوانی شود یا به صورت صریح مشخص نشود، مشتری پیام تأیید دریافت داده‌ای خواهد گرفت:

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

این پاسخ تضمین‌کننده بازیابی فوری داده نیست. از یک شکل از سازگاری محتمل استفاده می‌کند. ممکن است مدتی طول بکشد تا فرایند واقعی به‌روزرسانی مجموعه انجام شود. در واقع، این درخواست در نهایت ممکن است شکست بخورد. اگر درج یک تعداد بزرگی از بردارها نیاز دارید، ما همچنین پیشنهاد می‌دهیم که از فراخوانی‌های ناهمزمان برای به‌طور کامل بهره بردن از عملیات خطوط لوله استفاده کنید.

اگر منطق برنامه شما نیاز به دسترسی فوری برای جستجو پس از پاسخ API دارد، از پرچم ?wait=true استفاده کنید. در این صورت، API تنها پس از اتمام عملیات نتیجه را باز می‌گرداند:

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

شناسه امتیاز

Qdrant از اعداد صحیح بدون علامت 64 بیتی و UUIDها به عنوان شناسه برای امتیازها پشتیبانی می‌کند.

نمونه‌های نمایش رشته UUID به صورت زیر هستند:

• نمایش ساده: 936DA01F9ABD4d9d80C702AF85C822A8
• نمایش دارای خط: 550e8400-e29b-41d4-a716-446655440000
• URN: urn:uuid:F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4

این بدان معنی است که در هر درخواست، رشته‌های UUID می‌توانند به‌جای شناسه‌های عددی استفاده شوند. به عنوان مثال:

PUT /collections/{collection_name}/points

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

و

PUT /collections/{collection_name}/points

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

هر دو معتبر هستند.

بارگذاری نقاط داده‌ای

برای بهینه‌سازی عملکرد، Qdrant از بارگذاری دسته‌ای نقاط داده پشتیبانی می‌کند. این بدان معنی است که شما می‌توانید چندین نقطه داده را در یک تماس API واحد به سرویس بارگذاری کنید. بارگذاری دسته‌ای می‌تواند هزینه اتصال شبکه را به طور قابل توجهی کاهش دهد.

API Qdrant از دو روش ایجاد دسته‌ای پشتیبانی می‌کند - گراه گراه بر پایه نقاط داده و ستون گراه. در داخل، این گزینه‌ها قابل تشخیص نیستند و فقط برای راحتی در تعامل هستند.

ایجاد نقاط داده با استفاده از REST API:

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]
        ]
    }
}

یا از روش معادل استفاده کنید که بر پایه نقاط داده آن را انتخاب کنید:

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]
        }
    ]
}

تمام روش‌های API ها در Qdrant، از جمله بارگذاری نقطه داده، همگن هستند. این بدان معنی است که انجام یک روش مشابه به صورت متوالی، معادل یک اجرای تکی است.

در این سناریو، این بدان معنی است که هنگام بارگذاری مجدد نقاط داده با id یکسان، نقاط داده موجود بازنویسی خواهند شد.

ویژگی همگن بودن برای استفاده از صف‌های پیامی که ضمانت دقیق یکبار برای همیشه را ارائه نمی‌دهند، مفید است. حتی در این صورت، Qdrant از همسانی داده اطمینان حاصل می‌کند.

در دسترس از نسخه v0.10.0

اگر یک مجموعه ایجاد شده دارای چند بردار باشد، شما می‌توانید برای هر بردار داده مربوطه را با نام بردارها فراهم کنید:

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

بردارهای نامگذاری شده اختیاری هستند. هنگام بارگذاری نقاط داده، برخی از بردارها ممکن است حذف شوند. به عنوان مثال، می‌توانید یک نقطه داده را با تنها بردار image و یکی دیگر را با تنها بردار text بارگذاری کنید.

هنگام اصلاح نقطه داده با یک id موجود، نقطه داده موجود ابتدا حذف می‌شود و سپس با بردار مشخص شده دوباره درج می‌شود. به عبارت دیگر، نقطه داده کلی جایگزین خواهد شد و هر بردار مشخص نشده به null تنظیم خواهد شد. اگر می‌خواهید بردارهای موجود را بدون تغییر نگه دارید و فقط بردارهای مشخص شده را به‌روز کنید، لطفاً به به‌روزرسانی بردارها مراجعه کنید.

اصلاح نقاط داده

برای اصلاح یک نقطه داده، می‌توانید بردار یا بار خود را تغییر دهید. چندین روش برای رسیدن به این هدف وجود دارد.

به‌روزرسانی بردارها

قابل دسترسی از نسخه v1.2.0

این متد، بردارهای مشخص شده را در نقاط داده شده به‌روزرسانی می‌کند. بردارهای مشخص نشده بدون تغییر باقی خواهند ماند. تمام نقاط داده شده باید وجود داشته باشند.

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]
            }
        }
    ]
}

برای به‌روزرسانی نقاط و جایگزینی تمام بردارها، لطفا به عملیات بارگذاری نقطه مراجعه کنید.

حذف بردارها

قابل دسترسی از نسخه v1.2.0

این متد تنها بردارهای مشخص شده را از نقاط داده شده حذف می‌کند. سایر بردارها بدون تغییر باقی خواهند ماند. نقاط داده شده حذف نخواهند شد.

REST API (Schema):

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

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

تنظیم داده

تنظیم مقادیر داده داده شده در نقاط.

REST API (Schema):

POST /collections/{collection_name}/points/payload

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

شما نیازی به شناسه نقطه برای تغییر دادن ندارید. یک راه دیگر استفاده از فیلترها است.

POST /collections/{collection_name}/points/payload

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

جایگزینی داده

جایگزینی کامل داده موجود با داده داده شده.

REST API (Schema):

PUT /collections/{collection_name}/points/payload

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

مشابه تنظیم داده، شما نیازی به شناسه نقطه برای تغییر دادن ندارید. یک راه دیگر استفاده از فیلترها است.

حذف کلیدهای داده

REST API (Schema):

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

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

در صورت تمایل، می‌توانید از فیلترها برای حذف کلیدهای داده از نقاط استفاده کنید.

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

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

پاکسازی داده

این متد تمام کلیدهای داده را از نقاط مشخص شده حذف می‌کند.

REST API (Schema):

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

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

حذف نقاط

REST API (اسکیما):

POST /collections/{collection_name}/points/delete

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

روش دیگری برای مشخص کردن نقاطی که باید حذف شوند، استفاده از فیلتر است:

POST /collections/{collection_name}/points/delete

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

این مثال تمام نقاط با { "color": "red" } از مجموعه را حذف می‌کند.

بازیابی نقاط

روش برای بازیابی نقاط بر اساس شناسه‌های آن‌ها:

REST API (اسکیما):

POST /collections/{collection_name}/points

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

این روش دارای پارامترهای اضافی with_vectors و with_payload می‌باشد. با استفاده از این پارامترها می‌توانید بخش‌های مورد نیاز نتایج نقاط را انتخاب کنید. استثنا زدن کمک می‌کند تا از تلفات انتقال داده برای داده‌های بی‌هوده جلوگیری شود.

همچنین امکان بازیابی یک نقطه تکی از طریق API وجود دارد:

REST API (اسکیما):

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

پیمایش

گاهی اوقات لازم است تا تمام نقاط ذخیره شده را بدون دانستن شناسه‌های آن‌ها بازیابی کنیم، یا از طریق شرایط فیلتر کردن نقاطی که منطبق هستند را پیمایش کنیم.

REST API (اسکیما):

POST /collections/{collection_name}/points/scroll

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

تمام نقاطی که مطابق با color=red هستند را برمی‌گرداند:

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

API پیمایش تمام نقاطی را که با فیلتر مطابقت دارند به صورت صفحه بندی شده برمی‌گرداند.

تمام نقاط حاصله بر اساس شناسه مرتب می‌شوند. برای پرس‌وجوی صفحه بعد، نیاز است تا حداکثر شناسه کشف‌شده را در فیلد offset مشخص کنید. برای راحتی، این شناسه همچنین در فیلد next_page_offset برگردانده می‌شود. اگر مقدار فیلد next_page_offset null باشد، به این معنی است که آخرین صفحه رسیده است.

شمارش نقاط

در دسترس از نسخه v0.8.4

گاهی اوقات، مفید است که فقط تعداد نقاطی که با شرایط فیلتر مطابقت دارند را بدون انجام واقعی جستجو بدانیم.

به عنوان مثال، این می‌تواند در حالت‌های زیر مفید باشد:

• تخمین اندازه نتایج برای جستجوی دسته‌ای
• تعیین تعداد صفحات برای صفحه بندی
• اشکال‌زدایی سرعت اجرای پرس‌وجو

REST API (اسکیما):

POST /collections/{collection_name}/points/count

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

تعداد نقاطی که با شرایط فیلتر مطابقت دارند را برمی‌گرداند:

{
    "count": 3811
}

به‌روزرسانی دسته‌ای

قابل دسترس در نسخه v1.5.0

شما می‌توانید عملیات دسته‌ای روی چندین نقطه انجام دهید. این شامل درج، به‌روزرسانی و حذف نقاط، بردارها و بارها می‌شود.

یک درخواست به‌روزرسانی دسته‌ای شامل یک سری عملیات است که به ترتیب اجرا می‌شوند. عملیات‌های قابل انجام به صورت دسته‌ای عبارتند از:

• درج یا به‌روزرسانی نقاط: upsert یا UpsertOperation
• حذف نقاط: delete_points یا DeleteOperation
• به‌روزرسانی بردارها: update_vectors یا UpdateVectorsOperation
• حذف بردارها: delete_vectors یا DeleteVectorsOperation
• تنظیم بار: set_payload یا SetPayloadOperation
• بازنویسی بار: overwrite_payload یا OverwritePayload
• حذف بار: delete_payload یا DeletePayloadOperation
• پاکسازی بار: clear_payload یا ClearPayloadOperation

قطعه کد زیر به عنوان مثال از همه‌ی عملیات‌ها استفاده می‌کند.

رابط REST (Schema):

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]}}
    ]
}

برای استفاده از نقاط دسته‌ای با یک نوع عملیات، می‌توانید به‌صورت مستقیم از ویژگی دسته‌ای در همان عملیات استفاده کنید.