Skip to main content
Modelo de rerank

Rerank de texto

Um modelo de rerank reclassifica os documentos retornados na recuperação inicial e posiciona os resultados mais relevantes no topo.

Visão geral dos modelos

O modelo gte-rerank será descontinuado em 30 de maio de 2026. Migre para o qwen3-rerank.
  • Singapore
  • Beijing

Model

Max documents

Max input tokens per item

Max input tokens per request

Supported languages

Scenarios

qwen3-rerank

500

4.000

120.000

Mais de 100 idiomas principais, como chinês, inglês, espanhol, francês, português, indonésio, japonês, coreano, alemão e russo

  • Recuperação semântica de texto

  • Aplicações RAG

  • Máximo de tokens de entrada por item: Limite de tokens por consulta ou documento. Se a entrada de uma única consulta ou documento exceder esse limite, a API retornará um erro HTTP 400 e não truncará a entrada.
  • Máximo de documentos: Quantidade máxima de documentos por requisição. No modelo qwen3-vl-rerank, o limite varia conforme o tipo de documento (texto, imagem, vídeo ou misto).
  • Máximo de tokens de entrada por requisição: Calculado como Query Tokens × Number of documents + Total document tokens. Não ultrapasse o limite por requisição.

Limitações de entrada

Model

Image

Video

qwen3-vl-rerank

JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS e SGI (URL ou Base64)

MP4, AVI e MOV (apenas URL)

Pré-requisitos

Obtenha uma chave de API e defina a chave de API como variável de ambiente. Para usar o SDK, instale o DashScope SDK.

HTTP

Cada modelo usa um endpoint diferente:
  • qwen3-rerank: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-api/v1/reranks
  • qwen3-vl-rerank / gte-rerank-v2: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank
Substitua {WorkspaceId} pelo seu ID do workspace real.
As duas APIs diferem na estrutura do corpo da requisição e no formato da resposta. Consulte os exemplos de requisição e resposta de cada modelo.

Request

  • qwen3-rerank
  • qwen3-vl-rerank
  • gte-rerank-v2
# This is the Singapore region URL. Replace WorkspaceId with your actual workspace ID. URLs differ by region.
    curl --request POST \
      --url https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/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."
    }'
Replace WorkspaceId with your actual workspace ID.

Request headers

Content-Type string (Required)Tipo de conteúdo da requisição. Use application/json.
Authorization string (Required)Autentica a requisição com uma chave de API do Model Studio. Exemplo: Bearer sk-xxxx.

Request body

model string (Required)Nome do modelo. Valores aceitos: qwen3-rerank, gte-rerank-v2, qwen3-vl-rerank.
input object (Required)Conteúdo de entrada.
No qwen3-rerank, se não usar o objeto input, coloque query e os documentos no mesmo nível de model.

Properties

query string | object (Required)Texto da consulta (máximo de 4.000 tokens).O qwen3-vl-rerank aceita dois formatos de query:
  • Formato string: Passe uma string de texto diretamente. Ex.: "query": "What is a rerank model?".
  • Formato objeto: Passe um dicionário com o tipo de modalidade e o valor como {"modality type": "input content"}. Tipos aceitos: text e image.
    • Consulta de texto: "query": {"text": "What is a text rerank model?"}
    • Consulta de imagem: "query": {"image": "Image URL or Base64-encoded string"}
documents array (Required)Documentos candidatos para ordenação. Cada elemento é uma string.O qwen3-vl-rerank aceita um dicionário ou string por elemento: {"modality type": "text/image URL/video URL"}. Tipos aceitos: text, image, video.
  • Texto: A chave é text e o valor é uma string. Também é possível usar uma string simples sem dicionário.
  • Imagem: A chave é image e o valor é uma URL ou Data URI em Base64 (data:image/{format};base64,{data}, onde {format} é jpeg/png e {data} é a string codificada).
  • Vídeo: A chave é video e o valor deve ser uma URL publicamente acessível.
parameters object (Optional)Parâmetros opcionais.
No qwen3-rerank, o objeto parameters não é obrigatório. Coloque top_n e instruct no mesmo nível de model.

Properties

top_n int (Optional)Número de documentos mais bem classificados a retornar. Padrão: todos os documentos. Se o valor exceder o total de documentos, todos serão retornados.return_documents bool (Optional)Define se o texto do documento deve ser incluído nos resultados. Padrão: false. Modelos compatíveis: gte-rerank-v2, qwen3-vl-rerank.instruct string (Optional)Instrução personalizada de ordenação. Aplica-se aos modelos qwen3-rerank e qwen3-vl-rerank. Orienta o modelo a aplicar diferentes políticas de classificação. Exemplos:
  • Tarefa de recuperação de perguntas e respostas (padrão): "Given a web search query, retrieve relevant passages that answer the query."
    • Foco: Encontrar respostas. O modelo prioriza documentos que respondem à consulta.
    • Exemplo: Consulta "How to prevent a cold?". O documento "Washing hands frequently prevents colds" recebe alta pontuação; já "A cold is a common illness" recebe baixa pontuação (relevante pelo tópico, mas não responde à pergunta).
  • Tarefa de ordenação por similaridade semântica: "Retrieve semantically similar text."
    • Foco: Determinar equivalência semântica. O modelo avalia se a consulta e o documento têm significado central consistente, independentemente da redação ou estrutura.
    • Exemplo: Em cenários de FAQ, "How do I change my password?" e "What if I forget my password?" são semanticamente similares (alta pontuação). O modelo verifica se ambas refletem a mesma intenção do usuário.
