Word2VecSynonymFilter documents minAcceptedSimilarity as a cosine, but compares it with the score (1 + cosine) / 2

The only documentation of Word2VecSynonymFilter's minAcceptedSimilarity is the constructor javadoc: "minimal value of cosine similarity between the searched vector and the retrieved ones". Word2VecModel makes every vector unit length, and Word2VecSynonymProvider scores neighbours with VectorSimilarityFunction.DOT_PRODUCT, whose float score is max((1 + dot) / 2, 0); it keeps a neighbour when that score is >= the threshold. For unit vectors the dot product is the cosine, so the real cosine cutoff is 2m - 1: the factory default 0.8 admits cosine 0.6, 0.5 admits orthogonal terms, and lower values admit negatively correlated terms.

The score-scale code looks deliberate: the factory's range check is (0, 1], the score's range, and a co-author of the filter wrote "the vector similarity score is 0<=x<=1" in #12169. So this is a documentation defect: the proposed fix is a javadoc clarification, with a code change only as an option. It has been there since the filter's first commit and is in every release from 9.7.0 to 10.6.0 and on main.

1. The javadoc says cosine. Word2VecSynonymFilter.java:59-60: "@param minAcceptedSimilarity minimal value of cosine similarity between the searched vector and the retrieved ones". There is no other documentation of the value: Word2VecSynonymProvider.getSynonyms (:70-71) has no javadoc, the factory documents no parameters (Word2VecSynonymFilterFactory.java:29-34), and the package javadoc is one line.
2. Vectors are unit length. Word2VecModel.java:58-59 calls TermAndVector.normalizeVector(), which applies VectorUtil.l2normalize (TermAndVector.java:34-38). So the dot product of two model vectors is their cosine.
3. The provider scores with DOT_PRODUCT. Word2VecSynonymProvider.java:45-46 sets SIMILARITY_FUNCTION = VectorSimilarityFunction.DOT_PRODUCT; the query scorer from DefaultFlatVectorScorer returns similarityFunction.compare(...) (DefaultFlatVectorScorer.java:246). VectorSimilarityFunction.java:59-62: DOT_PRODUCT.compare returns normalizeToUnitInterval(dotProduct(v1, v2)), defined as Math.max((1 + value) / 2, 0) (VectorUtil.java:461-463).
4. The threshold is compared with that score. Word2VecSynonymProvider.java:94 takes topDocs.scoreDocs[i].score; :99 keeps the term when similarity >= minAcceptedSimilarity; :100 returns the same score as the TermAndBoost boost.
5. So a term is kept when (1 + cosine) / 2 >= m, that is cosine >= 2m - 1. In the repro, b's cosine 0.707 gives the score 0.854 >= 0.8.
6. The factory fits the score scale. Word2VecSynonymFilterFactory.java:42 sets the default 0.8f; :68-71 rejects values <= 0 or > 1, the range (0, 1] (a NaN, which getFloat parses with Float.parseFloat, is not caught by this check).

The closed form was proved with the Z3 SMT solver over the reals; over float32 the default 0.8f accepts exactly the dot products >= 0.6f, and at 0.5f rounding admits even tiny negative dot products. Executed checks agree: through the factory default, terms at cosine 0.75 and 0.61 are emitted and 0.59 is not; at 0.5 a term at cosine 0 is emitted; at 0.15 a term at cosine -0.6 is emitted.

The ranking of neighbours is the same under both readings (the score grows with the cosine); only the cutoff differs. The number of synonyms per token is still bounded by the provider's maxSynonymsPerTerm + 1 search (Word2VecSynonymProvider.java:83-90). The filter does not use the boost (Word2VecSynonymFilter.java:79-88); callers of getSynonyms see the score there.

