向量数据库Qdrant使用

一、什么是向量数据库？

向量数据库是专门用于存储、管理和检索“向量嵌入（Embedding）”的数据库。

• Embedding 的本质： 深度学习模型（如 OpenAI 的 text-embedding-3 或本地的 BGE 模型）能将文本、图片等转化为一串高维数值（向量）。在这个高维空间中，语义越接近的数据，其向量距离就越近。
• 核心功能： 与传统数据库通过 SQL WHERE 子句匹配关键词不同，向量数据库通过“最近邻搜索（ANN）”寻找语义上最相似的内容。它是实现 RAG（检索增强生成）技术的关键。

常见向量数据库

二、Qdrant介绍

2.1 什么是 Qdrant？

Qdrant 是一款使用 Rust 开发的开源向量数据库，专门用于高性能相似度搜索。

主要特点：

• 高性能 ANN 检索
• HNSW 索引
• REST API
• gRPC
• Payload 元数据过滤
• 多向量支持
• Snapshot 备份
• 集群部署
• Docker 支持

2.2 Qdrant 核心架构

               Client
                  │
        REST API / gRPC
                  │
           Collection
                  │
              Point
        ┌──────────────┐
        │   Vector     │
        │   Payload    │
        └──────────────┘

• Collection:类似 MySQL：Database
• Point:类似 MySQL 一行数据
• Vector： Embedding 后的数据
• Payload：类似普通数据库字段

2.3 Qdrant 检索原理

Qdrant 默认采用 HNSW（Hierarchical Navigable Small World） 索引。 与传统全表扫描不同：

1000万条
↓
无需全部计算
↓
快速找到最近邻

这种方式称为：

ANN（Approximate Nearest Neighbor）

能够在保证较高召回率的同时，大幅降低检索时间，非常适合 AI 场景。

三、Qdrant部署

3.1 快速部署（Docker 模式）

docker run -p 6333:6333 -p 6334:6334 \
    -v $(pwd)/qdrant_storage:/qdrant/storage:z \
    qdrant/qdrant

• 6333： REST API 端口。
• 6334： gRPC 端口（性能更高，建议在生产环境使用）。

浏览器访问：http://localhost:6333

创建 Collection

PUT /collections/articles

{
    "vectors":{
        "size":1536,
        "distance":"Cosine"
    }
}

插入 Point

{
    "points":[
        {
            "id":1,
            "vector":[0.12,0.55,...],
            "payload":{
                "title":"PHP教程"
            }
        }
    ]
}

四、Qdrant 实战（PHP）

Qdrant 提供 REST API 与 gRPC 接口，目前 PHP 更多采用 REST API 调用，结合 Guzzle 或 Symfony HttpClient 即可完成绝大多数业务场景

4.1 推荐项目结构

app
├── Services
│   ├── EmbeddingService.php
│   ├── QdrantService.php
│   └── RagService.php
├── Models
├── Controllers
└── Jobs

职责划分：

• EmbeddingService：负责调用 Embedding 模型，将文本转换为向量。
• QdrantService：负责 Collection 管理、向量写入、检索等操作。
• RagService：封装 RAG 检索流程，将检索结果交给大语言模型生成最终答案。

4.2 安装 HTTP 客户端

composer require guzzlehttp/guzzle

4.3 封装 QdrantService

可以将 Qdrant 的 REST API 封装为统一服务，例如：

class QdrantService
{
    public function createCollection(string $name): void {}

    public function upsert(array $points): void {}

    public function search(array $vector, int $limit = 5): array {}

    public function delete(array $ids): void {}
}

4.4 写入向量数据流程

文章内容
      │
      ▼
Embedding
      │
      ▼
1536维向量
      │
      ▼
Qdrant Upsert

可以在写入时同步保存 Payload，例如标题、作者、分类、创建时间等，方便后续过滤。

4.5 相似度搜索流程

用户输入问题
        │
        ▼
Embedding
        │
        ▼
Search API
        │
        ▼
Top K 文档

通常返回前 3～10 条最相似的数据，再交给 LLM 总结生成回答。

可进一步结合队列，将 Embedding 和向量写入放入异步任务中，提高接口响应速度。

4.6 企业级应用流程（RAG）

PDF / Word / Markdown
          │
          ▼
      文本切块（Chunk）
          │
          ▼
   Embedding 向量化
          │
          ▼
    写入 Qdrant
          │
          ▼
      用户提问
          │
          ▼
   问题 Embedding
          │
          ▼
   Qdrant 检索 Top K
          │
          ▼
  将上下文拼接到 Prompt
          │
          ▼
      LLM 生成回答

4.7 实践建议

在生产环境中，可以参考以下实践：

• Collection 设计：按业务（文档、FAQ、产品等）划分 Collection，避免单个集合过于庞大。
• Payload 设计：保存标题、分类、标签、权限等元数据，便于过滤与权限控制。
• 批量写入：文档导入时采用批量 Upsert，提高导入效率。
• 异步处理：Embedding 计算和向量写入放入队列，避免阻塞用户请求。
• 连接管理：使用 HTTP Keep-Alive 或连接池，降低网络开销。
• 备份与恢复：定期创建 Snapshot，并制定恢复方案。
• 监控与告警：关注写入延迟、检索耗时、磁盘空间等指标。