JavaScript

import SGPClient from 'sgp';

const client = new SGPClient({
  apiKey: 'My API Key',
});

const rankedChunksResponse = await client.chunks.rank({
  query: 'query',
  rank_strategy: { method: 'cross_encoder' },
  relevant_chunks: [{ chunk_id: 'chunk_id', score: 0, text: 'text' }],
});

console.log(rankedChunksResponse.relevant_chunks);

{
  "relevant_chunks": [
    {
      "chunk_id": "<string>",
      "text": "<string>",
      "score": 123,
      "embedding": [
        123
      ],
      "metadata": {},
      "user_supplied_metadata": {},
      "attachment_url": "<string>",
      "title": "<string>"
    }
  ]
}

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

chunks

rank

JavaScript

import SGPClient from 'sgp';

const client = new SGPClient({
  apiKey: 'My API Key',
});

const rankedChunksResponse = await client.chunks.rank({
  query: 'query',
  rank_strategy: { method: 'cross_encoder' },
  relevant_chunks: [{ chunk_id: 'chunk_id', score: 0, text: 'text' }],
});

console.log(rankedChunksResponse.relevant_chunks);

{
  "relevant_chunks": [
    {
      "chunk_id": "<string>",
      "text": "<string>",
      "score": 123,
      "embedding": [
        123
      ],
      "metadata": {},
      "user_supplied_metadata": {},
      "attachment_url": "<string>",
      "title": "<string>"
    }
  ]
}

Authorizations

x-api-key

string

header

required

Body

application/json

query

string

required

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

relevant_chunks

ChunkV2 · object[]

required

List of chunks to rank

Show child attributes

relevant_chunks.chunk_id

string

required

The unique ID of the chunk with embedding

relevant_chunks.text

string

required

The text associated with the chunk

relevant_chunks.score

number

required

A number between 0 and 1 representing how similar a chunk's embedding is to the query embedding. Higher numbers mean that this chunk with embedding is more similar.

relevant_chunks.embedding

number[]

The vector embedding of the text associated with the chunk

relevant_chunks.metadata

Metadata · object

Any additional key value pairs of information stored by you on the chunk with embedding

relevant_chunks.user_supplied_metadata

User Supplied Metadata · object

Any additional key value pairs of information returned from the custom chunking.

relevant_chunks.attachment_url

string

Original attachment URL from which this chunk got its data from

relevant_chunks.title

string

Title for this chunk, for example the file name

rank_strategy

CrossEncoderRankStrategy · object

required

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

rank_strategy.method

string

default:cross_encoder

The name of the rank strategy. Must be cross_encoder.

Allowed value: "cross_encoder"

rank_strategy.params

CrossEncoderRankParams · object

The parameters needed for ranking.

Show child attributes

rank_strategy.params.cross_encoder_model

enum<string>

default:cross-encoder/ms-marco-MiniLM-L-12-v2

Cross encoder model to use when ranking. Currently supports cross-encoder/ms-marco-MiniLM-L-12-v2 and cross-encoder/mmarco-mMiniLMv2-L12-H384-v1.

Available options:

cross-encoder/ms-marco-MiniLM-L-12-v2,

cross-encoder/mmarco-mMiniLMv2-L12-H384-v1

top_k

integer

Number of chunks to return. Must be greater than 0 if specified. If not specified, all chunks will be returned.

account_id

string

Account to rank chunks with. If you have access to more than one account, you must specify an account_id

Response

Successful Response

relevant_chunks

ChunkV2 · object[]

required

List of chunks ranked by the requested rank strategy

Show child attributes

relevant_chunks.chunk_id

string

required

The unique ID of the chunk with embedding

relevant_chunks.text

string

required

The text associated with the chunk

relevant_chunks.score

number

required

A number between 0 and 1 representing how similar a chunk's embedding is to the query embedding. Higher numbers mean that this chunk with embedding is more similar.

relevant_chunks.embedding

number[]

The vector embedding of the text associated with the chunk

relevant_chunks.metadata

Metadata · object

Any additional key value pairs of information stored by you on the chunk with embedding

relevant_chunks.user_supplied_metadata

User Supplied Metadata · object

Any additional key value pairs of information returned from the custom chunking.

relevant_chunks.attachment_url

string

Original attachment URL from which this chunk got its data from

relevant_chunks.title

string

Title for this chunk, for example the file name

Update Upload Schedule Execute Agent

⌘I

Knowledge Bases

Chunks

Agents

Completions

Chat Completions

Models

Users

Accounts

Organizations

Question Sets

Evaluations

Evaluation Configs

Evaluation Datasets

Studio Projects

Application Specs

Questions

Knowledge Base Data Sources

Model Templates V3 (Beta)

Model server

API Reference

Fine Tuning Jobs V3 (Beta)

Training Datasets V3 (Beta)

package deployments

Beta

Applications

ChatThreads

Interactions

MonitoringDashboard

Chat Themes

account groups

Rank Chunks

Description

Details

Restrictions and Limits

Authorizations

Body

Response