opendunes
Model types · 3 min
Copy page ▾

Rerank

Order your documents by a question.

  1. Pick a rerank model.
  2. Send the question and the documents.
  3. Read the order.

1. Pick a rerank model

A rerank model reads a question and a list of documents, and scores each document by how well it answers. A search that already found fifty candidates sends them here to put the best on top. Copy its model IDModel IDThe name a request calls a model by, lab/model, copied from Models.More on Models → from its page in Models and send it in model as it stands.

2. Send the question and the documents

Send the question in query and the documents in documents to /v1/rerank. Yacine's Souk Bot answers the customers of a clothing shop in Oran. Asked about refunds, it sends the shop's help texts and keeps the two best.

import json
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/rerank"
MODEL = "cohere/rerank-4-pro"

documents = [
    "Deposits are held for the life of the account.",
    "A cancelled order refunds the deposit within 14 days.",
    "Delivery outside Algiers takes three to five days.",
    "Refunds return to the original payment method.",
]

request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(
        {
            "model": MODEL,
            "query": "Is the deposit refundable if I cancel?",
            "documents": documents,
            "top_n": 2,
        }
    ).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    answer = json.load(response)

for result in answer["results"]:
    index = result["index"]
    print(index, result["relevance_score"], documents[index])
print(answer["usage"]["cost"])
You sendHolds
modela rerank model's ID
querythe question the documents are matched against
documentsthe documents to score: strings, or objects
top_nhow many results come back, best first

Every field: Ranking.

Watch out

top_n trims what comes back, never what is scored. Every document you send is scored and charged.

3. Read the order

200, with the documents in order, best first.

FieldHolds
resultstop_n entries, best first
indexin each entry: the document's place in what you sent, from 0
relevance_scorein each entry: how well the document answers the question
documentin each entry: the document you sent, echoed back as its text, or its image
usagesearch_units: the searches counted. total_tokens: the tokens read. cost: the charge, in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges →

Two headers come back.

HeaderHolds
X-Generation-Idthe request's receipt: Receipt
X-Balance-Availableyour balanceBalanceWhat you can spend, in DA.More on Balance and charges → after this charge, in µDAµDAA millionth of a DA: 1 DA = 1 000 000 µDA.More on Balance and charges →

What it cost

Charged in DA from your balance the moment the answer ends, and read in usage.cost. Only what you send is counted: the ranking that comes back never is. A rerank model sells one of two things, and its page in Models says which, at what rate.

The model sellsCharged on
a searchsearch_units: the searches the answer reports
tokenstotal_tokens: the length of the question and the documents

Both counts ride every answer; the model's own meter decides which one is charged.

On a model that sells a search, one request can count more than one search: the count in search_units is the one charged.

An error before the model answers charges nothing. An answer with no result still charges: the documents were scored.

Errors

The body says why.

StatusWhen
400model, query or documents is missing, or a field has the wrong type
401the key is missing, wrong, disabled or expired
402your balance is at zero or below, cannot pay the request's hold, or the key's cap is spent; error.metadata.limit_source names which, and deposit_url or key_url says where to lift it. After up to 60 seconds of waiting for money your running requests hold, the 402 carries Retry-After: 60
404model is not a rerank model on sale
429the API keyAPI keyThe key you create and send with every request that calls a model.More on API keys →'s own rate limit is reached (metadata.limit_source is key), or the provider is limiting its rate; Retry-After says how many seconds to wait
502the model is down, or answered with nothing usable

What to do on each: Errors and retries.

Last modified on