API 示例API REFERENCE

重排序模型（Reranker）

Reranker 对召回候选进行二次相关性排序，常用于检索增强生成（RAG）链路。

统一 API Endpointhttps://api.tokensapi.cn/v1POST /rerank

认证方式Bearer API Key

响应协议JSON

调用入口统一网关

请求接口

请求地址固定，请根据当前页面的参数说明替换模型 ID 和业务输入。

POST${base_url}/rerank

Header 参数

Reranker 请求使用 Bearer API Key 鉴权，并以 JSON 发送查询和候选文档。

参数	类型	必填	默认值	说明
`Authorization`	`string`	是	—	在 Bearer 后拼接当前工作空间的 API Key。可选值 / 约束：Bearer <API_KEY>。
`Content-Type`	`string`	是	`application/json`	请求体使用 JSON 格式。

Body 参数

提交查询文本和候选文档列表，服务会返回按相关性排序的结果。

参数	类型	必填	默认值	说明
`model`	`string`	是	—	模型广场中的 Reranker 模型 ID，区分大小写。可选值 / 约束：精确复制当前可用的 model ID。
`query`	`string`	是	—	用于比较相关性的非空查询文本。
`documents`	`string[]`	是	—	待重排序的非空候选文档列表。可选值 / 约束：1–500 项，每项必须是非空字符串。
`top_n`	`integer`	否	—	只返回相关性最高的前 N 条结果。可选值 / 约束：范围为 1 到 documents 数量。
`instruct`	`string`	否	—	当前模型支持时的可选排序指令。
`extra_body`	`object`	否	—	统一 API 的扩展字段。可选值 / 约束：provider。
`extra_body.provider`	`object`	否	—	服务商选择、过滤、排序及指标范围。可选值 / 约束：筛选应用顺序：ignore → ranges → only → sort → order。
`extra_body.provider.only`	`string[]`	否	—	服务商白名单，仅在指定集合内选择。可选值 / 约束：服务商名称区分大小写。
`extra_body.provider.ignore`	`string[]`	否	—	服务商黑名单，从候选集合中排除。可选值 / 约束：非空 only 与 ignore 不得重叠；校验失败返回 HTTP 400 / invalid_request。
`extra_body.provider.order`	`string[]`	否	—	在最后提升指定服务商的优先顺序。可选值 / 约束：服务商名称区分大小写。
`extra_body.provider.sort`	`string \| string[]`	否	—	服务商排序策略，支持多个关键字，数组前面的优先级更高。可选值 / 约束：input_price、output_price、throughput、latency、input_length。
`extra_body.provider.input_price_range`	`[number, number]`	否	—	限制当前账号的输入价格范围。可选值 / 约束：单位：USD / 百万 tokens；range=[] 非法。
`extra_body.provider.output_price_range`	`[number, number]`	否	—	限制当前账号的输出价格范围。可选值 / 约束：单位：USD / 百万 tokens；必须恰好两个非负值且下界不大于上界。
`extra_body.provider.throughput_range`	`[number, number]`	否	—	限制实时吞吐范围。可选值 / 约束：单位：tokens/s。
`extra_body.provider.latency_range`	`[number, number]`	否	—	限制实时延迟范围。可选值 / 约束：单位：秒。
`extra_body.provider.input_length_range`	`[number, number]`	否	—	限制服务商支持的最大输入长度范围。可选值 / 约束：单位：Token。
`extra_body.provider.allow_fallbacks`	`boolean`	否	—	非空 only 时默认 false；否则默认 true。可选值 / 约束：最终无通道时返回 HTTP 503 / no_available_provider。

返回结构

返回按相关性降序排列的结果，并附加实际路由服务商信息。

参数	类型	必填	默认值	说明
`model`	`string`	否	—	本次请求实际使用的模型 ID。
`results`	`array`	否	—	重排序后的结果列表，通常按 relevance_score 从高到低排列。
`results[].index`	`integer`	否	—	文档在原始 documents 列表中的索引。
`results[].relevance_score`	`number`	否	—	相关性分值，数值越大通常表示越相关。分值只适合在同一模型和同一任务内比较。
`usage.prompt_tokens`	`integer`	否	—	协议返回时输入查询和候选文档的 Token 数量。
`usage.total_tokens`	`integer`	否	—	本次调用统计的总 Token 数量。
`provider`	`string`	否	—	实际承载请求的服务商通道信息。可选值 / 约束：仅非流式 JSON 中可能出现。

候选集与排序

先通过关键词或向量检索召回候选集，再提交 query 和 documents 进行二次排序。使用 top_n 控制进入后续上下文的文档数量。

结果与质量控制

relevance_score 是模型相关性信号，不代表事实正确性。应结合阈值、来源权限、文档新鲜度和最终生成模型做综合判断。

