Add int8 / byte-vector similarity support by r-devulap · Pull Request #709 · datastax/jvector

r-devulap · 2026-08-11T08:26:34Z

INT8 (Byte-Vector) Support for JVector

Overview

This branch adds full INT8 (byte-vector) support to JVector — from the math primitives all the way through graph building, on-disk storage, SIMD acceleration, and end-to-end tests.

Commits

1. `fd131a7` — Add random-access int8 vector value support

Introduces a new VectorValues super-interface that captures shared random-access behavior, then refactors RandomAccessVectorValues (float) to extend it, and adds RandomAccessByteVectorValues and its list-backed implementation ListRandomAccessByteVectorValues as the byte-vector counterpart. Also updates BuildScoreProvider to use the generalized thread-local supplier.

2. `c55574c` — Add byte-similarity methods to VectorUtilSupport / VectorUtil / DefaultVectorUtilSupport

Adds dotProduct, squaredL2, and cosine for byte[] / ByteSequence to the vector utility stack.

3. `9ba737a` — Add ByteVectorSimilarityFunction enum

Mirrors the float VectorSimilarityFunction enum; wraps the three byte similarity metrics with a compare() API and score normalization.

4. `5652b46` — Add BuildScoreProvider.byteVectorScoreProvider and searchProviderFor(ByteSequence)

Adds byteVectorScoreProvider() factory and searchProviderFor(ByteSequence) so the graph builder can score byte-vector candidates.

5. `389c391` — Wire byteVectorScoreProvider into GraphIndexBuilder

GraphIndexBuilder now accepts RandomAccessByteVectorValues and routes to the byte score provider, enabling full graph construction over int8 data.

6. `c6dfea0` — Vectorize ByteSequence similarity metrics with SIMD

Panama SIMD and AVX-512 native kernels for int8 dot-product, L2, and cosine; adds native benchmarks and C++ unit tests.

7. `3d4dada` — Add InlineByteVectors feature for native int8 on-disk storage

New FeatureId and InlineByteVectors class for serializing byte vectors into the graph index file format, plus OnDiskGraphIndex reader support.

8. `974f508` — Add INT8 end-to-end tutorial (Int8Example)

End-to-end walkthrough showing how to build, serialize, and query a byte-vector graph index; registered in TutorialRunner.

9. `b0ad5cd` — Add int8 test coverage for byte-vector similarity, RABVV, BSP, SIMD, graph build, and disk round-trip

Unit tests for ByteVectorSimilarityFunction, BuildScoreProvider, TestVectorizationProvider (SIMD), TestVectorGraph (build), TestOnDiskGraphIndex (round-trip), and ListRandomAccessByteVectorValues.

github-actions · 2026-08-11T08:26:44Z

r-devulap · 2026-08-12T04:31:32Z

To do:

Update all the docs/README to reflect these changes
Add release notes
Add BenchYAML results

jshook

This PR needs to be updated.

merge conflicts need to be addressed
the base commit this branch depends on should probably determine the target of the merge, rather than main, since there are direct dependencies.

r-devulap · 2026-08-17T14:24:29Z

This PR needs to be updated.

merge conflicts need to be addressed

Fixed, it is now rebased with the latest changes in main.

the base commit this branch depends on should probably determine the target of the merge, rather than main, since there are direct dependencies.

This is no longer a problem since it includes the commits in #708

r-devulap · 2026-08-18T07:52:29Z

Marking this as draft until I resolve the question of leveraging NVQ for INT8.

MarkWolters

Thanks for addressing my requested changes!

tlwillke · 2026-09-17T21:23:51Z

@r-devulap this missing acceptance criteria and evidence that it is met. It involves new scoring on a new vector type. We either need the requester(s) to provide some dataset benchmarks and metrics (what is acceptable recall and performance?), or we need to create int8 datasets and set our own standards. How do you want to proceed?

r-devulap · 2026-09-21T03:43:56Z

We either need the requester(s) to provide some dataset benchmarks and metrics (what is acceptable recall and performance?)

@lvca is it possible to provide some datasets that we can you use to measure recall and performance?

lvca · 2026-09-21T04:24:21Z

@tae898 Can you help on this?

tae898 · 2026-09-21T15:24:01Z

@r-devulap

I've been benchmarking ArcadeDB's jvector-backed vector index on SIFT-1M and DEEP-10M, fp32 and int8, for both build and search.

The datasets I've been using are not int8:

http://ann-benchmarks.com/sift-128-euclidean.hdf5 — 501 MiB, 1,000,000×128, L2
http://ann-benchmarks.com/deep-image-96-angular.hdf5 — 3.58 GiB, 9,990,000×96, angular

