Cosine Similarity¶

Class: CosineSimilarityBlockV1

Source: inference.core.workflows.core_steps.math.cosine_similarity.v1.CosineSimilarityBlockV1

Calculate the cosine similarity between two embedding vectors by computing the cosine of the angle between them, measuring directional similarity regardless of magnitude to enable similarity comparison, semantic matching, embedding-based search, and similarity-based filtering workflows.

How This Block Works¶

This block computes cosine similarity, a measure of similarity between two vectors based on the cosine of the angle between them. The block:

Receives two embedding vectors from workflow steps (e.g., from CLIP, Perception Encoder, or other embedding models)
Validates embedding dimensions:
Ensures both embeddings have the same dimensionality (same number of elements)
Raises an error if dimensions don't match
Computes cosine similarity:
Calculates the dot product of the two embedding vectors
Computes the L2 norm (magnitude) of each embedding vector
Divides the dot product by the product of the two norms: similarity = (a · b) / (||a|| × ||b||)
This measures the cosine of the angle between the vectors, indicating directional similarity
Returns similarity score:
Outputs a similarity value ranging from -1 to 1
Value of 1: Vectors point in the same direction (identical or proportional) - maximum similarity
Value of 0: Vectors are orthogonal (perpendicular) - no similarity
Value of -1: Vectors point in opposite directions - maximum dissimilarity
Greater values (closer to 1) indicate greater similarity

Cosine similarity is magnitude-invariant, meaning it measures similarity in direction rather than size. Two vectors that point in the same direction will have high cosine similarity even if they have different magnitudes. This makes it ideal for comparing embeddings where magnitude may vary but semantic meaning (direction) is what matters.

Common Use Cases¶

Semantic Similarity Comparison: Compare semantic similarity between images, text, or other data types using embeddings (e.g., compare image embeddings, match text to images, find similar content), enabling similarity comparison workflows
Embedding-Based Search: Use similarity scores for embedding-based search and retrieval (e.g., find similar images, search by embedding similarity, retrieve similar content), enabling embedding search workflows
Cross-Modal Matching: Match embeddings across different modalities (e.g., match images to text, find images matching text descriptions, match text to images), enabling cross-modal matching workflows
Similarity-Based Filtering: Filter data based on similarity thresholds (e.g., filter similar items, find duplicates using similarity, identify near-duplicates), enabling similarity filtering workflows
Content Recommendation: Use similarity scores for content recommendation and matching (e.g., recommend similar content, match related items, suggest similar products), enabling recommendation workflows
Quality Control and Validation: Validate embeddings or compare embeddings for quality control (e.g., validate embedding quality, compare embeddings for consistency, check embedding similarity), enabling quality control workflows

Connecting to Other Blocks¶

This block receives embeddings from embedding model blocks and produces similarity scores:

After embedding model blocks (CLIP, Perception Encoder, etc.) to compare embeddings (e.g., compare image and text embeddings, compare multiple embeddings, compute similarity scores), enabling embedding-to-similarity workflows
Before logic blocks like Continue If to use similarity scores in conditions (e.g., continue if similarity exceeds threshold, filter based on similarity, make decisions using similarity), enabling similarity-based decision workflows
Before filtering blocks to filter based on similarity (e.g., filter by similarity threshold, remove low-similarity items, keep high-similarity matches), enabling similarity-to-filter workflows
Before data storage blocks to store similarity scores (e.g., store similarity metrics, log similarity comparisons, save similarity results), enabling similarity storage workflows
Before notification blocks to send similarity-based alerts (e.g., notify on high similarity matches, alert on similarity changes, send similarity reports), enabling similarity notification workflows
In workflow outputs to provide similarity scores as final output (e.g., similarity comparison outputs, matching results, similarity metrics), enabling similarity output workflows

Requirements¶

This block requires two embedding vectors with the same dimensionality (same number of elements). Embeddings can be from any embedding model (CLIP, Perception Encoder, etc.) and can represent images, text, or other data types. The embeddings are passed as lists of floats. The block computes cosine similarity using the dot product divided by the product of L2 norms, producing a similarity score between -1 and 1. Values closer to 1 indicate greater similarity, values closer to 0 indicate orthogonal vectors, and values closer to -1 indicate opposite directions.

Type identifier¶

Use the following identifier in step "type" field: roboflow_core/cosine_similarity@v1to add the block as as step in your workflow.

Properties¶

Name	Type	Description	Refs
`name`	`str`	Unique name of step in workflows.	❌

The Refs column marks possibility to parametrise the property with dynamic values available in workflow runtime. See Bindings for more info.

Available Connections¶

Compatible Blocks

Check what blocks you can connect to Cosine Similarity in version v1.

Input and Output Bindings¶

The available connections depend on its binding kinds. Check what binding kinds Cosine Similarity in version v1 has.

Bindings

input
- embedding_1 (embedding): First embedding vector to compare. Must have the same dimensionality (same number of elements) as embedding_2. Can be from any embedding model (CLIP, Perception Encoder, etc.) and can represent images, text, or other data types. Embedding vectors are lists of floats representing high-dimensional feature representations..
- embedding_2 (embedding): Second embedding vector to compare. Must have the same dimensionality (same number of elements) as embedding_1. Can be from any embedding model (CLIP, Perception Encoder, etc.) and can represent images, text, or other data types. Embedding vectors are lists of floats representing high-dimensional feature representations. The cosine similarity measures the similarity between embedding_1 and embedding_2..
output
- similarity (float): Float value.

Example JSON definition of step Cosine Similarity in version v1

{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/cosine_similarity@v1",
    "embedding_1": "$steps.clip_image.embedding",
    "embedding_2": "$steps.clip_text.embedding"
}