Roboflow Visual Search Classifier

Classify an image by finding the most visually similar annotated image.

Search a Roboflow classification project for the visually closest image and return the matched image's classification annotation as a standard classification prediction. Single-label annotations are returned in single-label classification shape, and multi-label annotations are returned in multi-label classification shape. Classification confidence is derived from the best candidate's public Roboflow project search score field when present.

This block performs an external visual search API call and is not intended for real-time or high-throughput workloads. To bound latency, query images are downscaled with aspect ratio preserved to a maximum side length of 224 pixels by default. Increase max_image_size when finer visual matching is more important than lower latency.

How This Block Works

This block uses Roboflow project image search:

1. Receives an input image from the workflow

2. Downscales the query image if its larger side exceeds max_image_size

3. Sends the query image to Roboflow project search as image_base64

4. Requests candidate image fields and classification labels or annotations

5. Uses the best candidate's annotation as the predicted class

6. Maps the API score field to classification confidence when present

7. Returns the result through the standard predictions classification output

The target project must expose classification annotation data in visual search results. This block does not train a model, create annotations, consume raw search backend relevance scores, or manage the visual search index.

Type identifier

Use the following identifier in step "type" field: roboflow_core/visual_search_classifier@v1 to add the block as a step in your workflow.

Properties

Name	Type	Description	Refs
name	str	Enter a unique identifier for this step..	❌
target_project	str	Roboflow classification project URL slug to search..	✅
workspace	str	Optional Roboflow workspace URL slug that owns the target project. If not provided, the workspace is resolved from the request API key..	✅
top_k	int	Number of visually similar image candidates to request. The nearest candidate is used for classification..	✅
max_image_size	int	Maximum side length, in pixels, for the visual search query image. Images larger than this are downscaled with aspect ratio preserved before search. Increase this value for finer matching at higher latency..	✅

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

Runtime compatibility

requires_internet - air-gapped / offline deployments : This block depends on a service that is not reachable from fully offline / air-gapped deployments.

Input and Output Bindings

The available connections depend on its binding kinds. Check what binding kinds Roboflow Visual Search Classifier in version v1 has.

Input and output bindings

• input

  • image (image): Image to classify using visual search..

  • target_project (roboflow_project): Roboflow classification project URL slug to search..

  • workspace (string): Optional Roboflow workspace URL slug that owns the target project. If not provided, the workspace is resolved from the request API key..

  • top_k (integer): Number of visually similar image candidates to request. The nearest candidate is used for classification..

  • max_image_size (integer): Maximum side length, in pixels, for the visual search query image. Images larger than this are downscaled with aspect ratio preserved before search. Increase this value for finer matching at higher latency..

• output

  • predictions (classification_prediction): Predictions from classifier.

  • inference_id (inference_id): Inference identifier.

  • candidate_found (boolean): Boolean flag.

  • class_found (boolean): Boolean flag.

  • best_candidate (dictionary): Dictionary.

  • candidates (list_of_values): List of values of any type.

  • best_candidate_image (image): Image in workflows.

  • visual_search_score (float): Float value.

  • error_status (boolean): Boolean flag.

  • message (string): String value.

Example JSON definition

{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/visual_search_classifier@v1",
	    "image": "$inputs.image",
	    "target_project": "reference-images",
	    "workspace": "my-workspace",
	    "top_k": 1,
	    "max_image_size": 224
	}