项目介绍

🔥🔥🔥使用MyBatisPlus的方式，优雅的操作向量数据库 Milvus，同时支持spring和solon

项目详情

Dromara MilvusPlus：向量数据库增强操作库

项目简介

🔥🔥🔥MilvusPlus（简称 MP）是一个 Milvus 的操作工具，旨在简化与 Milvus 向量数据库的交互，为开发者提供类似 MyBatis-Plus 注解和方法调用风格的直观 API,提高效率而生。

特性

无侵入：只做增强不做改变，引入它不会对现有工程产生影响，如丝般顺滑
损耗小：启动即会自动注入基本 CURD，性能基本无损耗，直接面向对象操作
强大的 CRUD 操作：通用 MilvusMapper，仅仅通过少量配置即可实现 CRUD 操作，更有强大的条件构造器，满足各类使用需求
直观的 API：直接的 API 设计简化数据库操作，MilvusService 提供丰富的API。
支持 Lambda 形式调用：通过 Lambda 表达式，方便的编写各类查询条件，无需再担心字段写错
支持主键自动生成：完美解决主键问题
支持自定义全局通用操作：支持全局通用方法注入
注解式配置：采用与 MyBatis-Plus 类似的注解方式配置实体模型。
易于扩展：核心设计注重可扩展性。
类型安全：利用 Java 类型安全减少错误。

快速开始

自定义扩展支持：


org.dromara.milvus-plus
milvus-plus-core
2.3.0

Spring应用支持：


org.dromara.milvus-plus
milvus-plus-boot-starter
2.3.0

Solon应用支持：


org.dromara.milvus-plus
milvus-plus-solon-plugin
2.3.0

需知

2.3.0 版本升级官方 milvus-sdk-java 至 3.0.4（对齐 Milvus 3.0.x 服务端），并修复 addField / Gson / 搜索参数等已知问题
2.3.0 详细使用指南（推荐阅读） → docs/2.3.0-使用指南.md
变更清单 → CHANGELOG.md
本地 Docker → docker/README.md
2.2.0版本支持数据库版本2.5.x，增强文本搜索能力
2.1.7版本之后groupId修改为 org.dromara.milvus-plus，版本之前为 org.dromara
2.0.0版本必须使用索引注解定义索引，不然启动报错后，再添加无效，需要先删除集合
2.0.0版本暂未发布 MilvusService 功能

配置文件

milvus:
  uri: https://in03-a5357975ab80da7.api.gcp-us-west1.zillizcloud.com
  token: x'x'x'x
  enable: true
  open-log: true （默认 false 不打印）
  db-name: (可选)
  username: (可选)
  password: (可选)
  # 集合结构同步：IGNORE(默认兼容) / VALIDATE / AUTO_ADD(推荐新项目) / RECREATE(危险)
  schema-mode: AUTO_ADD
  # 仅 schema-mode=RECREATE 时生效，生产务必 false
  enable-recreate: false
  packages:
    - com.example.entity

milvus：定义了与Milvus服务相关的配置。
uri：Milvus服务的URI，应用程序通过这个URI与Milvus服务进行通信。
token：用于验证和授权的令牌（Token），确保访问Milvus服务的安全性。
enable：一个布尔值，用于指示Milvus模块是否应该被启用。
packages：这些包包含了自定义注解对应的Java类，你可以认为这是你自定义的实体类所在的包。
schema-mode：实体注解与服务端 collection 的同步策略。
enable-recreate：是否允许 RECREATE 删表重建。

2.3.0 快速示例

// 1) 自动补齐实体新增字段
milvusService.ensureSchema(Face.class);

// 2) 动态集合（分表/租户）
faceMapper.forCollection("face_" + tenantId).insert(face);

// 3) 语义化向量检索
faceMapper.queryWrapper()
.vectorSearch(Face::getFaceVector, embedding)
.eq(Face::getPersonName, "张三")
.top(10)
.options(opt -> opt.metricType(IndexParam.MetricType.IP))
.query();

// 4) 文本检索（BM25，无需手写 _sparse）
faceMapper.queryWrapper()
.textSearch(Face::getContent, "关键词")
.top(10)
.query();

// 5) 标量分页
faceMapper.queryWrapper().eq(Face::getStatus, 1).page(1, 20);

// 6) 部分更新
faceMapper.updateWrapper().partial().updateById(face);