Escreva as instruções em inglês. Padrão: Tarefa de recuperação de perguntas e respostas. Mais instruções estão disponíveis no repositório do modelo.fps float (Optional)Exclusivo do qwen3-vl-rerank. Controla a quantidade de quadros extraídos do vídeo. Valores menores resultam em menos quadros. Intervalo: 0-1 (padrão: 1,0).

Response

  • Successful response
  • Failed response
{
    "object": "list",
    "results": [
        {
            "index": 0,
            "relevance_score": 0.9334521178273196
        },
        {
            "index": 2,
            "relevance_score": 0.34100082626411193
        }
    ],
    "model": "qwen3-rerank",
    "id": "85ba5752-1900-47d2-8896-23f99b13f6e1",
    "usage": {
        "total_tokens": 79
    }
}
request_id stringIdentificador exclusivo da requisição para rastreamento e solução de problemas.
output objectSaída da tarefa.
No qwen3-rerank, a resposta não contém o objeto output. O array results está no nível superior.

Properties

results arrayResultados da ordenação, classificados por relevance_score em ordem decrescente.

Properties

document dictObjeto do documento original. Retornado apenas quando return_documents for true. Formato: {"text": "Original document text"}.index intÍndice do documento no array de entrada documents.relevance_score doubleRelevância semântica entre o documento e a consulta. Intervalo: 0,0-1,0 (quanto maior, mais relevante).
As pontuações são relativas à requisição atual e não podem ser comparadas entre requisições.
usage objectEstatísticas de uso de tokens.

Properties

total_tokens intTotal de tokens consumidos pela requisição.
code stringCódigo de erro. Retornado apenas em requisições com falha. Consulte Error codes.
message stringMensagem de erro detalhada. Retornada apenas em requisições com falha. Consulte Error codes.

Uso do SDK

Exemplo

Chame a API do modelo de rerank.
Os nomes dos parâmetros no SDK correspondem aos da API HTTP, mas a estrutura difere. O HTTP usa objetos aninhados input e parameters ; já o SDK adota uma estrutura plana. 
import dashscope
# China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID. The configuration varies by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

def text_rerank():
    resp = dashscope.TextReRank.call(
        model="gte-rerank-v2",
        query="What is a rerank model?",
        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."
        ],
        top_n=2,
        return_documents=True
    )
    print(resp)

if __name__ == '__main__':
    text_rerank()
Use o modelo qwen3-vl-rerank para rerank multimodal com consulta por imagem. 
import dashscope
from http import HTTPStatus
import json
# China (Beijing) region. Replace {WorkspaceId} with your actual workspace ID.
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

def vl_rerank():
    resp = dashscope.TextReRank.call(
        model="qwen3-vl-rerank",
        query={"image": "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"},
        documents=[
            {"text": "Rerank models are widely used in search engines and recommendation systems. They sort candidate documents based on text relevance."},
            {"image": "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"},
            {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250107/lbcemt/new+video.mp4"}
        ],
        top_n=2,
        return_documents=True
    )
    if resp.status_code == HTTPStatus.OK:
        print(json.dumps(resp, default=str, ensure_ascii=False, indent=4))
    else:
        print(resp)

if __name__ == '__main__':
    vl_rerank()

Saída de exemplo

O SDK encapsula a resposta HTTP. Em requisições bem-sucedidas, code e message são sempre strings vazias.
{
    "status_code": 200,
    "request_id": "4b0805c0-6b36-490d-8bc1-4365f4c89905",
    "code": "",
    "message": "",
    "output": {
        "results": [
            {
                "index": 0,
                "relevance_score": 0.9334521178273196,
                "document": {
                    "text": "Rerank models are widely used in search engines and recommendation systems. They sort candidate documents based on text relevance."
                }
            },
            {
                "index": 2,
                "relevance_score": 0.34100082626411193,
                "document": {
                    "text": "The development of pre-trained language models has brought new advancements to rerank models."
                }
            }
        ]
    },
    "usage": {
        "total_tokens": 79
    }
}

Códigos de erro

Se a chamada do modelo falhar e retornar uma mensagem de erro, consulte Códigos de erro para resolver o problema.
Uso da API
Referência da API de Geração de Texto
Geração de Imagens
  • FAQ
Geração de Vídeo
Áudio
Multimodal em Tempo Real
API em tempo real
Incorporação de Texto
Mais Modelos
Toolkit/Framework
Produção de Modelos
File Management
Gerenciamento de modelos
Mais