Dane wektorowe Qdrant (Punkty)

Punkty

Punkty stanowią podstawowe jednostki manipulowane przez Qdrant. Punkt to rekord składający się z wektora i opcjonalnych danych ładunkowych.

Możesz wyszukiwać punkty zgrupowane w kolekcji na podstawie podobieństwa wektorów. Bardziej szczegółowy opis procesu znajduje się w sekcji Wyszukiwanie i Filtracja.

Ta sekcja przedstawia, jak tworzyć i zarządzać wektorami.

Każda operacja modyfikacji punktu jest asynchroniczna i podzielona na dwie etapy. W pierwszym etapie operacja zostanie zapisana do dziennika zapisu transakcji.

W tym momencie, nawet jeśli maszyna straci zasilanie, usługa nie utraci danych.

Wskazówka: Punkty są abstrakcyjnym pojęciem w Qdrant, można je traktować jako wiersz danych w tabeli MySQL.

Oczekiwanie na Wyniki

Jeśli API jest wywoływane z parametrem &wait=false, bądź nie jest on jawnie określony, klient otrzyma potwierdzenie odbioru danych:

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

To odpowiedź nie gwarantuje natychmiastowego pobrania danych. Wykorzystuje ona formę spójności ostatecznej. W rzeczywistości, ten rodzaj żądania może ostatecznie nie powieść się. Jeśli wstawiane jest duże ilości wektorów, zalecamy również korzystanie z żądań asynchronicznych, aby w pełni wykorzystać operacje potoku.

Jeśli logika aplikacji wymaga natychmiastowej dostępności do wyszukiwania po odpowiedzi API, należy użyć flagi ?wait=true. W tym przypadku API zwróci wynik dopiero po zakończeniu operacji:

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

ID Punktów

Qdrant obsługuje wykorzystanie 64-bitowych liczb całkowitych bez znaku oraz UUID jako identyfikatory punktów.

Przykłady reprezentacji ciągów znaków UUID są następujące:

• Prosta reprezentacja: 936DA01F9ABD4d9d80C702AF85C822A8
• Reprezentacja z łącznikiem: 550e8400-e29b-41d4-a716-446655440000
• URN: urn:uuid:F9168C5E-CEB2-4faa-B6BF-329BF39FA1E4

Oznacza to, że w każdym żądaniu ciągi znaków UUID można użyć zamiast identyfikatorów liczbowych. Na przykład:

PUT /kolekcje/{nazwa_kolekcji}/punkty

{
    "punkty": [
        {
            "id": "5c56c793-69f3-4fbf-87e6-c4bf54c28c26",
            "ładunek": {"kolor": "czerwony"},
            "wektor": [0.9, 0.1, 0.1]
        }
    ]
}

oraz

PUT /kolekcje/{nazwa_kolekcji}/punkty

{
    "punkty": [
        {
            "id": 1,
            "ładunek": {"kolor": "czerwony"},
            "wektor": [0.9, 0.1, 0.1]
        }
    ]
}

są oba poprawne.

Wczytywanie punktów danych

Aby zoptymalizować wydajność, Qdrant obsługuje wsadowe wczytywanie punktów danych. Oznacza to, że możesz wczytać wiele punktów danych do usługi za pomocą pojedynczego wywołania interfejsu API. Wczytywanie wsadowe może znacząco zmniejszyć nadmiarowe połączenia sieciowe.

Interfejs API Qdrant obsługuje dwie metody tworzenia punktów wsadowych - zorientowane na rekordy i zorientowane na kolumny. Wewnętrznie te opcje są nierozróżnialne i służą wyłącznie wygody w interakcji.

Tworzenie punktów danych za pomocą interfejsu API REST:

PUT /collections/{collection_name}/points

{
    "batch": {
        "ids": [1, 2, 3],
        "payloads": [
            {"color": "czerwony"},
            {"color": "zielony"},
            {"color": "niebieski"}
        ],
        "vectors": [
            [0.9, 0.1, 0.1],
            [0.1, 0.9, 0.1],
            [0.1, 0.1, 0.9]
        ]
    }
}

Lub skorzystaj z równoważnej metody zorientowanej na rekordy:

PUT /collections/{collection_name}/points

{
    "points": [
        {
            "id": 1,
            "payload": {"color": "czerwony"},
            "vector": [0.9, 0.1, 0.1]
        },
        {
            "id": 2,
            "payload": {"color": "zielony"},
            "vector": [0.1, 0.9, 0.1]
        },
        {
            "id": 3,
            "payload": {"color": "niebieski"},
            "vector": [0.1, 0.1, 0.9]
        }
    ]
}

