Qdrant PHP Client：为 PHP 生态打造的向量数据库客户端

想象这样一个场景：你经营一家电商平台，用户在搜索栏里输入"适合夏天穿的轻薄长裙"，传统关键词搜索只能找到包含"裙子""夏天"字样的商品；但向量数据库能理解"轻薄""长款""适合高温天气"这些语义，让你返回真正符合用户意图的结果——这就是 Qdrant 存在的意义。而 qdrant-php 则让这套能力在 PHP 世界里触手可及。

一、项目背景与作者故事

qdrant-php（GitHub: hkulekci/qdrant-php，174★，174 forks，174 stars）是由土耳其开发者 Haydar Kulekci 主导开发的 Qdrant 向量数据库官方 PHP 客户端。Qdrant 本身由 Rust 编写，是当前最流行的开源向量相似度搜索引擎之一，与 Weaviate、Milvus、Pinecone 并列为 AI 时代的基础设施级产品。Qdrant 提供 RESTful API，支持 HNSW、量化等高级索引算法，能在毫秒级完成百万级向量的相似度检索。

作者 Haydar 在 Medium 上活跃分享 Qdrant PHP 集成经验，涵盖向量排序、条件过滤、滚动分页等实战用法。他从 2023 年 3 月开始维护该项目，README 文档清晰完整，代码遵循 PSR-4 自动加载规范，质量在社区 PHP 库中属于上乘。

图1：qdrant-php 项目 GitHub 概览

二、为什么需要 qdrant-php？

2.1 PHP 生态在 AI 时代的缺口

PHP 是全球最广泛使用的 Web 后端语言之一，但 AI/ML 领域长期被 Python 主导。许多企业在 PHP 遗留系统上运行着核心业务，无法轻易迁移到 Python 生态，却又迫切需要引入语义搜索、推荐系统、RAG（检索增强生成）等 AI 能力。qdrant-php 填补了这个空白：开发者无需换语言，就能在 Laravel、Symfony 等主流 PHP 框架中直接调用向量检索能力。

2.2 与其他语言的对比

客户端	Stars	维护状态	特点
Python (官方)	7k+	活跃	功能最全
TypeScript (官方)	1k+	活跃	前后端通用
Go (官方)	2k+	活跃	高性能
PHP (社区)	174	活跃	PHP 生态集成

作为社区维护而非官方维护的客户端，qdrant-php 得到了 Qdrant 官方 GitHub Organization 的认可和推广。

三、核心功能与技术实现

3.1 架构设计

项目采用经典的 Endpoint 模式（Builder Pattern 变体），将 Qdrant REST API 的不同功能域封装为独立端点类：

$client->collections('contents')   // Collections 端点
       ->points()                   // Points 子端点
       ->upsert($points);           // 插入/更新向量

源码结构清晰，src/Endpoints/ 下每个文件对应 Qdrant API 的一个 Endpoint：

• Collections.php — 集合管理（创建、删除、列表、别名）
• Cluster.php — 集群健康检查与节点管理
• Snapshots.php — 快照备份与恢复
• Service.php — 服务健康状态查询

核心文件 src/Endpoints/Collections/Points.php（5828 bytes）封装了点操作：upsert（插入/更新）、retrieve（检索）、delete（删除）、scroll（滚动遍历）和 query（综合查询）。值得注意的是，search() 方法在源码中已被标记为 deprecated（推荐使用更强大的 query() 端点），这与 Qdrant 服务端 API 演进保持一致。

3.2 模型层设计

src/Models/ 目录下是一套完整的请求/响应 DTO（Data Transfer Objects）：

use Qdrant\Models\Request\CreateCollection;
use Qdrant\Models\Request\VectorParams;

$create = new CreateCollection();
$create->addVector(new VectorParams(1536, VectorParams::DISTANCE_COSINE), 'content');
$client->collections('my_collection')->create($create);

向量距离支持 cosine（余弦相似度）、dot（点积）、euclid（欧氏距离）三种算法，与 Qdrant 服务端完全对齐。Filter 系统支持 must/must_not/should/minShould 组合条件，提供了比 Qdrant 原生 API 更友好的 PHP 式 Builder API。

3.3 依赖与生态

项目依赖精简，严格遵循 PSR 标准：

• psr/http-client — HTTP 客户端接口（支持 Guzzle、Httplug 等多种实现）
• psr/http-message — HTTP 消息抽象
• psr/log — 日志接口
• webmozart/assert — 运行时类型断言
• php-http/discovery — 自动发现 HTTP 适配器

