Векторные данные Qdrant (точки)

Очки

Очки - это основные сущности, с которыми работает Qdrant. Очка представляет собой запись, состоящую из вектора и необязательной полезной нагрузки.

Вы можете искать точки, сгруппированные в коллекции на основе сходства векторов. Более подробное описание процесса предоставлено в разделе Поиск и Фильтрация.

Этот раздел вводит способы создания и управления векторами.

Любая операция модификации точки является асинхронной и состоит из двух этапов. На первом этапе операция будет записана в журнал операций.

В данное время, даже если произойдет потеря питания устройства, сервис не потеряет данные.

Совет: Очки - это абстрактное понятие в 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, включая загрузку точек данных, являются идемпотентными. Это означает, что выполнение одного и того же метода последовательно эквивалентно однократному выполнению.

В этом сценарии, это означает, что при повторной загрузке точек данных с тем же идентификатором существующие точки данных будут перезаписаны.

Свойство идемпотентности полезно для использования очередей сообщений, которые не обеспечивают точных гарантий единократного выполнения. Даже в этом случае 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.

При модификации точки данных с существующим идентификатором, существующая точка данных сначала удаляется, а затем вставляется с указанным вектором. Иными словами, вся точка данных будет заменена, и любые неуказанные векторы будут установлены в null. Если вы хотите сохранить существующие векторы без изменений и обновить только указанные векторы, обратитесь к обновлению векторов.

Изменение точек данных

Чтобы изменить точку данных, вы можете изменить ее вектор или ее полезную нагрузку. Есть несколько методов для достижения этого.

Обновление векторов

Доступно с версии v1.2.0

Этот метод обновляет указанные векторы в заданных точках. Неуказанные векторы останутся без изменений. Все указанные точки должны существовать.

REST API (Схема):

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 (Схема):

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

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

Установка загрузки

Установите заданные значения загрузки на точках.

REST API (Схема):

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 (Схема):

PUT /collections/{collection_name}/points/payload

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

Аналогично Установка загрузки, вам не нужно знать идентификатор точки для модификации. Другой способ - использовать фильтры.

Удаление ключей загрузки

REST API (Схема):

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 (Схема):

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 Прокрутки вернет все точки, которые соответствуют фильтру пагинированно.

Все полученные точки отсортированы по идентификатору. Чтобы запросить следующую страницу, необходимо указать максимальный обнаруженный ID в поле offset. Для удобства этот ID также возвращается в поле 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 API (Схема):

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

Для использования пакетных точек с одним типом операции используйте функцию пакетного обновления непосредственно внутри этой операции.

Очки

Ожидание Результатов

Идентификатор Точки

Загрузка точек данных

Изменение точек данных

Обновление векторов

Удаление векторов

Установка загрузки

Перезапись загрузки

Удаление ключей загрузки

Очистка загрузки

Удаление точек

Получение точек

Прокрутка

Подсчет точек

Пакетное обновление

Связанные Учебные Пособия