重排序候选内容¶

根据查询意图为候选内容排序，并从 results[] 读取精排结果。文本和多模态候选内容使用同一接口；本页以文本候选内容说明最小请求。

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

调用前准备¶

请求地址为 https://token.moi.matrixorigin.cn/v1/rerank。准备具有 Genesis 权限的访问凭据、支持 Rerank 的模型 ID，以及候选项与其业务 ID 的映射。

下方示例使用：

$GENESIS_ACCESS_TOKEN：实际访问令牌或服务账号 API Key，通过 Authorization Header 传递。
$MODEL_ID：要调用的模型 ID，填入请求体的 model 字段。

请求头¶

请求头	是否必填	说明
`Authorization`	是	使用 `Bearer <GENESIS_ACCESS_TOKEN>` 传递访问凭据。
`Content-Type`	是	设置为 `application/json`。

请求体¶

请求体包含以下字段。

类型后的 [] 表示数组。例如，string[] 是字符串数组，object[] 是对象数组。

字段	类型	是否必填	说明
`model`	string	是	支持 Rerank 的模型 ID。
`query`	string 或 object	是	排序依据。文本请求使用字符串。
`documents`	string[] 或 object[]	是	待排序的候选内容。文本请求使用字符串数组。
`top_n`	integer	否	限制返回的最高相关性结果数量。
`return_documents`	boolean	否	是否在结果中返回原始候选内容。

请求示例¶

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": "什么是检索增强生成？",
    "documents": [
      "RAG 通过检索外部知识库增强模型回答能力。",
      "深度学习是机器学习的一个分支。",
      "向量数据库可以存储和检索高维向量。"
    ],
    "top_n": 2,
    "return_documents": true
  }'

成功响应¶

{
  "id": "<REQUEST_ID>",
  "model": "<MODEL_ID>",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.987,
      "document": "RAG 通过检索外部知识库增强模型回答能力。"
    }
  ]
}

响应中用于读取排序结果的字段如下。

字段路径中的 [] 表示数组中的每一项。例如，results[].index 表示 results 数组中每一项的 index 字段。该字段始终用于关联本次请求的 documents 下标；不要用排序后的数组位置替代原始候选项位置。

字段	类型	说明
`id`	string	本次重排序请求的标识。
`model`	string	实际处理请求的模型 ID。
`results`	array	按当前请求相关性排序的结果列表。
`results[].index`	integer	原始 `documents` 数组的下标。
`results[].relevance_score`	number	当前模型给出的相关性分数。仅在相同模型和业务语境内比较。
`results[].document`	string 或 object	`return_documents` 为 `true` 时返回的原始候选内容。
`results[].document.text`	string	`document` 为对象时的文本候选内容；仅在响应实际包含时读取。

错误响应¶

接口不使用 code、msg、data 包络。收到非成功 HTTP 状态时，不要从 results[] 读取排序结果。错误对象由兼容的模型服务返回；除 error.message 外的字段可能省略。

错误对象字段¶

{
  "error": {
    "message": "<可读错误信息>",
    "type": "<错误类型，可能省略>",
    "code": "<错误代码，可能省略>"
  }
}

错误正文中可能出现的字段如下。

字段	类型	说明
`error.message`	string	可读错误信息。
`error.type`	string，可选	上游错误类别。
`error.code`	string 或 null，可选	上游错误代码。

常见 HTTP 错误¶

下表说明收到不同 HTTP 状态时应执行的操作。

HTTP 状态码	错误代码	常见原因	建议操作
`400`	—	查询、候选内容或参数组合不符合接口要求。	先使用一个短查询和少量文本候选内容验证。
`401`	—	凭据无效，或当前凭据无权调用该模型。	检查认证 Header 和模型范围。
`403`	—	凭据无效，或当前凭据无权调用该模型。	检查认证 Header 和模型范围。
`413`	—	候选内容或请求体超过允许范围。	减少单次候选项数量并分批处理。
`429`	—	当前服务受到限制或暂时不可用。	降低请求频率，或稍后再次提交请求。
`5xx`	—	当前服务受到限制或暂时不可用。	降低请求频率，或稍后再次提交请求。

后续操作¶

最后更新于 2026 年 8 月 22 日