Alibaba Cloud Model Studio:Text rerank

import dashscope
from http import HTTPStatus


def text_rerank():
    resp = dashscope.TextReRank.call(
        model="gte-rerank-v2",
        query="What is a text rerank model",
        documents=[
            "Text rerank models are widely used in search engines and recommendation systems. They sort candidate texts based on text relevance",
            "Quantum computing is a cutting-edge field in computer science",
            "The development of pre-trained language models has brought new progress to text rerank models"
        ],
        top_n=10,
        return_documents=True
    )
    if resp.status_code == HTTPStatus.OK:
        print(resp)
    else:
        print(resp)


if __name__ == '__main__':
    text_rerank()

{
    "status_code": 200, // 200 indicates success. Other values indicate a failure.
    "request_id": "9676afe6-fa1a-9895-bf00-b8376333062a", // The request ID.
    "code": "", // The error code if the request failed.
    "message": "", // The error message if the request failed.
    "output": {
         "results": [
            {
                "index": 0,
                "relevance_score": 0.7314485774089865,
                "document": {
                    "text": "Text rerank models are widely used in search engines and recommendation systems. They sort candidate texts based on text relevance"
                }
            },
            {
                "index": 2,
                "relevance_score": 0.5831720487049298,
                "document": {
                    "text": "The development of pre-trained language models has brought new progress to text rerank models"
                }
            },
            {
                "index": 1,
                "relevance_score": 0.04973238644524712,
                "document": {
                    "text": "Quantum computing is a cutting-edge field in computer science"
                }
            }
        ]
    },
    "usage": {
        "total_tokens": 79
    }
}

Use HTTP

You can call this model using HTTP for more flexible development. The following cURL command sends a POST request to the API endpoint: https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank

Parameters

1. Request parameters

   Passing method	Field	Type	Required	Description	Example
   Header	Content-Type	String	Yes	Request type: application/json	application/json
   	Authorization	String	Yes	For information about how to obtain an API key, see Prerequisites.	Bearer d1**2a
   Body	model	String	Yes	Specifies the model to call. Only gte-rerank-v2.	gte-rerank-v2
   	input.query	String	Yes	The query. The maximum length is 4,000 tokens.	"What is a text rerank model"
   	input.documents	Array	Yes	A list of candidate documents to sort.	[ "Text rerank models are widely used in search engines and recommendation systems. They sort candidate texts based on text relevance", "Quantum computing is a cutting-edge field in computer science", "The development of pre-trained language models has brought new progress to text rerank models" ]
   	parameters.top_n	Integer	No	The number of top-ranked documents to return. If this parameter is not specified, all candidate documents are returned. If the value of top_n is greater than the number of input candidate documents, all candidate documents are returned.	10
   	parameters.return_documents	Boolean	No	Specifies whether to return the original text of each document in the sorted list. The default value is False.	True

2. Response parameters

   Field	Type	Description	Example
   output.results	Array	The algorithm output for the request. This is an array of structures. Each element in the array contains the algorithm output that corresponds to an input text.	[ { "document": { "text": "Text rerank models are widely used in search engines and recommendation systems. They sort candidate texts based on text relevance" }, "index": 0, "relevance_score": 0.7314485774089865 }, { "document": { "text": "The development of pre-trained language models has brought new progress to text rerank models" }, "index": 2, "relevance_score": 0.5831720487049298 }, { "document": { "text": "Quantum computing is a cutting-edge field in computer science" }, "index": 1, "relevance_score": 0.04973238644524712 } ]
   output.results.index	Integer	The index of the document in the input `documents` array that corresponds to the algorithm result in this structure.	0,1,2,3...
   output.results.relevance_score	Double	The similarity score. The value is a floating-point number that ranges from 0.0 to 1.0.	0.7314485774089865,0.5831720487049298...
   output.results.document	Dict	The original content of the document.	"Quantum computing is a cutting-edge field in computer science"
   usage	Dict	The number of tokens consumed by the request.	{ "total_tokens": 79 }
   code	String	The error code. This parameter is returned when the task fails.	InvalidApiKey
   message	String	The error details. This parameter is returned when the task fails.	Invalid API-key provided.
   request_id	String	The unique ID of the request.	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Example

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "gte-rerank-v2",
    "input":{
         "query": "What is a text rerank model",
         "documents": [
         "Text rerank models are widely used in search engines and recommendation systems. They sort candidate texts based on text relevance",
         "Quantum computing is a cutting-edge field in computer science",
         "The development of pre-trained language models has brought new progress to text rerank models"
         ]
    },
    "parameters": {
        "return_documents": true,
        "top_n": 5
    }
}'

Sample output

{
    "output": {
        "results": [
            {
                "document": {
                    "text": "Text rerank models are widely used in search engines and recommendation systems. They sort candidate texts based on text relevance"
                },
                "index": 0,
                "relevance_score": 0.7314485774089865
            },
            {
                "document": {
                    "text": "The development of pre-trained language models has brought new progress to text rerank models"
                },
                "index": 2,
                "relevance_score": 0.5831720487049298
            },
            {
                "document": {
                    "text": "Quantum computing is a cutting-edge field in computer science"
                },
                "index": 1,
                "relevance_score": 0.04973238644524712
            }
        ]
    },
    "usage": {
        "total_tokens": 79
    },
    "request_id": "d09e1029-e3a7-9fee-a7b0-d75af1c73932"
}

Sample failed request

If a request fails, the code and message fields in the output indicate the cause of the error.

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1"
}