// 7) 类 SQL WHERE（实验子集，不是完整 MySQL）
faceMapper.queryWrapper()
.sqlWhere("status = 1 AND name LIKE '%张%' OR type IN ('A','B')")
.top(10)
.query();

// 8) 原生滤器表达式（Milvus boolean expression）
faceMapper.queryWrapper()
.filter("status == 1 && array_contains(tags, \"vip\")")
.query();

本地 Docker 测试

cd docker
docker compose up -d
# uri: http://localhost:19530

详见 docker/README.md。

应用场景

相似性搜索：快速检索与给定向量最相似的项。
推荐系统：根据用户行为和偏好推荐相关内容。
图像检索：在大规模图像库中找到与查询图像最相似的图像。
自然语言处理：将文本转换为向量并执行语义搜索。
生物信息学：分析和比较生物序列，如蛋白质和基因组数据。

自定义注解详解

使用自定义注解自动化Milvus数据库集成，提供了以下显著优势：

简化开发流程：通过注解直接在代码中声明数据库结构，不用手动创建集合、属性、索引、分区，项目启动即自动构建，减少手动编写Milvus API调用的需要。
提高开发效率：注解驱动的方式使得数据库结构的创建和管理更加快捷，加快开发速度。
增强代码可读性：将数据库结构定义与业务逻辑代码紧密结合，提高代码的可读性和可维护性。
减少错误：自动化创建数据库结构减少了人为错误的可能性，提高了系统的稳定性。
易于维护：注解的使用使得数据库结构的变更更加集中和明确，便于后期维护和升级。

@ExtraParam 注解

用途：定义索引或其他自定义功能的额外参数。
属性：
- key(): 参数的键名。
- value(): 参数的值。

@MilvusCollection 注解

用途：定义Milvus数据库中的集合。
属性：
- name(): 集合的名称。

@MilvusField 注解

用途：定义Milvus集合中的字段。
属性：
- name(): 字段名称，默认为Java字段名。
- dataType(): 数据类型，默认为FLOAT_VECTOR。
- dimension(): 向量维度，默认为-1。
- isPrimaryKey(): 是否为主键，默认为false。
- autoID(): 是否自动生成ID，默认为false。
- description(): 字段描述，默认为空。
- elementType(): 元素类型，默认为None。
- maxLength(): 最大长度，默认为-1。
- maxCapacity(): 最大容量，默认为-1。
- isPartitionKey(): 是否为分区键，默认为false。

@MilvusIndex 注解

用途：定义Milvus集合中的索引。
属性：
- indexType(): 索引类型，默认为FLAT。
- metricType(): 度量类型，默认为L2。
- indexName(): 索引名称，默认为空。
- extraParams(): 额外参数，使用ExtraParam注解定义。

@MilvusPartition 注解

用途：定义Milvus集合的分区。
属性：
- name(): 分区的名称数组。

通过这些注解，开发者可以轻松地定义和管理Milvus数据库的结构，实现项目启动时自动构建所需数据库结构的目标。

索引与度量类型详解

索引类型（IndexType）

INVALID：无效索引类型，仅用于内部标记。
FLAT：暴力搜索，适用于小规模数据集。
IVF_FLAT：倒排索引平面模式，适用于中等规模数据集。
IVF_SQ8：倒排索引量化模式，适用于大规模数据集，牺牲精度提升速度。
IVF_PQ：倒排索引产品量化模式，适用于大规模高维数据集，平衡速度和精度。
HNSW：分层导航小世界图，提供快速搜索，适用于大规模数据集。
DISKANN：基于磁盘的近似最近邻搜索，适用于存储在磁盘上的大规模数据集。
AUTOINDEX：自动选择最优索引类型。
SCANN：使用扫描和树结构加速搜索。
GPU_IVF_FLAT、GPU_IVF_PQ：GPU 加速索引，适用于 GPU 环境。
BIN_FLAT、BIN_IVF_FLAT：二进制向量专用索引。
TRIE：适用于字符串类型的字典树索引。
STL_SORT：适用于标量字段的排序索引。

度量类型（MetricType）

INVALID：无效度量类型，仅用于内部标记。
L2：欧几里得距离，适用于浮点向量。
IP：内积，用于计算余弦相似度。
COSINE：余弦相似度，适用于文本和图像搜索。
HAMMING：汉明距离，适用于二进制向量。
JACCARD：杰卡德相似系数，适用于集合相似度计算。

