Skip to content

Add fp16 (float16) vector encoding support - no quantization support #16383

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
msokolov merged 5 commits into from
Jul 27, 2026
Merged

Add fp16 (float16) vector encoding support - no quantization support #16383

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2e75346
feat: Add fp16 (float16) vector encoding support
Pulkitg64 Jul 10, 2026
cea9b63
Fixed typo
Pulkitg64 Jul 10, 2026
2a6f9e1
Update the github change id in CHANGES.txt
Pulkitg64 Jul 10, 2026
2a839c5
Addressed comments: fixed comments and java docs
Pulkitg64 Jul 13, 2026
497631d
Addressed some more comments
Pulkitg64 Jul 16, 2026
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
2 changes: 2 additions & 0 deletions lucene/CHANGES.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -313,6 +313,8 @@ New Features
and document length instead of corpus statistics such as document frequency. It also supports k3
query-term frequency saturation. (Tianxiao Wei)

* GITHUB#16383: Add fp16 vector encoding support. (Pulkit Gupta)

Improvements
---------------------

Expand Down
7 changes: 7 additions & 0 deletions ...rc/java/org/apache/lucene/backward_codecs/lucene102/Lucene102BinaryFlatVectorsScorer.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,13 @@ public RandomVectorScorer getRandomVectorScorer(
return nonQuantizedDelegate.getRandomVectorScorer(similarityFunction, vectorValues, target);
}

@Override
public RandomVectorScorer getRandomVectorScorer(

@mikemccand mikemccand Jul 21, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there some reason we can't add a default implementation in the base interface/class that does this? It makes me nervous seeing so many backwards-codecs sources changing... but it looks like it's mostly (entirely?) these new short[] / Float16 boilerplate methods.

@Pulkitg64 Pulkitg64 Jul 22, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually here I followed the same pattern as Byte vector encoding, I think byte vector encoding was implemented in the same way where we added UnsupportedOperationException explicitly in every backward codec files.
Moreover since these functions are abstract (getRandomVectorScorer, abstract, getVectorValues)in the base class, this makes every subclass to take decision forcibly on implementing and completing these functions which may be better than just implementing the default.

But if we want to make this as default implementation, this needs to change across all three vector encoding not just Float16.

VectorSimilarityFunction similarityFunction, KnnVectorValues vectorValues, short[] target)
throws IOException {
throw new UnsupportedOperationException();
}

@Override
public String toString() {
return "Lucene102BinaryFlatVectorsScorer(nonQuantizedDelegate=" + nonQuantizedDelegate + ")";
Expand Down
11 changes: 11 additions & 0 deletions ...va/org/apache/lucene/backward_codecs/lucene102/Lucene102BinaryQuantizedVectorsReader.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@
import org.apache.lucene.index.DocsWithFieldSet;
import org.apache.lucene.index.FieldInfo;
import org.apache.lucene.index.FieldInfos;
import org.apache.lucene.index.Float16VectorValues;
import org.apache.lucene.index.FloatVectorValues;
import org.apache.lucene.index.IndexFileNames;
import org.apache.lucene.index.KnnVectorValues;
Expand Down Expand Up @@ -211,6 +212,11 @@ public RandomVectorScorer getRandomVectorScorer(String field, byte[] target) thr
return rawVectorsReader.getRandomVectorScorer(field, target);
}

@Override
public RandomVectorScorer getRandomVectorScorer(String field, short[] target) throws IOException {
throw new UnsupportedOperationException();
}

