Skip to content

[MOD-8365] Update datatypes and metric support in README #686

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
May 28, 2025
Merged

[MOD-8365] Update datatypes and metric support in README #686

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
fc5e9f8
readme update
meiravgri May 28, 2025
029b609
Update README.md
meiravgri May 28, 2025
07bee4c
Update README.md
meiravgri May 28, 2025
4f61564
Update README.md
meiravgri May 28, 2025
6b56eb6
skip spellcheck
meiravgri May 28, 2025
1598205
upadte spellcheckwordlist
meiravgri May 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .github/wordlist.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,3 +68,13 @@ Enforceability
stackoverflow
semantical
PRs
BW
FMA
UINT
VBMI
VL
VNNI
CPUs
DOTPROD
SVE
UINT
74 changes: 60 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,10 @@


# VectorSimilarity
Starting with version 8.0, RediSearch and this vector similarity library is an integral part of Redis. See https://github.com/redis/redis
Starting with version 8.0, RediSearch and this vector similarity library is an integral part of Redis. See https://github.com/redis/redis

This repo exposes C API for using vector similarity search.
Allows Creating indices of vectors and searching for top K similar to some vector in two methods: brute force, and by using the hnsw algorithm (probabilistic).
This repo exposes a C API for using vector similarity search.
Allows creating indices of vectors and searching for top K similar to some vector in two methods: brute force, and by using the hnsw algorithm (probabilistic).

The API header files are `vec_sim.h` and `query_results.h`, which are located in `src/VecSim`.

Expand All @@ -22,23 +22,69 @@ All of the algorithms in this library are designed to work inside RediSearch and
5. Multiple vector indexing for the same label (multi-value indexing)
6. 3rd party allocators

#### Datatypes SIMD support

| Operation | x86_64 | arm64v8 | Apple silicone |
|-----------|--------|---------|-----------------|
| FP32 Internal product |SSE, AVX, AVX512 | No SIMD support | No SIMD support |
| FP32 L2 distance |SSE, AVX, AVX512| No SIMD support | No SIMD support |
| FP64 Internal product |SSE, AVX, AVX512 | No SIMD support | No SIMD support |
| FP64 L2 distance |SSE, AVX, AVX512 | No SIMD support | No SIMD support |

### Flat (Brute Force)

Brute force comparison of the query vector `q` with the stored vectors. Vectors are stored in vector blocks, which are contiguous memory blocks, with configurable size.
Brute force comparison of the query vector `q` with the stored vectors. Vectors are stored in vector blocks, which are contiguous memory blocks with a configurable size.


### HNSW
Modified implementation of [hnswlib](https://github.com/nmslib/hnswlib). Modified to accommodate the above feature set.

## Metrics
We support three popular distance metrics to measure the degree of similarity between two vectors:

| Distance metric | Description | Value range |
|-----------------|----------------------------------------------------------------|------------------|
| L2 | Euclidean distance between two vectors. | [0, +∞) |
| IP | Inner product distance (vectors are assumed to be normalized). | [0, 2] |
| COSINE | Cosine distance of two vectors. | [0, 2] |

The above metrics calculate the distance between two vectors, where smaller values indicate that the vectors are closer in the vector space.

### Datatypes and SIMD support
The library supports the following data types for distance computation:
* `float32`
* `float64`
* `bfloat16`
* `float16`
* `int8`
* `uint8`

To accelerate performance, we leverage SIMD instructions on both x86 and ARM CPUs.
The tables below detail the supported SIMD instruction sets (CPU flags) used for each data type on each architecture.

#### x86_64 SIMD Support
| Operation | CPU flags |
|--------------------|---------------------------------------------------------------------|
| FP32 IP & Cosine | SSE, AVX, AVX512F |
| FP32 L2 distance | SSE, AVX, AVX512F |
| FP64 IP & Cosine | SSE, AVX, AVX512F |
| FP64 L2 distance | SSE, AVX, AVX512F |
| FP16 IP & Cosine | F16C+FMA+AVX, AVX512F, AVX512FP16+AVX512VL |
| FP16 L2 distance | F16C+FMA+AVX, AVX512F, AVX512FP16+AVX512VL |
| BF16 IP & Cosine | SSE3, AVX2, AVX512BW+AVX512VBMI2, AVX512BF16+AVX512VL |
| BF16 L2 distance | SSE3, AVX2, AVX512BW+AVX512VBMI2 |
| INT8 IP & Cosine | AVX512F+AVX512BW+AVX512VL+AVX512VNNI |
| INT8 L2 distance | AVX512F+AVX512BW+AVX512VL+AVX512VNNI |
| UINT8 IP & Cosine | AVX512F+AVX512BW+AVX512VL+AVX512VNNI |
| UINT8 L2 distance | AVX512F+AVX512BW+AVX512VL+AVX512VNNI |

#### ARM SIMD Support (arm64v8 & Apple Silicon)
| Operation | CPU flags |
|---------------------|-------------------------------------------|
| FP32 IP & Cosine | NEON, SVE, SVE2 |
| FP32 L2 distance | NEON, SVE, SVE2 |
| FP64 IP & Cosine | NEON, SVE, SVE2 |
| FP64 L2 distance | NEON, SVE, SVE2 |
| FP16 IP & Cosine | NEON_HP, SVE, SVE2 |
| FP16 L2 distance | NEON_HP, SVE, SVE2 |
| BF16 IP & Cosine | NEON_BF16, SVE_BF16 |
| BF16 L2 distance | NEON_BF16, SVE_BF16 |
| INT8 IP & Cosine | NEON, NEON_DOTPROD, SVE, SVE2 |
| INT8 L2 distance | NEON, NEON_DOTPROD, SVE, SVE2 |
| UINT8 IP & Cosine | NEON, NEON_DOTPROD, SVE, SVE2 |
| UINT8 L2 distance | NEON, NEON_DOTPROD, SVE, SVE2 |

## Build
For building you will need:
1. Python 3 as `python` (either by creating a virtual environment or setting your system python to point to the right python distribution)
Expand Down Expand Up @@ -110,4 +156,4 @@ Starting with Redis 8, this library is licensed under your choice of: (i) Redis
## Code contributions


By contributing code to this Redis module in any form, including sending a pull request via GitHub, a code fragment or patch via private email or public discussion groups, you agree to release your code under the terms of the Redis Software Grant and Contributor License Agreement. Please see the CONTRIBUTING.md file in this source distribution for more information. For security bugs and vulnerabilities, please see SECURITY.md.
By contributing code to this Redis module in any form, including sending a pull request via GitHub, a code fragment or patch via private email or public discussion groups, you agree to release your code under the terms of the Redis Software Grant and Contributor License Agreement. Please see the CONTRIBUTING.md file in this source distribution for more information. For security bugs and vulnerabilities, please see SECURITY.md.
Loading