Wszystkie interfejsy API w Qdrant, włącznie z wczytywaniem punktów danych, są idempotentne. Oznacza to, że wykonanie tej samej metody kilkakrotnie jest równoważne pojedynczemu wykonaniu.

W tym scenariuszu oznacza to, że podczas ponownego wczytywania punktów danych o takim samym identyfikatorze istniejące punkty danych zostaną nadpisane.

Własność idempotentności jest przydatna podczas korzystania z kolejkowania wiadomości, które nie zapewniają precyzyjnej gwarancji jednorazowego wykonania. Nawet w tym przypadku Qdrant zapewnia spójność danych.

Dostępne od wersji v0.10.0

Jeśli utworzona kolekcja ma wiele wektorów, możesz dostarczyć dane dla każdego wektora, nadając im nazwy:

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

Dostępne od wersji v1.2.0

Nazwane wektory są opcjonalne. Podczas wczytywania punktów danych niektóre wektory można pomijać. Na przykład możesz wczytać punkt danych tylko z wektorem image i inny tylko z wektorem text.

Podczas modyfikacji punktu danych o istniejącym identyfikatorze, istniejący punkt danych zostanie najpierw usunięty, a następnie ponownie wstawiony z określonym wektorem. Innymi słowy, cały punkt danych zostanie zastąpiony, a nieokreślone wektory zostaną ustawione na null. Jeśli chcesz zachować istniejące wektory bez zmian i aktualizować tylko określone wektory, prosimy o odwołanie się do aktualizacji wektorów.

Modyfikowanie punktów danych

Aby zmodyfikować punkt danych, można zmodyfikować jego wektor lub jego ładunek. Istnieje kilka metod osiągnięcia tego.

Aktualizacja wektorów

Dostępne od wersji v1.2.0

Ta metoda aktualizuje określone wektory w określonych punktach. Niesprecyzowane wektory pozostaną niezmienione. Wszystkie podane punkty muszą istnieć.

REST API (Schemat):

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

Aby zaktualizować punkty i zastąpić wszystkie wektory, proszę odnosić się do operacji przesyłania punktów.

Usuwanie wektorów

Dostępne od wersji v1.2.0

Ta metoda usuwa tylko określone wektory z podanych punktów. Inne wektory pozostaną niezmienione. Punkty nie zostaną usunięte.

REST API (Schemat):

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

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

Ustawianie ładunku

Ustawia określone wartości ładunku na punktach.

REST API (Schemat):

POST /collections/{collection_name}/points/payload

{
    "payload": {
        "właściwość1": "ciąg znaków",
        "właściwość2": "ciąg znaków"
    },
    "points": [
        0, 3, 100
    ]
}

Nie jest konieczne znać id punktu, który ma być modyfikowany. Innym sposobem jest użycie filtrów.

POST /collections/{collection_name}/points/payload

{
    "payload": {
        "właściwość1": "ciąg znaków",
        "właściwość2": "ciąg znaków"
    },
    "filter": {
        "must": [
            {
                "klucz": "kolor",
                "zgodne": {
                    "wartość": "czerwony"
                }
            }
        ]
    }
}

Nadpisywanie ładunku

Całkowicie zastępuje istniejący ładunek podanym ładunkiem.

REST API (Schemat):

PUT /collections/{collection_name}/points/payload

{
    "payload": {
        "właściwość1": "ciąg znaków",
        "właściwość2": "ciąg znaków"
    },
    "points": [
        0, 3, 100
    ]
}

Podobnie jak w przypadku Ustawiania ładunku, nie jest konieczne znać id punktu, który ma być modyfikowany. Innym sposobem jest użycie filtrów.

Usuwanie kluczy ładunku

REST API (Schemat):

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

{
    "klucze": ["kolor", "cena"],
    "punkty": [0, 3, 100]
}

Alternatywnie, można użyć filtrów do usuwania kluczy ładunku z punktów.

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

{
    "klucze": ["kolor", "cena"],
    "filter": {
        "must": [
            {
                "klucz": "kolor",
                "zgodne": {
                    "wartość": "czerwony"
                }
            }
        ]
    }
}

Wyczyszczenie ładunku

Ta metoda usuwa wszystkie klucze ładunku z określonych punktów.

REST API (Schemat):

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

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

Usuń punkty

REST API (Schema):

POST /collections/{collection_name}/points/delete

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

Inny sposób określenia punktów do usunięcia polega na użyciu filtru:

