USearch

USearch

Smaller & Faster Single-File
Similarity Search & Clustering Engine for Vectors & Texts

               

Spatial • Binary • Probabilistic • User-Defined Metrics
C++11 • Python 3 • JavaScript • Java • Rust • C99 • Objective-C • Swift • C# • Go • Wolfram
Linux • macOS • Windows • iOS • Android • WebAssembly • SQLite

--- - ✅ __[10x faster][faster-than-faiss]__ [HNSW][hnsw-algorithm] implementation than [FAISS][faiss]. - ✅ Simple and extensible [single C++11 header][usearch-header] __library__. - ✅ [Trusted](#integrations) by giants like Google and DBs like [ClickHouse][clickhouse-docs] & [DuckDB][duckdb-docs]. - ✅ [SIMD][simd]-optimized and [user-defined metrics](#user-defined-functions) with JIT compilation. - ✅ Hardware-agnostic `bf16`, `e5m2`, & `i8` - [half-precision & quarter-precision support](#memory-efficiency-downcasting-and-quantization). - ✅ [View large indexes from disk](#serialization--serving-index-from-disk) without loading into RAM. - ✅ Heterogeneous lookups, renaming/relabeling, and on-the-fly deletions. - ✅ Binary Tanimoto and Sorensen coefficients for [Genomics and Chemistry applications](#usearch--rdkit--molecular-search). - ✅ Space-efficient point-clouds with `uint40_t`, accommodating 4B+ size. - ✅ Compatible with OpenMP and custom "executors" for fine-grained parallelism. - ✅ [Semantic Search](#usearch--uform--ucall--multimodal-semantic-search) and [Joins](#joins-one-to-one-one-to-many-and-many-to-many-mappings). - Near-real-time [clustering and sub-clustering](#clustering) for Tens or Millions of clusters. [faiss]: https://github.com/facebookresearch/faiss [usearch-header]: https://github.com/unum-cloud/USearch/blob/main/include/usearch/index.hpp [obscure-use-cases]: https://ashvardanian.com/posts/abusing-vector-search [hnsw-algorithm]: https://arxiv.org/abs/1603.09320 [simd]: https://en.wikipedia.org/wiki/Single_instruction,_multiple_data [faster-than-faiss]: https://www.unum.cloud/blog/2023-11-07-scaling-vector-search-with-intel [clickhouse-docs]: https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/annindexes#usearch [duckdb-docs]: https://duckdb.org/2024/05/03/vector-similarity-search-vss.html __Technical Insights__ and related articles: - [Uses Arm SVE and x86 AVX-512's masked loads to eliminate tail `for`-loops](https://ashvardanian.com/posts/simsimd-faster-scipy/#tails-of-the-past-the-significance-of-masked-loads). - [Uses Horner's method for polynomial approximations, beating GCC 12 by 119x](https://ashvardanian.com/posts/gcc-12-vs-avx512fp16/). - [For every language implements a custom separate binding](https://ashvardanian.com/posts/porting-cpp-library-to-ten-languages/). ## Comparison with FAISS FAISS is a widely recognized standard for high-performance vector search engines. USearch and FAISS both employ the same HNSW algorithm, but they differ significantly in their design principles. USearch is compact and broadly compatible without sacrificing performance, primarily focusing on user-defined metrics and fewer dependencies. | | FAISS | USearch | Improvement | | :------------------------------------------- | ----------------------: | -----------------------: | ----------------------: | | Indexing time ⁰ | | | | | 100 Million 96d `f32`, `f16`, `i8` vectors | 2.6 · 2.6 · 2.6 h | 0.3 · 0.2 · 0.2 h | __9.6 · 10.4 · 10.7 x__ | | 100 Million 1536d `f32`, `f16`, `i8` vectors | 5.0 · 4.1 · 3.8 h | 2.1 · 1.1 · 0.8 h | __2.3 · 3.6 · 4.4 x__ | | | | | | | Codebase length ¹ | 84 K [SLOC][sloc] | 3 K [SLOC][sloc] | maintainable | | Supported metrics ² | 9 fixed metrics | any metric | extendible | | Supported languages ³ | C++, Python | 10 languages | portable | | Supported ID types ⁴ | 32-bit, 64-bit | 32-bit, 40-bit, 64-bit | efficient | | Filtering ⁵ | ban-lists | any predicates | composable | | Required dependencies ⁶ | BLAS, OpenMP | - | light-weight | | Bindings ⁷ | SWIG | Native | low-latency | | Python binding size ⁸ | [~ 10 MB][faiss-weight] | [< 1 MB][usearch-weight] | deployable | [sloc]: https://en.wikipedia.org/wiki/Source_lines_of_code [faiss-weight]: https://pypi.org/project/faiss-cpu/#files [usearch-weight]: https://pypi.org/project/usearch/#files > ⁰ [Tested][intel-benchmarks] on Intel Sapphire Rapids, with the simplest inner-product distance, equivalent recall, and memory consumption while also providing far superior search speed. > ¹ A shorter codebase of `usearch/` over `faiss/` makes the project easier to maintain and audit. > ² User-defined metrics allow you to customize your search for various applications, from GIS to creating custom metrics for composite embeddings from multiple AI models or hybrid full-text and semantic search. > ³ With USearch, you can reuse the same preconstructed index in various programming languages. > ⁴ The 40-bit integer allows you to store 4B+ vectors without allocating 8 bytes for every neighbor reference in the proximity graph. > ⁵ With USearch the index can be combined with arbitrary external containers, like Bloom filters or third-party databases, to filter out irrelevant keys during index traversal. > ⁶ Lack of obligatory dependencies makes USearch much more portable. > ⁷ Native bindings introduce lower call latencies than more straightforward approaches. > ⁸ Lighter bindings make downloads and deployments faster. [intel-benchmarks]: https://www.unum.cloud/blog/2023-11-07-scaling-vector-search-with-intel Base functionality is identical to FAISS, and the interface must be familiar if you have ever investigated Approximate Nearest Neighbors search: ```py # pip install usearch import numpy as np from usearch.index import Index index = Index(ndim=3) # Default settings for 3D vectors vector = np.array([0.2, 0.6, 0.4]) # Can be a matrix for batch operations index.add(42, vector) # Add one or many vectors in parallel matches = index.search(vector, 10) # Find 10 nearest neighbors assert matches[0].key == 42 assert matches[0].distance <= 0.001 assert np.allclose(index[42], vector, atol=0.1) # Ensure high tolerance in mixed-precision comparisons ``` More settings are always available, and the API is designed to be as flexible as possible. The default storage/quantization level is hardware-dependant for efficiency, but `bf16` is recommended for most modern CPUs. ```py index = Index( ndim=3, # Define the number of dimensions in input vectors metric='cos', # Choose 'l2sq', 'ip', 'haversine' or other metric, default = 'cos' dtype='bf16', # Store as 'f64', 'f32', 'bf16', 'f16', 'e5m2', 'e4m3', 'e3m2', 'e2m3', 'u8', 'i8', 'b1'..., default = None connectivity=16, # Optional: Limit number of neighbors per graph node expansion_add=128, # Optional: Control the recall of indexing expansion_search=64, # Optional: Control the quality of the search multi=False, # Optional: Allow multiple vectors per key, default = False ) ``` ## Serialization & Serving `Index` from Disk USearch supports multiple forms of serialization: - Into a __file__ defined with a path. - Into a __stream__ defined with a callback, serializing or reconstructing incrementally. - Into a __buffer__ of fixed length or a memory-mapped file that supports random access. The latter allows you to serve indexes from external memory, enabling you to optimize your server choices for indexing speed and serving costs. This can result in __20x cost reduction__ on AWS and other public clouds. ```py index.save("index.usearch") index.load("index.usearch") view = Index.restore("index.usearch", view=True, ...) other_view = Index(ndim=..., metric=...) other_view.view("index.usearch") ``` ## Exact vs. Approximate Search Approximate search methods, such as HNSW, are predominantly used when an exact brute-force search becomes too resource-intensive. This typically occurs when you have millions of entries in a collection. For smaller collections, we offer a more direct approach with the `search` method. ```py from usearch.index import search, MetricKind, Matches, BatchMatches import numpy as np # Generate 10'000 random vectors with 1024 dimensions vectors = np.random.rand(10_000, 1024).astype(np.float32) vector = np.random.rand(1024).astype(np.float32) one_in_many: Matches = search(vectors, vector, 50, MetricKind.L2sq, exact=True) many_in_many: BatchMatches = search(vectors, vectors, 50, MetricKind.L2sq, exact=True) ``` If you pass the `exact=True` argument, the system bypasses indexing altogether and performs a brute-force search through the entire dataset using SIMD-optimized similarity metrics from [NumKong](https://github.com/ashvardanian/numkong). When compared to FAISS's `IndexFlatL2` in Google Colab, __[USearch may offer up to a 20x performance improvement](https://github.com/unum-cloud/USearch/issues/176#issuecomment-1666650778)__: - `faiss.IndexFlatL2`: __55.3 ms__. - `usearch.index.search`: __2.54 ms__. ## User-Defined Metrics While most vector search packages concentrate on just two metrics, "Inner Product distance" and "Euclidean distance", USearch allows arbitrary user-defined metrics. This flexibility allows you to customize your search for various applications, from computing geospatial coordinates with the rare [Haversine][haversine] distance to creating custom metrics for composite embeddings from multiple AI models, like joint image-text embeddings. You can use [Numba][numba], [Cppyy][cppyy], or [PeachPy][peachpy] to define your [custom metric even in Python](https://unum-cloud.github.io/USearch/python#user-defined-metrics-and-jit-in-python): ```py from numba import cfunc, types, carray from usearch.index import Index, MetricKind, MetricSignature, CompiledMetric ndim = 256 @cfunc(types.float32(types.CPointer(types.float32), types.CPointer(types.float32))) def python_inner_product(a, b): a_array = carray(a, ndim) b_array = carray(b, n