在 Java/Spring Boot +…

适用于需要为 Java/Spring Boot 应用接入 Qdrant 向量数据库，完成 embedding 存储、相似搜索、RAG/语义搜索/推荐等向量检索任务的场景。

适用场景

解决思路

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 使用 `io.qdrant:client:1.15.0`；Gradle 使用 `implementation 'io.qdrant:client:1.15.0'`。
3. 初始化客户端：基础方式 `QdrantClient client = new QdrantClient(QdrantGrpcClient.newBuilder("localhost").build());`；生产环境带 API key 方式 `QdrantClient client = new QdrantClient(QdrantGrpcClient.newBuilder("localhost", 6334, false).withApiKey("YOUR_API_KEY").build());`。
4. 创建 collection：调用 `client.createCollectionAsync("search-collection", VectorParams.newBuilder().setDistance(Distance.Cosine).setSize(384).build()).get();`；验证时检查 `client.getCollectionAsync("search-collection").get()`。
5. Upsert 向量：构建 `PointStruct` 列表，设置 `id`、`vectors` 和 payload，例如 `putAllPayload(Map.of("title", value("Spring Boot Documentation")))`，然后调用 `client.upsertAsync("search-collection", points).get();`；验证该调用未抛异常。
6. 搜索向量：使用 `client.queryAsync(QueryPoints.newBuilder().setCollectionName("search-collection").setLimit(5).setQuery(nearest(0.2f, 0.1f, 0.9f, 0.7f)).build()).get();`。
7. 过滤搜索：使用 `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();`。
8. LangChain4j RAG 集成：使用 `QdrantEmbeddingStore.builder().collectionName("rag-collection").host("localhost").port(6334).apiKey("YOUR_API_KEY").build();` 构建 `EmbeddingStore<TextSegment>`。
9. Spring Boot + LangChain4j 配置：定义 `@Bean public EmbeddingStore<TextSegment> embeddingStore()`，内部用 `QdrantEmbeddingStore.builder().collectionName("rag-collection").host(host).port(port).build();`；定义 `@Bean public EmbeddingModel embeddingModel()` 返回 `new AllMiniLmL6V2EmbeddingModel();`。
10. Spring Boot 注入 QdrantClient：创建 `@Configuration` 类 `QdrantConfig`，用 `@Value("${qdrant.host:localhost}")` 和 `@Value("${qdrant.port:6334}")` 注入 host/port，定义 `@Bean public QdrantClient qdrantClient()` 返回 `new QdrantClient(QdrantGrpcClient.newBuilder(host, port, false).build());`。
11. REST 搜索端点：创建 `@RestController` 和 `@RequestMapping("/api/search")` 的 `SearchController`，注入 `VectorSearchService`；`@GetMapping` 方法接收 `@RequestParam String query`，用 `embeddingModel.embed(query).content().vectorAsList()` 生成查询向量，再调用 `searchService.search("documents", queryVector)`。
12. 选择距离度量：归一化文本 embedding 使用 `Cosine`，非归一化使用 `Euclidean`。
13. 批量 upsert：优先使用批量操作，而不是逐条插入点。
14. 配置连接池：高吞吐生产负载下配置连接池。
15. 异步错误处理：用 try/catch 包裹异步操作，处理 `ExecutionException` 和 `InterruptedException`。
16. 管理 API key：存放在环境变量或 Spring config 中，绝不硬编码。
17. 多租户存储：实现 `upsertForTenant(String tenantId, List<PointStruct> points)`，collectionName 设为 `"tenant_" + tenantId + "_documents"`，然后调用 `client.upsertAsync(collectionName, points).get();`。
18. 生产 Docker Compose：定义 `qdrant` 服务，使用 `image: qdrant/qdrant:v1.7.0`，暴露 `6333:6333` 和 `6334:6334`，挂载 `qdrant_storage:/qdrant/storage`。
19. 确保向量维度与 embedding 模型完全一致；维度不匹配会导致 upsert 错误。
20. 输入验证：在文档摄取前清理所有文档内容；不可信 payload 可能包含 prompt injection 攻击。
21. 内容过滤：将检索到的文档传给 LLM 前，先应用内容过滤。
22. 为大 collection 建立适当索引，以获得可接受的搜索性能。
23. 生产环境使用 gRPC API（端口 6334）；REST API（端口 6333）仅用于调试。
24. 重建 collection 会删除所有数据；生产环境实现备份策略。
25. 查阅参考：`references/references.md`（完整客户端 API 文档）、`references/examples.md`（完整 Spring Boot 示例）、Qdrant 文档和 LangChain4j 文档。

适用边界 · 注意事项

• 不使用 Java/Spring Boot/LangChain4j 技术栈时，不应套用本经验。
• 没有可部署或可访问的 Qdrant 实例，或不想引入 Qdrant 依赖时，不适用。
• 只需要简单关键词搜索、无需向量相似检索/RAG/语义搜索/推荐时，不适用。