# ann-benchmark

**Repository Path**: tizi8/ann-benchmark

## Basic Information

- **Project Name**: ann-benchmark
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-10-10
- **Last Updated**: 2025-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

** 本项目基于ann-benchmarks，进行了大量的重构，增加了很多更加便捷测试的功能。**

> ⚠️ 本项目需要 Python 3.10 及以上版本。

1. 安装依赖

```
# 创建虚拟环境
mkdir -p venv
python3 -m venv venv
# 激活虚拟环境
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt
```

2. 下载测试数据集
本项目使用的测试数据集来自ann-benchmarks项目，可以从以下地址下载：

**数据集下载地址：** https://github.com/erikbern/ann-benchmarks

### 常用数据集
| 数据集名称 | 维度 | 训练数据量 | 查询数据量 | 距离度量 | 下载链接 |
|------------|------|------------|------------|----------|----------|
| SIFT | 128 | 1,000,000 | 10,000 | Euclidean | [HDF5](http://ann-benchmarks.com/sift-128-euclidean.hdf5) (501MB) |
| GloVe | 100 | 1,183,514 | 10,000 | Angular | [HDF5](http://ann-benchmarks.com/glove-100-angular.hdf5) (463MB) |
| Fashion-MNIST | 784 | 60,000 | 10,000 | Euclidean | [HDF5](http://ann-benchmarks.com/fashion-mnist-784-euclidean.hdf5) (217MB) |
| NYTimes | 256 | 290,000 | 10,000 | Angular | [HDF5](http://ann-benchmarks.com/nytimes-256-angular.hdf5) (301MB) |

### 数据集命名规则
数据集文件名格式：`{dataset_name}-{dimensions}-{distance_metric}.hdf5`

例如：
- `sift-128-euclidean.hdf5` - SIFT数据集，128维，欧几里得距离
- `glove-100-angular.hdf5` - GloVe数据集，100维，角度距离

下载的数据集文件请放置在项目根目录或指定的data目录中。

3. 修改数据库链接配置
* 修改algorithms/milvus/module.py中的get_conn方法，修改数据库链接配置
* 修改algorithms/opengauss/module.py中的get_conn方法，修改数据库链接配置
...
* 如需更多数据库支持，可以联系测试人员，协助添加，或者仿照milvus和opengauss的module.py，添加新的数据库支持。

4. 设置测试参数
测试参数分为索引参数和查询参数，索引参数变化时，会drop表，重新插入数据创建索引。

* 修改algorithms/milvus/config.yml中的参数，设置测试参数
* 修改algorithms/opengauss/config.yml中的参数，设置测试参数
...
* 如果不想测试某个索引，可以将其disabled设置为true


5. 运行性能测试 (runner.py)

```bash
python runner.py --dataset sift-128-euclidean --algorithms milvus-ivfflat
```

### 主要参数
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--dataset` | 测试数据集名称，必需参数 | - |
| `--algorithms` | 要测试的算法，多个算法用英文逗号分隔 | 所有算法 |
| `--count` | 返回的最近邻居数量 | 10 |
| `--runs` | 运行测试的次数，只保留QPS最高的运行结果 | 1 |
| `--duration` | 每次测试运行的时间(秒) | 30 |
| `--parallel_workers` | 索引构建的并行线程数 | 8 |
| `--tablename` | 数据库表名 | items |
| `--reuse` | 是否尝试重用现有数据和索引 | False |
| `--drop_after_test` | 测试后是否删除表 | False |
| `--reads` | 查询的并发数 | 1 |
| `--results_dir` | 结果保存目录 | results |

### 特性说明
* 多次运行：当`--runs > 1`时，会执行多次测试，但只保留QPS最高的结果。这对有缓存优化的数据库很有用。
* 重用机制：使用`--reuse`参数可以尝试重用已有的数据和索引，避免重复构建。
* 并发测试：`--reads`参数允许设置并发查询数，测试系统在高并发下的表现。
* 指定运行时间：`--duration`设置测试持续时间而不是固定查询次数，更接近真实场景。

6. 绘制结果图表 (plot.py)

```bash
python plot.py --dataset sift-128-euclidean
```

### 主要参数
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--dataset` | 要可视化的数据集 | glove-100-angular |
| `--count` | 邻居数量 | 10 |
| `--output` | 输出图表文件路径 | results/{dataset}.png |
| `--x-axis` | X轴指标 | k-nn |
| `--y-axis` | Y轴指标 | qps |
| `--x-scale` | X轴比例尺 | linear |
| `--y-scale` | Y轴比例尺 | linear |
| `--x-min` | X轴最小值 | 自动 |
| `--raw` | 是否显示非Pareto前沿的原始结果 | False |
| `--results_dir` | 结果读取目录 | results |
| `--recompute` | 是否重新计算指标 | False |

### 支持的绘图指标
- `k-nn`: 查询的k值
- `qps`: 每秒查询次数
- `recall`: 召回率
- `build`: 索引构建时间
- `indexsize`: 索引大小
- `queriessize`: 查询大小
- `distcomps`: 距离计算次数
- `rel`: 相对误差
- `quar-rec`: 查询精度
- `latency`: 查询延迟时间

### 特性说明
* 灵活的坐标轴：可以自定义X轴和Y轴显示的指标。
* 多种比例尺：支持linear、log、logit、a2等多种比例尺。
* X轴最小值：可以手动设置X轴的最小值，方便查看细节区域。
* 原始结果显示：使用`--raw`可以显示非Pareto前沿的所有测试点。