Qdrant

本节将指导您设置 Qdrant VectorStore 以存储文档嵌入，并执行相似度搜索。

This section walks you through setting up the Qdrant VectorStore to store document embeddings and perform similarity searches.

Qdrant 是一个开源、高性能的向量搜索引擎/数据库。它使用 HNSW（分层可导航小世界）算法进行高效的 k-NN 搜索操作，并为基于元数据的查询提供高级过滤功能。

Qdrant is an open-source, high-performance vector search engine/database. It uses HNSW (Hierarchical Navigable Small World) algorithm for efficient k-NN search operations and provides advanced filtering capabilities for metadata-based queries.

Prerequisites

Qdrant 实例：按照 Qdrant 文档中的 installation instructions 设置 Qdrant 实例。
Qdrant Instance: Set up a Qdrant instance by following the installation instructions in the Qdrant documentation.
如果需要， EmbeddingModel 的 API 密钥用于生成由 QdrantVectorStore 存储的嵌入。
If required, an API key for the EmbeddingModel to generate the embeddings stored by the QdrantVectorStore.

建议提前使用适当的维度和配置 created Qdrant 集合。如果未创建集合， QdrantVectorStore 将尝试使用 Cosine 相似度和配置的 EmbeddingModel 维度创建一个集合。

It is recommended that the Qdrant collection is created in advance with the appropriate dimensions and configurations. If the collection is not created, the QdrantVectorStore will attempt to create one using the Cosine similarity and the dimension of the configured EmbeddingModel.

Auto-configuration

Spring AI 自动配置、启动器模块的工件名称发生了重大变化。请参阅 upgrade notes 以获取更多信息。

There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the upgrade notes for more information.

Spring AI 为 Qdrant 向量存储提供 Spring Boot 自动配置。要启用它，请将以下依赖项添加到项目的 Maven pom.xml 文件中：

Spring AI provides Spring Boot auto-configuration for the Qdrant Vector Store. To enable it, add the following dependency to your project’s Maven pom.xml file:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-qdrant</artifactId>
</dependency>

或添加到 Gradle build.gradle 构建文件中。

or to your Gradle build.gradle build file.

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-qdrant'
}

参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

Refer to the Dependency Management section to add the Spring AI BOM to your build file.

请查看向量存储的 configuration parameters 列表，了解默认值和配置选项。

Please have a look at the list of qdrant-vectorstore-properties for the vector store to learn about the default values and configuration options.

将Maven Central和/或Snapshot存储库添加到您的构建文件中，请参阅 Artifact Repositories 部分。

Refer to the Artifact Repositories section to add Maven Central and/or Snapshot Repositories to your build file.

向量存储实现可以为您初始化必要的模式，但您必须通过在构建器中指定 initializeSchema 布尔值或在 application.properties 文件中设置 …initialize-schema=true 来选择启用。

The vector store implementation can initialize the requisite schema for you, but you must opt-in by specifying the initializeSchema boolean in the builder or by setting …initialize-schema=true in the application.properties file.

这是一个重大更改！在早期版本的Spring AI中，此架构初始化是默认发生的。

this is a breaking change! In earlier versions of Spring AI, this schema initialization happened by default.

此外，您还需要一个配置好的 EmbeddingModel bean。有关更多信息，请参阅 EmbeddingModel 部分。

Additionally, you will need a configured EmbeddingModel bean. Refer to the EmbeddingModel section for more information.

现在，您可以在应用程序中自动装配 QdrantVectorStore 作为向量存储。

Now you can auto-wire the QdrantVectorStore as a vector store in your application.

@Autowired VectorStore vectorStore;

// ...

List<Document> documents = List.of(
    new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
    new Document("The World is Big and Salvation Lurks Around the Corner"),
    new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")));

// Add the documents to Qdrant
vectorStore.add(documents);

// Retrieve documents similar to a query
List<Document> results = vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());

Configuration Properties

要连接到 Qdrant 并使用 QdrantVectorStore ，您需要提供实例的访问详细信息。可以通过 Spring Boot 的 application.yml 提供一个简单的配置：

To connect to Qdrant and use the QdrantVectorStore, you need to provide access details for your instance. A simple configuration can be provided via Spring Boot’s application.yml:

spring:
  ai:
    vectorstore:
      qdrant:
        host: <qdrant host>
        port: <qdrant grpc port>
        api-key: <qdrant api key>
        collection-name: <collection name>
        use-tls: false
        initialize-schema: true

以 spring.ai.vectorstore.qdrant.* 开头的属性用于配置 QdrantVectorStore ：

Properties starting with spring.ai.vectorstore.qdrant.* are used to configure the QdrantVectorStore:

Property Description Default Value

