告别 Python 依赖!用 PHPVector 在 PHP 中实现向量检索

大家好，我是小皮。

说到向量数据库，很多人第一反应就是 Python 生态里的 Chroma、Qdrant、Pinecone、Weaviate。但如果你是一个 PHP 开发者，你的项目已经在 PHP 里跑了七八年，数据、认证、业务逻辑全在 PHP 这一层——难道每次要做向量检索，都得额外搞一个 Python 服务？

今天给大家介绍PHPVector，一个纯 PHP 实现的向量数据库，零外部扩展依赖，一行 Composer 命令就能接入你的项目。

一、向量数据库到底能干什么？

在聊 PHPVector 之前，先搞清楚向量数据库的应用场景。简单说，它解决的是一个核心问题：语义搜索。

传统搜索靠关键词匹配。你搜「怎么减肥」，只能匹配到包含「减肥」这个词的文档。但如果文档里写的是「如何科学减脂」——关键词对不上，再好的文章也搜不到。

向量数据库的做法是：把文本转成向量（一串数字），然后用数学方法计算向量之间的相似度。「减肥」和「减脂」在语义上是近似的，它们的向量距离就很近。

几个典型的应用场景：

• RAG（检索增强生成）：让 AI 先从你的知识库里检索相关内容，再基于这些内容回答问题。这是目前企业应用 AI 最主流的模式。
• 智能客服：用户提问 → 检索最相似的历史工单/FAQ → 用 AI 生成回复。
• 商品推荐：用户浏览过的商品向量 → 找最相似的其他商品。
• 代码搜索：用自然语言描述功能 → 检索代码库里最匹配的实现。
• 图片检索：以图搜图，CLIP 模型生成的图片向量存入数据库。

核心流程都一样：生成向量 → 存入数据库 → 查询相似向量 → 返回结果。以前这只能在 Python 里做，现在 PHPVector 来了。

二、PHPVector 是什么？

PHPVector 是一个纯 PHP 向量数据库，作者是 Enrico Zimuel（Elasticsearch PHP 客户端的核心开发者）。它实现了：

• HNSW（Hierarchical Navigable Small World）—— 近似最近邻搜索，向量检索的主力算法
• BM25—— 全文检索，传统关键词搜索的最佳拍档
• 混合搜索—— 向量 + 关键词双路召回，结果更准

核心特性：

• 要求 PHP 8.2+，无需任何外部 PHP 扩展
• 可选ext-pcntl开启异步写入，进一步提升插入性能
• 支持四种距离度量：余弦、欧几里得、点积、曼哈顿
• 支持数据持久化到磁盘

三、快速上手

安装

composer require ezimuel/phpvector

一行命令，没有 C 扩展编译，没有 Docker 依赖，纯 PHP。

第一步：插入文档

usePHPVector\Document;usePHPVector\VectorDatabase;$db = new VectorDatabase();$db->addDocuments([new Document(        id: 1,        vector: [0.12, 0.85, 0.44, 0.67],        text: 'PHP vector database with HNSW index',        metadata: ['url' => 'https://example.com/1', 'lang' => 'en'],    ),new Document(        id: 2,        vector: [0.91, 0.23, 0.78, 0.05],        text: 'Approximate nearest neighbour search in PHP',        metadata: ['url' => 'https://example.com/2', 'lang' => 'en'],    ),new Document(        id: 3,        vector: [0.33, 0.61, 0.19, 0.88],        text: 'BM25 full-text ranking algorithm explained',        metadata: ['url' => 'https://example.com/3', 'lang' => 'en'],    ),]);

每个 Document 包含三个要素：向量（用于语义搜索）、文本（用于 BM25 全文检索）、元数据（查询结果中返回）。

第二步：向量搜索

用 HNSW 算法查找与查询向量最相似的文档：

