Update README.md#136
Conversation
| ## Building | ||
| ## What is cuvs-lucene? | ||
|
|
||
| `cuvs-lucene` provides a pluggable [KnnVectorsFormat](https://lucene.apache.org/core/10_3_1/core/org/apache/lucene/codecs/KnnVectorsFormat.html) that uses cuVS to offload vector index build — and optionally search — to NVIDIA GPUs. Because it plugs in through a standard Lucene codec, existing Lucene applications can take advantage of GPU acceleration with minimal code changes and gracefully fall back to the default CPU codec when no GPU is present. |
There was a problem hiding this comment.
The link uses docs for 10.3.1. We can instead use https://lucene.apache.org/core/10_2_0/core/org/apache/lucene/codecs/KnnVectorsFormat.html as we currently use 10.2.0
| - `Lucene101AcceleratedHNSWCodec` — GPU-accelerated HNSW build with CPU HNSW search. The on-disk format is standard Lucene HNSW, so indexes built on the GPU can be read by any stock Lucene 10.x reader. | ||
| - `LuceneAcceleratedHNSWScalarQuantizedCodec` — scalar-quantized vectors for a smaller index footprint. | ||
| - `LuceneAcceleratedHNSWBinaryQuantizedCodec` — binary-quantized vectors for an even smaller index footprint. | ||
| - `CuVS2510GPUSearchCodec` — GPU-accelerated HNSW build and GPU search |
There was a problem hiding this comment.
I don't think we have a codec for CPU build HNSW search. We have codecs for GPU build CPU search and for GPU build GPU search. Can you verify? @narangvivek10
There was a problem hiding this comment.
CPU build HNSW search
I guess here you mean indexing on the CPU and searching on the CPU for HNSW. No, we do not because Lucene itself has codecs and formats available for that. We, however, have a fallback mechanism in formats like, for example, in Lucene99AcceleratedHNSWVectorsFormat that internally refers to Lucene's index and search on CPU logic. This is helpful for people who use our Codec/format, and they do not have a GPU/cuVS available.
| - [CUDA 12.0+](https://developer.nvidia.com/cuda-toolkit-archive) | ||
| - [JDK 22](https://jdk.java.net/archive/) | ||
| - [Maven 3.9.6+](https://maven.apache.org/download.cgi) | ||
| - The native `libcuvs_c.so` on the runtime library path. Please see the cuVS [Build and Install Guide](https://docs.rapids.ai/api/cuvs/nightly/build/) for install options (conda, pip, tarball, or build from source). |
There was a problem hiding this comment.
I think a better way to word this for the uninformed user is that they just that they should have a compatible version of cuvs installed. I think this also warrants adding a page to the cuvs docs on what a compatible version means (spoiler alert- we change the ABI twice a year- 2x.02 and 2x.08, so 2, 4, 6 are compatible with each other and 8, 10, 12 are compatible with each other). You should just be able to say "cuVS 24.04 - 24.06" for the compatible version. We'll bump this every version.
| The artifacts would be built and available in the target / folder. | ||
|
|
||
| ### Running Tests | ||
| The resulting artifacts are written to `target/`. To run the tests, point `LD_LIBRARY_PATH` at a local `libcuvs_c.so`: |
There was a problem hiding this comment.
I think we should try to avoid using libcuvs_c.so explicitly where possible and tell fols to install the cuvs tarball. (You can point to the tarball install instructions. Same as above in the prereqs).
|
|
||
| ## Getting Started | ||
|
|
||
| The snippet below plugs the GPU-accelerated HNSW codec into a standard Lucene `IndexWriter`. Once the codec is set on the `IndexWriterConfig`, indexing proceeds exactly as it would with the default Lucene codec, and search uses the stock `KnnFloatVectorQuery`: |
There was a problem hiding this comment.
Did you verify this locally by copying into a file and building?
| } | ||
| ``` | ||
|
|
||
| For fully runnable versions of this example, including one that indexes and searches entirely on the GPU using `CuVS2510GPUSearchCodec`, please refer to the [`examples/`](examples) directory. |
There was a problem hiding this comment.
Can you verify this link renders properly? Maybe github has updated it, but I've never had luck trying to get highlighted code snippets to render as links.
There was a problem hiding this comment.
Yep, it renders properly. You can can check the rendered Readme on my branch:
https://github.com/aamijar/cuvs-lucene/tree/update-readme
| try (Directory dir = FSDirectory.open(indexPath); | ||
| IndexWriter writer = new IndexWriter(dir, config)) { | ||
| Document doc = new Document(); | ||
| doc.add(new KnnFloatVectorField("vector_field", embedding, EUCLIDEAN)); |
There was a problem hiding this comment.
I notice embedding here, which I guess isn't pointing to anything. Am I missing something? Ideally, we should have code snippets that folks would just want to copy and see in action without the need to make changes for it to work.
3 participants
This PR improves the README.md in the following ways: