Mixedbread

Reranking

API reference for Mixedbread's Reranking endpoint. This documentation covers request parameters, response structure, and includes examples for reordering documents based on their relevance to a given query.

POST/v1/reranking

This endpoint sorts a list of documents based on their relevance to a given query. It returns a relevance score for each document, which you can use to enhance search results and recommendations.

Request Body

  • model
    model
    Type
    string
    Required or Optional
    required
    Description

    The model to be used for reranking the documents.

  • query
    query
    Type
    string
    Required or Optional
    required
    Description

    The query to rerank the documents for.

    • Max 256 Tokens.
  • input
    input
    Type
    string[] | object[]
    Required or Optional
    required
    Description

    The input documents to be reranked. These can either be plain strings or structured objects.

    • Between 1-1000 items.
    • Documents exceeding token limit will be truncated.
  • rank fields
    rank fields
    Type
    string[]
    Required or Optional
    optional
    Description

    Specifies the fields within the objects that should be considered for ranking.

    • Must adhere to JMESPath or a similar JSON query language syntax.
  • top_k
    top_k
    Type
    integer
    Required or Optional
    optional
    Description

    The number of top documents to return after reranking. If not provided, all input documents will be returned.

    • Between 1 and the number of passed documents
    • Default is the number of input documents
  • return_input
    return_input
    Type
    boolean
    Required or Optional
    optional
    Description

    Option to include the original input documents in the response. Default is false.

Response Body

  • model
    model
    Type
    string
    Required or Optional
    required
    Description

    The reranking model used, which can be one of our hosted models or a custom fine-tuned model.

  • top_k
    top_k
    Type
    integer
    Required or Optional
    required
    Description

    The number of top documents returned after reranking.

  • return_input
    return_input
    Type
    boolean
    Required or Optional
    required
    Description

    Indicates whether the original input documents are included in the response.

  • object
    object
    Type
    string
    Required or Optional
    required
    Description

    The type of the returned object. Always "list".

  • data
    data
    Type
    RankedDocument[]
    Required or Optional
    required
    Description

    A list of the reranked documents.

  • data[x].index
    data[x].index
    Type
    integer
    Required or Optional
    required
    Description

    The index of the document in the original input list.

  • data[x].score
    data[x].score
    Type
    number
    Required or Optional
    required
    Description

    The relevance score of the document to the query. Higher values indicate higher relevance.

  • data[x].input
    data[x].input
    Type
    object
    Required or Optional
    optional
    Description

    The original input document, if return_input was set to true.

  • data[x].object
    data[x].object
    Type
    string
    Required or Optional
    required
    Description

    The type of the returned object. Always "text_document".

  • usage
    usage
    Type
    object
    Required or Optional
    required
    Description

    Information about API usage for this request.

  • usage.prompt_tokens
    usage.prompt_tokens
    Type
    integer
    Required or Optional
    required
    Description

    The number of tokens in the query and input documents.

  • usage.total_tokens
    usage.total_tokens
    Type
    integer
    Required or Optional
    required
    Description

    The total tokens used for reranking, including the model's overhead.

Examples

Object Reranking

from mixedbread_ai.client import MixedbreadAI
 
mxbai = MixedbreadAI(api_key="YOUR_API_KEY")
 
object_input = [
    {
        "item_id": "001",
        "name": "Smartphone A",
        "description": "High-end smartphone with a 6.5-inch OLED display, 128GB storage, and 5G connectivity.",
        "prices": [
            {"price": 999.99, "currency": "USD"},
            {"price": 110000, "currency": "JPY"}
        ],
        "stock_quantity": 100
    },
    {
        "item_id": "002",
        "name": "Smartphone B",
        "description": "Mid-range smartphone with a 6.2-inch LCD display, 64GB storage, and 4G connectivity.",
        "prices": [
            {"price": 599.99, "currency": "USD"},
            {"price": 66000, "currency": "JPY"}
        ],
        "stock_quantity": 150
    },
    {
        "item_id": "003",
        "name": "Smartphone C",
        "description": "Budget-friendly smartphone with a 5.8-inch LCD display, 32GB storage, and 4G connectivity.",
        "prices": [
            {"price": 399.99, "currency": "USD"},
            {"price": 44000, "currency": "JPY"}
        ],
        "stock_quantity": 200
    },
    {
        "item_id": "004",
        "name": "Smartphone D",
        "description": "Premium smartphone with a 6.8-inch OLED display, 256GB storage, and 5G connectivity.",
        "prices": [
            {"price": 1199.99, "currency": "USD"},
            {"price": 132000, "currency": "JPY"}
        ],
        "stock_quantity": 75
    },
    {
        "item_id": "005",
        "name": "Smartphone E",
        "description": "Mid-range smartphone with a 6.0-inch OLED display, 128GB storage, and 5G connectivity.",
        "prices": [
            {"price": 799.99, "currency": "USD"},
            {"price": 88000, "currency": "JPY"}
        ],
        "stock_quantity": 120
    }
]
 
 
res = mxbai.reranking(
    model="mixedbread-ai/mxbai-rerank-large-v1",
    query="Smartphone within $500 to $800 price range in USD",
    input=items,
    rank_fields=["name", "description", "prices", "stock_quantity"],
    top_k=3,
    return_input=True
)
 
print(res.data)

Previous

Embeddings