So each vector db used their own quantization function to turn fp32 into int8. If you are looking for more "formal" int8 vector dataset, perhaps these two are not the best ones.

Worth knowing what "int8" means on the ArcadeDB side: the index writes an int8 copy of each vector into its own pages, then dequantizes back to float32 on the read path, so jvector always receives float32. That's the gap filed in #665.

My results: https://humem.ai/projects/arcadedb. Those are databases, not libraries, so it isn't a direct comparison with jvector on its own.

Let me know if there's anything else I can help you with.

r-devulap · 2026-09-24T03:27:51Z

@tae898 & @lvca Thanks for your response and patience. We are close to merging this. I will use quantize those datasets to INT8 and add them to our benchYAML pipeline and get some recall/perf numbers for our reference. That should hopefully complete this patch.

…ByteSequence) Add a new static factory byteVectorScoreProvider(RandomAccessByteVectorValues, ByteVectorSimilarityFunction) that performs exact byte×byte scoring with no float32 round-trip. The returned BuildScoreProvider implements isExact()=true, approximateCentroid(), searchProviderFor(ByteSequence), searchProviderFor(int), diversityProviderFor(int), and diversityScoreFunctionFor(int), using two independent threadLocalSupplier() handles for thread-safe concurrent builds. Also adds a default searchProviderFor(ByteSequence<?>) to the interface that throws UnsupportedOperationException, so existing float-based providers are unaffected.

Add builder(RandomAccessByteVectorValues, ByteVectorSimilarityFunction, int M) and builder(..., List<Integer> maxDegrees) factory overloads so callers can build a graph over int8 byte vectors without touching the builder core. Generalize build(RandomAccessVectorValues) to build(VectorValues<?>) and switch the parallel addGraphNode loop to use scoreProvider.searchProviderFor(node) directly, removing the float-only getVector path that was incompatible with byte-vector score providers. Add addGraphNode(int node, ByteSequence<?> vector) as a public single-node insertion entry point for byte vectors. Update TestVectorGraph to add explicit casts (RandomAccessVectorValues, VectorSimilarityFunction) on the null arguments so the compiler resolves the correct overload now that the new byte-vector builder() overloads exist.

Replace scalar loop implementations of dotProduct, squareDistance, and cosine for ByteSequence with Panama Vector API implementations in PanamaVectorUtilSupport, and native AVX-512/AVX2 kernels wired through NativeVectorUtilSupport -> NativeSimdOps JNI bindings. Java (Panama) path: - Widen signed bytes to int32 via B2I conversion, accumulate products in IntVector lanes, then reduce. - Dispatch on PREFERRED_BIT_SIZE: 512-bit: load 16 bytes (SPECIES_128) -> IntVector.SPECIES_512 256-bit: load 8 bytes (SPECIES_64) -> IntVector.SPECIES_256 128-bit: scalar fallback - cosine variants accumulate dot/norm products in long after reduction to avoid int32 overflow on large vectors. Native path (C++): - New kernels in jvector_simd_kernels.cpp and jvector_avx3_dl_kernels.cpp: dot_product_i8, euclidean_i8, cosine_i8 using Highway SIMD (AVX-512 / AVX2 dispatch). - Registered in jvector_simd_kernel_list.h and exported via jvector_simd.cpp. - Microbenchmarks added in bench_similarity_i8.cpp. - C++ unit tests added in test_similarity_i8.cpp using a prime-length (107-element) vector to exercise tail handling. Java tests: - TestVectorizationProvider.testSimilarityMetricsByte cross-checks SIMD results against scalar DefaultVectorUtilSupport baseline.

Introduces InlineByteVectors, a new Feature that stores signed int8 vectors inline in an OnDiskGraphIndex at 1 byte per component — 4x more compact than the float32 InlineVectors representation. Changes: - InlineByteVectors.java: new Feature implementation backed by VectorTypeSupport.writeByteSequence / readByteSequence - FeatureId: add INLINE_BYTE_VECTORS as ordinal 5 (backward-compatible) - AbstractGraphIndexWriter.Builder: accept INLINE_BYTE_VECTORS as the canonical source for the vector dimension in the file header - OnDiskGraphIndex.View: add getByteVector(int) to read a stored int8 vector from disk, and byteVectorRerankerFor(ByteSequence, ByteVectorSimilarityFunction) to wire byte-by-byte disk scoring directly into the search path

Demonstrates the full int8 pipeline using the siftsmall dataset: - Read siftsmall_base.fvecs and convert float32 vectors to signed int8 - Build a graph index with byte-by-byte scoring (no float32 round-trip) - Save the graph to disk using InlineByteVectors (1 byte/component) - Load the index from disk - Search with random int8 query vectors, scoring directly from disk byte vectors Also registers the tutorial under the 'int8' key in TutorialRunner.