• Who. Users of Word2VecSynonymFilter through its public constructor or the factory (SPI name Word2VecSynonym, parameter minAcceptedSimilarity, default 0.8) who choose the threshold from the javadoc.
• Default vs opt-in. Opt-in and @lucene.experimental (Word2VecSynonymFilter.java:37, Word2VecSynonymFilterFactory.java:32); no default analyzer uses it.
• What goes wrong. Weaker neighbours are injected as synonyms, within the maxSynonymsPerTerm limit of the search: at the default, cosines 0.6 to 0.8; at 0.5, unrelated terms. Silent and deterministic. At index time the extra synonyms are written into the index, so correcting the threshold later needs a reindex.
• Scale and age. Ordinary models and text; every release with the filter (9.7.0 to 9.12.3, 10.0.0 to 10.6.0) and main.
• Why upstream tests never noticed. Their vectors are either at cosine >= 0.99 or at score <= 0.887, never in the gap [2m - 1, m) where the two readings differ (the study's reading); with the comparison changed to the cosine scale all 21 upstream word2vec tests still pass.

• Deterministic in practice. With two model vectors the HNSW search for maxSynonymsPerTerm + 1 = 11 neighbours is expected to return both whatever the seed (the seed only drives the graph's random levels); it ran with seed DEADBEEF, and assertions on and off fail the same way.
• It transcribes the current javadoc. Under the recommended javadoc fix it does not pass; it becomes obsolete, because the documented contract becomes the score scale. Under the code alternative it passes unchanged.
• As a regression test for the javadoc fix (optional for a javadoc-only change): this same test with the expectation the clarified javadoc gives, new String[] {"a", "b"}, and the comment "b: cosine 0.71 >= 2 * 0.8 - 1 = 0.6, score (1 + cos) / 2 = 0.85 >= 0.8, so b is a synonym". The run copy also renames the class to TestWord2VecMinAcceptedSimilarityScore and the method to testThresholdIsComparedWithNormalizedScore; the body is otherwise the same. It passes with the javadoc fix, with assertions on and off; it pins the scale, so a silent change of the comparison would be caught.
• Releases. The same file fails unchanged on the 9.7.0, 9.8.0, 9.12.3, 10.0.0, 10.5.2 and 10.6.0 release jars; 9.6.0 has no word2vec package.

cp $REPRO/TestWord2VecMinAcceptedSimilarityCosine.java $LUCENE/lucene/analysis/common/src/test/org/apache/lucene/analysis/synonym/word2vec/
cd $LUCENE
./gradlew :lucene:analysis:common:test --tests org.apache.lucene.analysis.synonym.word2vec.TestWord2VecMinAcceptedSimilarityCosine -Ptests.seed=DEADBEEF -Ptests.asserts=true
# assertions off: -Ptests.asserts=false (same failure)

# gradle, main 645d4fe14a20, seed DEADBEEF, -Ptests.asserts=true
TestWord2VecMinAcceptedSimilarityCosine > testTermBelowCosineThresholdIsNotASynonym FAILED
    java.lang.AssertionError: TokenStream has more tokens than expected (expected count=1); extra token=b
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:9B455D092792C978]:0)
        at junit@4.13.2/org.junit.Assert.fail(Assert.java:89)
        at org.apache.lucene.test_framework@11.0.0-SNAPSHOT/org.apache.lucene.tests.analysis.BaseTokenStreamTestCase.assertTokenStreamContents(BaseTokenStreamTestCase.java:402)
        ...
        at org.apache.lucene.analysis.synonym.word2vec.TestWord2VecMinAcceptedSimilarityCosine.testTermBelowCosineThresholdIsNotASynonym(TestWord2VecMinAcceptedSimilarityCosine.java:33)
:lucene:analysis:common:test (FAILURE): 1 test, 1  failure
# -Ptests.asserts=false: the same failure
# javadoc fix (option A): changes no code; the same test expecting [a, b] passes
# code alternative (option B): BUILD SUCCESSFUL, 1 test

