Overview
Utility functions for computing cosine similarity and maximal marginal relevance (MMR) over embedding vectors in the Qdrant integration.
Description
This module, part of the langchain-qdrant partner package, provides two core mathematical utility functions used for vector similarity operations. cosine_similarity computes row-wise cosine similarity between two matrices, with an optional fast path using the simsimd library. maximal_marginal_relevance implements the MMR algorithm to select a diverse set of results that balances relevance to a query with diversity among selected items. A Matrix type alias is also defined for flexible matrix input types.
Usage
Import these utilities when implementing custom vector search logic that requires cosine similarity computation or MMR-based result diversification within the Qdrant vector store integration.
Code Reference
Source Location
Signature
Matrix: TypeAlias = list[list[float]] | list[np.ndarray] | np.ndarray
def maximal_marginal_relevance(
query_embedding: np.ndarray,
embedding_list: list,
lambda_mult: float = 0.5,
k: int = 4,
) -> list[int]:
"""Calculate maximal marginal relevance."""
...
def cosine_similarity(X: Matrix, Y: Matrix) -> np.ndarray:
"""Row-wise cosine similarity between two equal-width matrices."""
...
Import
from langchain_qdrant._utils import maximal_marginal_relevance, cosine_similarity, Matrix
I/O Contract
maximal_marginal_relevance
Inputs
| Name |
Type |
Required |
Description
|
| query_embedding |
np.ndarray |
Yes |
The embedding vector of the query.
|
| embedding_list |
list |
Yes |
List of candidate embedding vectors to select from.
|
| lambda_mult |
float |
No |
Trade-off parameter between relevance and diversity (0 to 1). Defaults to 0.5.
|
| k |
int |
No |
Maximum number of results to return. Defaults to 4.
|
Outputs
| Name |
Type |
Description
|
| return |
list[int] |
Indices of the selected embeddings from embedding_list, ordered by MMR score.
|
cosine_similarity
Inputs
| Name |
Type |
Required |
Description
|
| X |
Matrix |
Yes |
First matrix of shape (n, d).
|
| Y |
Matrix |
Yes |
Second matrix of shape (m, d). Must have the same number of columns as X.
|
Outputs
| Name |
Type |
Description
|
| return |
np.ndarray |
Cosine similarity matrix of shape (n, m). Returns empty array if either input is empty.
|
Usage Examples
Basic Usage
import numpy as np
from langchain_qdrant._utils import cosine_similarity, maximal_marginal_relevance
# Compute cosine similarity
query = np.array([[1.0, 0.0, 0.0]])
docs = np.array([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.5, 0.5, 0.0]])
similarity = cosine_similarity(query, docs)
# similarity shape: (1, 3)
# Use MMR for diverse result selection
query_emb = np.array([1.0, 0.0, 0.0])
doc_embs = [
np.array([1.0, 0.0, 0.0]),
np.array([0.9, 0.1, 0.0]),
np.array([0.0, 1.0, 0.0]),
]
selected_indices = maximal_marginal_relevance(query_emb, doc_embs, lambda_mult=0.5, k=2)
# Returns indices balancing relevance and diversity
Related Pages