…graph build, and disk round-trip

…DUCT

…ilingual-v3 (1M) to BenchYAML

- RandomAccessVectorValues/RandomAccessByteVectorValues: covariant threadLocalSupplier() overrides; VectorValues returns Supplier<? extends ...> - BuildScoreProvider: drop asRandomAccessSupplier now that the supplier is typed - GraphIndexBuilder.build: read float sources through per-thread views so borrowed vectors are not shared across workers - AbstractGraphIndexFormat: v6 supports INLINE_BYTE_VECTORS (test updated) - NativeVectorUtilSupport: remove leftover merge conflict marker and fix braces - provider-selection fixtures: export dot_product_i8, euclidean_i8, cosine_i8

…peline New types and APIs: - BaseDataSet: common interface for all dataset types (size(), getQueryCount(), getDimension(), getName(), getGroundTruth()); DataSet and the new ByteDataSet both extend it, replacing the previous DataSet-only hierarchy - ByteDataSet: interface for signed int8 vector datasets (getBaseRavv, getSimilarityFunction, getBaseVectors, getQueryVectors) - ByteSimpleDataSet: concrete in-memory implementation of ByteDataSet - DataSetProperties.isInt8() / KEY_IS_INT8: metadata flag that signals a dataset stores native byte vectors - SiftLoader.readBvecs(): reads .bvecs files into List<ByteSequence<?>> Dataset loading: - DataSetLoaderSimpleMFD: branches on isInt8() to call readBvecs and return a ByteSimpleDataSet; buffered loading is rejected for int8 datasets - DataSetInfo.getDataSet() is now generic (<T extends BaseDataSet>) to avoid unchecked casts at call sites Index build and write: - Grid: new int8 build path uses BuildScoreProvider.byteVectorScoreProvider, writes INLINE_BYTE_VECTORS feature; the existing float path is preserved and selected via instanceof dispatch - ConfiguredSystem.ds typed as BaseDataSet; scoreProviderFor(ByteSequence, View) added for int8 queries; exactVectors is null for int8 datasets Query execution and benchmarks: - QueryExecutor.executeQuery dispatches to float or int8 path based on dataset type; new overload for ByteSequence queries - ThroughputBenchmark warm-up generates random signed byte queries for int8 datasets instead of random float vectors - AccuracyBenchmark, CountBenchmark, ExecutionTimeBenchmark, LatencyBenchmark: switched from getQueryVectors().size() to getQueryCount() YAML config validation: - ConstructionParameters: reranking and fusedGraph default to ["FP"] / [false] when absent, so int8 YAML configs need not specify them - MultiConfig.validateForInt8Dataset(): throws if reranking is set or any compression type is not "None"; called in BenchYAML and AutoBenchYAML immediately after the dataset is loaded Reporting: - DatasetInfoWriter.createRow() and RunArtifacts.registerDataset() accept BaseDataSet; similarity function is resolved via instanceof - AutoBenchYAML: compaction benchmark is skipped for int8 datasets; ds.size() used in place of getBaseVectors().size() Dataset metadata: - dataset-metadata.yml: new int8 dataset entries added

- RandomAccessVectorValues: redeclare VectorFloat<?> getVector(int) so the float-vector binary signature is retained for existing callers and implementations. - GraphIndexBuilder: keep build(RandomAccessVectorValues) as a forwarding overload of build(VectorValues<?>) for binary compatibility. - ByteVectorSimilarityFunction.EUCLIDEAN: use 1 / (1 + squaredL2) like the float version. Dividing by n * 255^2 collapsed nearby distances to the same float score (e.g. squared distances 0..3 at 1024 dimensions) and broke ratio-based diversity pruning. - BuildScoreProvider.byteVectorScoreProvider: copy the reference vector when the source shares its buffer, mirroring the float provider, so creating another scorer no longer changes earlier comparisons.

- PanamaVectorUtilSupport: support sliced byte inputs in the 256/512-bit dot product, squared distance and cosine paths. fromByteSequence no longer casts to ArrayByteSequence (which threw ClassCastException for slices), and the loads now start at offset() + i. - BuildScoreProvider.byteVectorScoreProvider: skip null vectors in approximateCentroid, matching the float provider. - SiftLoader: rename readBvecs to readInt8Bvecs and document that only signed int8 payloads are supported, not the conventional unsigned uint8 .bvecs format. Clarify the same contract on DataSetProperties.isInt8/KEY_IS_INT8, in dataset-metadata.yml and at the DataSetLoaderSimpleMFD call site. Also move the isValid Javadoc back onto isValid. - VectorUtil.cosine(ByteSequence, ByteSequence): mirror the float overload with a dimension check and an assertion that the result is finite; zero vectors are documented as unsupported.