@Override
public void checkIntegrity(MergePolicy.OneMerge merge) throws IOException {
rawVectorsReader.checkIntegrity(merge);
Expand Down Expand Up @@ -253,6 +259,11 @@ public ByteVectorValues getByteVectorValues(String field) throws IOException {
return rawVectorsReader.getByteVectorValues(field);
}

@Override
public Float16VectorValues getFloat16VectorValues(String field) throws IOException {
throw new UnsupportedOperationException();
}

@Override
public void search(String field, byte[] target, KnnCollector knnCollector, AcceptDocs acceptDocs)
throws IOException {
Expand Down
12 changes: 12 additions & 0 deletions ...codecs/src/java/org/apache/lucene/backward_codecs/lucene90/Lucene90HnswVectorsReader.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
import org.apache.lucene.index.CorruptIndexException;
import org.apache.lucene.index.FieldInfo;
import org.apache.lucene.index.FieldInfos;
import org.apache.lucene.index.Float16VectorValues;
import org.apache.lucene.index.FloatVectorValues;
import org.apache.lucene.index.IndexFileNames;
import org.apache.lucene.index.MergePolicy;
Expand Down Expand Up @@ -243,6 +244,11 @@ public ByteVectorValues getByteVectorValues(String field) {
throw new UnsupportedOperationException();
}

@Override
public Float16VectorValues getFloat16VectorValues(String field) throws IOException {
throw new UnsupportedOperationException();
}

@Override
public void search(String field, float[] target, KnnCollector knnCollector, AcceptDocs acceptDocs)
throws IOException {
Expand Down Expand Up @@ -280,6 +286,12 @@ public void search(String field, byte[] target, KnnCollector knnCollector, Accep
throw new UnsupportedOperationException();
}

@Override
public void search(String field, short[] target, KnnCollector knnCollector, AcceptDocs acceptDocs)
throws IOException {
throw new UnsupportedOperationException();
}

private OffHeapFloatVectorValues getOffHeapVectorValues(FieldEntry fieldEntry)
throws IOException {
IndexInput bytesSlice =
Expand Down
12 changes: 12 additions & 0 deletions ...codecs/src/java/org/apache/lucene/backward_codecs/lucene91/Lucene91HnswVectorsReader.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
import org.apache.lucene.index.CorruptIndexException;
import org.apache.lucene.index.FieldInfo;
import org.apache.lucene.index.FieldInfos;
import org.apache.lucene.index.Float16VectorValues;
import org.apache.lucene.index.FloatVectorValues;
import org.apache.lucene.index.IndexFileNames;
import org.apache.lucene.index.MergePolicy;
Expand Down Expand Up @@ -239,6 +240,11 @@ public ByteVectorValues getByteVectorValues(String field) throws IOException {
throw new UnsupportedOperationException();
}

@Override
public Float16VectorValues getFloat16VectorValues(String field) throws IOException {
throw new UnsupportedOperationException();
}

@Override
public void search(String field, float[] target, KnnCollector knnCollector, AcceptDocs acceptDocs)
throws IOException {
Expand All @@ -264,6 +270,12 @@ public void search(String field, byte[] target, KnnCollector knnCollector, Accep
throw new UnsupportedOperationException();
}

@Override
public void search(String field, short[] target, KnnCollector knnCollector, AcceptDocs acceptDocs)
throws IOException {
throw new UnsupportedOperationException();
}

private OffHeapFloatVectorValues getOffHeapVectorValues(FieldEntry fieldEntry)
throws IOException {
IndexInput bytesSlice =
Expand Down
12 changes: 12 additions & 0 deletions ...codecs/src/java/org/apache/lucene/backward_codecs/lucene92/Lucene92HnswVectorsReader.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
import org.apache.lucene.index.CorruptIndexException;
import org.apache.lucene.index.FieldInfo;
import org.apache.lucene.index.FieldInfos;
import org.apache.lucene.index.Float16VectorValues;
import org.apache.lucene.index.FloatVectorValues;
import org.apache.lucene.index.IndexFileNames;
import org.apache.lucene.index.MergePolicy;
Expand Down Expand Up @@ -236,6 +237,11 @@ public ByteVectorValues getByteVectorValues(String field) {
throw new UnsupportedOperationException();
}

@Override
public Float16VectorValues getFloat16VectorValues(String field) throws IOException {
throw new UnsupportedOperationException();
}

@Override
public void search(String field, float[] target, KnnCollector knnCollector, AcceptDocs acceptDocs)
throws IOException {
Expand All @@ -261,6 +267,12 @@ public void search(String field, byte[] target, KnnCollector knnCollector, Accep
throw new UnsupportedOperationException();
}

@Override
public void search(String field, short[] target, KnnCollector knnCollector, AcceptDocs acceptDocs)
throws IOException {
throw new UnsupportedOperationException();
}

private HnswGraph getGraph(FieldEntry entry) throws IOException {
IndexInput bytesSlice =
vectorIndex.slice("graph-data", entry.vectorIndexOffset, entry.vectorIndexLength);
Expand Down
13 changes: 13 additions & 0 deletions ...codecs/src/java/org/apache/lucene/backward_codecs/lucene94/Lucene94HnswVectorsReader.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
import org.apache.lucene.index.CorruptIndexException;
import org.apache.lucene.index.FieldInfo;
import org.apache.lucene.index.FieldInfos;
import org.apache.lucene.index.Float16VectorValues;
import org.apache.lucene.index.FloatVectorValues;
import org.apache.lucene.index.IndexFileNames;
import org.apache.lucene.index.MergePolicy;
Expand Down Expand Up @@ -178,6 +179,7 @@ private void validateFieldEntry(FieldInfo info, FieldEntry fieldEntry) {
switch (info.getVectorEncoding()) {
case BYTE -> Byte.BYTES;
case FLOAT32 -> Float.BYTES;
case FLOAT16 -> Short.BYTES;
};
long vectorBytes = Math.multiplyExact((long) dimension, byteSize);
long numBytes = Math.multiplyExact(vectorBytes, fieldEntry.size);
Expand Down Expand Up @@ -270,6 +272,11 @@ public ByteVectorValues getByteVectorValues(String field) throws IOException {
return OffHeapByteVectorValues.load(fieldEntry, vectorData);
}

@Override
public Float16VectorValues getFloat16VectorValues(String field) throws IOException {
throw new UnsupportedOperationException();
}

@Override
public void search(String field, float[] target, KnnCollector knnCollector, AcceptDocs acceptDocs)
throws IOException {
Expand Down Expand Up @@ -308,6 +315,12 @@ public void search(String field, byte[] target, KnnCollector knnCollector, Accep
vectorValues.getAcceptOrds(acceptDocs.bits()));
}

@Override
public void search(String field, short[] target, KnnCollector knnCollector, AcceptDocs acceptDocs)
throws IOException {
throw new UnsupportedOperationException();
}

private HnswGraph getGraph(FieldEntry entry) throws IOException {
IndexInput bytesSlice =
vectorIndex.slice("graph-data", entry.vectorIndexOffset, entry.vectorIndexLength);
Expand Down
1 change: 1 addition & 0 deletions ...-codecs/src/java/org/apache/lucene/backward_codecs/lucene94/OffHeapFloatVectorValues.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,7 @@ static OffHeapFloatVectorValues load(
switch (fieldEntry.vectorEncoding()) {
case BYTE -> fieldEntry.dimension();
case FLOAT32 -> fieldEntry.dimension() * Float.BYTES;
case FLOAT16 -> fieldEntry.dimension() * Short.BYTES;
};
if (fieldEntry.docsWithFieldOffset() == -1) {
return new DenseOffHeapVectorValues(
Expand Down
13 changes: 13 additions & 0 deletions ...codecs/src/java/org/apache/lucene/backward_codecs/lucene95/Lucene95HnswVectorsReader.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
import org.apache.lucene.index.CorruptIndexException;
import org.apache.lucene.index.FieldInfo;
import org.apache.lucene.index.FieldInfos;
import org.apache.lucene.index.Float16VectorValues;
import org.apache.lucene.index.FloatVectorValues;
import org.apache.lucene.index.IndexFileNames;
import org.apache.lucene.index.MergePolicy;
Expand Down Expand Up @@ -177,6 +178,7 @@ private void validateFieldEntry(FieldInfo info, FieldEntry fieldEntry) {
int byteSize =
switch (info.getVectorEncoding()) {
case BYTE -> Byte.BYTES;
case FLOAT16 -> Short.BYTES;
case FLOAT32 -> Float.BYTES;
};
long vectorBytes = Math.multiplyExact((long) dimension, byteSize);
Expand Down Expand Up @@ -290,6 +292,11 @@ public ByteVectorValues getByteVectorValues(String field) throws IOException {
vectorData);
}

@Override
public Float16VectorValues getFloat16VectorValues(String field) throws IOException {
throw new UnsupportedOperationException();
}

@Override
public void search(String field, float[] target, KnnCollector knnCollector, AcceptDocs acceptDocs)
throws IOException {
Expand Down Expand Up @@ -346,6 +353,12 @@ public void search(String field, byte[] target, KnnCollector knnCollector, Accep
vectorValues.getAcceptOrds(acceptDocs.bits()));
}

@Override
public void search(String field, short[] target, KnnCollector knnCollector, AcceptDocs acceptDocs)
throws IOException {
throw new UnsupportedOperationException();
}

/** Get knn graph values; used for testing */
@Override
public HnswGraph getGraph(String field) throws IOException {
Expand Down
11 changes: 11 additions & 0 deletions ...java/org/apache/lucene/backward_codecs/lucene99/Lucene99ScalarQuantizedVectorsReader.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
import org.apache.lucene.index.CorruptIndexException;
import org.apache.lucene.index.FieldInfo;
import org.apache.lucene.index.FieldInfos;
import org.apache.lucene.index.Float16VectorValues;
import org.apache.lucene.index.FloatVectorValues;
import org.apache.lucene.index.IndexFileNames;
import org.apache.lucene.index.MergePolicy;
Expand Down Expand Up @@ -228,6 +229,11 @@ public ByteVectorValues getByteVectorValues(String field) throws IOException {
return rawVectorsReader.getByteVectorValues(field);
}

@Override
public Float16VectorValues getFloat16VectorValues(String field) throws IOException {
throw new UnsupportedOperationException();
}

private static IndexInput openDataInput(
SegmentReadState state,
int versionMeta,
Expand Down Expand Up @@ -291,6 +297,11 @@ public RandomVectorScorer getRandomVectorScorer(String field, float[] target) th
return vectorScorer.getRandomVectorScorer(fieldEntry.similarityFunction, vectorValues, target);
}

@Override
public RandomVectorScorer getRandomVectorScorer(String field, short[] target) throws IOException {
throw new UnsupportedOperationException();
}

@Override
public RandomVectorScorer getRandomVectorScorer(String field, byte[] target) throws IOException {
return rawVectorsReader.getRandomVectorScorer(field, target);
Expand Down
6 changes: 6 additions & 0 deletions ...rg/apache/lucene/backward_codecs/lucene102/TestLucene102BinaryQuantizedVectorsFormat.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@
import org.apache.lucene.index.IndexWriterConfig;
import org.apache.lucene.index.KnnVectorValues;
import org.apache.lucene.index.LeafReader;
import org.apache.lucene.index.VectorEncoding;
import org.apache.lucene.index.VectorSimilarityFunction;
import org.apache.lucene.search.IndexSearcher;
import org.apache.lucene.search.KnnFloatVectorQuery;
Expand Down Expand Up @@ -187,6 +188,11 @@ public void testQuantizedVectorsWriteAndRead() throws IOException {
}
}

@Override
protected VectorEncoding randomVectorEncoding() {
return random().nextBoolean() ? VectorEncoding.BYTE : VectorEncoding.FLOAT32;
}

@Override
protected boolean supportsFloatVectorFallback() {
return false;
Expand Down
6 changes: 6 additions & 0 deletions ...pache/lucene/backward_codecs/lucene102/TestLucene102HnswBinaryQuantizedVectorsFormat.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@
import org.apache.lucene.index.IndexWriter;
import org.apache.lucene.index.KnnVectorValues;
import org.apache.lucene.index.LeafReader;
import org.apache.lucene.index.VectorEncoding;
import org.apache.lucene.index.VectorSimilarityFunction;
import org.apache.lucene.search.AcceptDocs;
import org.apache.lucene.search.TopDocs;
Expand Down Expand Up @@ -178,6 +179,11 @@ public void testSimpleOffHeapSize() throws IOException {
}
}

@Override
protected VectorEncoding randomVectorEncoding() {
return random().nextBoolean() ? VectorEncoding.BYTE : VectorEncoding.FLOAT32;
}

@Override
protected boolean supportsFloatVectorFallback() {
return false;
Expand Down
7 changes: 7 additions & 0 deletions ...codecs/src/test/org/apache/lucene/backward_codecs/lucene90/Lucene90HnswVectorsWriter.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@
import org.apache.lucene.codecs.CodecUtil;
import org.apache.lucene.index.ByteVectorValues;
import org.apache.lucene.index.FieldInfo;
import org.apache.lucene.index.Float16VectorValues;
import org.apache.lucene.index.FloatVectorValues;
import org.apache.lucene.index.IndexFileNames;
import org.apache.lucene.index.KnnVectorValues;
Expand Down Expand Up @@ -177,6 +178,12 @@ protected void writeField(FieldInfo fieldInfo, ByteVectorValues byteVectorValues
throw new UnsupportedOperationException("byte vectors not supported in this version");
}

@Override
protected void writeField(
FieldInfo fieldInfo, Float16VectorValues float16VectorValues, int maxDoc) {
throw new UnsupportedOperationException("float16 vectors not supported in this version");
}

/**
* Writes the vector values to the output and returns a mapping from dense ordinals to document
* IDs. The length of the returned array matches the total number of documents with a vector
Expand Down
7 changes: 7 additions & 0 deletions ...codecs/src/test/org/apache/lucene/backward_codecs/lucene91/Lucene91HnswVectorsWriter.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
import org.apache.lucene.index.ByteVectorValues;
import org.apache.lucene.index.DocsWithFieldSet;
import org.apache.lucene.index.FieldInfo;
import org.apache.lucene.index.Float16VectorValues;
import org.apache.lucene.index.FloatVectorValues;
import org.apache.lucene.index.IndexFileNames;
import org.apache.lucene.index.KnnVectorValues;
Expand Down Expand Up @@ -173,6 +174,12 @@ protected void writeField(FieldInfo fieldInfo, ByteVectorValues byteVectorValues
throw new UnsupportedOperationException("byte vectors not supported in this version");
}

@Override
protected void writeField(
FieldInfo fieldInfo, Float16VectorValues float16VectorValues, int maxDoc) {
throw new UnsupportedOperationException("float16 vectors not supported in this version");
}

/**
* Writes the vector values to the output and returns a set of documents that contains vectors.
*/
Expand Down
7 changes: 7 additions & 0 deletions ...codecs/src/test/org/apache/lucene/backward_codecs/lucene92/Lucene92HnswVectorsWriter.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
import org.apache.lucene.index.ByteVectorValues;
import org.apache.lucene.index.DocsWithFieldSet;
import org.apache.lucene.index.FieldInfo;
import org.apache.lucene.index.Float16VectorValues;
import org.apache.lucene.index.FloatVectorValues;
import org.apache.lucene.index.IndexFileNames;
import org.apache.lucene.index.KnnVectorValues;
Expand Down Expand Up @@ -181,6 +182,12 @@ protected void writeField(FieldInfo fieldInfo, ByteVectorValues byteVectorValues
throw new UnsupportedOperationException("byte vectors not supported in this version");
}

@Override
protected void writeField(
FieldInfo fieldInfo, Float16VectorValues float16VectorValues, int maxDoc) {
throw new UnsupportedOperationException("float16 vectors not supported in this version");
}

/**
* Writes the vector values to the output and returns a set of documents that contains vectors.
*/
Expand Down
Loading
Loading