MilvusMapper 功能

MilvusMapper 是一个用于操作 Milvus 数据库的通用接口，提供了一系列的数据操作方法，包括查询、删除、更新和插入。以下是对 MilvusMapper 及其相关类的功能描述：

MilvusMapper

MilvusMapper 是一个泛型抽象类，继承自 BaseMilvusMapper，提供了与 Milvus 客户端交互的基本方法。

获取 Milvus 客户端: getClient() - 返回 MilvusClientV2 实例。

BaseMilvusMapper

BaseMilvusMapper 是一个抽象类，定义了与 Milvus 数据库交互的基础操作。

创建搜索构建器实例: queryWrapper() - 创建 LambdaQueryWrapper 实例。
创建删除构建器实例: deleteWrapper() - 创建 LambdaDeleteWrapper 实例。
创建更新构建器实例: updateWrapper() - 创建 LambdaUpdateWrapper 实例。
创建新增构建器实例: insertWrapper() - 创建 LambdaInsertWrapper 实例。

数据操作

通过 ID 获取数据getById(Serializable ... ids)

功能：根据提供的ID列表查询数据。

    `参数`：`ids` - 一个可序列化的ID列表。

    `返回`：`MilvusResp>>` - 包含查询结果的响应。

删除数据removeById(Serializable ... ids)

功能：根据提供的ID列表删除数据。

    `参数`：`ids` - 一个可序列化的ID列表。

    `返回`：`MilvusResp` - 删除操作的响应。

更新数据updateById(T ... entity)

功能：根据提供的实体更新数据。

    `参数`：`entity` - 一个实体对象列表。

    `返回`：`MilvusResp` - 更新操作的响应。

插入数据insert(T ... entity)

  `功能`：插入提供的实体到数据库。

  `参数`：`entity` - 一个实体对象列表。

  `返回`：`MilvusResp` - 插入操作的响应。

构建器方法

创建通用构建器实例: lambda(Wrapper wrapper) - 初始化并返回构建器实例。

LambdaQueryWrapper 类功能文档

LambdaQueryWrapper 是一个用于构建和执行 Milvus 搜索查询的构建器类。它提供了一系列方法来设置查询参数，并最终执行查询。

构造函数

LambdaQueryWrapper(): 无参构造函数。
LambdaQueryWrapper(String collectionName, MilvusClientV2 client, ConversionCache conversionCache, Class entityType): 构造函数，初始化集合名称、Milvus 客户端、类型转换缓存和实体类型。

分区设置

partition(String ... partitionName): 添加一个或多个分区名称到查询中。
partition(FieldFunction... partitionName): 根据提供的字段函数添加分区名称。

搜索参数设置

searchParams(Map searchParams): 设置搜索参数。
以下是 searchParams 支持的参数及其说明：
- metric_type
  类型：String
  描述：指定搜索操作使用的度量类型。必须与索引向量字段时使用的度量类型一致。
  可选值：
  L2：欧几里得距离，适用于高维空间的向量搜索。
  IP：内积，适用于余弦相似度搜索。
  COSINE：余弦相似度，与内积相同，适用于测量向量间的夹角。
  示例：
  searchParams.put("metric_type", "L2");
- radius
  类型：float
  描述：设置搜索操作的最小相似度阈值。当 metric_type 设置为 L2 时，此值应大于 range_filter；否则，应小于 range_filter。
  示例：
  searchParams.put("radius", 0.5f);
- range_filter
  类型：float
  描述：限定搜索操作的相似度范围。当 metric_type 设置为 IP 或 COSINE 时，此值应大于 radius；否则，应小于 radius。
  示例：
  searchParams.put("range_filter", 0.3f);
  使用示例
  以下是一个使用 searchParams 的示例，展示如何构建搜索请求并设置特定的搜索参数：

Map searchParams = new HashMap<>();
searchParams.put("metric_type", "L2");
searchParams.put("radius", 0.5f);
searchParams.put("range_filter", 0.3f);

radius(Object radius): 设置搜索半径。
rangeFilter(Object rangeFilter): 设置范围过滤器。
metricType(Object metric_type): 设置度量类型。

结果设置

outputFields(List outputFields): 设置要返回的字段。
roundDecimal(int roundDecimal): 设置返回的距离值的小数位数。

查询条件构建

