跳到主要内容

Milvus

Deepseek 3.2 中英对照 Milvus

Milvus 是一款开源向量数据库，在数据科学和机器学习领域引起了广泛关注。其突出的特点之一在于其对向量索引和查询的强大支持。Milvus 采用先进的前沿算法来加速搜索过程，使其在检索相似向量时异常高效，即使处理海量数据集也不例外。

前提条件​

  • 运行中的 Milvus 实例。有以下选项可用：

  • 如需要，用于生成 MilvusVectorStore 所存储嵌入向量的 EmbeddingModel 的 API 密钥。

依赖项​

备注

Spring AI 的自动配置和 starter 模块的 artifact 名称已发生重大变更。更多信息请参阅升级说明。

然后在你的项目中添加 Milvus VectorStore 启动器依赖：

<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物料清单添加到您的构建文件中。参考制品仓库部分，将Maven中央仓库和/或快照仓库添加到您的构建文件中。

向量存储实现可以为您初始化必要的架构，但您必须通过指定相关构造函数中的 initializeSchema 布尔值，或在 application.properties 文件中设置 …​initialize-schema=true 来选择启用此功能。

备注

这是一个破坏性变更！在 Spring AI 的早期版本中，默认会进行此模式初始化。

向量存储还需要一个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 向量存储并使用它。

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

nativeExpression 和 searchParamsJson 在 MilvusSearchRequest 中的重要性​

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

nativeExpression：允许使用 Milvus 的原生过滤表达式进行额外过滤。Milvus 过滤

示例：

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

searchParamsJson: 在使用 IVF_FLAT（Milvus 的默认索引）时，用于调整搜索行为的关键参数。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 数据库名称。默认
spring.ai.vectorstore.milvus.collection-name用于存储向量的 Milvus 集合名称向量存储
spring.ai.vectorstore.milvus.initialize-schema是否初始化 Milvus 后端false
spring.ai.vectorstore.milvus.embedding-dimension待存储在 Milvus 集合中的向量的维度。1536
spring.ai.vectorstore.milvus.index-typeMilvus 集合中要创建的索引类型。IVF_FLAT
spring.ai.vectorstore.milvus.metric-typeMilvus 集合所使用的度量类型。余弦
spring.ai.vectorstore.milvus.index-parametersMilvus 集合的索引参数。{"nlist":1024}
spring.ai.vectorstore.milvus.id-field-name集合的 ID 字段名称doc_id
spring.ai.vectorstore.milvus.auto-id布尔标志，用于指示是否为 ID 字段启用了自动生成 ID。false
spring.ai.vectorstore.milvus.content-field-name集合的内容字段名称内容
spring.ai.vectorstore.milvus.metadata-field-name集合的元数据字段名称元数据
spring.ai.vectorstore.milvus.embedding-field-name集合的嵌入字段名称嵌入
spring.ai.vectorstore.milvus.client.host主机名称或地址。localhost
spring.ai.vectorstore.milvus.client.port连接端口。19530
spring.ai.vectorstore.milvus.client.uriMilvus 实例的 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-pathtls双向认证的client.pem路径，仅在"secure"为true时生效-
spring.ai.vectorstore.milvus.client.ca-pem-pathtls双向认证的ca.pem路径，仅在"secure"为true时生效-
spring.ai.vectorstore.milvus.client.server-pem-path用于 TLS 单向认证的 server.pem 路径，仅在 "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客户端通道的空闲超时值。超时值必须大于零。24小时
spring.ai.vectorstore.milvus.client.username此连接的用户名和密码。根
spring.ai.vectorstore.milvus.client.password此连接的密码。milvus

启动 Milvus Store​

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

docker-compose up

清理环境：

docker-compose down; rm -Rf ./volumes

随后连接到向量存储，访问地址为 http://localhost:19530 或管理界面 http://localhost:9001 (用户名: minioadmin, 密码: minioadmin)

故障排除​

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

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

访问原生客户端​

Milvus 向量存储实现通过 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
}

原生客户端让你能够访问那些可能未通过VectorStore接口暴露的Milvus特有功能和操作。