BRASILTradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗
Reclassificação compatível com OpenAI
API de reclassificação compatível com OpenAI
Reclassifique documentos por relevância semântica para uma consulta usando qwen3-rerank.
O modelo gte-rerank será descontinuado em 30 de maio de 2026. Mude para qwen3-rerank para serviço continuado.
Antes de chamar a API, obtenha uma chave de API e defini-lo como uma variável de ambiente. Se você usa o OpenAI SDK, instale-o primeiro.
Modelo suportado: qwen3-rerank apenas.
Ponto final
-HTTP: POST https://maas.qwencloudapi.com/compatible-api/v1/reranks
-SDK base_url: https://maas.qwencloudapi.com/compatible-api/v1
Visão geral do modelo
| Modelo | Máximo de documentos | Máximo de tokens/documento | Máximo de tokens de solicitação | Idiomas | Casos de uso |
|---|---|---|---|---|---|
| qwen3-rerank | 500 | 4.000 | 120.000 | Mais de 100 idiomas | Pesquisa semântica de texto, RAG |
Para preços, consulte o Model Marketplace.
Definições de parâmetros:
- Max Tokens/Doc: Contagem máxima de tokens por consulta ou documento. Se uma consulta ou documento exceder esse limite, a API retornará um erro HTTP 400 e não truncará a entrada.
- Max Documentos: Número máximo de documentos por solicitação.
- Tokens máximos de solicitação: calculado como
Query Tokens x Document Count + Total Document Tokens. Não deve exceder o limite.
OpenAPI
openapi: 3.1.0
info:
title: QwenCloud Reranking API
description: Rerank retrieved documents by semantic relevance to improve search accuracy in RAG and retrieval systems.
version: 1.0.0
servers:
- url: https://maas.qwencloudapi.com/compatible-api/v1
description: Singapore
security:
- BearerAuth: []
paths:
/reranks:
post:
operationId: createTextRerank
summary: OpenAI compatible
description: Rerank documents by semantic relevance to a query using qwen3-rerank. Uses a flat request structure with `query`, `documents`, `top_n`, and `instruct` at the top level.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TextRerankRequest"
responses:
"200":
description: Reranking result
content:
application/json:
schema:
$ref: "#/components/schemas/TextRerankResponse"
"400":
description: Invalid request parameters
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"401":
description: Authentication failed — invalid or missing API Key
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
"429":
description: Rate limit exceeded
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
x-codeSamples:
- lang: bash
label: qwen3-rerank
source: |-
curl --request POST \
--url https://maas.qwencloudapi.com/compatible-api/v1/reranks \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "qwen3-rerank",
"documents": [
"Rerank models are widely used in search engines and recommendation systems. They sort candidate documents based on text relevance.",
"Quantum computing is a cutting-edge field of computer science.",
"The development of pre-trained language models has brought new advancements to rerank models."
],
"query": "What is a rerank model?",
"top_n": 2,
"instruct": "Given a web search query, retrieve relevant passages that answer the query."
}'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: QwenCloud API Key. Create one in the [console](https://home.qwencloud.com/api-keys).
schemas:
TextRerankRequest:
type: object
required:
- model
- query
- documents
properties:
model:
type: string
enum:
- qwen3-rerank
description: Model name. Must be `qwen3-rerank` for the text reranking endpoint.
example: qwen3-rerank
query:
type: string
description: Query text. Max 4,000 tokens.
example: What is a reranking model
documents:
type: array
items:
type: string
description: Documents to rank. An array of strings. Max 500 documents.
example:
- Reranking models are widely used in search engines and recommendation systems to sort candidates by relevance
- Quantum computing is a frontier field of computer science
- The development of pre-trained language models has brought new advances to reranking
top_n:
type: integer
minimum: 1
description: Return only the top N results. Defaults to returning all documents.
example: 2
instruct:
type: string
description: 'Custom ranking task instruction. English recommended. Default behavior is QA retrieval: `"Given a web search query, retrieve relevant passages that answer the query."`'
example: Given a web search query, retrieve relevant passages that answer the query.
DashScopeRerankRequest:
type: object
required:
- model
- input
properties:
model:
type: string
enum:
- qwen3-rerank
description: Model name. Must be `qwen3-rerank`.
example: qwen3-rerank
input:
type: object
required:
- query
- documents
description: Input data containing the query and documents to rank.
properties:
query:
type: string
description: Query text. Max 4,000 tokens.
example: What is a reranking model
documents:
type: array
items:
type: string
description: Documents to rank. An array of strings. Max 500 documents.
parameters:
type: object
description: Parameters for the reranking request. Must be wrapped inside this `parameters` object.
properties:
top_n:
type: integer
minimum: 1
description: Return only the top N results. Defaults to returning all documents.
example: 2
return_documents:
type: boolean
default: false
description: "Include original document text in results. Default: `false`."
example: true
instruct:
type: string
description: 'Custom ranking task instruction. English recommended. Default behavior is QA retrieval: `"Given a web search query, retrieve relevant passages that answer the query."`'
example: Given a web search query, retrieve relevant passages that answer the query.
TextRerankResponse:
type: object
properties:
id:
type: string
description: Unique request identifier.
object:
type: string
description: Object type. Always `list`.
example: list
model:
type: string
description: Model used for reranking.
example: qwen3-rerank
results:
type: array
description: Ranked results, sorted by `relevance_score` descending.
items:
$ref: "#/components/schemas/RerankResult"
usage:
type: object
description: Token usage statistics.
properties:
total_tokens:
type: integer
description: Total tokens consumed by this request.
DashScopeRerankResponse:
type: object
properties:
output:
type: object
description: Output wrapper containing ranked results.
properties:
results:
type: array
description: Ranked results, sorted by `relevance_score` descending.
items:
$ref: "#/components/schemas/RerankResult"
usage:
type: object
description: Token usage statistics.
properties:
total_tokens:
type: integer
description: Total tokens consumed by this request.
request_id:
type: string
description: Unique request identifier.
example: 85ba5752-1900-47d2-8896-23f99b13f6e1
RerankResult:
type: object
properties:
document:
type: object
description: Original document. Only returned when `return_documents` is `true`.
properties:
text:
type: string
description: Text content of the document.
index:
type: integer
description: Original position in the input `documents` list.
example: 0
relevance_score:
type: number
format: double
description: Relevance score between 0.0 and 1.0. Higher means more relevant. This is a relative score for the current request and should not be compared across requests.
example: 0.9334521178273196
ErrorResponse:
type: object
properties:
error:
type: object
properties:
message:
type: string
description: Error message.
type:
type: string
description: Error type.
code:
type: string
description: Error code.
param:
type: string
nullable: true
description: Parameter that caused the error.