当前位置：首页 > news >正文

MilvusVectorStore 使用指南 ——基于spring-ai（可用于搭建Rag）

news 2026/5/12 17:25:39

MilvusVectorStore是 Spring AI 提供的一个向量存储实现，用于将文档嵌入（embeddings）存储到 Milvus 向量数据库中，并支持高效的相似性搜索。它实现了VectorStore接口，提供了添加、删除和检索文档的基本功能。

本文档将帮助你理解如何配置、初始化并使用MilvusVectorStore。

1. 前提条件

Milvus 服务已启动：确保你的 Milvus 实例（单机或集群）正在运行，并可通过网络访问。
Spring Boot 项目：建议使用 Spring Boot 3.x + Spring AI。
依赖项：在pom.xml或build.gradle中添加必要依赖：

<!-- Spring AI Milvus Starter --><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-milvus-spring-boot-starter</artifactId><version>${spring-ai.version}</version></dependency>

注意：${spring-ai.version}应替换为实际版本（如1.1.3）。

2. 配置 Milvus 连接

方法一：通过`application.yml`自动配置（推荐）

spring:ai:milvus:uri:http://localhost:19530database:defaultcollection-name:my_documentsembedding-dimension:1536# 与你的嵌入模型维度一致（如 OpenAI text-embedding-ada-002 为 1536）

Spring Boot 会自动创建MilvusVectorStoreBean。

方法二：手动构建`MilvusVectorStore`

如果你需要更精细的控制（例如自定义观察器、批处理策略等），可以使用 Builder 模式：

