如需最新的快照版本,请使用 Spring AI 1.1.3spring-doc.cadn.net.cn

Milvus

Milvus 是一个开源向量数据库,在数据科学和机器学习领域备受关注。其突出特点之一在于对向量索引和查询的强大支持。Milvus 采用最先进的尖端算法加速搜索过程,即使在处理大规模数据集时也能高效检索相似向量。spring-doc.cadn.net.cn

前置条件

依赖项

Spring AI自动配置和starter模块的artifact名称有了重大变化。 请参阅升级说明获取更多信息。spring-doc.cadn.net.cn

然后将 Milvus VectorStore boot starter 依赖项添加到您的项目中:spring-doc.cadn.net.cn

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

请将以下内容添加到您的Gradle build.gradle 构建文件中。spring-doc.cadn.net.cn

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-milvus'
}
参考 依赖管理 部分,将 Spring AI BOM 添加到您的构建文件中。 参考 构件仓库 部分,将 Maven Central 和/或 Snapshot 仓库添加到您的构建文件中。

向量存储实现可以为您初始化所需的架构,但您必须通过在适当的构造函数中指定 initializeSchema 布尔值或在 application.properties 文件中设置 …​initialize-schema=true 来选择加入。spring-doc.cadn.net.cn

这是一个破坏性变更!在早期版本的 Spring AI 中,此架构初始化是默认发生的。

Vector Store(向量存储)还需要一个 EmbeddingModel 实例来计算文档的嵌入(embeddings)。 你可以选择一个可用的 EmbeddingModel 实现spring-doc.cadn.net.cn

要连接并配置 MilvusVectorStore,您需要为您的实例提供访问详细信息。 可以通过 Spring Boot 的 application.yml 提供简单的配置spring-doc.cadn.net.cn

spring:
	ai:
		vectorstore:
			milvus:
				client:
					host: "localhost"
					port: 19530
					username: "root"
					password: "milvus"
				databaseName: "default"
				collectionName: "vector_store"
				embeddingDimension: 1536
				indexType: IVF_FLAT
				metricType: COSINE
查看 配置参数 列表以了解默认值和配置选项。

现在您可以在您的应用程序中自动装配 Milvus 向量存储并使用它spring-doc.cadn.net.cn

@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 Milvus Vector Store
vectorStore.add(documents);

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

手动配置

不使用 Spring Boot 自动配置,您可以手动配置 MilvusVectorStore。 要将以下依赖项添加到您的项目中:spring-doc.cadn.net.cn

<dependency>
	<groupId>org.springframework.ai</groupId>
	<artifactId>spring-ai-milvus-store</artifactId>
</dependency>
请参阅依赖管理部分,将Spring AI BOM添加到您的构建文件中。

要在您的应用程序中配置 MilvusVectorStore,您可以使用以下设置:spring-doc.cadn.net.cn

	@Bean
	public VectorStore vectorStore(MilvusServiceClient milvusClient, EmbeddingModel embeddingModel) {
		return MilvusVectorStore.builder(milvusClient, embeddingModel)
				.collectionName("test_vector_store")
				.databaseName("default")
				.indexType(IndexType.IVF_FLAT)
				.metricType(MetricType.COSINE)
				.batchingStrategy(new TokenCountBatchingStrategy())
				.initializeSchema(true)
				.build();
	}

	@Bean
	public MilvusServiceClient milvusClient() {
		return new MilvusServiceClient(ConnectParam.newBuilder()
			.withAuthorization("minioadmin", "minioadmin")
			.withUri(milvusContainer.getEndpoint())
			.build());
	}

元数据过滤

您可以在 Milvus 存储中利用通用的、可移植的 元数据过滤器spring-doc.cadn.net.cn

例如,您可以使用文本表达式语言:spring-doc.cadn.net.cn

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:spring-doc.cadn.net.cn

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());
这些过滤表达式将被转换为等效的 Milvus 过滤器。