eq(String fieldName, Object value): 添加等于条件。
ne(String fieldName, Object value): 添加不等于条件。
gt(String fieldName, Object value): 添加大于条件。
ge(String fieldName, Object value): 添加大于等于条件。
lt(String fieldName, Object value): 添加小于条件。
le(String fieldName, Object value): 添加小于等于条件。
between(String fieldName, Object start, Object end): 添加范围条件。
isNull(String fieldName): 添加空值检查条件。
isNotNull(String fieldName): 添加非空值检查条件。
in(String fieldName, List values): 添加 IN 条件。
like(String fieldName, String value): 添加 LIKE 条件。

JSON 和数组操作

jsonContains(String fieldName, Object value): 添加 JSON 包含条件。
jsonContainsAll(String fieldName, List values): 添加 JSON 包含所有值的条件。
jsonContainsAny(String fieldName, List values): 添加 JSON 包含任意值的条件。
arrayContains(String fieldName, Object value): 添加数组包含条件。
arrayContainsAll(String fieldName, List values): 添加数组包含所有值的条件。
arrayContainsAny(String fieldName, List values): 添加数组包含任意值的条件。
arrayLength(String fieldName, int length): 添加数组长度条件。

逻辑操作

and(ConditionBuilder other): 添加 AND 条件。
or(ConditionBuilder other): 添加 OR 条件。
not(): 添加 NOT 条件。

向量搜索设置

annsField(String annsField): 设置要搜索的向量字段。
vector(List vector): 添加要搜索的向量。
vector(String annsField, List vector): 设置向量字段并添加要搜索的向量。
topK(Integer topK): 设置返回的 top-k 结果。
limit(Long limit): 设置查询结果的数量限制。

执行查询

query(): 构建并执行搜索请求，返回封装的 MilvusResp 对象，其中包含查询结果。
query(FieldFunction ... outputFields): 设置输出字段并执行查询。
query(String ... outputFields): 设置输出字段并执行查询。
getById(Serializable ... ids): 通过 ID 获取数据。

辅助方法

buildSearch(): 构建完整的搜索请求对象。
buildQuery(): 构建查询请求对象。

LambdaQueryWrapper 类提供了丰富的方法来构建复杂的搜索查询，支持各种条件、逻辑操作、JSON 和数组操作，以及向量搜索。通过链式调用这些方法，用户可以灵活地构造搜索请求并获取所需的查询结果。

LambdaDeleteWrapper

LambdaDeleteWrapper 是一个构建器类，用于构建和执行删除操作。

添加分区: partition(String partitionName)
添加等于条件: eq(String fieldName, Object value)
添加不等于条件: ne(String fieldName, Object value)
添加 ID 到删除列表: id(Object id)

执行删除

执行删除: remove() - 构建并执行删除请求。
通过 ID 删除: removeById(Serializable ... ids)

LambdaUpdateWrapper

LambdaUpdateWrapper 是一个构建器类，用于构建和执行更新操作。

添加分区: partition(String partitionName)
设置更新条件: 与 LambdaDeleteWrapper 相同

执行更新

更新数据: update(T t) - 构建并执行更新请求。
通过 ID 更新: updateById(T ... t)

LambdaInsertWrapper

LambdaInsertWrapper 是一个构建器类，用于构建和执行插入操作。

添加分区: partition(String partitionName)
添加字段值: put(String fieldName, Object value)

执行插入

插入数据: insert() - 构建并执行插入请求。
插入多个数据: insert(T ... t)

MilvusService 功能

MilvusService 是一个综合性服务，提供对 Milvus 数据库的全面管理，它实现了多个接口：IAMService（身份访问管理服务）、ICMService（集合管理服务）和 IVecMService（向量管理服务）。

身份访问管理 (IAMService)

IAMService 接口提供用户和角色的创建、删除、查询以及权限的授予和撤销等功能。

创建角色: createRole(String roleName)
创建用户: createUser(String userName, String password)
查询角色权限: describeRole(String roleName)
查询用户信息: describeUser(String userName)
删除角色: dropRole(String roleName)
删除用户: dropUser(String userName)
授予角色权限: grantPrivilege(String roleName, String objectType, String privilege, String objectName)
授予用户角色: grantRole(String roleName, String userName)
列出所有角色: listRoles()
列出所有用户: listUsers()
撤销角色权限: revokePrivilege(String roleName, String objectType, String privilege, String objectName, String databaseName)
撤销用户角色: revokeRole(String roleName, String userName)
更新用户密码: updatePassword(String userName, String password, String newPassword)