importio.milvus.client.MilvusClient;importio.milvus.param.ConnectParam;importorg.springframework.ai.embedding.EmbeddingModel;importorg.springframework.ai.milvus.MilvusVectorStore;importorg.springframework.ai.vectorstore.VectorStore;@ConfigurationpublicclassVectorStoreConfig{@BeanpublicMilvusClientmilvusClient(){returnnewMilvusClient(ConnectParam.newBuilder().withUri("http://localhost:19530").build());}@BeanpublicVectorStorevectorStore(MilvusClientmilvusClient,EmbeddingModelembeddingModel){returnMilvusVectorStore.builder().milvusClient(milvusClient).embeddingModel(embeddingModel).collectionName("my_documents").databaseName("default").dimension(1536).indexType(IndexType.IVF_FLAT)// 可选.metricType(MetricType.COSINE)// 可选.build();}}

注意：EmbeddingModel（如OpenAiEmbeddingModel）需单独配置。

3. 初始化方法使用说明

MilvusVectorStore是 Spring AI 提供的与Milvus 向量数据库集成的实现类，支持：

自动创建 Milvus Collection（表结构）
文档嵌入（Embedding）自动计算与存储
基于余弦、L2 或内积的相似性搜索
元数据过滤（支持表达式或原生 Milvus 表达式）
自定义字段名、索引类型、维度等高级配置

适用于 RAG（检索增强生成）、语义搜索、推荐系统等 AI 应用场景。

3.1 Schema 初始化机制

当initializeSchema(true)时，MilvusVectorStore会在首次启动时自动创建 Collection 和索引。

1. 自动创建的字段（默认）

字段名	类型	说明
`doc_id`	`VarChar(36)`	主键，文档唯一 ID（可自定义）
`content`	`VarChar(65535)`	原始文本内容
`metadata`	`JSON`	文档元数据（如来源、时间、标签等）
`embedding`	`FloatVector(D)`	嵌入向量，D 为维度（默认 1536）

✅ 所有字段名均可通过 Builder 自定义。

2. 索引配置（默认）

索引类型：IVF_FLAT
相似度度量：COSINE
索引参数：{"nlist": 1024}
一致性级别：STRONG
分片数：2

索引在 Collection 创建后自动建立，并加载到内存（loadCollection）。

3. 维度推断逻辑

若显式设置.embeddingDimension(d)，则使用该值；
否则尝试调用embeddingModel.dimensions()；
若失败，则回退到 OpenAI 默认维度1536。

3.2. 初始化 Milvus 客户端

MilvusServiceClientmilvusClient=newMilvusServiceClient(ConnectParam.newBuilder().withHost("localhost").withPort(19530).build());

3.3. 创建 Embedding 模型（以 OpenAI 为例）

OpenAiEmbeddingModelembeddingModel=newOpenAiEmbeddingModel(newOpenAiApi(System.getenv("OPENAI_API_KEY")));

3.4. 构建并初始化 Vector Store

MilvusVectorStorevectorStore=MilvusVectorStore.builder(milvusClient,embeddingModel).initializeSchema(true)// 自动创建 Collection 和索引.build();

⚠️ 首次运行会自动创建名为vector_store的 Collection（在default数据库中）。

4. 核心功能使用

4.1. 添加文档

List<Document>docs=List.of(newDocument("Spring AI is awesome!",Map.of("source","blog","author","Alice")),newDocument("Milvus powers fast vector search.",Map.of("source","docs","version","2.4")));vectorStore.add(docs);

Document.id会作为doc_id存入 Milvus。
若未设置 ID，需启用autoId(true)（但通常建议手动指定）。

4.2. 相似性搜索（基础）

List<Document>results=vectorStore.similaritySearch(SearchRequest.query("What is Spring AI?").withTopK(3).withSimilarityThreshold(0.6)// 余弦相似度 ≥ 0.6);

返回结果包含：

text: 原始内容
metadata: 元数据（含distance字段）
score: 相似度得分（0~1，越大越相似）

4.3. 元数据过滤

方式一：使用 Spring AI 过滤表达式（推荐）

FilterExpressionfilter=FilterExpression.text("source == 'blog'");List<Document>results=vectorStore.similaritySearch(SearchRequest.query("AI framework").withFilterExpression(filter).withTopK(2));

支持的操作符：==,!=,>,<,>=,<=,in,not in等。

方式二：使用原生 Milvus 表达式

MilvusSearchRequestrequest=MilvusSearchRequest.query("vector search").withNativeExpression("source == 'docs'")// Milvus 原生语法.withTopK(1);List<Document>results=vectorStore.similaritySearch(request);

4.4. 删除文档

按 ID 删除

vectorStore.delete(List.of("doc-001","doc-002"));

按过滤条件删除

vectorStore.delete(FilterExpression.text("author == 'Bob'"));

5. 高级配置（Builder 详解）

MilvusVectorStorestore=MilvusVectorStore.builder(milvusClient,embeddingModel).databaseName("my_ai_db").collectionName("rag_docs").embeddingDimension(1024).metricType(MetricType.L2)// 支持 COSINE / L2 / IP.indexType(IndexType.HNSW)// 如 HNSW, IVF_SQ8 等.indexParameters("{\"M\": 16, \"efConstruction\": 200}").iDFieldName("uuid").contentFieldName("text_body").metadataFieldName("attrs").embeddingFieldName("vec").autoId(false)// 默认 false，建议手动 ID.initializeSchema(true).batchingStrategy(newTokenCountBatchingStrategy())// 可选批处理策略.build();

💡提示：修改字段名后，需确保新 Collection 不存在，或手动管理 Schema。

6. 注意事项

ID 管理：
- 默认autoId = false，要求每个Document必须有唯一 ID。
- 若设为true，Milvus 自动生成 ID，但无法通过delete(List<String>)删除。
性能优化：
- 生产环境建议使用HNSW或IVF_PQ等高效索引。
- 调整indexParameters以平衡速度与精度。
元数据限制：
- metadata字段为 JSON 类型，Milvus 支持对其子字段建立标量索引（需手动添加）。
观测性：
- 集成 Micrometer，可通过ObservationRegistry监控向量操作耗时、维度等指标。

7. 完整示例

// 1. 初始化客户端MilvusServiceClientclient=newMilvusServiceClient(ConnectParam.newBuilder().withUri("http://localhost:19530").build());// 2. Embedding 模型EmbeddingModelmodel=newMyCustomEmbeddingModel();// 实现 EmbeddingModel 接口// 3. 构建 VectorStoreMilvusVectorStorevs=MilvusVectorStore.builder(client,model).collectionName("demo_rag").initializeSchema(true).build();// 4. 添加文档vs.add(List.of(newDocument("The sky is blue.",Map.of("topic","nature")),newDocument("Java is a programming language.",Map.of("topic","tech"))));// 5. 搜索 + 过滤varresults=vs.similaritySearch(SearchRequest.query("Tell me about programming").withFilterExpression(FilterExpression.text("topic == 'tech'")).withTopK(1));results.forEach(doc->System.out.println(doc.getText()+" [score="+doc.getScore()+"]"));