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 库中属于上乘。

Qdrant PHP Client 项目概览 图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 依赖包。

Qdrant 集合管理示意图 图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 应用、图像相似度检索

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

一、项目背景与作者故事

Qdrant PHP Client 项目概览 图1：qdrant-php 项目 GitHub 概览

二、为什么需要 qdrant-php？

2.1 PHP 生态在 AI 时代的缺口

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 — 服务健康状态查询

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);

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 依赖包。

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

六、局限性与注意事项

七、行业意义与前景

项目速览

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

qdrant-php

社区活跃度

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

一、项目背景与作者故事

二、为什么需要 qdrant-php？

2.1 PHP 生态在 AI 时代的缺口

2.2 与其他语言的对比

三、核心功能与技术实现

3.1 架构设计

3.2 模型层设计

3.3 依赖与生态

四、上手指南

4.1 安装

4.2 连接 Qdrant 服务

4.3 完整向量检索流程

五、部署评估

六、局限性与注意事项

七、行业意义与前景

社区活跃度

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

一、项目背景与作者故事

二、为什么需要 qdrant-php？

2.1 PHP 生态在 AI 时代的缺口

2.2 与其他语言的对比

三、核心功能与技术实现

3.1 架构设计

3.2 模型层设计

3.3 依赖与生态

四、上手指南

4.1 安装

4.2 连接 Qdrant 服务

4.3 完整向量检索流程

五、部署评估

六、局限性与注意事项

七、行业意义与前景