Skip to content

Commit a50a16a

Browse files
authored
Fix in-place mutation of inputs in cosine_similarity (#1357)
* Fix in-place mutation of inputs in cosine_similarity cosine_similarity normalized its `query` and `vectors` arguments in place via `/=`, which (1) mutated caller-owned arrays as a side effect and (2) raised UFuncTypeError on integer-dtype inputs, unlike the dot, euclidean, and manhattan distance functions. Switch to out-of-place division so the inputs are left untouched. Computed results are unchanged. Add regression tests asserting the query/vectors arguments are not mutated (1D and 2D query paths) and that integer-dtype inputs are accepted. * test: exercise 2D cosine query path with multiple rows Use a two-row 2D query so the batched per-row normalization path is verified, and assert the full distance matrix in addition to input immutability. * Keep vectors normalization in place per review, fix query only @joein noted that vectors is always already normalized when reaching cosine_similarity through the client API (cosine collections are normalized on upsert), so copying it is unnecessary overhead on what can be a large candidate set. Revert vectors to in-place normalization and keep only the query-side fix, which he agreed is worth the (minimal) copy cost since queries are fresh, user-supplied input each call and aren't guaranteed to be pre-normalized. Update tests to match: drop the vectors-not-mutated assertions and the vectors integer-dtype case (vectors is always float32 in real usage), keep the query-side mutation and integer-dtype coverage.
1 parent 5e6a3cc commit a50a16a

2 files changed

Lines changed: 44 additions & 4 deletions

File tree

‎qdrant_client/local/distances.py‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -127,16 +127,20 @@ def cosine_similarity(query: types.NumpyArray, vectors: types.NumpyArray) -> typ
127127
Returns:
128128
distances
129129
"""
130+
# `vectors` is normalized in place: through the normal client API it is
131+
# always already unit-normalized on cosine collections (normalized on
132+
# upsert), so this is a no-op in practice, and avoiding the copy matters
133+
# since `vectors` is the (potentially large) candidate set being searched.
130134
vectors_norm = np.linalg.norm(vectors, axis=-1)[:, np.newaxis]
131135
vectors /= np.where(vectors_norm != 0.0, vectors_norm, EPSILON)
132136

133137
if len(query.shape) == 1:
134138
query_norm = np.linalg.norm(query)
135-
query /= np.where(query_norm != 0.0, query_norm, EPSILON)
139+
query = query / np.where(query_norm != 0.0, query_norm, EPSILON)
136140
return np.dot(vectors, query)
137141

138142
query_norm = np.linalg.norm(query, axis=-1)[:, np.newaxis]
139-
query /= np.where(query_norm != 0.0, query_norm, EPSILON)
143+
query = query / np.where(query_norm != 0.0, query_norm, EPSILON)
140144
return np.dot(query, vectors.T)
141145

142146

‎qdrant_client/local/tests/test_distances.py‎

Lines changed: 38 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@ def test_distances() -> None:
1212
assert np.allclose(calculate_distance(query, vectors, models.Distance.DOT), [14.0, 14.0])
1313
assert np.allclose(calculate_distance(query, vectors, models.Distance.EUCLID), [0.0, 0.0])
1414
assert np.allclose(calculate_distance(query, vectors, models.Distance.MANHATTAN), [0.0, 0.0])
15-
# cosine modifies vectors inplace
1615
assert np.allclose(calculate_distance(query, vectors, models.Distance.COSINE), [1.0, 1.0])
1716

1817
query = np.array([1.0, 0.0, 1.0])
@@ -32,7 +31,6 @@ def test_distances() -> None:
3231
[4.0, 3.0],
3332
atol=0.0001,
3433
)
35-
# cosine modifies vectors inplace
3634
assert np.allclose(
3735
calculate_distance(query, vectors, models.Distance.COSINE),
3836
[0.75592895, 0.0],
@@ -55,3 +53,41 @@ def test_distances() -> None:
5553
multivector_query = np.array([[1, 2, 3], [3, 4, 5]])
5654
docs = [np.array([[1, 2, 3], [0, 1, 2]])]
5755
assert calculate_multi_distance(multivector_query, docs, models.Distance.DOT)[0] == 40.0
56+
57+
58+
def test_cosine_does_not_mutate_query() -> None:
59+
# cosine_similarity used to normalize its `query` argument in place,
60+
# corrupting caller-owned arrays. `vectors` is intentionally still
61+
# normalized in place: on cosine collections it is always already
62+
# unit-normalized through the normal client API (normalized on upsert),
63+
# so mutating it in place is a no-op there, and it avoids an unnecessary
64+
# copy of what can be a large candidate set.
65+
query = np.array([3.0, 4.0], dtype=np.float32)
66+
vectors = np.array([[6.0, 8.0], [1.0, 0.0]], dtype=np.float32)
67+
query_snapshot = query.copy()
68+
69+
result = calculate_distance(query, vectors, models.Distance.COSINE)
70+
71+
assert np.array_equal(query, query_snapshot), "query must not be mutated"
72+
# [6, 8] is colinear with the query -> 1.0; [1, 0] -> 3/5 = 0.6
73+
assert np.allclose(result, [1.0, 0.6], atol=0.0001)
74+
75+
# 2D (multivector-style) query path must also leave the query untouched
76+
query_2d = np.array([[3.0, 4.0], [0.0, 5.0]], dtype=np.float32)
77+
query_2d_snapshot = query_2d.copy()
78+
vectors_for_2d = np.array([[6.0, 8.0], [1.0, 0.0]], dtype=np.float32)
79+
result_2d = calculate_distance(query_2d, vectors_for_2d, models.Distance.COSINE)
80+
assert np.array_equal(query_2d, query_2d_snapshot), "2D query must not be mutated"
81+
# per-row cosine of [[3, 4], [0, 5]] against [[6, 8], [1, 0]]
82+
assert np.allclose(result_2d, [[1.0, 0.6], [0.8, 0.0]], atol=0.0001)
83+
84+
85+
def test_cosine_accepts_integer_dtype_query() -> None:
86+
# In-place normalization of `query` used to raise UFuncTypeError on an
87+
# integer query array, unlike the dot/euclidean/manhattan distances.
88+
# `vectors` is still expected to be float, matching how the client always
89+
# stores cosine vectors (see comment in cosine_similarity).
90+
query = np.array([3, 4], dtype=np.int64)
91+
vectors = np.array([[6.0, 8.0], [1.0, 0.0]], dtype=np.float32)
92+
result = calculate_distance(query, vectors, models.Distance.COSINE)
93+
assert np.allclose(result, [1.0, 0.6], atol=0.0001)

0 commit comments

Comments
 (0)