使用 MilvusSearchRequest

MilvusSearchRequest 扩展了 SearchRequest,允许您使用 Milvus 特定的搜索参数,例如原生表达式和搜索参数 JSON。spring-doc.cadn.net.cn

MilvusSearchRequest request = MilvusSearchRequest.milvusBuilder()
    .query("sample query")
    .topK(5)
    .similarityThreshold(0.7)
    .nativeExpression("metadata[\"age\"] > 30") // Overrides filterExpression if both are set
    .filterExpression("age <= 30") // Ignored if nativeExpression is set
    .searchParamsJson("{\"nprobe\":128}")
    .build();
List results = vectorStore.similaritySearch(request);

在使用 Milvus 特定搜索功能时,这提供了更大的灵活性。spring-doc.cadn.net.cn

重要性nativeExpressionsearchParamsJson in MilvusSearchRequest

这两个参数提高了 Milvus 搜索精度并确保了最佳的查询性能:spring-doc.cadn.net.cn

nativeExpression: 启用使用 Milvus 原生过滤表达式的额外过滤功能。 Milvus 过滤spring-doc.cadn.net.cn

MilvusSearchRequest request = MilvusSearchRequest.milvusBuilder()
    .query("sample query")
    .topK(5)
    .nativeExpression("metadata['category'] == 'science'")
    .build();

searchParamsJson:在使用 IVF_FLAT(Milvus 的默认索引)时,调整搜索行为的关键参数。 Milvus 向量索引spring-doc.cadn.net.cn

默认情况下,IVF_FLAT 需要设置 nprobe 才能获得准确结果。如果未指定,nprobe 默认为 1,这可能导致召回率低甚至没有搜索结果。spring-doc.cadn.net.cn

MilvusSearchRequest request = MilvusSearchRequest.milvusBuilder()
    .query("sample query")
    .topK(5)
    .searchParamsJson("{\"nprobe\":128}")
    .build();

使用 nativeExpression 确保高级过滤,而 searchParamsJson 防止因默认 nprobe 值过低导致的无效搜索。spring-doc.cadn.net.cn

Milvus VectorStore 属性

您可以在 Spring Boot 配置中使用以下属性来自定义 Milvus 向量存储。spring-doc.cadn.net.cn

<property> </property> <description> </description> 默认值

spring.ai.vectorstore.milvus.database-namespring-doc.cadn.net.cn

要使用的 Milvus 数据库名称。spring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.collection-namespring-doc.cadn.net.cn

用于存储向量的 Milvus 集合名称spring-doc.cadn.net.cn

vector_storespring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.initialize-schemaspring-doc.cadn.net.cn

是否初始化 Milvus 的后端spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.embedding-dimensionspring-doc.cadn.net.cn

要存储在 Milvus 集合中的向量的维度。spring-doc.cadn.net.cn

1536spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.index-typespring-doc.cadn.net.cn

要为 Milvus 集合创建的索引类型。spring-doc.cadn.net.cn

IVF_FLATspring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.metric-typespring-doc.cadn.net.cn

用于 Milvus 集合的指标类型。spring-doc.cadn.net.cn

COSINEspring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.index-parametersspring-doc.cadn.net.cn

用于 Milvus 集合的索引参数。spring-doc.cadn.net.cn

{"nlist":1024}spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.id-field-namespring-doc.cadn.net.cn

集合的 ID 字段名称spring-doc.cadn.net.cn

doc_idspring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.auto-idspring-doc.cadn.net.cn

布尔标志,指示是否对 ID 字段使用自动 IDspring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.content-field-namespring-doc.cadn.net.cn

集合的内容字段名称spring-doc.cadn.net.cn

内容spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.metadata-field-namespring-doc.cadn.net.cn

集合的元数据字段名称spring-doc.cadn.net.cn

元数据spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.embedding-field-namespring-doc.cadn.net.cn