… for disk reranking - DefaultVectorUtilSupport: accumulate byte dotProduct and squareDistance in int and byte cosine in long/double, converting to float only at the end. This matches the Panama and native implementations and avoids float rounding differences above 2^24 in high dimensions. - OnDiskGraphIndex.View: add getByteVectorInto, mirroring getVectorInto, and have byteVectorRerankerFor reuse one scratch ByteSequence instead of allocating a new vector for every comparison. getByteVector now delegates to getByteVectorInto. The reranker is documented as not thread-safe.

- TestByteVectorSimilarityFunction: update the EUCLIDEAN known value for the un-normalized 1 / (1 + squaredL2) mapping; add tests that small squared distances stay distinct at 1024 dimensions, sliced inputs match a scalar reference, the Default implementation accumulates exactly at 4096 dimensions, and cosine rejects mismatched dimensions and (under -ea) zero vectors. - BuildScoreProviderTest: add shared-buffer tests for byte search/diversity score functions and a test that approximateCentroid skips null vectors. - TestOnDiskGraphIndex: add a test that the disk reranker's reused scratch vector gives correct scores in any order and that getByteVectorInto matches getByteVector.

Replace the n*128^2 normalisation, which collapsed adjacent dot products to the same float32 score at ~1,024 dimensions, with a monotone mapping (dot < 0 ? 1/(1-dot) : dot+1). Update tests and add a high-dimension distinctness test.

Use it in the byte BuildScoreProvider to fill the private anchor copy directly. Relax the on-disk end-to-end score range check for the unbounded int8 DOT_PRODUCT mapping.

…ults getFeatureSets() now fails with a clear message when reranking or fusedGraph is missing. Int8 datasets get their own feature set (INLINE_BYTE_VECTORS) and reject fusedGraph: [Yes]. Also drop a redundant same-package VectorValues import in GraphIndexBuilder.

…float path The byte branch previously used the argument only for size() and took vectors from the score provider. It now reads them through a per-thread view and rejects unsupported VectorValues types.

r-devulap · 2026-11-05T05:45:49Z

Updates:

Rebase with main.
Addressed all review feedback (except for reranking, yet to resolve that one)
Added release notes.
Completed the PR checklist (will review the Bench results once its available).

RandomizedTest's nextBytes is biased toward zero runs, so short slices can be the zero vector, for which cosine is undefined. Skip the cosine check in the sliced-input test when a norm is zero, and draw non-zero vectors in the other random cosine tests.

r-devulap requested review from MarkWolters, ashkrisk, jshook and tlwillke as code owners August 11, 2026 08:26

r-devulap linked an issue Aug 11, 2026 that may be closed by this pull request

Native INT8 (byte vector) HNSW build + search API #665

Open

r-devulap mentioned this pull request Aug 11, 2026

Native INT8 (byte vector) HNSW build + search API #665

Open

r-devulap force-pushed the int8-support branch from 7aec240 to 9ee1486 Compare August 11, 2026 08:29

jshook requested changes Aug 14, 2026

View reviewed changes

r-devulap force-pushed the int8-support branch from 9ee1486 to 4c789ac Compare August 17, 2026 14:22

r-devulap marked this pull request as draft August 18, 2026 07:51

r-devulap force-pushed the int8-support branch 2 times, most recently from 2515d75 to 09c4e3c Compare September 2, 2026 10:09

r-devulap force-pushed the int8-support branch from 09c4e3c to ecc9edd Compare September 7, 2026 04:12

r-devulap marked this pull request as ready for review September 7, 2026 04:17

r-devulap marked this pull request as draft September 7, 2026 04:21

r-devulap force-pushed the int8-support branch from ecc9edd to b0ad5cd Compare September 8, 2026 07:59

r-devulap marked this pull request as ready for review September 8, 2026 08:04

MarkWolters reviewed Sep 8, 2026

View reviewed changes

Comment thread jvector-twenty/src/main/java/io/github/jbellis/jvector/vector/PanamaVectorUtilSupport.java Resolved

MarkWolters requested changes Sep 10, 2026

View reviewed changes

Comment thread jvector-base/src/main/java/io/github/jbellis/jvector/graph/similarity/BuildScoreProvider.java Resolved

Comment thread jvector-base/src/main/java/io/github/jbellis/jvector/vector/ByteVectorSimilarityFunction.java Resolved