生产使用建议

建议在服务端保存 query、候选文档数量、top_n 和 request ID，仅把通过权限过滤和相关性阈值的文档交给后续生成模型。

相关性分值只适合在同一模型和同一任务内比较。

调用示例

示例使用占位符，请替换为模型详情页中当前可用的 model ID，并将 API Key 保存在服务端环境变量中。

curl https://api.tokensapi.cn/v1/rerank \
  -H "Authorization: Bearer $TOKEN_MARKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<MODEL_ID>",
    "query": "What is machine learning?",
    "documents": [
      "Machine learning enables computers to learn from data.",
      "Deep learning is a subset of machine learning.",
      "Python is commonly used for data science."
    ],
    "top_n": 2,
    "extra_body": {
      "provider": {"sort": ["throughput"]}
    }
  }'

本页是否有帮助？

嵌入模型（Embedding）

音频（Audio）

参数

类型

必填

默认值

说明

Authorization

string

是

—

在 Bearer 后拼接当前工作空间的 API Key。

可选值 / 约束：Bearer <API_KEY>。

Content-Type

string

是

application/json

请求体使用 JSON 格式。

参数

类型

必填

默认值

说明

model

string

是

—

模型广场中的 Reranker 模型 ID，区分大小写。

可选值 / 约束：精确复制当前可用的 model ID。

query

string

是

—

用于比较相关性的非空查询文本。

documents

string[]

是

—

待重排序的非空候选文档列表。

可选值 / 约束：1–500 项，每项必须是非空字符串。

top_n

integer

否

—

只返回相关性最高的前 N 条结果。

可选值 / 约束：范围为 1 到 documents 数量。

instruct

string

否

—

当前模型支持时的可选排序指令。

extra_body

object

否

—

统一 API 的扩展字段。

可选值 / 约束：provider。

extra_body.provider

object

否

—

服务商选择、过滤、排序及指标范围。

可选值 / 约束：筛选应用顺序：ignore → ranges → only → sort → order。

extra_body.provider.only

string[]

否

—

服务商白名单，仅在指定集合内选择。

可选值 / 约束：服务商名称区分大小写。

extra_body.provider.ignore

string[]

否

—

服务商黑名单，从候选集合中排除。

可选值 / 约束：非空 only 与 ignore 不得重叠；校验失败返回 HTTP 400 / invalid_request。

extra_body.provider.order

string[]

否

—

在最后提升指定服务商的优先顺序。

可选值 / 约束：服务商名称区分大小写。

extra_body.provider.sort

string | string[]

否

—

服务商排序策略，支持多个关键字，数组前面的优先级更高。

可选值 / 约束：input_price、output_price、throughput、latency、input_length。

extra_body.provider.input_price_range

[number, number]

否

—

限制当前账号的输入价格范围。

可选值 / 约束：单位：USD / 百万 tokens；range=[] 非法。

extra_body.provider.output_price_range

[number, number]

否

—

限制当前账号的输出价格范围。

可选值 / 约束：单位：USD / 百万 tokens；必须恰好两个非负值且下界不大于上界。

extra_body.provider.throughput_range

[number, number]

否

—

限制实时吞吐范围。

可选值 / 约束：单位：tokens/s。

extra_body.provider.latency_range

[number, number]

否

—

限制实时延迟范围。

可选值 / 约束：单位：秒。

extra_body.provider.input_length_range

[number, number]

否

—

限制服务商支持的最大输入长度范围。

可选值 / 约束：单位：Token。

extra_body.provider.allow_fallbacks

boolean

否

—

非空 only 时默认 false；否则默认 true。

可选值 / 约束：最终无通道时返回 HTTP 503 / no_available_provider。

参数

类型

必填

默认值

说明

model

string

否

—

本次请求实际使用的模型 ID。

results

array

否

—

重排序后的结果列表，通常按 relevance_score 从高到低排列。

results[].index

integer

否

—

文档在原始 documents 列表中的索引。

results[].relevance_score

number

否

—

相关性分值，数值越大通常表示越相关。分值只适合在同一模型和同一任务内比较。

usage.prompt_tokens

integer

否

—

协议返回时输入查询和候选文档的 Token 数量。

usage.total_tokens

integer

否

—

本次调用统计的总 Token 数量。

provider

string

否

—

实际承载请求的服务商通道信息。

可选值 / 约束：仅非流式 JSON 中可能出现。

curl https://api.tokensapi.cn/v1/rerank \ -H "Authorization: Bearer $TOKEN_MARKET_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "<MODEL_ID>", "query": "What is machine learning?", "documents": [ "Machine learning enables computers to learn from data.", "Deep learning is a subset of machine learning.", "Python is commonly used for data science." ], "top_n": 2, "extra_body": { "provider": {"sort": ["throughput"]} } }'