集合的嵌入字段名称spring-doc.cadn.net.cn

嵌入spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.client.hostspring-doc.cadn.net.cn

主机的名称或地址。spring-doc.cadn.net.cn

本机主机spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.client.portspring-doc.cadn.net.cn

连接端口。spring-doc.cadn.net.cn

19530spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.client.urispring-doc.cadn.net.cn

Milvus 实例的 urispring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.client.tokenspring-doc.cadn.net.cn

作为用于标识和认证目的的密钥的Tokens。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.client.connect-timeout-msspring-doc.cadn.net.cn

客户端通道的连接超时值。超时值必须大于零。spring-doc.cadn.net.cn

10000spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.client.keep-alive-time-msspring-doc.cadn.net.cn

客户端通道的保持连接时间值。保持连接的值必须大于零。spring-doc.cadn.net.cn

55000spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.client.keep-alive-timeout-msspring-doc.cadn.net.cn

客户端通道的保活超时值。该超时值必须大于零。spring-doc.cadn.net.cn

20000spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.client.rpc-deadline-msspring-doc.cadn.net.cn

您愿意等待服务器回复的最长时间。通过设置截止时间,客户端在遇到因网络波动导致的快速 RPC 失败时会等待。截止时间值必须大于或等于零。spring-doc.cadn.net.cn

0spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.client.client-key-pathspring-doc.cadn.net.cn

用于 TLS 双向认证的 client.key 路径,仅在“secure”为 true 时生效spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.client.client-pem-pathspring-doc.cadn.net.cn

用于 TLS 双向认证的 client.pem 路径,仅在 "secure" 为 true 时生效spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.client.ca-pem-pathspring-doc.cadn.net.cn

tls 双向认证的 ca.pem 路径,仅在 "secure" 为 true 时生效spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.client.server-pem-pathspring-doc.cadn.net.cn

tls 单向认证的 server.pem 路径,仅在 "secure" 为 true 时生效。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.client.server-namespring-doc.cadn.net.cn

设置用于 SSL 主机名检查的目标名称覆盖,仅在 "secure" 为 True 时生效。注意:此值传递给 grpc.ssl_target_name_overridespring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.client.securespring-doc.cadn.net.cn

保护此连接的授权,设置为 True 以启用 TLS。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.client.idle-timeout-msspring-doc.cadn.net.cn

客户端通道的空闲超时值。超时值必须大于零。spring-doc.cadn.net.cn

24hspring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.client.usernamespring-doc.cadn.net.cn

此连接的用户名和密码。spring-doc.cadn.net.cn

根目录spring-doc.cadn.net.cn

spring.ai.vectorstore.milvus.client.passwordspring-doc.cadn.net.cn

此连接的密码。spring-doc.cadn.net.cn

Milvusspring-doc.cadn.net.cn

启动 Milvus Store

src/test/resources/ 文件夹内运行:spring-doc.cadn.net.cn

docker-compose up

清理环境:spring-doc.cadn.net.cn

docker-compose down; rm -Rf ./volumes

然后连接到向量存储 http://localhost:19530 或用于管理 http://localhost:9001(用户:minioadmin,密码:minioadminspring-doc.cadn.net.cn

故障排除

如果 Docker 报告资源问题,请执行:spring-doc.cadn.net.cn

docker system prune --all --force --volumes

访问原生客户端

Milvus 向量存储实现通过 getNativeClient() 方法提供对底层原生 Milvus 客户端 (MilvusServiceClient) 的访问:spring-doc.cadn.net.cn

MilvusVectorStore vectorStore = context.getBean(MilvusVectorStore.class);
Optional<MilvusServiceClient> nativeClient = vectorStore.getNativeClient();

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

原生客户端使您能够访问 Milvus 特有的功能和操作,这些功能和操作可能无法通过 VectorStore 接口暴露。spring-doc.cadn.net.cn