Qdrant 是一款高性能开源向量数据库，支持 HNSW 算法及元数据过滤。本文详解 Qdrant 核心特性，演示基于 Docker 的快速部署，并提供 Spring Boot 原生客户端集成方案。内容涵盖集合管理、点操作及 Spring AI 与 LangChain4j 框架的 RAG 应用构建，包含文档加载、相似度搜索及聊天控制器实现。此外还涉及向量维度选择、分片策略及索引参数调优等性能优化最佳实践，助力开发者快速搭建智能文档问答系统。
在人工智能和大语言模型（LLM）应用日益普及的今天，向量数据库成为了构建 AI 应用的关键基础设施。Qdrant 作为一款高性能的开源向量数据库，以其卓越的性能、易用性和丰富的功能特性，正在成为越来越多开发者的首选。
本文将详细介绍 Qdrant 的核心特性，并展示如何在 Spring Boot 项目中集成 Qdrant，以及如何配合 Spring AI 和 LangChain 等主流 AI 框架构建智能应用。
Qdrant（读音：quadrant）是一个用 Rust 编写的开源向量相似度搜索引擎，专门用于存储、搜索和管理向量嵌入（Vector Embeddings）。它提供了高性能的向量搜索能力，支持过滤、负载均衡等功能，非常适合构建推荐系统、语义搜索、AI 助手等应用。
最简单的启动方式是使用 Docker：
# 启动 Qdrant 实例
docker run -p6333:6333 -p6334:6334 \
-v$(pwd)/qdrant_storage:/qdrant/storage \
qdrant/qdrant
或者使用 docker-compose：
version: '3.8'
services:
qdrant:
image: qdrant/qdrant
ports:
- "6333:6333"
- "6334:6334"
volumes:
- ./qdrant_storage:/qdrant/storage
启动后：
在 pom.xml 中添加 Qdrant Java 客户端依赖：
<dependencies>
<!-- Qdrant Java Client -->
<dependency>
<groupId>io.qdrant</groupId>
<artifactId>qdrant-java-client</artifactId>
<version>1.7.0</version>
</dependency>
<!-- Spring Boot Web (可选，用于构建 REST API) -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- Lombok (简化代码) -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
</dependencies>
创建配置类来初始化 Qdrant 客户端：
package com.example.qdrant.config;
import io.qdrant.client.QdrantClient;
import io.qdrant.client.QdrantGrpcClient;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class QdrantConfig {
@Value("${qdrant.host:localhost}")
private String host;
@Value("${qdrant.port:6334}")
private int port;
@Value("${qdrant.api-key:}")
private String apiKey;
@Bean
public QdrantClient qdrantClient() {
QdrantGrpcClient.Builder builder = QdrantGrpcClient.newBuilder()
.host(host)
.port(port);
if (!apiKey.isEmpty()) {
builder.withApiKey(apiKey);
}
return builder.build();
}
}
在 application.yml 中添加配置：
qdrant:
host: localhost
port: 6334
api-key: # 如果设置了 API Key
spring:
application:
name: qdrant-demo
package com.example.qdrant.service;
import io.qdrant.client.QdrantClient;
import io.qdrant.client.grpc.Collections;
import io.qdrant.client.grpc.Points;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import java.util.List;
@Slf4j
@Service
@RequiredArgsConstructor
public class QdrantCollectionService {
private final QdrantClient qdrantClient;
/**
* 创建集合
*/
public void createCollection(String collectionName, int vectorSize) throws Exception {
Collections.VectorParams vectorParams = Collections.VectorParams.newBuilder()
.setSize(vectorSize)
.setDistance(Collections.Distance.Cosine)
.build();
qdrantClient.createCollectionAsync(
collectionName,
Collections.CreateCollection.newBuilder().setVectorsConfig(vectorParams).build()
).get();
log.info("Collection '{}' created successfully", collectionName);
}
/**
* 删除集合
*/
public void deleteCollection(String collectionName) throws Exception {
qdrantClient.deleteCollectionAsync(collectionName).get();
log.info("Collection '{}' deleted successfully", collectionName);
}
/**
* 检查集合是否存在
*/
public boolean collectionExists(String collectionName) Exception {
Collections. qdrantClient.getCollectionInfoAsync(collectionName).get();
info != ;
}
Collections.CollectionInfo Exception {
qdrantClient.getCollectionInfoAsync(collectionName).get();
}
}
package com.example.qdrant.service;
import io.qdrant.client.QdrantClient;
import io.qdrant.client.grpc.Points;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import java.util.List;
import java.util.Map;
@Slf4j
@Service
@RequiredArgsConstructor
public class QdrantPointService {
private final QdrantClient qdrantClient;
/**
* 插入/更新向量点
*/
public void upsertPoints(String collectionName, List<PointData> points) throws Exception {
List<Points.PointStruct> pointStructs = points.stream()
.map(this::convertToPointStruct)
.toList();
qdrantClient.upsertPointAsync(
collectionName,
Points.UpsertPoints.newBuilder().addAllPoints(pointStructs).build()
).get();
log.info("Successfully upserted {} points to collection '{}'", points.size(), collectionName);
}
/**
* 搜索向量
*/
public List<SearchResult> search(String collectionName, List<Float> vector, int limit, Map<String, String> filter) throws Exception {
Points.SearchPoints.Builder searchBuilder = Points.SearchPoints.newBuilder()
.addAllVector(vector)
.setLimit(limit)
.withVectorSelector(Points.QueryVector.newBuilder().build());
// 添加过滤条件
if (filter != null && !filter.isEmpty()) {
Points.Filter Points.Filter.newBuilder()
.addMust(Points.Condition.newBuilder()
.setField(Points.FieldCondition.newBuilder()
.setKey()
.setMatch(Points.Match.newBuilder().setTextValue(filter.get()).build()))
.build())
.build();
searchBuilder.setFilter(filterBuilder);
}
List<Points.RetrievedPoint> results = qdrantClient.searchPointAsync(
collectionName, searchBuilder.build()).get();
results.stream()
.map(::convertToSearchResult)
.toList();
}
Exception {
Points. Points.PointsSelector.newBuilder()
.setPointsSelector(Points.PointsIdsList.newBuilder()
.addAllIds(ids.stream()
.map(id -> Points.PointId.newBuilder().setNum(id).build())
.toList())
.build())
.build();
qdrantClient.deletePointAsync(collectionName, selector).get();
log.info(, ids.size(), collectionName);
}
Points.PointStruct {
Points.PointStruct. Points.PointStruct.newBuilder()
.setId(Points.PointId.newBuilder().setNum(pointData.getId()).build())
.addAllVector(pointData.getVector());
(pointData.getPayload() != ) {
pointData.getPayload().forEach((key, value) -> {
builder.putPayload(key, Points.Value.newBuilder().setStringValue(value.toString()).build());
});
}
builder.build();
}
SearchResult {
SearchResult.builder()
.id(retrievedPoint.getId().getNum())
.score(retrievedPoint.getScore())
.payload(retrievedPoint.getPayloadMap())
.build();
}
}
{
Long id;
List<Float> vector;
Map<String, Object> payload;
}
{
Long id;
score;
Map<String, Points.Value> payload;
}
Spring AI 是 Spring 生态系统中新兴的 AI 框架，提供了与各种 LLM 和向量数据库集成的统一接口。
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-qdrant-spring-boot-starter</artifactId>
<version>1.0.0-M4</version>
</dependency>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-openai-spring-boot-starter</artifactId>
<version>1.0.0-M4</version>
</dependency>
spring:
ai:
# OpenAI 配置（用于生成嵌入）
openai:
api-key: ${OPENAI_API_KEY}
# Qdrant 配置
vectorstore:
qdrant:
host: localhost
port: 6334
collection-name: documents
initialize-schema: true
package com.example.qdrant.service;
import org.springframework.ai.document.Document;
import org.springframework.ai.qdrant.QdrantVectorStore;
import org.springframework.ai.reader.TextReader;
import org.springframework.ai.transformer.splitter.TokenTextSplitter;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.core.io.Resource;
import org.springframework.stereotype.Service;
import java.util.List;
@Service
@RequiredArgsConstructor
public class RAGService {
private final VectorStore vectorStore;
private final QdrantVectorStore qdrantVectorStore;
/**
* 加载并存储文档
*/
public void loadAndStoreDocuments(Resource resource) throws Exception {
// 读取文档
TextReader textReader = new TextReader(resource);
List<Document> documents = textReader.get();
// 分割文档
TokenTextSplitter splitter = new TokenTextSplitter();
List<Document> splitDocuments = splitter.apply(documents);
// 存储到向量数据库
vectorStore.add(splitDocuments);
log.info("Stored {} document chunks in Qdrant", splitDocuments.size());
}
/**
* 相似度搜索
*/
public List<Document> {
vectorStore.similaritySearch(SearchRequest.query(query).withTopK(topK));
}
List<Document> {
vectorStore.similaritySearch(
SearchRequest.query(query).withTopK(topK).withFilterExpression( + category + ));
}
{
vectorStore.delete(ids);
}
}
package com.example.qdrant.controller;
import org.springframework.ai.chat.messages.UserMessage;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.openai.OpenAiChatModel;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.web.bind.annotation.*;
import java.util.stream.Collectors;
@RestController
@RequestMapping("/api/chat")
@RequiredArgsConstructor
public class ChatController {
private final OpenAiChatModel chatModel;
private final VectorStore vectorStore;
@PostMapping
public String chat(@RequestBody ChatRequest request) {
// 1. 检索相关文档
List<Document> relevantDocs = vectorStore.similaritySearch(
SearchRequest.query(request.getMessage()).withTopK(3));
// 2. 构建增强提示词
String context = relevantDocs.stream()
.map(Document::getContent)
.collect(Collectors.joining("\n\n"));
String enhancedPrompt = String.format(
"Based on the following context:\n\n%s\n\nAnswer the question: %s",
context, request.getMessage());
// 3. 调用 LLM
ChatResponse response = chatModel.call(new ( (enhancedPrompt)));
response.getResult().getOutput().getContent();
}
}
LangChain4j 是 LangChain 的 Java 实现，提供了丰富的 AI 应用构建能力。
<dependencies>
<!-- LangChain4j Qdrant -->
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-qdrant</artifactId>
<version>0.34.0</version>
</dependency>
<!-- LangChain4j OpenAI -->
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-open-ai</artifactId>
<version>0.34.0</version>
</dependency>
</dependencies>
package com.example.qdrant.config;
import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.model.openai.OpenAiEmbeddingModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.store.embedding.qdrant.QdrantEmbeddingStore;
import io.qdrant.client.QdrantClient;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class LangChainConfig {
@Value("${langchain4j.openai.api-key}")
private String openAiApiKey;
@Value("${qdrant.host:localhost}")
private String qdrantHost;
@Value("${qdrant.port:6334}")
private int qdrantPort;
@Bean
public QdrantEmbeddingStore qdrantEmbeddingStore(QdrantClient qdrantClient) {
return QdrantEmbeddingStore.builder()
.host(qdrantHost)
.port(qdrantPort)
.collectionName("langchain_docs")
.build();
}
@Bean
public OpenAiEmbeddingModel embeddingModel() {
return OpenAiEmbeddingModel.builder()
.apiKey(openAiApiKey)
.build();
}
@Bean
public OpenAiChatModel chatModel() {
return OpenAiChatModel.builder()
.apiKey(openAiApiKey)
.build();
}
@Bean
public ConversationRetriever {
EmbeddingStoreRetriever.builder()
.embeddingStore(embeddingStore)
.embeddingModel(embeddingModel)
.maxResults()
.minScore()
.build();
}
}
package com.example.qdrant.service;
import dev.langchain4j.data.document.Document;
import dev.langchain4j.data.document.DocumentSplitter;
import dev.langchain4j.data.document.splitter.DocumentSplitters;
import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.model.openai.OpenAiEmbeddingModel;
import dev.langchain4j.store.embedding.EmbeddingStore;
import dev.langchain4j.store.embedding.EmbeddingStoreIngestor;
import dev.langchain4j.store.embedding.qdrant.QdrantEmbeddingStore;
import dev.langchain4j.service.AiServices;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import java.nio.file.Paths;
import java.util.List;
@Slf4j
@Service
@RequiredArgsConstructor
public class LangChainRAGService {
private final QdrantEmbeddingStore embeddingStore;
private final OpenAiEmbeddingModel embeddingModel;
private final OpenAiChatModel chatModel;
/**
* 加载文档到向量存储
*/
public void ingestDocuments(String filePath) throws Exception {
// 创建文档摄入器
EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder()
.embeddingStore(embeddingStore)
.embeddingModel(embeddingModel)
.textSegmentSplitter(DocumentSplitters.recursive(, ))
.build();
FileSystemDocumentLoader.loadDocument(Paths.get(filePath));
ingestor.ingest(document);
log.info();
}
String {
{
String ;
}
AiServices.builder(Assistant.class)
.chatLanguageModel(chatModel)
.retriever(EmbeddingStoreRetriever.from(embeddingStore, embeddingModel, , ))
.build();
assistant.chat(message);
}
List<TextSegment> {
List<EmbeddingMatch<TextSegment>> matches = embeddingStore.findRelevant(
embeddingModel.embed(query).content(), topK);
matches.stream()
.map(EmbeddingMatch::embedded)
.toList();
}
}
┌─────────────┐
│ 用户查询 │
└──────┬──────┘
▼
┌─────────────────────┐
│ REST API 层 │
├─────────────────────┤
│ /api/chat │
│ /api/documents │
└──────┬──────────────┘
▼
┌─────────────────────┐
│ 业务服务层 │
├─────────────────────┤
│ - RAGService │
│ - DocumentService │
└──────┬──────────────┘
▼
┌──────────────────────────┐
│ AI 框架层 │
├──────────────────────────┤
│ - Spring AI / LangChain4j│
│ - Embedding Model │
│ - Chat Model │
└──────┬───────────────────┘
▼
┌──────────────────────────┐
│ Qdrant 向量数据库 │
├──────────────────────────┤
│ - Collection: documents │
│ - Vector Search │
└──────────────────────────┘
package com.example.qdrant;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import dev.langchain4j.service.EnableAiServices;
@SpringBootApplication
@EnableAiServices // LangChain4j
public class QdrantDemoApplication {
public static void main(String[] args) {
SpringApplication.run(QdrantDemoApplication.class, args);
}
}
@RestController
@RequestMapping("/api")
@RequiredArgsConstructor
public class DocumentController {
private final RAGService ragService;
private final LangChainRAGService langChainRAGService;
/**
* 上传文档
*/
@PostMapping("/documents/upload")
public ResponseEntity<String> uploadDocument(@RequestParam("file") MultipartFile file) {
try {
Path tempFile = Files.createTempFile("upload", ".txt");
file.transferTo(tempFile);
// 使用 Spring AI 方式
// ragService.loadAndStoreDocuments(new FileSystemResource(tempFile));
// 使用 LangChain4j 方式
langChainRAGService.ingestDocuments(tempFile.toString());
return ResponseEntity.ok("Document uploaded and processed successfully");
} catch (Exception e) {
log.error("Error processing document", e);
return ResponseEntity.status(500).body("Error processing document");
}
}
/**
* 问答接口
*/
@PostMapping("/chat")
public ResponseEntity<ChatResponse> chat(@RequestBody ChatRequest request) {
String answer = langChainRAGService.chat(request.getMessage());
return ResponseEntity.ok( (answer));
}
ResponseEntity<List<SearchResult>> {
List<TextSegment> results = langChainRAGService.semanticSearch(query, topK);
List<SearchResult> searchResults = results.stream()
.map(segment -> (segment.text(), ))
.toList();
ResponseEntity.ok(searchResults);
}
}
建议：根据模型选择合适的维度，维度越高精度越高但存储和搜索成本也越高。
// 创建分片集合
Collections.CreateCollection createCollection = Collections.CreateCollection.newBuilder()
.setVectorsConfig(vectorParams)
.setShardNumber(4) // 4 个分片
.setReplicationFactor(2) // 每个分片 2 个副本
.build();
Collections.HnswConfigDiff hnswConfig = Collections.HnswConfigDiff.newBuilder()
.setM(16) // 每个节点连接数（范围 2-100）
.setEfConstruct(100) // 构建索引时的搜索深度
.setFullScanThreshold(10000) // 触发全扫描的向量数量阈值
.build();
// 批量插入时控制批次大小
public void batchUpsert(String collectionName, List<PointData> allPoints) throws Exception {
int batchSize = 100;
List<List<PointData>> batches = Lists.partition(allPoints, batchSize);
for (List<PointData> batch : batches) {
upsertPoints(collectionName, batch);
Thread.sleep(100); // 避免 QPS 过高
}
}
Qdrant 作为一款现代化的向量数据库，具有以下优势：
通过本文的介绍，你应该能够：
接下来，建议你：
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online