Rerank¶

Rerank candidate content by query intent and return ranked results.

POST https://token.moi.matrixorigin.cn/v1/rerank

Before you call¶

Prepare credentials with Genesis access, a model ID that supports Rerank, and a mapping between candidate content and business IDs.

Request body¶

Replace $GENESIS_ACCESS_TOKEN with an access token or service-account API key, and $MODEL_ID with the model ID to call.

Request example

curl -X POST \
  "https://token.moi.matrixorigin.cn/v1/rerank" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "'"$MODEL_ID"'",
    "query": "What is retrieval-augmented generation?",
    "documents": [
      "RAG augments model answers by retrieving an external knowledge base.",
      "Deep learning is a branch of machine learning.",
      "A vector database can store and retrieve high-dimensional vectors."
    ],
    "top_n": 2,
    "return_documents": true
  }'

Parameter description

Field	Type	Required	Description
`model`	string	Yes	Rerank model ID to call.
`query`	string	Yes	Query text used to determine candidate relevance.
`documents`	array of string	Yes	Text candidates to rerank.
`top_n`	integer	No	Number of highest-relevance results to return.
`return_documents`	boolean	No	Whether to return original candidate content in the results.

Successful response¶

The service returns reranked candidate content.

Response example

{
  "id": "<REQUEST_ID>",
  "model": "<MODEL_ID>",
  "results": [
    { "index": 0, "relevance_score": 0.987, "document": "RAG augments model answers by retrieving an external knowledge base." }
  ]
}

Field description

Common fields

Field	Type	Description
`id`	string	Identifier for this rerank request.
`model`	string	Model ID that processed the request.
`results`	array of object	Result list ordered by relevance.

Result item

The following table expands each item in the example results array.

Field	Type	Description
`index`	integer	Index in the original `documents` array.
`relevance_score`	number	Relevance score assigned by the current model; compare it only within the same model and business context.
`document`	string or object	Original candidate content returned when `return_documents` is `true`.

Document object

The following table expands the results[].document object.

Field	Type	Description
`text`	string	Text candidate content when `document` is an object.

Error response¶

Response example

{
  "error": {
    "message": "<human-readable error message>",
    "type": "<error type; may be omitted>",
    "code": "<error code; may be omitted>"
  }
}

Field description

Common fields

Field	Type	Description
`error`	object	Error object.

Error object

The following table expands the example error object.

Field	Type	Description
`message`	string	Human-readable error message.
`type`	string	Error category; it may be omitted.
`code`	string or null	Error code; it may be omitted.