Sort And Relevance Cuffoff Part 3 - Add Relevance Cutoff Feature #1246

wanliAlex · 2025-06-23T02:17:03Z

Change Summary

This PR implements the relevance-cutoff functionality in Marqo Python and Java. Relevance Cutoff can be used to stub out irrelevant documents in the retrieval stage. Detailed changes are shown as below:

Sorting Enhancements:

Renamed sortCandidates to minSortCandidates across models, validation logic, and query construction for better clarity. (src/marqo/tensor_search/models/sort_by_model.py,
Updated all related test cases to use minSortCandidates instead of sortCandidates.

Relevance Cutoff Implementation:

Implement 3 different relevance cutoff methods in Java, namely "relative_max_score", "gap_detection", and "mean_std_dev",
1. Relative Max Score (relative_max_score)
  - Algorithm: Uses a dynamic threshold based on the top search result's score
  - Implementation:
  - Takes the highest scoring result's score
  - Multiplies it by a relativeScoreFactor parameter (0-1 range)
  - Keeps all results with scores ≥ this threshold
2. Gap Detection (gap_detection)
  - Algorithm: Finds the largest score gap between consecutive results (elbow detection)
  - Implementation:
  - Iterates through sorted results comparing adjacent scores
  - Finds the position with the maximum score difference (delta)
  - Cuts off at the position after the largest gap
    - Parameter: None required (no cutoff parameter)
3. Mean Standard Deviation (mean_std_dev)
  - Algorithm: Statistical approach using mean and standard deviation
  - Implementation:
  - Calculates mean score across all probe results
  - Calculates population standard deviation
  - Sets threshold as: mean + (stdDev × stdDevFactor)
  - Keeps results with scores ≥ threshold
New Response Metadata
All relevance cutoff searches return additional metadata:
- _relevantCandidates: Number of results passing relevance filter
- _probeCandidates: Total candidates analyzed during probe phase
New API Parameter: relevanceCutoff

API Structure

 {
   "relevanceCutoff": {
     "method": "relative_max_score|gap_detection|mean_std_dev",
     "parameters": {
       "relativeScoreFactor": 0.6,  # for relative_max_score
       "stdDevFactor": 0.3         # for mean_std_dev
     }
   }
 }

Example Usage

  # Just relevance cut-off
  response = client.index("my-index").search(
      q="machine learning AI",
      search_method="HYBRID",
      relevance_cutoff={
          "method": "relative_max_score",
          "parameters": {"relativeScoreFactor": 0.7}
      },
      limit=10
  )

  # Search with both relevance cut-off and sorting
  response = client.index("my-index").search(
      q="machine learning artificial intelligence",
      search_method="HYBRID",
      relevance_cutoff={
          "method": "relative_max_score",
          "parameters": {"relativeScoreFactor": 0.7}
      },
      sort_by={
          "fields": [
              {"fieldName": "sort_value", "order": "desc", "missing": "last"}
          ],
          "minSortCandidates": 10  # Optional: override relevance cutoff if needed
      },
  )

Related Jira Ticket

ticket link

Checklist

[*] Tests have been added for changes
[n/a] Documentation has been updated
[n/a] Breaking changes are clearly identified
[ n/a Python client changes linked or N/A