• The only documentation names the other scale. Word2VecSynonymFilter.java:59-60 calls the value a "minimal value of cosine similarity" and says nothing about normalization; the factory and getSynonyms add nothing.
• Lucene's own javadoc keeps the two scales apart. VectorUtil.java:96: cosine() "Returns the cosine similarity between the two vectors" (the raw value in [-1, 1]). VectorUtil.java:452-459: normalizeToUnitInterval "Converts a dot product or cosine similarity value to a normalized score in the [0, 1] range ... using the formula: (1 + value) / 2". VectorSimilarityFunction.java:122: compare() "Calculates a similarity score". FloatVectorSimilarityQuery.java:49 (and :76, :92, :105): "similarity score for result collection". No Lucene javadoc calls (1 + cosine) / 2 a "value of cosine similarity".
• Since the first commit. The javadoc line, the choice of DOT_PRODUCT, the comparison, the 0.8 default and the (0, 1] check all arrived together in 1f4f2bf50957 (#12169). The javadoc text and the comparison line are unchanged since; the code around them was refactored (for example #12434, #12529 and #15704 in the provider), and the DOT_PRODUCT score was clamped at 0 in 9.9.0 (#12727) and later moved into normalizeToUnitInterval (#15036), all without changing the (1 + dot) / 2 scale.
• The hazard is known in general. In the review of #11946 (a 2022 kNN similarity-threshold PR, closed unmerged, a different API) a reviewer warned: "a dotProduct of 0.7 ... ACTUALLY means they want to limit the scores to .85 ((1 + dotProduct)/2). How is the user supposed to know that?"

Strongest case for "leave it" (the study's intended-behaviour devil's advocate and a cross-model reviewer, OpenAI GPT-5.6): the score-scale code looks deliberate. The factory's range check (0, 1] is the score's range, not the cosine's [-1, 1]; a co-author (Alessandro Benedetti) wrote "the vector similarity score is 0<=x<=1" in #12169 (2023-03-22, about the boost); the open draft #12433 by the filter's author tests with normalized VectorSimilarityFunction.COSINE.compare values while calling them "the cosine similarity"; and Lucene itself labels VectorSimilarityFunction.COSINE, whose compare() returns the normalized score, "Cosine similarity" (VectorSimilarityFunction.java:77-80). In that vocabulary "cosine similarity" means Lucene's normalized cosine score, the API is experimental, and a committer could call the wording acceptable.

Why it fails: it rules out a code bug, which is why the proposal is a javadoc fix, but not the documentation defect. VectorSimilarityFunction.java:77-80 names a metric and adds "The similarity score is normalised to assure it is positive"; the filter javadoc names a value and never mentions normalization. The (0, 1] range does not tell a reader which scale applies, since it is also a natural range for a raw-cosine synonym cutoff (an independent Go port of the filter documents the 0.8 default as "the default minimum cosine similarity threshold"). The cross-model reviewer itself wrote: "A documentation clarification is warranted even if behavior remains unchanged." Confidence: high that the javadoc misdescribes the compared value, medium that a committer will want the change.

Two options; both were applied in a scratch worktree of main 645d4fe14a20 and run with gradle. The javadoc fix is the proposal, because the score-scale code appears deliberate.

Say that the value is a similarity score, (1 + cosine) / 2 for the normalized model vectors, and give the equivalent cosine cutoff.

   * @param maxSynonymsPerTerm maximum number of result returned by the synonym search
-  * @param minAcceptedSimilarity minimal value of cosine similarity between the searched vector and
-  *     the retrieved ones
+  * @param minAcceptedSimilarity minimal similarity score between the searched vector and the
+  *     retrieved ones. The model vectors are normalized and scored as (1 + cosine) / 2, so a term
+  *     is accepted when its cosine similarity is at least 2 * minAcceptedSimilarity - 1 (the
+  *     factory default 0.8 accepts cosine 0.6, 0.5 accepts orthogonal terms, and lower values also
+  *     accept negatively correlated terms)
   */

Trade-offs

• No behaviour change, so no existing configuration moves; it uses the vocabulary of VectorUtil.normalizeToUnitInterval and of the similarity queries ("similarity score").
• It does not help users who already set a cosine value; they need (1 + c) / 2 for a cosine cutoff c.
• Optionally add the same sentence to the factory's class javadoc, where SPI users look, and to getSynonyms (not run).

What the checks validated

• Gradle, scratch worktree of 645d4fe14a20, seed DEADBEEF: :lucene:analysis:common:checkGoogleJavaFormat and :lucene:analysis:common:renderJavadoc pass, and the rendered Word2VecSynonymFilter.html shows the new text.
• The word2vec tests (org.apache.lucene.analysis.synonym.word2vec.*: the 21 upstream tests plus the minimal test in its clarified form, expecting [a, b]) pass, 22 tests, with assertions on; the clarified-form test passes with assertions off too.
• The minimal test as written (the cosine reading) was not re-run with it: the fix changes only a comment, so it keeps failing as on stock main.

In Word2VecSynonymProvider.getSynonyms, compare 2 * similarity - 1 with the threshold, which makes the current javadoc true over the reals.

         // We remove the original query term
-        if (!synonym.equals(term) && similarity >= minAcceptedSimilarity) {
+        // DOT_PRODUCT scores unit vectors as (1 + cosine) / 2; the threshold is a cosine
+        float cosine = 2 * similarity - 1;
+        if (!synonym.equals(term) && cosine >= minAcceptedSimilarity) {
           result.addLast(new TermAndBoost(synonym, similarity));

Trade-offs

• Silently tightens every existing configuration (the default 0.8 would drop all neighbours between cosine 0.6 and 0.8), against the evident intent of the code; it would need a CHANGES entry as a behaviour change.
• The factory's range check (0, 1] would then forbid cutoffs at or below cosine 0; the boost stays on the score scale.
• Float caveat: 2 * similarity - 1 is not exact in float32. For m = 0.8f a dot product of exactly 0.8f scores 0.9f, and 2 * 0.9f - 1 = 0.79999995f < 0.8f, so this option rejects a cosine equal to the threshold (333 of the 1000 values m = i / 1000, in a standalone float check). Comparing the score with (1 + m) / 2 instead accepts that case (not run against Lucene); over the reals the two are the same test.

What the checks validated

• Same worktree and seed: the minimal test passes with assertions off (1 test), and the word2vec tests including it pass with assertions on (22 tests); checkGoogleJavaFormat passes.
• A standalone run agrees: with the change applied, the minimal test passes with assertions on and off, and the 21 upstream tests pass (2026-11-01). So no upstream test pins either scale.

• Lead. The hypothesis came from code reading: the javadoc says cosine, the provider uses DOT_PRODUCT.
• Translation validation. W2VExhaustiveTV.java drove the real analysis-common jar over a bounded exhaustive space of small models and thresholds and checked each output against oracles written from the javadoc. "Every synonym has exact cosine >= minAcceptedSimilarity" failed 3,530,652 of 9,136,266 checks; "every synonym has score >= minAcceptedSimilarity" held in all of them. The harness was mutant-checked.
• Proof. A Z3 script proved accept <=> cosine >= 2m - 1 over the reals and, over float32, that 0.8f accepts exactly the dot products >= 0.6f (10 of 10 queries as expected).
• Verification. A public-API JUnit, an independent reproducer, an intended-behaviour devil's advocate, an adjudication, a re-verification, a second adjudication and a cross-model reviewer (OpenAI GPT-5.6) followed; all agree on the behaviour and the root cause.