بيانات النقاط الاتجاهية لـ Qdrant

النقاط

النقاط هي الكيانات الأساسية التي تتلاعب بها Qdrant. النقطة هي سجل يتكون من متجه وحمولة اختيارية.

يمكنك البحث عن النقاط المجمعة في مجموعة استنادًا إلى تشابه المتجه. يتم توفير وصف أكثر تفصيلاً للعملية في قسم البحث والتصفية.

يقدم هذا القسم كيفية إنشاء وإدارة المتجهات.

أي عملية تعديل على نقطة هي غير مزامنة ومقسمة إلى خطوتين. في المرحلة الأولى ، سيتم كتابة العملية في سجل الكتابة المُسبقة.

في هذه اللحظة، وحتى إذا فقدت الجهاز الطاقة، لن تفقد الخدمة البيانات.

نصيحة: النقاط هي مفهوم مجرد في Qdrant، يمكنك التفكير فيها كصف من البيانات في جدول MySQL.

في انتظار النتائج

إذا تم استدعاء الواجه البرمجية مع المعلمة &انتظر=خطأ أو لم يتم تحديدها بشكل صريح، سيتلقى العميل رسالة تأكيد استلام البيانات:

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

هذا الرد لا يضمن استرجاع البيانات على الفور. إنه يستخدم نوعًا من التناسق النهائي. قد يستغرق بعض الوقت أثناء عملية تحديث المجموعة الفعلية. في الواقع، قد تفشل هذا الطلب في النهاية. إذا كنت تقوم بإدراج عدد كبير من المتجهات، فإننا نوصي أيضًا باستخدام الطلبات غير المتزامنة للاستفادة الكاملة من عمليات الخطوط الأنابيبية.

إذا كانت منطق التطبيق الخاص بك يتطلب التوافر الفوري للبحث بعد استجابة الواجه البرمجية، استخدم علامة ?انتظر=صحيح. في هذه الحالة، ستعيد الواجه البرمجية النتيجة فقط بعد اكتمال العملية:

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

هوية النقطة

يدعم Qdrant استخدام الأعداد الصحيحة غير المُوقعة بـ 64 بت و UUIDs كمعرفات للنقاط.

أمثلة على تمثيلات سلسلة 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 طريقتين لإنشاء دفعة - موجهة نحو السجل وموجهة نحو العمود. داخلياً، هذه الخيارات لا تميز بينها وتكون ببساطة للراحة في التفاعل.

إنشاء نقاط البيانات باستخدام واجهة برمجة التطبيقات (API) REST:

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

جميع واجهات برمجة التطبيقات في Qdrant، بما في ذلك تحميل نقاط البيانات، يمكن أن تكون متسامية. هذا يعني أن تنفيذ نفس الطريقة على التوالي مكافئ لتنفيذ وحيد.

في هذ scenarizo، هذا يعني أن عند إعادة تحميل نقاط البيانات بنفس المعرف، سيتم الكتابة على نقاط البيانات الحالية.

يعتبر خصائص السامي مناسبًا لاستخدام طوابير الرسائل التي لا توفر ضمانات دقيقة لمرة واحدة فقط. حتى في هذه الحالة، يضمن 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.

عند تعديل نقطة بيانات باستخدام معرف موجود، يتم حذف النقطة البيانية الحالية أولاً ثم يتم إعادة إدخالها مع النقطة المحددة. بمعنى آخر، سيتم استبدال النقطة البيانية بأكملها، وسيتم تعيين أي نقاط غير المحددة إلى القيمة الفارغة. إذا كنت ترغب في الاحتفاظ بالنقاط البيانية الحالية بدون تغيير وتحديث النقاط المحددة فقط، يرجى الرجوع إلى تحديث النقاط.

تعديل نقاط البيانات

لتعديل نقطة البيانات، يمكنك تعديل نقطتها البيانية أو تحميلها. هناك عدة طرق لتحقيق ذلك.

تحديث الفيكتورات

متوفر من الإصدار 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. باستخدام هذه المعلمات، يمكنك تحديد أجزاء نتائج النقاط التي تحتاج إليها. يساعد الاستبعاد في تجنب إهدار نقل البيانات على بيانات غير مفيدة.

كما يمكن استرجاع نقطة واحدة عبر واجهة برمجة التطبيقات:

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
}

سيقوم واجهة برمجة التطبيقات Scroll بإرجاع جميع النقاط التي تتوافق مع التصفية بطريقة مقسمة إلى صفحات.

يتم فرز جميع النقاط الناتجة حسب الهوية. للاستعلام عن الصفحة التالية، يجب تحديد الهوية القصوى التي تم اكتشافها في حقل 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 (المخطط):

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

لاستخدام عمليات النقاط بدفعة واحدة من نوع واحد، استخدم ميزة الدفعة مباشرةً داخل تلك العملية.