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

README

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

## 项目简介

<div style="display: inline-block; border: 4px solid #ccc; border-radius: 10px; box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1); margin: 10px; padding: 10px;">
  <img src="https://web-code-img.oss-cn-shanghai.aliyuncs.com/readme/f5af847a1930076f8190fe61.png" alt="MilvusPlus" style="border-radius: 10px;" />
</div>

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

## 特性

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

## 快速开始

自定义扩展支持：

```
<dependency>
    <groupId>org.dromara.milvus-plus</groupId>
    <artifactId>milvus-plus-core</artifactId>
    <version>2.3.0</version>
</dependency>
```

Spring应用支持：

```
<dependency>
    <groupId>org.dromara.milvus-plus</groupId>
    <artifactId>milvus-plus-boot-starter</artifactId>
    <version>2.3.0</version>
</dependency>
```

Solon应用支持：

```
<dependency>
    <groupId>org.dromara.milvus-plus</groupId>
    <artifactId>milvus-plus-solon-plugin</artifactId>
    <version>2.3.0</version>
</dependency>
```

## 需知
- 2.3.0 版本升级官方 `milvus-sdk-java` 至 **3.0.4**（对齐 Milvus **3.0.x** 服务端），并修复 addField / Gson / 搜索参数等已知问题
- **2.3.0 详细使用指南（推荐阅读）** → [docs/2.3.0-使用指南.md](https://gitee.com/dromara/MilvusPlus/blob/main/docs/2.3.0-使用指南.md)
- 变更清单 → [CHANGELOG.md](https://gitee.com/dromara/MilvusPlus/blob/main/CHANGELOG.md)
- 本地 Docker → [docker/README.md](https://gitee.com/dromara/MilvusPlus/blob/main/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 快速示例

```java
// 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 测试

```bash
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 数据库的通用接口，提供了一系列的数据操作方法，包括