$queryVector = [0.10, 0.80, 0.50, 0.60];$results = $db->vectorSearch(vector: $queryVector, k: 2);foreach ($results as $result) {echo sprintf("[%d] score=%.4f  %s\n",        $result->rank,        $result->score,        $result->document->metadata['url'],    );}// [1] score=0.9987  https://example.com/1// [2] score=0.8341  https://example.com/3

第三步：全文搜索

BM25 关键词检索，适合精确匹配场景：

$results = $db->textSearch(query: 'nearest neighbour PHP', k: 2);// [1] score=1.2430  https://example.com/2// [2] score=0.8761  https://example.com/1

第四步：混合搜索（重点）

实际项目中，纯向量搜索或纯关键词搜索往往不够。混合搜索把两者融合，结果质量显著提升。

PHPVector 支持两种融合模式：

RRF（倒数排名融合，推荐）—— 基于排名而非分数，无需调参：

usePHPVector\HybridMode;$results = $db->hybridSearch(    vector: $queryVector,    text:   'vector database PHP',    k:      3,    mode:   HybridMode::RRF,);

加权组合—— 如果你明确知道向量和文本的权重比例：

$results = $db->hybridSearch(    vector:       $queryVector,    text:         'vector database PHP',    k:            3,    mode:         HybridMode::Weighted,    vectorWeight: 0.7,    textWeight:   0.3,);

四、高级配置

HNSW 参数调优

usePHPVector\HNSW\ConfigasHNSWConfig;usePHPVector\Distance;$db = new VectorDatabase(    hnswConfig: new HNSWConfig(        M:               16,   // 每层每节点最大连接数，影响内存与召回率        efConstruction:  200,  // 构建时的束宽，越高图质量越好但插入越慢        efSearch:        50,   // 查询时的束宽，越高召回率越好但查询越慢        distance:        Distance::Cosine,        useHeuristic:    true, // 多样化邻居选择，推荐开启    ),);

速查表：

距离度量选择

BM25 参数

usePHPVector\BM25\ConfigasBM25Config;usePHPVector\BM25\SimpleTokenizer;$db = new VectorDatabase(    bm25Config: new BM25Config(        k1: 1.5,   // TF 饱和度，推荐 1.2-2.0        b:  0.75,  // 长度归一化，0=不归一化，1=完全归一化    ),    tokenizer: new SimpleTokenizer(        stopWords:      SimpleTokenizer::DEFAULT_STOP_WORDS,        minTokenLength: 2,    ),);

五、数据持久化

PHPVector 支持将数据保存到磁盘，重启不丢失：

$db = new VectorDatabase(path: '/var/data/mydb');$db->addDocuments([...]);// 刷盘：HNSW 图 + BM25 索引 + 文档全部写入磁盘$db->save();// 下次使用直接加载$db = VectorDatabase::open('/var/data/mydb');

磁盘目录结构：

/var/data/mydb/  meta.json     — 数据库元信息  hnsw.bin      — HNSW 图数据  bm25.bin      — BM25 倒排索引  docs/    0.bin       — 单个文档    1.bin    ...

设计上的两个亮点：

• 低内存：只加载索引结构，文档本身懒加载
• 低延迟：如果启用了ext-pcntl，文档写入通过子进程异步完成，addDocument()立即返回

总结

PHPVector 的出现，让 PHP 开发者终于可以在自己的技术栈里闭环完成向量检索——不需要启动 Python 微服务，不需要多学一套工具链。

它的优势很明确：

• 零外部依赖，纯 PHP 实现
• HNSW + BM25 + 混合搜索三合一
• 磁盘持久化开箱即用
• Composer 一行安装，和现有 PHP 项目无缝集成

如果你的项目已经在做 RAG、智能搜索、推荐系统，或者你正在考虑给产品加上 AI 能力——PHPVector 值得一试。它也许不是性能最强的（比不过 C++ 写的 Qdrant），但绝对是最容易接入 PHP 技术栈的。

感谢大家阅读，个人观点仅供参考，欢迎在评论区发表不同观点。

欢迎关注、分享、点赞、收藏、在看，我是微信公众号「PHP驿站」作者小皮。