Milvus 向量检索服务 + SpringBoot 实战：电商商品语义检索与相似商品推荐

字段名

说明

是否参与拼接

商品ID

主键，唯一标识

不参与向量化，Milvus主键字段

商品名称

核心名称

✅ 必选

商品分类

一级/二级分类（如：鞋靴>运动鞋）

✅ 必选

商品规格

尺码、版型、材质（如：网面、透气、低帮）

✅ 必选

商品卖点/短描述

营销文案、功能特点

✅ 必选

品牌名称

品牌信息

✅ 必选

价格、库存、上下架状态

业务状态字段

❌ 不向量化，作为Milvus标量字段过滤

Plaintext
【品牌】+【商品名称】+【分类】+【材质/规格】+【卖点描述】

Plaintext
耐克 男子网面运动跑鞋 鞋靴>休闲运动鞋 网面透气、轻便、低帮 夏季新款、防滑减震

XML
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.7.18</version>
<relativePath/>
</parent>

<groupId>com.ecommerce</groupId>
<artifactId>milvus-product-search</artifactId>
<version>1.0.0</version>

<dependencies>
<!-- Spring Web -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- Milvus Java SDK 兼容2.4版本 -->
<dependency>
<groupId>io.milvus</groupId>
<artifactId>milvus-sdk-java</artifactId>
<version>2.4.6</version>
</dependency>

<!-- 阿里云通义Embedding SDK -->
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>dashscope-sdk-java</artifactId>
<version>2.14.0</version>
</dependency>

<!-- 工具类 -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
</dependencies>
</project>

YAML
server:
port: 8080

# Milvus 配置
milvus:
host: c-xxxxxxxx.milvus.aliyuncs.com
port: 19530
username: root
password: 你的实例密码
collection-name: product_vector_collection
vector-dimension: 1536
default-top-k: 12

# 通义千问 Embedding 配置
dashscope:
api-key: 你的阿里云通义API-KEY
embedding-model: text-embedding-v1

Java
import io.milvus.client.MilvusClient;
import io.milvus.client.MilvusClientV2;
import io.milvus.param.ConnectParam;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class MilvusConfig {

@Value("${milvus.host}")
private String host;
@Value("${milvus.port}")
private Integer port;
@Value("${milvus.username}")
private String username;
@Value("${milvus.password}")
private String password;

/**
* 全局唯一Milvus客户端，单例复用
*/
@Bean
public MilvusClient milvusClient() {
ConnectParam connectParam = ConnectParam.newBuilder()
.withHost(host)
.withPort(port)
.withUserName(username)
.withPassword(password)
.build();
return new MilvusClientV2(connectParam);
}
}

Java
import com.alibaba.dashscope.embeddings.TextEmbedding;
import com.alibaba.dashscope.embeddings.TextEmbeddingParam;
import com.alibaba.dashscope.embeddings.TextEmbeddingResult;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;
import java.util.ArrayList;
import java.util.List;

@Component
public class EmbeddingUtil {

@Value("${dashscope.api-key}")
private String apiKey;
@Value("${dashscope.embedding-model}")
private String model;

/**
* 步骤1：多字段拼接为待向量化文本（电商标准规则）
*/
public String buildProductText(String brand, String productName,
String category, String spec, String salesDesc) {
// 过滤空值，避免无效字符
StringBuilder sb = new StringBuilder();
if (brand != null) sb.append(brand).append(" ");
if (productName != null) sb.append(productName).append(" ");
if (category != null) sb.append(category).append(" ");
if (spec != null) sb.append(spec).append(" ");
if (salesDesc != null) sb.append(salesDesc);
return sb.toString().trim();
}

/**
* 步骤2：文本生成1536维浮点向量
*/
public List<Float> getEmbeddingVector(String text) throws NoApiKeyException, InputRequiredException {
TextEmbeddingParam param = TextEmbeddingParam.builder()
.apiKey(apiKey)
.model(model)
.text(text)
.build();
TextEmbedding embedding = new TextEmbedding();
TextEmbeddingResult result = embedding.call(param);

List<Float> vector = new ArrayList<>();
result.getOutput().getEmbeddings().get(0).getEmbedding().forEach(vector::add);
return vector;
}
}

Java
import lombok.Data;
import java.util.List;

/**
* Milvus 集合映射实体
* 存储：商品ID(主键)、品牌、分类、上下架状态、向量
*/
@Data
public class ProductVectorDO {
/** 商品主键ID，INT64 非自增 */
private Long productId;
/** 品牌名称，字符串 */
private String brand;
/** 商品全分类路径 */
private String category;
/** 上下架状态 0-下架 1-上架（标量过滤字段） */
private Integer status;
/** 1536维向量 */
private List<Float> vector;
}

Java
import io.milvus.client.MilvusClient;
import io.milvus.param.*;
import io.milvus.param.collection.CreateCollectionParam;
import io.milvus.param.collection.FieldType;
import io.milvus.param.index.CreateIndexParam;
import io.milvus.param.dml.InsertParam;
import io.milvus.param.dml.SearchParam;
import lombok.RequiredArgsConstructor;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
import java.util.*;
import java.util.stream.Collectors;

