Qdrant-Vektordaten (Punkte)

Punkte

Punkte sind die zentralen Entitäten, die von Qdrant bearbeitet werden. Ein Punkt ist ein Datensatz, der aus einem Vektor und optionalen Nutzdaten besteht.

Anhand der Vektorsimilarity können Punkte in einer Sammlung gruppiert und durchsucht werden. Eine ausführlichere Beschreibung des Prozesses wird im Abschnitt Suche und Filter bereitgestellt.

Dieser Abschnitt stellt vor, wie Vektoren erstellt und verwaltet werden.

Jede Änderungsoperation an einem Punkt erfolgt asynchron und ist in zwei Schritte unterteilt. In der ersten Phase wird die Operation in ein Write-Ahead Log geschrieben.

In diesem Moment geht auch bei einem Maschinenstromausfall keine Daten verloren.

Tipp: Punkte sind ein abstraktes Konzept in Qdrant, man kann sie sich als Datensatz in einer MySQL-Tabelle vorstellen.

Warten auf Ergebnisse

Wenn die API mit dem Parameter &wait=false aufgerufen wird oder nicht explizit angegeben ist, erhält der Client eine Bestätigungsmeldung für den Empfang der Daten:

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

Diese Antwort garantiert keine sofortige Rückgabe der Daten. Es wird eine Form von eventueller Konsistenz verwendet. Es kann einige Zeit dauern, bis die tatsächliche Aktualisierung der Sammlung erfolgt. In der Realität kann dieser Vorgang letztendlich fehlschlagen. Wenn eine große Anzahl von Vektoren eingefügt wird, empfehlen wir außerdem die Verwendung asynchroner Anfragen, um Pipeline-Operationen voll auszunutzen.

Wenn die Anwendungslogik sofortige Verfügbarkeit für die Suche nach der API-Antwort erfordert, verwenden Sie das Flag ?wait=true. In diesem Fall gibt die API das Ergebnis erst zurück, nachdem die Operation abgeschlossen ist:

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

Punkt-ID

Qdrant unterstützt die Verwendung von 64-Bit-Unsigned-Integers und UUIDs als Identifikatoren für Punkte.

Beispiele für die Zeichenkettenrepräsentation von UUIDs sind wie folgt:

Einfache Repräsentation: 936DA01F9ABD4d9d80C702AF85C822A8
Bindestrichrepräsentation: 550e8400-e29b-41d4-a716-446655440000
URN: urn:uuid:F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4

Daher können in jeder Anfrage UUID-Zeichenketten anstelle von numerischen IDs verwendet werden. Zum Beispiel:

PUT /collections/{collection_name}/points

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

und

PUT /collections/{collection_name}/points

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

sind beide gültig.

Hochladen von Datenpunkten

Um die Leistung zu optimieren, unterstützt Qdrant das stapelweise Laden von Datenpunkten. Das bedeutet, dass Sie mehrere Datenpunkte mit einem einzigen API-Aufruf in den Service laden können. Das stapelweise Laden kann erheblich die Netzwerkverbindungskosten reduzieren.

Die Qdrant-API unterstützt zwei Methoden zur Stapelerstellung - eine records-orientierte und eine spaltenorientierte Methode. Intern sind diese Optionen nicht unterscheidbar und dienen lediglich zur Bequemlichkeit bei der Interaktion.

Erstellen von Datenpunkten mit der 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]
        ]
    }
}

Oder verwenden Sie die äquivalente Methode mit dem records-orientierten Ansatz:

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

Alle APIs in Qdrant, einschließlich des Ladens von Datenpunkten, sind idempotent. Das bedeutet, dass die aufeinanderfolgende Ausführung derselben Methode äquivalent zu einer einzelnen Ausführung ist.

In diesem Szenario bedeutet dies, dass beim erneuten Hochladen von Datenpunkten mit derselben ID die vorhandenen Datenpunkte überschrieben werden.

Die Idempotenz-Eigenschaft ist nützlich für die Verwendung von Nachrichtenwarteschlangen, die keine präzisen Einmal-Garantien bieten. Auch in diesem Fall gewährleistet Qdrant Datenkonsistenz.

Verfügbar seit v0.10.0

Wenn eine erstellte Sammlung mehrere Vektoren hat, können Sie Daten für jeden Vektor bereitstellen, indem Sie die Vektoren benennen:

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

Verfügbar seit v1.2.0

Benannte Vektoren sind optional. Beim Hochladen von Datenpunkten können einige Vektoren weggelassen werden. Sie können beispielsweise einen Datenpunkt nur mit dem image-Vektor und einen anderen nur mit dem text-Vektor hochladen.

Bei der Änderung eines Datenpunkts mit einer vorhandenen ID wird der vorhandene Datenpunkt zuerst gelöscht und dann mit dem angegebenen Vektor neu eingefügt. Mit anderen Worten, der gesamte Datenpunkt wird ersetzt und alle nicht spezifizierten Vektoren werden auf null gesetzt. Wenn Sie vorhandene Vektoren unverändert lassen und nur spezifizierte Vektoren aktualisieren möchten, beachten Sie bitte die Aktualisierung von Vektoren.

Ändern von Datenpunkten

Um einen Datenpunkt zu ändern, können Sie seinen Vektor oder seine Nutzlast ändern. Dafür gibt es mehrere Methoden.

Vektoren aktualisieren

Verfügbar ab Version v1.2.0

Diese Methode aktualisiert die angegebenen Vektoren an den angegebenen Punkten. Die nicht angegebenen Vektoren bleiben unverändert. Alle angegebenen Punkte müssen vorhanden sein.

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

