Co.rerank (Beta)

📘
This Guide Uses the Rerank Endpoint.
You can find more information about the endpoint here.

In this guide, we show how to use the Rerank endpoint to rank a series of articles based on a simple query. This guide uses a simple subset of article titles to illustrate the endpoint’s functionality. To see a more robust semantic search demo, see our Colab.

1. Set up

Install the SDK.

$ pip install cohere

Set up the Cohere client and import dependencies.

import cohere

api_key = ""
co = cohere.Client(api_key)

2. Add Query and Documents

Add a query and documents to the endpoints. The SDK accepts either a list of strings or a list of dictionaries that contain the key text as documents such that if you have an existing upstream search system you can pass the entire JSON object without parsing for our endpoint.

query = "What is the capital of the United States?"
docs = [
    "Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a population of 55,274.",
    "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan.",
    "Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people. The city is on the island of Saint Thomas.",
    "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district. The President of the USA and many major national government offices are in the territory. This makes it the political center of the United States of America.",
    "Capital punishment (the death penalty) has existed in the United States since before the United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states. The federal government (including the United States military) also uses capital punishment."]

3. Print Results

Below, we'll print a certain number of documents based on their relevancy to the query. The SDK will always return the text of the documents passed in with the result, but for visibility’s sake, we’ve beautified the output.

results = co.rerank(query=query, documents=docs, top_n=3, model='rerank-english-v2.0') # Change top_n to change the number of results returned. If top_n is not passed, all results will be returned.
for idx, r in enumerate(results):
  print(f"Document Rank: {idx + 1}, Document Index: {r.index}")
  print(f"Document: {r.document['text']}")
  print(f"Relevance Score: {r.relevance_score:.2f}")
  print("\n")

Example Response

Document Rank: 1, Document Index: 3
Document: Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district. The President of the USA and many major national government offices are in the territory. This makes it the political center of the United States of America.
Relevance Score: 0.99


Document Rank: 2, Document Index: 1
Document: The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan.
Relevance Score: 0.30


Document Rank: 3, Document Index: 5
Document: Capital punishment (the death penalty) has existed in the United States since before the United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states. The federal government (including the United States military) also uses capital punishment.
Relevance Score: 0.27

Next Steps

Check out our Cross Encoder Demo here, which shows a more complicated search program.