Apache Lucene open-source search software
Add multi-thread searchability to OnHeapHnswGraph (#12257)
Patrick Zhai8a602b5063d2
diff --git a/lucene/CHANGES.txt b/lucene/CHANGES.txtindex 4f981b13cc3..026b1cc38a5 100644--- a/lucene/CHANGES.txt+++ b/lucene/CHANGES.txt@@ -118,7 +118,8 @@ API ChangesNew Features----------------------(No changes)++* GITHUB#12257: Create OnHeapHnswGraphSearcher to let OnHeapHnswGraph to be searched in a thread-safety manner. (Patrick Zhai)Improvements---------------------diff --git a/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraphSearcher.java b/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraphSearcher.javaindex 4857d5b9d57..d6e63f483b2 100644--- a/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraphSearcher.java+++ b/lucene/core/src/java/org/apache/lucene/util/hnsw/HnswGraphSearcher.java@@ -100,28 +100,31 @@ public class HnswGraphSearcher<T> {similarityFunction,new NeighborQueue(topK, true),new SparseFixedBitSet(vectors.size()));- NeighborQueue results;+ return search(query, topK, vectors, graph, graphSearcher, acceptOrds, visitedLimit);+ }- int initialEp = graph.entryNode();- if (initialEp == -1) {- return new NeighborQueue(1, true);- }- int[] eps = new int[] {initialEp};- int numVisited = 0;- for (int level = graph.numLevels() - 1; level >= 1; level--) {- results = graphSearcher.searchLevel(query, 1, level, eps, vectors, graph, null, visitedLimit);- numVisited += results.visitedCount();- visitedLimit -= results.visitedCount();- if (results.incomplete()) {- results.setVisitedCount(numVisited);- return results;- }- eps[0] = results.pop();- }- results =- graphSearcher.searchLevel(query, topK, 0, eps, vectors, graph, acceptOrds, visitedLimit);- results.setVisitedCount(results.visitedCount() + numVisited);- return results;+ /**+ * Search {@link OnHeapHnswGraph}, this method is thread safe, for parameters please refer to+ * {@link #search(float[], int, RandomAccessVectorValues, VectorEncoding,+ * VectorSimilarityFunction, HnswGraph, Bits, int)}+ */+ public static NeighborQueue search(+ float[] query,+ int topK,+ RandomAccessVectorValues<float[]> vectors,+ VectorEncoding vectorEncoding,+ VectorSimilarityFunction similarityFunction,+ OnHeapHnswGraph graph,+ Bits acceptOrds,+ int visitedLimit)+ throws IOException {+ OnHeapHnswGraphSearcher<float[]> graphSearcher =+ new OnHeapHnswGraphSearcher<>(+ vectorEncoding,+ similarityFunction,+ new NeighborQueue(topK, true),+ new SparseFixedBitSet(vectors.size()));+ return search(query, topK, vectors, graph, graphSearcher, acceptOrds, visitedLimit);}/**@@ -161,6 +164,46 @@ public class HnswGraphSearcher<T> {similarityFunction,new NeighborQueue(topK, true),new SparseFixedBitSet(vectors.size()));+ return search(query, topK, vectors, graph, graphSearcher, acceptOrds, visitedLimit);+ }++ /**+ * Search {@link OnHeapHnswGraph}, this method is thread safe, for parameters please refer to+ * {@link #search(byte[], int, RandomAccessVectorValues, VectorEncoding, VectorSimilarityFunction,+ * HnswGraph, Bits, int)}+ */+ public static NeighborQueue search(+ byte[] query,+ int topK,+ RandomAccessVectorValues<byte[]> vectors,+ VectorEncoding vectorEncoding,+ VectorSimilarityFunction similarityFunction,+ OnHeapHnswGraph graph,+ Bits acceptOrds,+ int visitedLimit)+ throws IOException {+ OnHeapHnswGraphSearcher<byte[]> graphSearcher =+ new OnHeapHnswGraphSearcher<>(+ vectorEncoding,+ similarityFunction,+ new NeighborQueue(topK, true),+ new SparseFixedBitSet(vectors.size()));+ return search(query, topK, vectors, graph, graphSearcher, acceptOrds, visitedLimit);+ }++ private static <T> NeighborQueue search(+ T query,+ int topK,+ RandomAccessVectorValues<T> vectors,+ HnswGraph graph,+ HnswGraphSearcher<T> graphSearcher,+ Bits acceptOrds,+ int visitedLimit)+ throws IOException {+ int initialEp = graph.entryNode();+ if (initialEp == -1) {+ return new NeighborQueue(1, true);+ }NeighborQueue results;int[] eps = new int[] {graph.entryNode()};int numVisited = 0;@@ -252,9 +295,9 @@ public class HnswGraphSearcher<T> {}int topCandidateNode = candidates.pop();- graph.seek(level, topCandidateNode);+ graphSeek(graph, level, topCandidateNode);int friendOrd;- while ((friendOrd = graph.nextNeighbor()) != NO_MORE_DOCS) {+ while ((friendOrd = graphNextNeighbor(graph)) != NO_MORE_DOCS) {assert friendOrd < size : "friendOrd=" + friendOrd + "; size=" + size;if (visited.getAndSet(friendOrd)) {continue;@@ -298,4 +341,60 @@ public class HnswGraphSearcher<T> {}visited.clear(0, visited.length());}++ /**+ * Seek a specific node in the given graph. The default implementation will just call {@link+ * HnswGraph#seek(int, int)}+ *+ * @throws IOException when seeking the graph+ */+ void graphSeek(HnswGraph graph, int level, int targetNode) throws IOException {+ graph.seek(level, targetNode);+ }++ /**+ * Get the next neighbor from the graph, you must call {@link #graphSeek(HnswGraph, int, int)}+ * before calling this method. The default implementation will just call {@link+ * HnswGraph#nextNeighbor()}+ *+ * @return see {@link HnswGraph#nextNeighbor()}+ * @throws IOException when advance neighbors+ */+ int graphNextNeighbor(HnswGraph graph) throws IOException {+ return graph.nextNeighbor();+ }++ /**+ * This class allow {@link OnHeapHnswGraph} to be searched in a thread-safe manner.+ *+ * <p>Note the class itself is NOT thread safe, but since each search will create one new graph+ * searcher the search method is thread safe.+ */+ private static class OnHeapHnswGraphSearcher<C> extends HnswGraphSearcher<C> {++ private NeighborArray cur;+ private int upto;++ private OnHeapHnswGraphSearcher(+ VectorEncoding vectorEncoding,+ VectorSimilarityFunction similarityFunction,+ NeighborQueue candidates,+ BitSet visited) {+ super(vectorEncoding, similarityFunction, candidates, visited);+ }++ @Override+ void graphSeek(HnswGraph graph, int level, int targetNode) {+ cur = ((OnHeapHnswGraph) graph).getNeighbors(level, targetNode);+ upto = -1;+ }++ @Override+ int graphNextNeighbor(HnswGraph graph) {+ if (++upto < cur.size()) {+ return cur.node[upto];+ }+ return NO_MORE_DOCS;+ }+ }}diff --git a/lucene/core/src/test/org/apache/lucene/util/hnsw/HnswGraphTestCase.java b/lucene/core/src/test/org/apache/lucene/util/hnsw/HnswGraphTestCase.javaindex 9825d4a5f41..e74660405b0 100644--- a/lucene/core/src/test/org/apache/lucene/util/hnsw/HnswGraphTestCase.java+++ b/lucene/core/src/test/org/apache/lucene/util/hnsw/HnswGraphTestCase.java@@ -33,6 +33,12 @@ import java.util.Locale;import java.util.Map;import java.util.Random;import java.util.Set;+import java.util.concurrent.ExecutionException;+import java.util.concurrent.ExecutorService;+import java.util.concurrent.Executors;+import java.util.concurrent.Future;+import java.util.concurrent.TimeUnit;+import java.util.concurrent.TimeoutException;import java.util.stream.Collectors;import org.apache.lucene.codecs.KnnVectorsFormat;import org.apache.lucene.codecs.lucene95.Lucene95Codec;@@ -67,6 +73,7 @@ import org.apache.lucene.util.ArrayUtil;import org.apache.lucene.util.BitSet;import org.apache.lucene.util.Bits;import org.apache.lucene.util.FixedBitSet;+import org.apache.lucene.util.NamedThreadFactory;import org.apache.lucene.util.RamUsageEstimator;import org.apache.lucene.util.VectorUtil;import org.apache.lucene.util.hnsw.HnswGraph.NodesIterator;@@ -991,6 +998,105 @@ abstract class HnswGraphTestCase<T> extends LuceneTestCase {assertTrue("overlap=" + overlap, overlap > 0.9);}+ /* test thread-safety of searching OnHeapHnswGraph */+ @SuppressWarnings("unchecked")+ public void testOnHeapHnswGraphSearch()+ throws IOException, ExecutionException, InterruptedException, TimeoutException {+ int size = atLeast(100);+ int dim = atLeast(10);+ AbstractMockVectorValues<T> vectors = vectorValues(size, dim);+ int topK = 5;+ HnswGraphBuilder<T> builder =+ HnswGraphBuilder.create(+ vectors, getVectorEncoding(), similarityFunction, 10, 30, random().nextLong());+ OnHeapHnswGraph hnsw = builder.build(vectors.copy());+ Bits acceptOrds = random().nextBoolean() ? null : createRandomAcceptOrds(0, size);++ List<T> queries = new ArrayList<>();+ List<NeighborQueue> expects = new ArrayList<>();+ for (int i = 0; i < 100; i++) {+ NeighborQueue expect;+ T query = randomVector(dim);+ queries.add(query);+ expect =+ switch (getVectorEncoding()) {+ case BYTE -> HnswGraphSearcher.search(+ (byte[]) query,+ 100,+ (RandomAccessVectorValues<byte[]>) vectors,+ getVectorEncoding(),+ similarityFunction,+ hnsw,+ acceptOrds,+ Integer.MAX_VALUE);+ case FLOAT32 -> HnswGraphSearcher.search(+ (float[]) query,+ 100,+ (RandomAccessVectorValues<float[]>) vectors,+ getVectorEncoding(),+ similarityFunction,+ hnsw,+ acceptOrds,+ Integer.MAX_VALUE);+ };++ while (expect.size() > topK) {+ expect.pop();+ }+ expects.add(expect);+ }++ ExecutorService exec =+ Executors.newFixedThreadPool(4, new NamedThreadFactory("onHeapHnswSearch"));+ List<Future<NeighborQueue>> futures = new ArrayList<>();+ for (T query : queries) {+ futures.add(+ exec.submit(+ () -> {+ NeighborQueue actual;+ try {+ actual =+ switch (getVectorEncoding()) {+ case BYTE -> HnswGraphSearcher.search(+ (byte[]) query,+ 100,+ (RandomAccessVectorValues<byte[]>) vectors,+ getVectorEncoding(),+ similarityFunction,+ hnsw,+ acceptOrds,+ Integer.MAX_VALUE);+ case FLOAT32 -> HnswGraphSearcher.search(+ (float[]) query,+ 100,+ (RandomAccessVectorValues<float[]>) vectors,+ getVectorEncoding(),+ similarityFunction,+ hnsw,+ acceptOrds,+ Integer.MAX_VALUE);+ };+ } catch (IOException ioe) {+ throw new RuntimeException(ioe);+ }+ while (actual.size() > topK) {+ actual.pop();+ }+ return actual;+ }));+ }+ List<NeighborQueue> actuals = new ArrayList<>();+ for (Future<NeighborQueue> future : futures) {+ actuals.add(future.get(10, TimeUnit.SECONDS));+ }+ exec.shutdownNow();+ for (int i = 0; i < expects.size(); i++) {+ NeighborQueue expect = expects.get(i);+ NeighborQueue actual = actuals.get(i);+ assertArrayEquals(expect.nodes(), actual.nodes());+ }+ }+private int computeOverlap(int[] a, int[] b) {Arrays.sort(a);Arrays.sort(b);