Um Punkte zu aktualisieren und alle Vektoren zu ersetzen, siehe die "Upload Point" Operation.

Vektoren löschen

Verfügbar ab Version v1.2.0

Diese Methode löscht nur die angegebenen Vektoren von den angegebenen Punkten. Andere Vektoren bleiben unverändert. Die Punkte werden nicht gelöscht.

REST-API (Schema):

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

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

Nutzlast festlegen

Setzen Sie die angegebenen Nutzlastwerte auf Punkte.

REST-API (Schema):

POST /collections/{collection_name}/points/payload

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

Sie müssen die ID des zu ändernden Punktes nicht kennen. Eine andere Möglichkeit ist die Verwendung von Filtern.

POST /collections/{collection_name}/points/payload

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

Nutzlast überschreiben

Ersetzen Sie die vorhandene Nutzlast vollständig durch die angegebene Nutzlast.

REST-API (Schema):

PUT /collections/{collection_name}/points/payload

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

Ähnlich wie Set Payload müssen Sie die ID des zu ändernden Punktes nicht kennen. Eine andere Möglichkeit ist die Verwendung von Filtern.

Schlüssel der Nutzlast löschen

REST-API (Schema):

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

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

Alternativ können Sie Filter verwenden, um Nutzlastschlüssel von Punkten zu löschen.

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

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

Nutzlast löschen

Diese Methode entfernt alle Nutzlastschlüssel von den angegebenen Punkten.

REST-API (Schema):

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

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

Punkte löschen

REST-API (Schema):

POST /collections/{collection_name}/points/delete

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

Eine andere Möglichkeit, die zu löschenden Punkte zu spezifizieren, ist die Verwendung eines Filters:

POST /collections/{collection_name}/points/delete

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

Dieses Beispiel löscht alle Punkte mit { "color": "red" } aus der Sammlung.

Punkte abrufen

Methode zum Abrufen von Punkten anhand ihrer IDs:

REST-API (Schema):

POST /collections/{collection_name}/points

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

Diese Methode verfügt über zusätzliche Parameter with_vectors und with_payload. Durch die Verwendung dieser Parameter können Sie die Teile der Punkteergebnisse auswählen, die Sie benötigen. Das Ausschließen hilft, Datenübertragung für nutzlose Daten zu vermeiden.

Es ist auch möglich, einen einzelnen Punkt über die API abzurufen:

REST-API (Schema):

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

Scroll

Manchmal ist es notwendig, alle gespeicherten Punkte abzurufen, ohne ihre IDs zu kennen, oder durch Punkte zu iterieren, die Filterbedingungen erfüllen.

REST-API (Schema):

POST /collections/{collection_name}/points/scroll

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

Gibt alle Punkte zurück, die color=red entsprechen:

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

Die Scroll-API gibt alle Punkte zurück, die dem Filter entsprechen, in paginierter Form.

Alle resultierenden Punkte sind nach ID sortiert. Um die nächste Seite abzufragen, müssen Sie die maximale gefundene ID im Feld offset angeben. Zur Bequemlichkeit wird diese ID auch im Feld next_page_offset zurückgegeben. Wenn der Wert des Felds next_page_offset null ist, bedeutet dies, dass die letzte Seite erreicht wurde.

Punkte zählen

Verfügbar ab Version v0.8.4

Manchmal ist es nützlich, nur zu wissen, wie viele Punkte den Filterbedingungen entsprechen, ohne tatsächlich eine Suche durchzuführen.

Beispielsweise kann dies in den folgenden Szenarien nützlich sein:

Schätzen der Ergebnisgröße für facettierte Suche
Bestimmung der Anzahl der Seiten für die Paginierung
Debuggen der Ausführungsgeschwindigkeit von Abfragen

REST-API (Schema):

POST /collections/{collection_name}/points/count

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

Gibt die Anzahl der Punkte zurück, die den angegebenen Filterbedingungen entsprechen:

{
    "count": 3811
}

Batch Update

Verfügbar ab v1.5.0

Sie können Batch-Operationen auf mehreren Punkten ausführen. Dies umfasst das Einfügen, Aktualisieren und Löschen von Punkten, Vektoren und Nutzlasten.

Eine Batch-Update-Anfrage besteht aus einer Reihe von Operationen, die nacheinander ausgeführt werden. Die Operationen, die gebündelt werden können, umfassen:

Punkte einfügen oder aktualisieren: upsert oder UpsertOperation
Punkte löschen: delete_points oder DeleteOperation
Vektoren aktualisieren: update_vectors oder UpdateVectorsOperation
Vektoren löschen: delete_vectors oder DeleteVectorsOperation
Nutzlast setzen: set_payload oder SetPayloadOperation
Nutzlast überschreiben: overwrite_payload oder OverwritePayload
Nutzlast löschen: delete_payload oder DeletePayloadOperation
Nutzlast löschen: clear_payload oder ClearPayloadOperation

Das folgende Codebeispiel verwendet alle Operationen.

REST-API (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]}}
    ]
}

Um Batch-Punkte mit einem einzelnen Typ von Operation zu verwenden, verwenden Sie die Batch-Funktion direkt innerhalb dieser Operation.

Punkte

Warten auf Ergebnisse

Punkt-ID

Hochladen von Datenpunkten

Ändern von Datenpunkten

Vektoren aktualisieren

Vektoren löschen

Nutzlast festlegen

Nutzlast überschreiben

Schlüssel der Nutzlast löschen

Nutzlast löschen

Punkte löschen

Punkte abrufen

Scroll

Punkte zählen

Batch Update

Verwandte Tutorials