r-devulap force-pushed the int8-support branch from ae41d3d to 2964864 Compare September 15, 2026 08:58

MarkWolters approved these changes Sep 15, 2026

View reviewed changes

r-devulap added 25 commits November 5, 2026 05:38

Add int8 test coverage for byte-vector similarity, RABVV, BSP, SIMD, …

038630e

…graph build, and disk round-trip

Remove dead offset locals from byte similarity methods

5058cb3

Fix maxMagnitude calculation for ByteVectorSimilarityFunction.DOT_PRO…

eba5d5a

…DUCT

Extract asRandomAccessSupplier with type check in BuildScoreProvider

7ba4f24

Add INT8 dataset configs for wikipedia-2023-11-en-mxbai and wiki-mult…

bad2515

…ilingual-v3 (1M) to BenchYAML

Fix dot_product_i8 and cosine_i8 odd accumulator loss on ARM SVE/NEON

1667b91

Get rid of local paths

90cb671

Mark new int8 vector APIs as @experimental

ce14e62

Add getVectorInto to the common VectorValues interface

1703eb0

Use it in the byte BuildScoreProvider to fill the private anchor copy directly. Relax the on-disk end-to-end score range check for the unbounded int8 DOT_PRODUCT mapping.

Fix Int8Example comments: siftsmall ships with the repo

6d242b4

Make GraphIndexBuilder.build read the supplied int8 vectors like the …

630ea61

…float path The byte branch previously used the argument only for size() and took vectors from the score provider. It now reads them through a per-thread view and rejects unsupported VectorValues types.

Add 4.1.0 release note for int8 vector support

ae896f4

r-devulap force-pushed the int8-support branch from 575dcee to ae896f4 Compare November 5, 2026 05:42

MarkWolters added 4.1.0 Release Label enhancement New feature or request labels Nov 6, 2026

Conversation

r-devulap commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

INT8 (Byte-Vector) Support for JVector

Overview

Commits

1. fd131a7 — Add random-access int8 vector value support

2. c55574c — Add byte-similarity methods to VectorUtilSupport / VectorUtil / DefaultVectorUtilSupport

3. 9ba737a — Add ByteVectorSimilarityFunction enum

4. 5652b46 — Add BuildScoreProvider.byteVectorScoreProvider and searchProviderFor(ByteSequence)

5. 389c391 — Wire byteVectorScoreProvider into GraphIndexBuilder

6. c6dfea0 — Vectorize ByteSequence similarity metrics with SIMD

7. 3d4dada — Add InlineByteVectors feature for native int8 on-disk storage

8. 974f508 — Add INT8 end-to-end tutorial (Int8Example)

9. b0ad5cd — Add int8 test coverage for byte-vector similarity, RABVV, BSP, SIMD, graph build, and disk round-trip

Uh oh!

github-actions Bot commented Aug 11, 2026 • edited by r-devulap Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

r-devulap commented Aug 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jshook left a comment

Choose a reason for hiding this comment

Uh oh!

r-devulap commented Aug 17, 2026

Uh oh!

r-devulap commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MarkWolters left a comment

Choose a reason for hiding this comment

Uh oh!

tlwillke commented Sep 17, 2026

Uh oh!

r-devulap commented Sep 21, 2026

Uh oh!

lvca commented Sep 21, 2026

Uh oh!

tae898 commented Sep 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

r-devulap commented Sep 24, 2026

Uh oh!

r-devulap commented Nov 5, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

r-devulap commented Aug 11, 2026 •

edited

Loading

1. `fd131a7` — Add random-access int8 vector value support

2. `c55574c` — Add byte-similarity methods to VectorUtilSupport / VectorUtil / DefaultVectorUtilSupport

3. `9ba737a` — Add ByteVectorSimilarityFunction enum

4. `5652b46` — Add BuildScoreProvider.byteVectorScoreProvider and searchProviderFor(ByteSequence)

5. `389c391` — Wire byteVectorScoreProvider into GraphIndexBuilder

6. `c6dfea0` — Vectorize ByteSequence similarity metrics with SIMD

7. `3d4dada` — Add InlineByteVectors feature for native int8 on-disk storage

8. `974f508` — Add INT8 end-to-end tutorial (Int8Example)

9. `b0ad5cd` — Add int8 test coverage for byte-vector similarity, RABVV, BSP, SIMD, graph build, and disk round-trip

github-actions Bot commented Aug 11, 2026 •

edited by r-devulap

Loading

r-devulap commented Aug 12, 2026 •

edited

Loading

r-devulap commented Aug 18, 2026 •

edited

Loading

tae898 commented Sep 21, 2026 •

edited

Loading