POST /collections/{collection_name}/points/delete

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

Ten przykład usuwa wszystkie punkty z { "color": "red" } z kolekcji.

Pobierz punkty

Metoda pobierania punktów za pomocą ich identyfikatorów:

REST API (Schema):

POST /collections/{collection_name}/points

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

Ta metoda ma dodatkowe parametry with_vectors i with_payload. Korzystając z tych parametrów, można wybrać części wyników punktów, których potrzebujesz. Wykluczenie pomaga uniknąć marnotrawienia transferu danych na niepotrzebne dane.

Istnieje także możliwość pobrania pojedynczego punktu za pośrednictwem interfejsu API:

REST API (Schema):

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

Przewiń

Czasami konieczne jest pobranie wszystkich przechowywanych punktów bez znajomości ich identyfikatorów lub iteracja przez punkty spełniające warunki filtrowania.

REST API (Schema):

POST /collections/{collection_name}/points/scroll

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

Zwraca wszystkie punkty pasujące do color=red:

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

API Przewijania zwróci wszystkie punkty pasujące do filtra w formie paginowanej.

Wszystkie wynikowe punkty są sortowane według identyfikatora. Aby zapytać następną stronę, należy określić maksymalny znaleziony identyfikator w polu offset. Dla wygody ten identyfikator jest również zwracany w polu next_page_offset. Jeśli wartość pola next_page_offset wynosi null, oznacza to, że osiągnięto ostatnią stronę.

Liczenie punktów

Dostępne od wersji v0.8.4

Czasami przydatne jest tylko poznanie liczby punktów pasujących do warunków filtrowania bez faktycznego wykonywania wyszukiwania.

Na przykład może to być przydatne w następujących scenariuszach:

• Szacowanie rozmiaru wyniku dla wyszukiwania wielofasetowego
• Określenie liczby stron do paginacji
• Debugowanie prędkości wykonania zapytania

REST API (Schema):

POST /collections/{collection_name}/points/count

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

Zwraca liczbę punktów pasujących do określonych warunków filtrowania:

{
    "count": 3811
}

Aktualizacja masowa

Dostępne od wersji v1.5.0

Możesz wykonywać operacje masowe na wielu punktach. Obejmuje to wstawianie, aktualizowanie i usuwanie punktów, wektorów i ładunków.

Zapytanie o aktualizację masową składa się z serii operacji, które są wykonywane sekwencyjnie. Operacje, które mogą być wykonywane masowo, obejmują:

• Wstawianie lub aktualizowanie punktów: upsert lub UpsertOperation
• Usuwanie punktów: delete_points lub DeleteOperation
• Aktualizowanie wektorów: update_vectors lub UpdateVectorsOperation
• Usuwanie wektorów: delete_vectors lub DeleteVectorsOperation
• Ustawianie ładunku: set_payload lub SetPayloadOperation
• Nadpisywanie ładunku: overwrite_payload lub OverwritePayload
• Usuwanie ładunku: delete_payload lub DeletePayloadOperation
• Czyszczenie ładunku: clear_payload lub ClearPayloadOperation

Poniższy przykładowy fragment kodu wykorzystuje wszystkie operacje.

REST API (Schemat):

POST /kolekcje/{nazwa_kolekcji}/punkty/masowe

{
    "operacje": [
        {
            "upsert": {
                "punkty": [
                    {
                        "id": 1,
                        "wektor": [1.0, 2.0, 3.0, 4.0],
                        "ładunek": {}
                    }
                ]
            }
        },
        {
            "update_vectors": {
                "punkty": [
                    {
                        "id": 1,
                        "wektor": [1.0, 2.0, 3.0, 4.0]
                    }
                ]
            }
        },
        {
            "delete_vectors": {
                "punkty": [1],
                "wektor": [""]
            }
        },
        {
            "overwrite_payload": {
                "ładunek": {
                    "test_payload": "1"
                },
                "punkty": [1]
            }
        },
        {
            "set_payload": {
                "ładunek": {
                    "test_payload_2": "2",
                    "test_payload_3": "3"
                },
                "punkty": [1]
            }
        },
        {
            "delete_payload": {
                "klucze": ["test_payload_2"],
                "punkty": [1]
            }
        },
        {
            "clear_payload": {
                "punkty": [1]
            }
        },
        {"delete": {"punkty": [1]}}
    ]
}

Aby korzystać z punktów masowych z pojedynczym typem operacji, użyj funkcji masowej bezpośrednio w tej operacji.