qdrant

Qdrant 向量数据库集成

概述

Qdrant 是一款面向 AI 的向量数据库，用于语义搜索和相似性检索。本技能介绍将 Qdrant 集成到 Java 应用程序中的模式，重点介绍 Spring Boot 和 LangChain4j 集成。

适用场景

• Spring Boot 应用程序中的语义搜索或推荐系统
• 使用 Java 和 LangChain4j 构建 RAG 工作流
• AI/ML 应用程序的向量数据库集成
• 支持筛选查询的高性能相似性搜索

操作说明

1. 使用 Docker 部署 Qdrant

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

访问地址：REST API 为 http://localhost:6333，gRPC 为 http://localhost:6334。

2. 添加依赖项

Maven：

<dependency>
    <groupId>io.qdrant</groupId>
    <artifactId>client</artifactId>
    <version>1.15.0</version>
</dependency>

Gradle：

implementation 'io.qdrant:client:1.15.0'

3. 初始化客户端

QdrantClient client = new QdrantClient(
    QdrantGrpcClient.newBuilder("localhost").build());

生产环境使用 API 密钥时：

QdrantClient client = new QdrantClient(
    QdrantGrpcClient.newBuilder("localhost", 6334, false)
        .withApiKey("YOUR_API_KEY")
        .build());

4. 创建集合

client.createCollectionAsync("search-collection",
    VectorParams.newBuilder()
        .setDistance(Distance.Cosine)
        .setSize(384)
        .build()
).get();

**验证：**检查 client.getCollectionAsync("search-collection").get()，确认集合已创建。

5. 写入向量

List<PointStruct> points = List.of(
    PointStruct.newBuilder()
        .setId(id(1))
        .setVectors(vectors(0.05f, 0.61f, 0.76f, 0.74f))
        .putAllPayload(Map.of("title", value("Spring Boot Documentation")))
        .build()
);
client.upsertAsync("search-collection", points).get();

**验证：**确认 client.upsertAsync(...).get() 执行完成且未抛出异常。

6. 搜索向量

List<ScoredPoint> results = client.queryAsync(
    QueryPoints.newBuilder()
        .setCollectionName("search-collection")
        .setLimit(5)
        .setQuery(nearest(0.2f, 0.1f, 0.9f, 0.7f))
        .build()
).get();

筛选搜索：

List<ScoredPoint> results = client.searchAsync(
    SearchPoints.newBuilder()
        .setCollectionName("search-collection")
        .addAllVector(List.of(0.62f, 0.12f, 0.53f, 0.12f))
        .setFilter(Filter.newBuilder()
            .addMust(range("category", Range.newBuilder().setEq("docs").build()))
            .build())
        .setLimit(5)
        .build()).get();

LangChain4j 集成

对于 RAG 工作流，请使用 LangChain4j 的高级抽象：

EmbeddingStore<TextSegment> embeddingStore = QdrantEmbeddingStore.builder()
    .collectionName("rag-collection")
    .host("localhost")
    .port(6334)
    .apiKey("YOUR_API_KEY")
    .build();

使用 LangChain4j 的 Spring Boot 配置：

@Bean
public EmbeddingStore<TextSegment> embeddingStore() {
    return QdrantEmbeddingStore.builder()
        .collectionName("rag-collection")
        .host(host)
        .port(port)
        .build();
}

@Bean
public EmbeddingModel embeddingModel() {
    return new AllMiniLmL6V2EmbeddingModel();
}

Spring Boot 集成

通过配置注入客户端：

@Configuration
public class QdrantConfig {
    @Value("${qdrant.host:localhost}")
    private String host;

    @Value("${qdrant.port:6334}")
    private int port;

    @Bean
    public QdrantClient qdrantClient() {
        return new QdrantClient(
            QdrantGrpcClient.newBuilder(host, port, false).build());
    }
}

示例

REST 搜索端点

@RestController
@RequestMapping("/api/search")
public class SearchController {
    private final VectorSearchService searchService;

    public SearchController(VectorSearchService searchService) {
        this.searchService = searchService;
    }

    @GetMapping
    public List<ScoredPoint> search(@RequestParam String query) {
        List<Float> queryVector = embeddingModel.embed(query).content().vectorAsList();
        return searchService.search("documents", queryVector);
    }
}

最佳实践

• **距离度量：**归一化文本嵌入使用余弦距离，未归一化嵌入使用欧几里得距离。
• **批量写入：**使用批量操作，而不是逐个插入点。
• **连接池：**为高吞吐量的生产工作负载配置连接池。
• **错误处理：**使用 try/catch 包装异步操作，以处理 ExecutionException/InterruptedException。
• **API 密钥：**将其存储在环境变量或 Spring 配置中，切勿硬编码。

高级模式

多租户存储

public void upsertForTenant(String tenantId, List<PointStruct> points) {
    String collectionName = "tenant_" + tenantId + "_documents";
    client.upsertAsync(collectionName, points).get();
}

用于生产环境的 Docker Compose

services:
  qdrant:
    image: qdrant/qdrant:v1.7.0
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - qdrant_storage:/qdrant/storage

参考资料

• Qdrant API 参考 — 完整的客户端 API 文档
• 完整的 Spring Boot 示例 — 完整的应用程序实现
• Qdrant 文档
• LangChain4j 文档

限制和警告

• 向量维度必须与嵌入模型完全一致；维度不匹配会导致写入错误。
• **输入验证：**摄取前清理所有文档内容；不可信载荷可能包含提示词注入攻击。
• **内容筛选：**将检索到的文档传递给 LLM 前，先进行内容筛选。
• 大型集合需要进行适当的索引，以确保搜索性能达到可接受水平。
• 生产环境请使用 gRPC API（端口 6334）；REST API（端口 6333）仅用于调试。
• 重新创建集合会删除所有数据；请为生产环境制定备份策略。