{"id":13596992,"url":"https://github.com/rapidsai/cuvs","last_synced_at":"2025-05-14T18:02:51.100Z","repository":{"id":208328985,"uuid":"721217347","full_name":"rapidsai/cuvs","owner":"rapidsai","description":"cuVS - a library for vector search and clustering on the GPU","archived":false,"fork":false,"pushed_at":"2025-05-12T20:20:20.000Z","size":8421,"stargazers_count":403,"open_issues_count":271,"forks_count":102,"subscribers_count":18,"default_branch":"branch-25.06","last_synced_at":"2025-05-12T21:24:14.910Z","etag":null,"topics":["anns","clustering","cuda","distance","gpu","information-retrieval","llm","machine-learning","nearest-neighbors","neighborhood-methods","similarity-search","sparse","statistics","vector-search","vector-similarity","vector-store"],"latest_commit_sha":null,"homepage":"https://docs.rapids.ai/api/cuvs/stable/","language":"Cuda","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rapidsai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-11-20T15:42:25.000Z","updated_at":"2025-05-12T15:05:44.000Z","dependencies_parsed_at":"2024-01-14T15:22:16.913Z","dependency_job_id":"887fd95e-11d0-4749-b0fd-8e10f7dd1baf","html_url":"https://github.com/rapidsai/cuvs","commit_stats":{"total_commits":223,"total_committers":43,"mean_commits":5.186046511627907,"dds":0.820627802690583,"last_synced_commit":"f127b06b83e3c9e3c3034fdc902441edbf841b90"},"previous_names":["rapidsai/cuvs"],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapidsai%2Fcuvs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapidsai%2Fcuvs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapidsai%2Fcuvs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rapidsai%2Fcuvs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rapidsai","download_url":"https://codeload.github.com/rapidsai/cuvs/tar.gz/refs/heads/branch-25.06","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253826865,"owners_count":21970426,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anns","clustering","cuda","distance","gpu","information-retrieval","llm","machine-learning","nearest-neighbors","neighborhood-methods","similarity-search","sparse","statistics","vector-search","vector-similarity","vector-store"],"created_at":"2024-08-01T17:00:17.269Z","updated_at":"2025-05-14T18:02:46.091Z","avatar_url":"https://github.com/rapidsai.png","language":"Cuda","readme":"# \u003cdiv align=\"left\"\u003e\u003cimg src=\"https://rapids.ai/assets/images/rapids_logo.png\" width=\"90px\"/\u003e\u0026nbsp;cuVS: Vector Search and Clustering on the GPU\u003c/div\u003e\n\n\u003e [!note]\n\u003e cuVS is a new library mostly derived from the approximate nearest neighbors and clustering algorithms in the [RAPIDS RAFT](https://github.com/rapidsai/raft) library of machine learning and data mining primitives. As of version 24.10 (Release in October 2024), cuVS contains the most fully-featured versions of the approximate nearest neighbors and clustering algorithms from RAFT. The algorithms which have been migrated over to cuVS will be removed from RAFT in version 24.12 (released in December 2024).\n\n## Contents\n\n1. [Useful Resources](#useful-resources)\n2. [What is cuVS?](#what-is-cuvs)\n3. [Installing cuVS](#installing-cuvs)\n4. [Getting Started](#getting-started)\n5. [Contributing](#contributing)\n6. [References](#references)\n\n## Useful Resources\n\n- [Documentation](https://docs.rapids.ai/api/cuvs/nightly/): Library documentation.\n- [Build and Install Guide](https://docs.rapids.ai/api/cuvs/nightly/build): Instructions for installing and building cuVS.\n- [Getting Started Guide](https://docs.rapids.ai/api/cuvs/nightly/getting_started): Guide to getting started with cuVS.\n- [Code Examples](https://github.com/rapidsai/cuvs/tree/HEAD/examples): Self-contained Code Examples.\n- [API Reference Documentation](https://docs.rapids.ai/api/cuvs/nightly/api_docs): API Documentation.\n- [RAPIDS Community](https://rapids.ai/community.html): Get help, contribute, and collaborate.\n- [GitHub repository](https://github.com/rapidsai/cuvs): Download the cuVS source code.\n- [Issue tracker](https://github.com/rapidsai/cuvs/issues): Report issues or request features.\n\n## What is cuVS?\n\ncuVS contains state-of-the-art implementations of several algorithms for running approximate nearest neighbors and clustering on the GPU. It can be used directly or through the various databases and other libraries that have integrated it. The primary goal of cuVS is to simplify the use of GPUs for vector similarity search and clustering.\n\nVector search is an information retrieval method that has been growing in popularity over the past few  years, partly because of the rising importance of multimedia embeddings created from unstructured data and the need to perform semantic search on the embeddings to find items which are semantically similar to each other.\n\nVector search is also used in _data mining and machine learning_ tasks and comprises an important step in many _clustering_ and _visualization_ algorithms like [UMAP](https://arxiv.org/abs/2008.00325), [t-SNE](https://lvdmaaten.github.io/tsne/), K-means, and [HDBSCAN](https://hdbscan.readthedocs.io/en/latest/how_hdbscan_works.html).\n\nFinally, faster vector search enables interactions between dense vectors and graphs. Converting a pile of dense vectors into nearest neighbors graphs unlocks the entire world of graph analysis algorithms, such as those found in [GraphBLAS](https://graphblas.org/) and [cuGraph](https://github.com/rapidsai/cugraph).\n\nBelow are some common use-cases for vector search\n\n\n- ### Semantic search\n  - Generative AI \u0026 Retrieval augmented generation (RAG)\n  - Recommender systems\n  - Computer vision\n  - Image search\n  - Text search\n  - Audio search\n  - Molecular search\n  - Model training\n\n\n- ### Data mining\n  - Clustering algorithms\n  - Visualization algorithms\n  - Sampling algorithms\n  - Class balancing\n  - Ensemble methods\n  - k-NN graph construction\n\n## Why cuVS?\n\nThere are several benefits to using cuVS and GPUs for vector search, including\n\n1. Fast index build\n2. Latency critical and high throughput search\n3. Parameter tuning\n4. Cost savings\n5. Interoperability (build on GPU, deploy on CPU)\n6. Multiple language support\n7. Building blocks for composing new or accelerating existing algorithms\n\nIn addition to the items above, cuVS takes on the burden of keeping non-trivial accelerated code up to date as new NVIDIA architectures and CUDA versions are released. This provides a delightful development experience, guaranteeing that any libraries, databases, or applications built on top of it will always be getting the best performance and scale.\n\n## cuVS Technology Stack\n\ncuVS is built on top of the RAPIDS RAFT library of high performance machine learning primitives and provides all the necessary routines for vector search and clustering on the GPU.\n\n![cuVS is built on top of low-level CUDA libraries and provides many important routines that enable vector search and clustering on the GPU](img/tech_stack.png \"cuVS Technology Stack\")\n\n\n\n## Installing cuVS\n\ncuVS comes with pre-built packages that can be installed through [conda](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html#managing-python) and [pip](https://pip.pypa.io/en/stable/). Different packages are available for the different languages supported by cuVS:\n\n| Python | C/C++     |\n|--------|-----------|\n| `cuvs` | `libcuvs` |\n\n### Stable release\n\nIt is recommended to use [mamba](https://conda.github.io/conda-libmamba-solver/user-guide/) to install the desired packages. The following command will install the Python package. You can substitute `cuvs` for any of the packages in the table above:\n\n```bash\nconda install -c conda-forge -c nvidia -c rapidsai cuvs\n```\n\nThe cuVS Python package can also be `installed through pip \u003chttps://docs.rapids.ai/install#pip\u003e`_.\n\nFor CUDA 11 packages:\n```bash\npip install cuvs-cu11 --extra-index-url=https://pypi.nvidia.com\n````\n\nAnd CUDA 12 packages:\n```bash\npip install cuvs-cu12 --extra-index-url=https://pypi.nvidia.com\n```\n\n### Nightlies\nIf installing a version that has not yet been released, the `rapidsai` channel can be replaced with `rapidsai-nightly`:\n\n```bash\nconda install -c conda-forge -c nvidia -c rapidsai-nightly cuvs=25.06\n```\n\ncuVS also has `pip` wheel packages that can be installed. Please see the [Build and Install Guide](https://docs.rapids.ai/api/cuvs/nightly/build/) for more information on installing the available cuVS packages and building from source.\n\n## Getting Started\n\nThe following code snippets train an approximate nearest neighbors index for the CAGRA algorithm in the various different languages supported by cuVS.\n\n### Python API\n\n```python\nfrom cuvs.neighbors import cagra\n\ndataset = load_data()\nindex_params = cagra.IndexParams()\n\nindex = cagra.build(build_params, dataset)\n```\n\n### C++ API\n\n```c++\n#include \u003ccuvs/neighbors/cagra.hpp\u003e\n\nusing namespace cuvs::neighbors;\n\nraft::device_matrix_view\u003cfloat\u003e dataset = load_dataset();\nraft::device_resources res;\n\ncagra::index_params index_params;\n\nauto index = cagra::build(res, index_params, dataset);\n```\n\nFor more code examples of the C++ APIs, including drop-in Cmake project templates, please refer to the [C++ examples](https://github.com/rapidsai/cuvs/tree/HEAD/examples) directory in the codebase.\n\n### C API\n\n```c\n#include \u003ccuvs/neighbors/cagra.h\u003e\n\ncuvsResources_t res;\ncuvsCagraIndexParams_t index_params;\ncuvsCagraIndex_t index;\n\nDLManagedTensor *dataset;\nload_dataset(dataset);\n\ncuvsResourcesCreate(\u0026res);\ncuvsCagraIndexParamsCreate(\u0026index_params);\ncuvsCagraIndexCreate(\u0026index);\n\ncuvsCagraBuild(res, index_params, dataset, index);\n\ncuvsCagraIndexDestroy(index);\ncuvsCagraIndexParamsDestroy(index_params);\ncuvsResourcesDestroy(res);\n```\n\nFor more code examples of the C APIs, including drop-in Cmake project templates, please refer to the [C examples](https://github.com/rapidsai/cuvs/tree/branch-25.06/examples/c)\n\n### Rust API\n\n```rust\nuse cuvs::cagra::{Index, IndexParams, SearchParams};\nuse cuvs::{ManagedTensor, Resources, Result};\n\nuse ndarray::s;\nuse ndarray_rand::rand_distr::Uniform;\nuse ndarray_rand::RandomExt;\n\n/// Example showing how to index and search data with CAGRA\nfn cagra_example() -\u003e Result\u003c()\u003e {\n    let res = Resources::new()?;\n\n    // Create a new random dataset to index\n    let n_datapoints = 65536;\n    let n_features = 512;\n    let dataset =\n        ndarray::Array::\u003cf32, _\u003e::random((n_datapoints, n_features), Uniform::new(0., 1.0));\n\n    // build the cagra index\n    let build_params = IndexParams::new()?;\n    let index = Index::build(\u0026res, \u0026build_params, \u0026dataset)?;\n    println!(\n        \"Indexed {}x{} datapoints into cagra index\",\n        n_datapoints, n_features\n    );\n\n    // use the first 4 points from the dataset as queries : will test that we get them back\n    // as their own nearest neighbor\n    let n_queries = 4;\n    let queries = dataset.slice(s![0..n_queries, ..]);\n\n    let k = 10;\n\n    // CAGRA search API requires queries and outputs to be on device memory\n    // copy query data over, and allocate new device memory for the distances/ neighbors\n    // outputs\n    let queries = ManagedTensor::from(\u0026queries).to_device(\u0026res)?;\n    let mut neighbors_host = ndarray::Array::\u003cu32, _\u003e::zeros((n_queries, k));\n    let neighbors = ManagedTensor::from(\u0026neighbors_host).to_device(\u0026res)?;\n\n    let mut distances_host = ndarray::Array::\u003cf32, _\u003e::zeros((n_queries, k));\n    let distances = ManagedTensor::from(\u0026distances_host).to_device(\u0026res)?;\n\n    let search_params = SearchParams::new()?;\n\n    index.search(\u0026res, \u0026search_params, \u0026queries, \u0026neighbors, \u0026distances)?;\n\n    // Copy back to host memory\n    distances.to_host(\u0026res, \u0026mut distances_host)?;\n    neighbors.to_host(\u0026res, \u0026mut neighbors_host)?;\n\n    // nearest neighbors should be themselves, since queries are from the\n    // dataset\n    println!(\"Neighbors {:?}\", neighbors_host);\n    println!(\"Distances {:?}\", distances_host);\n    Ok(())\n}\n```\n\nFor more code examples of the Rust APIs, including a drop-in project templates, please refer to the [Rust examples](https://github.com/rapidsai/cuvs/tree/branch-25.06/examples/rust).\n\n## Contributing\n\nIf you are interested in contributing to the cuVS library, please read our [Contributing guidelines](docs/source/contributing.md). Refer to the [Developer Guide](docs/source/developer_guide.md) for details on the developer guidelines, workflows, and principles.\n\n## References\n\nFor the interested reader, many of the accelerated implementations in cuVS are also based on research papers which can provide a lot more background. We also ask you to please cite the corresponding algorithms by referencing them in your own research.\n- [CAGRA: Highly Parallel Graph Construction and Approximate Nearest Neighbor Search](https://arxiv.org/abs/2308.15136)\n- [Top-K Algorithms on GPU: A Comprehensive Study and New Methods](https://dl.acm.org/doi/10.1145/3581784.3607062)\n- [Fast K-NN Graph Construction by GPU Based NN-Descent](https://dl.acm.org/doi/abs/10.1145/3459637.3482344?casa_token=O_nan1B1F5cAAAAA:QHWDEhh0wmd6UUTLY9_Gv6c3XI-5DXM9mXVaUXOYeStlpxTPmV3nKvABRfoivZAaQ3n8FWyrkWw\u003e)\n- [cuSLINK: Single-linkage Agglomerative Clustering on the GPU](https://arxiv.org/abs/2306.16354)\n- [GPU Semiring Primitives for Sparse Neighborhood Methods](https://arxiv.org/abs/2104.06357)\n","funding_links":[],"categories":["Open Sources","Multidimensional data / Vectors","Cuda"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frapidsai%2Fcuvs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frapidsai%2Fcuvs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frapidsai%2Fcuvs/lists"}