Skip to main content

Rerank

Um modelo de reranking reavalia a pontuação de documentos recuperados e prioriza os resultados mais relevantes. Esse processo aumenta a precisão da busca quando a etapa inicial de recuperação favorece a velocidade em detrimento da exatidão.

Quando o reranking agrega mais valor: O reranking é mais eficaz quando a recuperação inicial retorna entre 20 e mais de 100 candidatos com relevância variada. Ele traz pouco benefício se os resultados já forem precisos, como em correspondências exatas de palavras-chave. Em um fluxo de trabalho típico de RAG, um modelo de embedding recupera de 50 a 100 candidatos e, em seguida, o reranking seleciona os 5 a 10 melhores para envio a um modelo de linguagem grande.

Pré-requisitos

Obtain an API key, set it as an environment variable e install the SDK.

Reordenar documentos

Envie uma consulta e uma lista de documentos candidatos para a API. O modelo retorna os documentos ordenados por relevância.

Reranking de texto (qwen3-rerank)

  • OpenAI compatible
  • DashScope
python
import os
from openai import OpenAI

client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-api/v1",
)

results = client.post(
  "/reranks",
  body={
    "model": "qwen3-rerank",
    "query": "What is a reranking model?",
    "documents": [
      "Reranking models are widely used in search engines and recommendation systems to sort candidate texts by relevance.",
      "Quantum computing is a cutting-edge field in computer science.",
      "The development of pretrained language models has led to new advancements in reranking models."
    ],
    "top_n": 2
  },
  cast_to=object
)

print(results)

Reranking multimodal (qwen3-vl-rerank)

O modelo qwen3-vl-rerank reordena textos, imagens e vídeos. A consulta pode ser um texto ou uma imagem, e os documentos podem conter qualquer combinação dessas modalidades.
O reranking multimodal está disponível apenas por meio do SDK ou da API do DashScope, não pelo endpoint compatível com OpenAI.
Python
import os
import dashscope
import json

# A configuração abaixo refere-se à região China (Pequim). Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
  # Se você não tiver configurado uma variável de ambiente, substitua a linha a seguir pela sua API Key do Model Studio: api_key="sk-xxx"
  # As API Keys são específicas de cada região. Para obter uma API Key, consulte https://www.alibabacloud.com/help/model-studio/get-api-key
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  workspace="{WorkspaceId}",
  region="cn-beijing",
)

resp = client.rerank.create(
  model="qwen3-vl-rerank",
  query={"text": "What is a text reranking model"},
  documents=[
    {"text": "Text reranking models are widely used in search engines and recommender systems."},
    {"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
)

print(json.dumps(resp.model_dump(), ensure_ascii=False, indent=4))

Recursos principais

Reranking com instruções (instruct)

O parâmetro instruct define a estratégia de classificação. Escreva as instruções em inglês.
  • Recuperação para perguntas e respostas (padrão): "Given a web search query, retrieve relevant passages that answer the query." Foca em encontrar respostas diretas. Para a consulta "How to prevent a cold?", o trecho "Washing hands frequently can prevent colds" recebe uma pontuação maior do que "A cold is a common illness", pois este último é topicalmente relevante, mas não responde à pergunta.
  • Similaridade semântica: "Retrieve semantically similar text." Prioriza a equivalência de significado e é robusto a diferenças de redação. A pergunta "How do I change my password?" corresponde a "What if I forgot my password?", o que é útil para deduplicação de FAQs.
Se não for definido, o sistema usa a recuperação para perguntas e respostas como padrão.
OpenAI compatible
curl --request POST \
  --url https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-api/v1/reranks \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "qwen3-rerank",
    "query": "How do I change my password?",
    "documents": [
      "Go to Settings > Security > Change Password to update your credentials.",
      "What if I forgot my password?",
      "Our platform supports two-factor authentication."
    ],
    "instruct": "Retrieve semantically similar text."
}'

Retornar os N principais resultados (top_n)

Use top_n para retornar apenas os documentos com melhor classificação. Caso top_n não esteja definido, todos os documentos serão retornados em ordem de relevância. Se o valor de top_n superar a quantidade de documentos de entrada, o sistema retorna todos os documentos disponíveis.

Visão geral dos modelos

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

Modelo

Máximo de documentos

Máximo de tokens por documento

Máximo de tokens por solicitação

Idiomas suportados

Casos de uso

qwen3-rerank

500

32.768

120.000

Mais de 100 idiomas

Busca semântica de texto, aplicações RAG

Termos importantes:
  • Máximo de tokens por documento: Limite de tokens para uma única 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 solicitação. No modelo qwen3-vl-rerank, esse limite varia conforme o tipo de documento (texto, imagem, vídeo ou misto).
  • Máximo de tokens por solicitação: Calculado como Tokens da Consulta × Número de Documentos + Total de Tokens dos Documentos.

Referência da API

Rerank API reference.

Códigos de erro

Se uma chamada falhar, consulte Error codes.

Limites de taxa

Rate limiting.