Qdrant
本节介绍如何配置 Qdrant VectorStore 以存储文档嵌入并执行相似度搜索。
Qdrant 是一款开源的高性能向量搜索引擎/数据库。它采用 HNSW（Hierarchical Navigable Small World）算法实现高效的 k-NN 搜索操作，并提供基于元数据的高级过滤功能。
前提条件
-
Qdrant 实例：按照 Qdrant 文档中的 安装说明 搭建一个 Qdrant 实例。
-
如有必要，提供一个用于 EmbeddingModel 的 API key，以生成存储在
QdrantVectorStore中的 embeddings。
建议提前创建 Qdrant 集合，并设置合适的维度和配置。如果未创建集合，QdrantVectorStore 将尝试使用 Cosine 相似度以及已配置的 EmbeddingModel 的维度来创建一个集合。
自动配置
Spring AI 的自动配置以及 starter 模块的构件名称已发生重大变更。更多信息请参考 升级说明。
Spring AI 为 Qdrant 向量存储提供了 Spring Boot 自动配置。要启用它，请将以下依赖项添加到项目的 Maven pom.xml 文件中：
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-vector-store-qdrant</artifactId>
</dependency>
或添加到你的 Gradle build.gradle 构建文件中。
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-vector-store-qdrant'
}
请参见 依赖管理 部分，以将 Spring AI BOM 添加到你的构建文件中。
请查看 配置参数 列表，以了解向量存储的默认值和配置选项。
请参阅 Artifact Repositories 部分，以在构建文件中添加 Maven Central 和/或 Snapshot Repositories。
向量存储（vector store）实现可以为您初始化所需的模式（schema），但您必须通过以下方式之一显式选择加入（opt-in）：在构建器（builder）中指定 initializeSchema 布尔值，或在 application.properties 文件中设置 …initialize-schema=true。
这是一次破坏性更改！在 Spring AI 的早期版本中，此 schema 初始化是默认执行的。
此外，还需要配置 EmbeddingModel bean。有关更多信息，请参阅 EmbeddingModel 部分。
现在您可以在应用程序中将 QdrantVectorStore 自动配置为向量存储。
@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());
配置属性
要连接到 Qdrant 并使用 QdrantVectorStore，您需要提供实例的访问详情。您可以通过 Spring Boot 的 application.yml 提供一个简单的配置：
spring:
ai:
vectorstore:
qdrant:
host: <qdrant host>
port: <qdrant grpc port>
api-key: <qdrant api key>
collection-name: <collection name>
content-field-name: <content field name>
use-tls: false
initialize-schema: true
以 spring.ai.vectorstore.qdrant.* 开头的属性用于配置 QdrantVectorStore：
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.vectorstore.qdrant.host | Qdrant 服务器的主机名 | localhost |
spring.ai.vectorstore.qdrant.port | Qdrant 服务器的 gRPC 端口 | 6334 |
spring.ai.vectorstore.qdrant.api-key | 用于身份验证的 API 密钥 | - |
spring.ai.vectorstore.qdrant.collection-name | 要使用的集合名称 | vector_store |
spring.ai.vectorstore.qdrant.content-field-name | Qdrant 负载中存储文档内容的字段名称。当集成使用不同字段名称（如 "page_content"、"text"、"content"）的现有集合时非常有用。 | doc_content |
spring.ai.vectorstore.qdrant.use-tls | 是否使用 TLS(HTTPS) | false |
spring.ai.vectorstore.qdrant.initialize-schema | 是否初始化 schema | false |
手动配置
除了使用 Spring Boot 自动配置，你还可以手动配置 Qdrant 向量存储。为此，你需要在项目中添加 spring-ai-qdrant-store：
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-qdrant-store</artifactId>
</dependency>
或添加到你的 Gradle build.gradle 构建文件中。
dependencies {
implementation 'org.springframework.ai:spring-ai-qdrant-store'
}
请参阅 依赖管理 章节，将 Spring AI BOM 添加到你的构建文件中。
创建一个 Qdrant 客户端 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：
@Bean
public VectorStore vectorStore(QdrantClient qdrantClient, EmbeddingModel embeddingModel) {
return QdrantVectorStore.builder(qdrantClient, embeddingModel)
.collectionName("custom-collection") // Optional: defaults to "vector_store"
.contentFieldName("page_content") // Optional: defaults to "doc_content"
.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(OpenAiEmbeddingOptions.builder().apiKey(System.getenv("OPENAI_API_KEY")).build());
}
处理现有集合
在将 Spring AI 与现有的 Qdrant 集合集成时，你可能需要配置内容字段名以匹配已使用的 schema。
默认情况下，QdrantVectorStore 将文档内容存储在名为 doc_content 的字段中。但是，现有集合可能会使用不同的命名约定，例如 page_content、text、content 或其他自定义名称。
使用自定义内容字段名称
你可以配置 content 字段名以匹配现有的 collection 架构：
Via 属性：
spring:
ai:
vectorstore:
qdrant:
collection-name: my_existing_collection
content-field-name: page_content # Match existing schema
通过编程方式：
@Bean
public VectorStore vectorStore(QdrantClient qdrantClient, EmbeddingModel embeddingModel) {
return QdrantVectorStore.builder(qdrantClient, embeddingModel)
.collectionName("my_existing_collection")
.contentFieldName("text") // Use existing field name
.initializeSchema(false) // Don't recreate existing schema
.build();
}
元数据过滤
你也可以在 Qdrant 存储中使用通用的、可移植的 metadata 过滤器。
例如，你可以使用文本表达式语言：
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：
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 专有的过滤表达式。
访问 Native Client
Qdrant Vector Store 实现通过 getNativeClient() 方法提供对底层原生 Qdrant 客户端（QdrantClient）的访问：
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 接口暴露）的访问权限。