Qdrant PHP Client: векторный поиск для PHP 7.2 и 8.*

Многие PHP-приложения до сих пор работают на PHP 7.2, и быстро обновить их не получается. Большинству новых AI-инструментов нужен PHP 8 или новее, поэтому команды оказываются в затруднительном положении. Эта небольшая библиотека позволяет добавить векторный поиск даже в старый проект: клиент работает и с PHP 7.2, и с PHP 8.*.

Что такое векторный поиск

Векторный поиск находит объекты, близкие по смыслу. Мы преобразуем текст или другие объекты в наборы чисел — векторы, а затем ищем по расстоянию между ними. Такой подход подходит для семантического поиска, рекомендаций и устранения дубликатов.

Как получить векторные представления — эмбеддинги

Важная часть векторного поиска — преобразование данных в векторы. Для этого нужны нейросетевые модели, обученные создавать векторные представления (эмбеддинги) текста, изображений или других объектов.

• Облачные API крупных провайдеров. С ними легко начать, и они часто дают качественный результат, но за использование нужно платить, а данные передаются по сети.
• Открытые модели, которые можно запустить локально или в собственной инфраструктуре. Больше контроля над данными и конфиденциальностью, но потребуются оборудование и настройка.
• Специализированные сервисы векторизации. Они предлагают простую интеграцию, определённые возможности управления и соглашения об уровне обслуживания (SLA).

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

Зачем это проектам на старых версиях PHP

• Многие компании не могут обновить PHP прямо сейчас.
• При этом потребность в AI-функциях остаётся.
• Большинство новых библиотек уже не поддерживает PHP 7.2, и для многих сайтов это становится препятствием.
• Этот клиент работает с PHP 7.2 и новее и обращается к серверу Qdrant по HTTP.

С помощью клиента можно добавлять новые возможности без полного переписывания приложения.

Установка

composer require tenqz/qdrant

Также понадобится сервер Qdrant — локальный или облачный. Порт по умолчанию — 6333.

Быстрый старт

1. Создать клиент

<?php
use Tenqz\Qdrant\QdrantClient;
use Tenqz\Qdrant\Transport\Infrastructure\Factory\CurlHttpClientFactory;

$factory = new CurlHttpClientFactory();
$httpClient = $factory->create("localhost", 6333);
$client = new QdrantClient($httpClient);

2. Создать коллекцию

При создании коллекции нужно задать размерность вектора и метрику расстояния. Для короткого примера используем размерность 4 и косинусную метрику Cosine.

<?php
$client->createCollection("products", 4, "Cosine");

3. Добавить или обновить точки: векторы и дополнительные данные

<?php
$client->upsertPoints("products", [
    ["id" => 1, "vector" => [0.1, 0.2, 0.3, 0.4], "payload" => ["name" => "T-shirt", "price" => 19]],
    ["id" => 2, "vector" => [0.6, 0.1, 0.8, 0.2], "payload" => ["name" => "Jeans",   "price" => 49]],
]);

4. Выполнить поиск по вектору

<?php
$results = $client->search("products", [0.1, 0.2, 0.3, 0.5], 3);

foreach ($results as $hit) {
    // score, id, payload
    echo $hit["id"] . " " . $hit["score"] . PHP_EOL;
}

Обработка ошибок

<?php
use Tenqz\Qdrant\Transport\Domain\Exception\TransportException;
use Tenqz\Qdrant\Transport\Domain\Exception\HttpException;
use Tenqz\Qdrant\Transport\Domain\Exception\NetworkException;

try {
    $results = $client->search("products", [0.1, 0.2, 0.3, 0.5], 5);
} catch (HttpException $e) {
    echo "HTTP Error {$e->getStatusCode()}: {$e->getMessage()}" . PHP_EOL;
} catch (NetworkException $e) {
    echo "Network Error: {$e->getMessage()}" . PHP_EOL;
} catch (TransportException $e) {
    echo "Error: {$e->getMessage()}" . PHP_EOL;
}

Что можно построить

• Семантический поиск по товарам или документации.
• Рекомендации похожих объектов.
• Поиск почти одинаковых объектов.
• Автоматическое назначение тегов и объединение объектов в группы.

Что учесть

• В реальных приложениях размерность векторов обычно больше — например, 384 или 768.
• Можно добавлять фильтры: по цене, категории или идентификатору пользователя.
• Qdrant можно запустить в Docker, что упрощает начало работы.

Итог

Старая кодовая база не закрывает путь к AI. С этим клиентом векторный поиск можно добавить даже в приложение на PHP 7.2. Начните с небольшой задачи, доведите её до полезного результата и планируйте обновление платформы отдельно.

Ссылки

• GitHub: tenqz/qdrant
• Публикация на Zenodo: A PHP Client for Vector Search in Legacy Projects