@Service
@RequiredArgsConstructor
public class ProductVectorService {

private final MilvusClient milvusClient;
private final EmbeddingUtil embeddingUtil;

@Value("${milvus.collection-name}")
private String collectionName;
@Value("${milvus.vector-dimension}")
private Integer vectorDim;

/**
* 初始化集合 + 索引（项目部署/首次启动执行一次）
*/
public void initCollection() {
// 判断集合是否存在
boolean exist = milvusClient.hasCollection(
HasCollectionParam.newBuilder().withCollectionName(collectionName).build()
).getData();
if (exist) {
return;
}

// 定义字段：主键、字符串、整型、向量
List<FieldType> fieldList = new ArrayList<>();
// 1. 商品ID 主键
fieldList.add(FieldType.newBuilder()
.withName("product_id")
.withDataType(DataType.Int64)
.withPrimaryKey(true)
.withAutoID(false)
.build());
// 2. 品牌
fieldList.add(FieldType.newBuilder()
.withName("brand")
.withDataType(DataType.VARCHAR)
.withMaxLength(64)
.build());
// 3. 分类
fieldList.add(FieldType.newBuilder()
.withName("category")
.withDataType(DataType.VARCHAR)
.withMaxLength(128)
.build());
// 4. 上下架状态（用于检索过滤）
fieldList.add(FieldType.newBuilder()
.withName("status")
.withDataType(DataType.Int32)
.build());
// 5. 向量字段
fieldList.add(FieldType.newBuilder()
.withName("product_vector")
.withDataType(DataType.FloatVector)
.withDimension(vectorDim)
.build());

// 创建集合
milvusClient.createCollection(CreateCollectionParam.newBuilder()
.withCollectionName(collectionName)
.withFieldTypes(fieldList)
.withShardsNum(3) // 分片数，根据数据量调整
.build());

// 创建 HNSW 索引 + 余弦相似度（语义检索标配）
CreateIndexParam indexParam = CreateIndexParam.newBuilder()
.withCollectionName(collectionName)
.withFieldName("product_vector")
.withIndexType(IndexType.HNSW)
.withMetricType(MetricType.COSINE)
.withExtraParam("{\"M\":16,\"efConstruction\":80}")
.build();
milvusClient.createIndex(indexParam);
}

/**
* 新增/更新商品向量（商品新增、编辑时调用，异步执行）
*/
public void saveProductVector(ProductVectorDO product) throws Exception {
// 1. 拼接待向量化文本
String text = embeddingUtil.buildProductText(
product.getBrand(),
"",
product.getCategory(),
"",
""
);
// 2. 生成向量
List<Float> vector = embeddingUtil.getEmbeddingVector(text);
product.setVector(vector);

// 3. 组装插入参数
List<InsertParam.Field> fields = new ArrayList<>();
fields.add(new InsertParam.Field("product_id", Collections.singletonList(product.getProductId())));
fields.add(new InsertParam.Field("brand", Collections.singletonList(product.getBrand())));
fields.add(new InsertParam.Field("category", Collections.singletonList(product.getCategory())));
fields.add(new InsertParam.Field("status", Collections.singletonList(product.getStatus())));
fields.add(new InsertParam.Field("product_vector", Collections.singletonList(vector)));

// 4. 写入Milvus
milvusClient.insert(InsertParam.newBuilder()
.withCollectionName(collectionName)
.withFields(fields)
.build());
// 强制刷盘，保证实时可见
milvusClient.flush(FlushParam.newBuilder()
.addCollectionName(collectionName)
.build());
}

/**
* 语义检索：用户搜索词 → 向量检索 + 过滤下架商品
*/
public List<Long> searchSimilarProduct(String searchText, int topK) throws Exception {
// 1. 搜索词生成向量
List<Float> queryVector = embeddingUtil.getEmbeddingVector(searchText);

// 2. 构建检索条件：仅查询上架商品 status = 1
String filter = "status == 1";

// 3. 检索参数
SearchParam searchParam = SearchParam.newBuilder()
.withCollectionName(collectionName)
.withVectorFieldName("product_vector")
.withQueryVectors(Collections.singletonList(queryVector))
.withTopK(topK)
.withMetricType(MetricType.COSINE)
.withFilter(filter) // 标量过滤，排除下架商品
.withOutputFields(Collections.singletonList("product_id"))
.withParams("{\"ef\":40}")
.build();

// 4. 执行检索
var result = milvusClient.search(searchParam);
List<Long> productIdList = new ArrayList<>();
result.getData().forEach(group ->
group.getResults().forEach(item ->
productIdList.add(item.getId().getValue().asLong())
)
);
return productIdList;
}
}

Java
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;
import java.util.List;

@RestController
@RequestMapping("/api/product/vector")
@RequiredArgsConstructor
public class ProductVectorController {

private final ProductVectorService vectorService;

/**
* 初始化集合与索引（部署执行一次）
*/
@PostMapping("/init")
public String init() {
try {
vectorService.initCollection();
return "集合&索引初始化成功";
} catch (Exception e) {
return "初始化失败：" + e.getMessage();
}
}

/**
* 同步商品向量（商品新增/编辑调用）
*/
@PostMapping("/save")
public String save(@RequestBody ProductVectorDO product) {
try {
vectorService.saveProductVector(product);
return "向量保存成功";
} catch (Exception e) {
return "向量保存失败：" + e.getMessage();
}
}

/**
* 语义搜索接口（前端调用）
*/
@GetMapping("/search")
public List<Long> search(@RequestParam String keyword,
@RequestParam(defaultValue = "10") Integer topK) {
try {
return vectorService.searchSimilarProduct(keyword, topK);
} catch (Exception e) {
e.printStackTrace();
return Collections.emptyList();
}
}
}

HTTP
POST /api/product/vector/save
{
"productId": 10001,
"brand": "耐克",
"category": "鞋靴>休闲运动鞋",
"status": 1
}

HTTP
GET /api/product/vector/search?keyword=夏季透气运动跑鞋&topK=5