Milvus

本站(springdoc.cn)中的内容来源于 spring.io ，原始版权归属于 spring.io。由 springdoc.cn 进行翻译，整理。可供个人学习、研究，未经许可，不得进行任何转载、商用或与之相关的行为。 商标声明：Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。

Milvus 是一个开源的向量数据库，在数据科学和机器学习领域获得了广泛关注。其突出特点之一是对向量索引和查询的强大支持。Milvus 采用最先进的算法来加速搜索过程，即使在处理大规模数据集时也能高效检索相似向量。

先决条件

  • 一个正在运行的 Milvus 实例。以下选项可用：

  • 如需生成 MilvusVectorStore 存储的嵌入向量，需为 EmbeddingModel 配置 API Key。

依赖

Spring AI 的自动配置及 Starter 模块的构件名称发生重大变更。详情请查阅 升级说明。

然后在项目中添加 Milvus VectorStore 的 Boot Starter 依赖：

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

或者添加到你的 Gradle build.gradle 构建文件中：

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-milvus'
}
参考 “依赖管理” 部分将 Spring AI BOM 添加到构建文件，并参考 “Artifact 仓库” 部分添加 Maven Central 和/或 Snapshot Repositories 至构建配置。

向量存储实现可自动初始化所需 Schema，但需通过以下方式显式启用：

  • 在构造函数中指定 initializeSchema 布尔参数

  • 或在 application.properties 文件中设置 …​initialize-schema=true

注意：此为破坏性变更！旧版 Spring AI 中该 Schema 初始化默认为自动执行。

向量存储还需一个 EmbeddingModel 实例来计算文档嵌入。可从现有 EmbeddingModel 实现 中选择。

要连接并配置 MilvusVectorStore，需提供实例的访问参数。可通过 Spring Boot 的 application.yml 进行简易配置：

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 VectorStore 并使用它：

@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。需在项目中添加以下依赖：

<dependency>
	<groupId>org.springframework.ai</groupId>
	<artifactId>spring-ai-milvus-store</artifactId>
</dependency>
参考 “依赖管理” 部分将 Spring AI BOM 添加至构建文件。

要在应用中配置 MilvusVectorStore，可使用以下设置：

	@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 存储使用通用的、可移植的 元数据过滤器。

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

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

使用 MilvusSearchRequest

MilvusSearchRequest 继承自 SearchRequest，支持使用 Milvus 特有的搜索参数，例如原生表达式和 JSON 格式的搜索参数配置。

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 特有搜索功能提供了更高的灵活性。

MilvusSearchRequest 中的 nativeExpression 和 searchParamsJson 重要性

这两个参数提高了 Milvus 的搜索精度，并确保最佳查询性能：

nativeExpression： 使用 Milvus 原生过滤表达式启用附加过滤功能。 Milvus 过滤

示例:

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

searchParamsJson： 使用 Milvus 默认索引 IVF_FLAT 时调整搜索行为所必需的。 Milvus 向量索引

默认情况下，IVF_FLAT 要求设置 nprobe 以获得准确结果。如果不指定，nprobe 默认为 1，这可能导致检索结果不准确，甚至为零。

示例:

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

使用 nativeExpression 可以确保高级过滤，而 searchParamsJson 则可以防止因默认 nprobe 值过低而导致搜索无效。

Milvus VectorStore 配置属性

你可以在 Spring Boot 配置中使用以下属性来自定义 Milvus 向量存储。

属性 说明 默认值

spring.ai.vectorstore.milvus.database-name

使用的 Milvus 数据库名称。

default

spring.ai.vectorstore.milvus.collection-name

存储向量的 Milvus 集合名称。

vector_store

spring.ai.vectorstore.milvus.initialize-schema

是否初始化 Milvus 后端

false

spring.ai.vectorstore.milvus.embedding-dimension

存储在 Milvus 集合中的向量维度。

1536

spring.ai.vectorstore.milvus.index-type

为 Milvus 集合创建的索引类型。

IVF_FLAT

spring.ai.vectorstore.milvus.metric-type

用于 Milvus 集合的度量类型。

COSINE

spring.ai.vectorstore.milvus.index-parameters

用于 Milvus 集合的索引参数。

{"nlist":1024}

spring.ai.vectorstore.milvus.id-field-name

集合的 ID 字段名称。

doc_id

spring.ai.vectorstore.milvus.is-auto-id

布尔标志，指示 ID 字段是否使用自动生成。

false

spring.ai.vectorstore.milvus.content-field-name

集合的内容字段名称。

content

spring.ai.vectorstore.milvus.metadata-field-name

集合的元数据字段名称。

metadata

spring.ai.vectorstore.milvus.embedding-field-name

集合的嵌入字段名称。

embedding

spring.ai.vectorstore.milvus.client.host

主机名称或地址。

localhost

spring.ai.vectorstore.milvus.client.port

连接端口

19530

spring.ai.vectorstore.milvus.client.uri

Milvus 实例的 URI

-

spring.ai.vectorstore.milvus.client.token

用于身份识别和认证的令牌。

-

spring.ai.vectorstore.milvus.client.connect-timeout-ms

客户端通道的连接超时值。超时值必须大于零。

10000

spring.ai.vectorstore.milvus.client.keep-alive-time-ms

客户端通道的保活时间值。保活值必须大于零。

55000

spring.ai.vectorstore.milvus.client.keep-alive-timeout-ms

客户端通道的保活超时值。超时值必须大于零。

20000

spring.ai.vectorstore.milvus.client.rpc-deadline-ms

等待服务器响应的截止时间。设置截止时间后，客户端在遇到网络波动导致的快速 RPC 失败时会持续等待。截止时间值必须大于或等于零。

0

spring.ai.vectorstore.milvus.client.client-key-path

客户端密钥路径（用于 TLS 双向认证），仅在 "secure" 为 true 时生效

-

spring.ai.vectorstore.milvus.client.client-pem-path

客户端证书路径（用于 TLS 双向认证），仅在 "secure" 为 true 时生效

-

spring.ai.vectorstore.milvus.client.ca-pem-path

CA 证书路径（用于 TLS 双向认证），仅在 "secure" 为 true 时生效

-

spring.ai.vectorstore.milvus.client.server-pem-path

服务器证书路径（用于 TLS 单向认证），仅在 "secure" 为 true 时生效。

-

spring.ai.vectorstore.milvus.client.server-name

设置 SSL 主机名检查的目标名称覆盖，仅在 "secure" 为 True 时生效。注意：该值会传递给 grpc.ssl_target_name_override。

-

spring.ai.vectorstore.milvus.client.secure

启用连接的安全授权，设置为 True 以开启 TLS。

false

spring.ai.vectorstore.milvus.client.idle-timeout-ms

客户端通道的空闲超时值。超时值必须大于零。

24h

spring.ai.vectorstore.milvus.client.username

此连接的用户名和密码。

root

spring.ai.vectorstore.milvus.client.password

此连接的密码。

milvus

启动 MilvusStore

从 src/test/resources/ 文件夹内运行：

docker-compose up

清理环境：

docker-compose down; rm -Rf ./volumes

然后通过以下地址连接向量存储：

故障排除

如果 Docker 提示资源不足，则执行：

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

访问原生客户端

Milvus VectorStore 实现通过 getNativeClient() 方法提供对底层原生 Milvus 客户端（MilvusServiceClient）的访问：

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 接口暴露。