集合管理 (ICMService)

ICMService 接口提供集合的创建、删除、查询、重命名、索引创建和管理等功能。

创建集合: createCollection(MilvusEntity milvusEntity)
添加字段: addField(String collectionName, AddFieldReq ... addFieldReq)
获取字段: getField(String collectionName, String fieldName)
获取集合详细信息: describeCollection(String collectionName)
删除集合: dropCollection(String collectionName)
检查集合是否存在: hasCollection(String collectionName)
获取集合统计信息: getCollectionStats(String collectionName)
重命名集合: renameCollection(String oldCollectionName, String newCollectionName)
为集合创建索引: createIndex(String collectionName, List indexParams)
获取集合索引信息: describeIndex(String collectionName, String fieldName)
删除集合索引: dropIndex(String collectionName, String fieldName)
获取集合或分区的加载状态: getLoadState(String collectionName, String partitionName)
加载集合数据到内存: loadCollection(String collectionName)
从内存中释放集合数据: releaseCollection(String collectionName)
创建集合分区: createPartition(String collectionName, String partitionName)
删除集合分区: dropPartition(String collectionName, String partitionName)
检查分区是否存在: hasPartition(String collectionName, String partitionName)
列出集合中的所有分区: listPartitions(String collectionName)
加载集合分区到内存: loadPartitions(String collectionName, List partitionNames)
从内存中释放集合分区: releasePartitions(String collectionName, List partitionNames)

向量管理 (IVecMService)

IVecMService 接口提供向量的插入、更新、查询、删除以及相似性搜索等功能。

删除实体: delete(String collectionName, String partitionName, String filter, List ids)
根据ID获取实体: get(String collectionName, String partitionName, List ids, List outputFields)
插入数据: insert(String collectionName, List data, String partitionName)
根据标量过滤条件查询: query(String collectionName, List partitionNames, List outputFields, List ids, String filter, ConsistencyLevel consistencyLevel, long offset, long limit)
执行向量相似性搜索: search(String collectionName, List partitionNames, String annsField, int topK, String filter, List outputFields, List data, long offset, long limit, int roundDecimal, Map searchParams, long guaranteeTimestamp, long gracefulTime, ConsistencyLevel consistencyLevel, boolean ignoreGrowing)
插入或更新数据: upsert(String collectionName, String partitionName, List data)

公共方法

除了上述功能，MilvusService 还提供了一个公共方法来获取 MilvusClientV2 实例：

获取 Milvus 客户端: `getClient()

使用案例

以下是使用 MilvusPlus 进行向量搜索的示例：

@Data
@MilvusCollection(name = "face_collection") // 指定Milvus集合的名称
public class Face {
@MilvusField(
name = "person_id", // 字段名称
dataType = DataType.Int64, // 数据类型为64位整数
isPrimaryKey = true, // 标记为主键
)
private Long personId; // 人员的唯一标识符

@MilvusField(
name = "face_vector", // 字段名称
dataType = DataType.FloatVector, // 数据类型为浮点型向量
dimension = 128, // 向量维度，假设人脸特征向量的维度是128
)
@MilvusIndex(
indexType = IndexParam.IndexType.IVF_FLAT, // 使用IVF_FLAT索引类型
metricType = IndexParam.MetricType.L2, // 使用L2距离度量类型
indexName = "face_index", // 索引名称
extraParams = { // 指定额外的索引参数
@ExtraParam(key = "nlist", value = "100") // 例如，IVF的nlist参数
}
)
private List faceVector; // 存储人脸特征的向量
}
@Component
public class FaceMilvusMapper extends MilvusMapper {

}

@Component
@Slf4j
public class ApplicationRunnerTest implements ApplicationRunner {
private final FaceMilvusMapper mapper;

public ApplicationRunnerTest(FaceMilvusMapper mapper) {
this.mapper = mapper;
}

@Override
public void run(ApplicationArguments args){
Face f

...（内容过长，已截断，更多详情请访问项目地址）

## ⬇️ 下载地址 ##

{cloud title="MilvusPlus 源码下载" type="gitee" url="https://gitee.com/dromara/MilvusPlus/repository/archive/master.zip" /}

下载后请先检查文件完整性，如有问题请在评论区反馈