这种设计使得项目高度解耦，开发者可以自由选择底层的 HTTP 实现（如 Symfony HttpClient、Guzzle 等），不会对业务项目造成额外负担。

四、上手指南

4.1 安装

composer require hkulekci/qdrant

要求：PHP 8.1+，官方 CI 已在 8.1/8.2/8.3/8.4 上测试通过。

4.2 连接 Qdrant 服务

use Qdrant\Qdrant;
use Qdrant\Config;
use Qdrant\Http\Builder;

$config = new Config('http://localhost:6333');
$config->setApiKey('your_api_key');
$transport = (new Builder())->build($config);
$client = new Qdrant($transport);

Qdrant 服务可以通过 Docker 一键启动：

docker pull qdrant/qdrant
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

4.3 完整向量检索流程

// 1. 接入 OpenAI embedding（也可以用任何其他嵌入模型）
$openai = OpenAI::client(OPENAI_API_KEY);
$response = $openai->embeddings()->create([
    'model' => 'text-embedding-ada-002',
    'input' => '适合夏天穿的轻薄长裙'
]);
$embedding = array_values($response->embeddings[0]->embedding);

// 2. 插入向量
$points = new PointsStruct();
$points->addPoint(
    new PointStruct($id, new VectorStruct($embedding, 'content'), ['meta' => 'data'])
);
$client->collections('products')->points()->upsert($points, ['wait' => 'true']);

// 3. 语义检索
$searchRequest = (new SearchRequest(new VectorStruct($embedding, 'content')))
    ->setFilter((new Filter())->addMust(new MatchString('category', 'dress')))
    ->setLimit(10)
    ->setWithPayload(true);
$results = $client->collections('products')->points()->search($searchRequest);

五、部署评估

qdrant-php 本身是一个 Composer 库，没有独立部署需求。部署评估应针对其运行时依赖的两个组件：

组件	部署方式	难度
PHP 8.1+	系统包 / Docker	简单
Qdrant 服务	Docker 单命令启动	极简单

# 一行命令启动 Qdrant
docker run -d --name qdrant -p 6333:6333 -p 6334:6334 qdrant/qdrant

Qdrant 本身提供 Helm Chart，支持 Kubernetes 部署。qdrant-php 的部署复杂度为零，属于"即装即用"的 Composer 依赖包。

图2：Qdrant 集合与向量数据管理示意

六、局限性与注意事项

局限性一：非官方维护。qdrant-php 是社区项目而非 Qdrant 官方维护，存在 API 同步滞后风险。例如 search() 方法已标记 deprecated 但 query() 方法的 PHP 封装可能尚未完全覆盖 Qdrant 最新 API 的所有参数。

局限性二：异步支持缺失。底层依赖同步 PSR-18 HTTP Client，在高并发场景下（如 PHP-FPM 大量并发请求）可能成为瓶颈。对于需要异步非阻塞调用的场景，建议通过 Swoole/ReactPHP 封装。

局限性三：向量维度依赖外部生成。qdrant-php 只负责向量存储和检索，嵌入向量本身需要依赖 OpenAI API、Cohere、HuggingFace 等外部服务，需要额外处理网络调用和成本控制。

局限性四：错误处理粗糙。当服务端返回 4xx/5xx 错误时，仅抛出通用 InvalidArgumentException/ServerException，缺少细粒度的错误码和用户友好的错误信息。

七、行业意义与前景

向量数据库是 LLM 应用（RAG、Agent Memory、语义搜索）的核心基础设施，Qdrant 作为其中最活跃的开源项目之一，生态持续扩张。qdrant-php 虽然规模不大，但它是 PHP 开发者进入 AI 应用开发的最低门槛桥梁。

随着 PHP 8.4 引入 JIT 优化和更强的类型系统，以及 Laravel 生态对 AI 集成的需求增长（如 Laravel AI SDK），qdrant-php 有望获得更多关注。对于需要构建 PHP 版语义搜索、推荐引擎或多模态检索系统的团队，这个项目值得作为基础设施纳入技术栈。

---

项目速览

• 仓库：hkulekci/qdrant-php
• 语言：PHP 8.1+
• 授权：MIT
• 包管理：Composer（hkulekci/qdrant）
• CI 状态：✅ PHP 8.1~8.4 全版本通过
• Stars/Forks：174★ / 31
• 适用场景：电商语义搜索、内容推荐、RAG 应用、图像相似度检索