Rank Chunks
curl --request POST \
--url https://api.egp.scale.com/v4/chunks/rank \
--header 'Content-Type: application/json' \
--data '
{
"query": "<string>",
"relevant_chunks": [
{
"chunk_id": "<string>",
"text": "<string>",
"score": 123,
"embedding": [
123
],
"metadata": {},
"user_supplied_metadata": {},
"attachment_url": "<string>",
"title": "<string>"
}
],
"rank_strategy": {
"method": "cross_encoder",
"params": {
"cross_encoder_model": "cross-encoder/ms-marco-MiniLM-L-12-v2"
}
},
"top_k": 123,
"account_id": "<string>"
}
'import requests
url = "https://api.egp.scale.com/v4/chunks/rank"
payload = {
"query": "<string>",
"relevant_chunks": [
{
"chunk_id": "<string>",
"text": "<string>",
"score": 123,
"embedding": [123],
"metadata": {},
"user_supplied_metadata": {},
"attachment_url": "<string>",
"title": "<string>"
}
],
"rank_strategy": {
"method": "cross_encoder",
"params": { "cross_encoder_model": "cross-encoder/ms-marco-MiniLM-L-12-v2" }
},
"top_k": 123,
"account_id": "<string>"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
query: '<string>',
relevant_chunks: [
{
chunk_id: '<string>',
text: '<string>',
score: 123,
embedding: [123],
metadata: {},
user_supplied_metadata: {},
attachment_url: '<string>',
title: '<string>'
}
],
rank_strategy: {
method: 'cross_encoder',
params: {cross_encoder_model: 'cross-encoder/ms-marco-MiniLM-L-12-v2'}
},
top_k: 123,
account_id: '<string>'
})
};
fetch('https://api.egp.scale.com/v4/chunks/rank', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.egp.scale.com/v4/chunks/rank",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => '<string>',
'relevant_chunks' => [
[
'chunk_id' => '<string>',
'text' => '<string>',
'score' => 123,
'embedding' => [
123
],
'metadata' => [
],
'user_supplied_metadata' => [
],
'attachment_url' => '<string>',
'title' => '<string>'
]
],
'rank_strategy' => [
'method' => 'cross_encoder',
'params' => [
'cross_encoder_model' => 'cross-encoder/ms-marco-MiniLM-L-12-v2'
]
],
'top_k' => 123,
'account_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.egp.scale.com/v4/chunks/rank"
payload := strings.NewReader("{\n \"query\": \"<string>\",\n \"relevant_chunks\": [\n {\n \"chunk_id\": \"<string>\",\n \"text\": \"<string>\",\n \"score\": 123,\n \"embedding\": [\n 123\n ],\n \"metadata\": {},\n \"user_supplied_metadata\": {},\n \"attachment_url\": \"<string>\",\n \"title\": \"<string>\"\n }\n ],\n \"rank_strategy\": {\n \"method\": \"cross_encoder\",\n \"params\": {\n \"cross_encoder_model\": \"cross-encoder/ms-marco-MiniLM-L-12-v2\"\n }\n },\n \"top_k\": 123,\n \"account_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.egp.scale.com/v4/chunks/rank")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"<string>\",\n \"relevant_chunks\": [\n {\n \"chunk_id\": \"<string>\",\n \"text\": \"<string>\",\n \"score\": 123,\n \"embedding\": [\n 123\n ],\n \"metadata\": {},\n \"user_supplied_metadata\": {},\n \"attachment_url\": \"<string>\",\n \"title\": \"<string>\"\n }\n ],\n \"rank_strategy\": {\n \"method\": \"cross_encoder\",\n \"params\": {\n \"cross_encoder_model\": \"cross-encoder/ms-marco-MiniLM-L-12-v2\"\n }\n },\n \"top_k\": 123,\n \"account_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.egp.scale.com/v4/chunks/rank")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"<string>\",\n \"relevant_chunks\": [\n {\n \"chunk_id\": \"<string>\",\n \"text\": \"<string>\",\n \"score\": 123,\n \"embedding\": [\n 123\n ],\n \"metadata\": {},\n \"user_supplied_metadata\": {},\n \"attachment_url\": \"<string>\",\n \"title\": \"<string>\"\n }\n ],\n \"rank_strategy\": {\n \"method\": \"cross_encoder\",\n \"params\": {\n \"cross_encoder_model\": \"cross-encoder/ms-marco-MiniLM-L-12-v2\"\n }\n },\n \"top_k\": 123,\n \"account_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"relevant_chunks": [
{
"chunk_id": "<string>",
"text": "<string>",
"score": 123,
"embedding": [
123
],
"metadata": {},
"user_supplied_metadata": {},
"attachment_url": "<string>",
"title": "<string>"
}
]
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Chunks
Rank Chunks
Description
Sorts a list of text chunks by similarity against a given query string.
Details
Use this API endpoint to rank which text chunks provide the most relevant responses to a given a query string.
This is useful for stuffing chunks into a prompt where order may matter or for filtering out less relevant chunks according to the ranking strategy. For example, this API may be useful when doing retrieval augment generation (RAG). Sometimes vector store similarity search does not always return the best ranking of text chunks, since this is heavily dependent on embedding generation. This API endpoint can act as a post-processing step to re-sort the given chunks using more complex strategies that may outperform vector search, and then filter only the top-k most relevant chunks to stuff into the prompt for RAG.
Restrictions and Limits
Ranking can be a very intensive and slow process depending on methodology where duration scales with number of chunks. For best performance, we recommend ranking less than 640 chunks at a time, and you may see a decrease in performance as the number of chunks ranked increases.
POST
/
v4
/
chunks
/
rank
Rank Chunks
curl --request POST \
--url https://api.egp.scale.com/v4/chunks/rank \
--header 'Content-Type: application/json' \
--data '
{
"query": "<string>",
"relevant_chunks": [
{
"chunk_id": "<string>",
"text": "<string>",
"score": 123,
"embedding": [
123
],
"metadata": {},
"user_supplied_metadata": {},
"attachment_url": "<string>",
"title": "<string>"
}
],
"rank_strategy": {
"method": "cross_encoder",
"params": {
"cross_encoder_model": "cross-encoder/ms-marco-MiniLM-L-12-v2"
}
},
"top_k": 123,
"account_id": "<string>"
}
'import requests
url = "https://api.egp.scale.com/v4/chunks/rank"
payload = {
"query": "<string>",
"relevant_chunks": [
{
"chunk_id": "<string>",
"text": "<string>",
"score": 123,
"embedding": [123],
"metadata": {},
"user_supplied_metadata": {},
"attachment_url": "<string>",
"title": "<string>"
}
],
"rank_strategy": {
"method": "cross_encoder",
"params": { "cross_encoder_model": "cross-encoder/ms-marco-MiniLM-L-12-v2" }
},
"top_k": 123,
"account_id": "<string>"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
query: '<string>',
relevant_chunks: [
{
chunk_id: '<string>',
text: '<string>',
score: 123,
embedding: [123],
metadata: {},
user_supplied_metadata: {},
attachment_url: '<string>',
title: '<string>'
}
],
rank_strategy: {
method: 'cross_encoder',
params: {cross_encoder_model: 'cross-encoder/ms-marco-MiniLM-L-12-v2'}
},
top_k: 123,
account_id: '<string>'
})
};
fetch('https://api.egp.scale.com/v4/chunks/rank', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.egp.scale.com/v4/chunks/rank",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => '<string>',
'relevant_chunks' => [
[
'chunk_id' => '<string>',
'text' => '<string>',
'score' => 123,
'embedding' => [
123
],
'metadata' => [
],
'user_supplied_metadata' => [
],
'attachment_url' => '<string>',
'title' => '<string>'
]
],
'rank_strategy' => [
'method' => 'cross_encoder',
'params' => [
'cross_encoder_model' => 'cross-encoder/ms-marco-MiniLM-L-12-v2'
]
],
'top_k' => 123,
'account_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.egp.scale.com/v4/chunks/rank"
payload := strings.NewReader("{\n \"query\": \"<string>\",\n \"relevant_chunks\": [\n {\n \"chunk_id\": \"<string>\",\n \"text\": \"<string>\",\n \"score\": 123,\n \"embedding\": [\n 123\n ],\n \"metadata\": {},\n \"user_supplied_metadata\": {},\n \"attachment_url\": \"<string>\",\n \"title\": \"<string>\"\n }\n ],\n \"rank_strategy\": {\n \"method\": \"cross_encoder\",\n \"params\": {\n \"cross_encoder_model\": \"cross-encoder/ms-marco-MiniLM-L-12-v2\"\n }\n },\n \"top_k\": 123,\n \"account_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.egp.scale.com/v4/chunks/rank")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"<string>\",\n \"relevant_chunks\": [\n {\n \"chunk_id\": \"<string>\",\n \"text\": \"<string>\",\n \"score\": 123,\n \"embedding\": [\n 123\n ],\n \"metadata\": {},\n \"user_supplied_metadata\": {},\n \"attachment_url\": \"<string>\",\n \"title\": \"<string>\"\n }\n ],\n \"rank_strategy\": {\n \"method\": \"cross_encoder\",\n \"params\": {\n \"cross_encoder_model\": \"cross-encoder/ms-marco-MiniLM-L-12-v2\"\n }\n },\n \"top_k\": 123,\n \"account_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.egp.scale.com/v4/chunks/rank")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"<string>\",\n \"relevant_chunks\": [\n {\n \"chunk_id\": \"<string>\",\n \"text\": \"<string>\",\n \"score\": 123,\n \"embedding\": [\n 123\n ],\n \"metadata\": {},\n \"user_supplied_metadata\": {},\n \"attachment_url\": \"<string>\",\n \"title\": \"<string>\"\n }\n ],\n \"rank_strategy\": {\n \"method\": \"cross_encoder\",\n \"params\": {\n \"cross_encoder_model\": \"cross-encoder/ms-marco-MiniLM-L-12-v2\"\n }\n },\n \"top_k\": 123,\n \"account_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"relevant_chunks": [
{
"chunk_id": "<string>",
"text": "<string>",
"score": 123,
"embedding": [
123
],
"metadata": {},
"user_supplied_metadata": {},
"attachment_url": "<string>",
"title": "<string>"
}
]
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Body
application/json
Natural language query to re-rank chunks against. If a vector store query was originally used to retrieve these chunks, please use the same query for this ranking
List of chunks to rank
Show child attributes
Show child attributes
The ranking strategy to use.
Rank strategies determine how the ranking is done, They consist of the ranking method name and additional params needed to compute the ranking.
Use the built-in cross_encoder or rouge strategies or create a custom one with the Models API.
- CrossEncoderRankStrategy
- RougeRankStrategy
- ModelRankStrategy
- AzureAIFoundryRankStrategy
Show child attributes
Show child attributes
Number of chunks to return. Must be greater than 0 if specified. If not specified, all chunks will be returned.
Account to rank chunks with. If you have access to more than one account, you must specify an account_id
Response
Successful Response
List of chunks ranked by the requested rank strategy
Show child attributes
Show child attributes