Property	Description	Default Value
`spring.ai.vectorstore.qdrant.host`	The host of the Qdrant server	`localhost`
`spring.ai.vectorstore.qdrant.port`	The gRPC port of the Qdrant server	`6334`
`spring.ai.vectorstore.qdrant.api-key`	The API key to use for authentication	-
`spring.ai.vectorstore.qdrant.collection-name`	The name of the collection to use	`vector_store`
`spring.ai.vectorstore.qdrant.use-tls`	Whether to use TLS(HTTPS)	`false`
`spring.ai.vectorstore.qdrant.initialize-schema`	Whether to initialize the schema	`false`

spring.ai.vectorstore.qdrant.host

The host of the Qdrant server

localhost

spring.ai.vectorstore.qdrant.port

The gRPC port of the Qdrant server

6334

spring.ai.vectorstore.qdrant.api-key

The API key to use for authentication

spring.ai.vectorstore.qdrant.collection-name

The name of the collection to use

vector_store

spring.ai.vectorstore.qdrant.use-tls

Whether to use TLS(HTTPS)

false

spring.ai.vectorstore.qdrant.initialize-schema

Whether to initialize the schema

false

Manual Configuration

除了使用 Spring Boot 自动配置之外，您还可以手动配置 Qdrant 向量存储。为此，您需要将 spring-ai-qdrant-store 添加到项目中：

Instead of using the Spring Boot auto-configuration, you can manually configure the Qdrant vector store. For this you need to add the spring-ai-qdrant-store to your project:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-qdrant-store</artifactId>
</dependency>

或添加到 Gradle build.gradle 构建文件中。

or to your Gradle build.gradle build file.

dependencies {
    implementation 'org.springframework.ai:spring-ai-qdrant-store'
}

参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

Refer to the Dependency Management section to add the Spring AI BOM to your build file.

创建 Qdrant 客户端 bean：

Create a Qdrant client bean:

@Bean
public QdrantClient qdrantClient() {
    QdrantGrpcClient.Builder grpcClientBuilder =
        QdrantGrpcClient.newBuilder(
            "<QDRANT_HOSTNAME>",
            <QDRANT_GRPC_PORT>,
            <IS_TLS>);
    grpcClientBuilder.withApiKey("<QDRANT_API_KEY>");

    return new QdrantClient(grpcClientBuilder.build());
}

然后使用构建器模式创建 QdrantVectorStore bean：

Then create the QdrantVectorStore bean using the builder pattern:

@Bean
public VectorStore vectorStore(QdrantClient qdrantClient, EmbeddingModel embeddingModel) {
    return QdrantVectorStore.builder(qdrantClient, embeddingModel)
        .collectionName("custom-collection")     // Optional: defaults to "vector_store"
        .initializeSchema(true)                  // Optional: defaults to false
        .batchingStrategy(new TokenCountBatchingStrategy()) // Optional: defaults to TokenCountBatchingStrategy
        .build();
}

// This can be any EmbeddingModel implementation
@Bean
public EmbeddingModel embeddingModel() {
    return new OpenAiEmbeddingModel(new OpenAiApi(System.getenv("OPENAI_API_KEY")));
}

Metadata Filtering

您也可以将通用的、可移植的 metadata filters 与 Qdrant 存储一起使用。

You can leverage the generic, portable metadata filters with Qdrant store as well.

例如，你可以使用文本表达式语言：

For example, you can use either the text expression language:

vectorStore.similaritySearch(
    SearchRequest.builder()
        .query("The World")
        .topK(TOP_K)
        .similarityThreshold(SIMILARITY_THRESHOLD)
        .filterExpression("author in ['john', 'jill'] && article_type == 'blog'").build());

或使用 Filter.Expression DSL 以编程方式：

or programmatically using the Filter.Expression DSL:

FilterExpressionBuilder b = new FilterExpressionBuilder();

vectorStore.similaritySearch(SearchRequest.builder()
    .query("The World")
    .topK(TOP_K)
    .similarityThreshold(SIMILARITY_THRESHOLD)
    .filterExpression(b.and(
        b.in("author", "john", "jill"),
        b.eq("article_type", "blog")).build()).build());

这些（可移植的）过滤器表达式会自动转换为专有的 Qdrant filter expressions 。

These (portable) filter expressions get automatically converted into the proprietary Qdrant filter expressions.

Accessing the Native Client

Qdrant 向量存储实现通过 getNativeClient() 方法提供对底层原生 Qdrant 客户端 ( QdrantClient ) 的访问：

The Qdrant Vector Store implementation provides access to the underlying native Qdrant client (QdrantClient) through the getNativeClient() method:

QdrantVectorStore vectorStore = context.getBean(QdrantVectorStore.class);
Optional<QdrantClient> nativeClient = vectorStore.getNativeClient();

if (nativeClient.isPresent()) {
    QdrantClient client = nativeClient.get();
    // Use the native client for Qdrant-specific operations
}

原生客户端允许您访问 Qdrant 特定的功能和操作，这些功能和操作可能未通过 VectorStore 接口公开。

The native client gives you access to Qdrant-specific features and operations that might not be exposed through the VectorStore interface.