Rerank Results

Use the rerank operation to re-rank search results based on relevance to a query.

The operation uses a reranking model to score and reorder documents relative to a query. This improves search quality by performing a more detailed comparison between the query and each candidate document.

For details about loading your own reranking model (in ONNX format) into the database, see Load Your Own ONNX Model.

See the following for an example of how to rerank query search results using rerank().

Begin by loading a reranking model into your database. This action only needs to be completed once.

from oracle_vecdb import OracleVecDB, Configuration

client = OracleVecDB(Configuration(
    rest_url="https://<host>/ords/<schema>/_/db-api/stable/vecdb/",
    access_token="<bearer-token>", # or username="<user>", password="<pass>"
))


#first, load a reranking model into your database
load_mod_response = client.load_model(
    model_name='cohere-rerank-3.5',
    url='https://objectstorage.us-phoenix-1.oraclecloud.com/n/namespace/b/bucket/o/model.onnx',
    model_params={
        'provider': 'database',
        'credential': 'OCI_CREDENTIAL'
    }
)
print(load_mod_response)


#verify that the model was loaded by using the list_models() API
models = client.list_models()
print(models)

Now that the model is successfully loaded, you can perform a search and rerank the results.

#perform an initial search
import json
search_results = client.query(
    table_name='documents',
    query_by={'text': 'machine learning'},
    top_k=20
)
print(search_results)


#then, rerank the results for better relevance]
reranked = client.rerank(
    query='machine learning applications in healthcare',
    documents=[
        result.metadata["content"]
        for result in search_results.items
        if result.metadata and "content" in result.metadata
    ],
    model_name='cohere-rerank-3.5',
    model_params={'top_n': 5}
)
for item in reranked.items:
    original = search_results.items[item.index]
    print(f"{item.score:.3f} - {original.metadata['content']}")

A JSON response is returned containing reranked documents with relevance scores. An error is raised if the model is not loaded or if inputs are invalid.

Example response:

{
  "items": [
    {
      "index": 0,
      "score": 0.82
    }
  ]
}

For more information about the rerank operation, see Python API Reference.

See how POST /vecdb/rerank can be used in the following example:

curl -X POST \
  "https://<host>:<port>/ords/<schema>/_/db-api/stable/vecdb/rerank" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  # Choose ONE authentication method:

  # Option 1: Basic authentication
  -u "<user>:<password>" \

  # Option 2: OAuth Bearer token
  # -H "Authorization: Bearer <access_token>" \

  -d '{
    "modelName": "RERANK_MODEL",
    "query": "good headphone",
    "documents": [
      "Studio Monitor Headphones",
      "Wireless Earbuds",
      "Coffee Grinder"
    ],
    "modelParams": {
      "top_n": 2
    }
  }'

Responses:

Example 200 response:

[
  {
    "index": 0,
    "score": 0.92
  },
  {
    "index": 1,
    "score": 0.76
  }
]

400 - the request body included invalid parameters.

For more information about POST /vecdb/rerank, see REST API Reference.

See how DBMS_VECTOR_DATABASE.RERANK can be used in the following example:

dbms_vector_database.rerank(
    model_name => 'RERANK_MODEL',
    query => 'good headphone',
    documents => JSON('[
      "Studio Monitor Headphones",
      "Wireless Earbuds",
      "Coffee Grinder"
    ]'),
    model_params => JSON('{"top_n": 2}')
);

Example response:

[
  {
    "index": 0,
    "score": 0.92
  },
  {
    "index": 1,
    "score": 0.76
  }
]

For more information about the PL/SQL implementation, including parameters, see RERANK.