Skip to main content

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

Substitua {WorkspaceId} pelo seu ID do workspace real.
Esta seção descreve a API HTTP DashScope. Além disso, qwen3-rerank e qwen3.7-text-rerank também são compatíveis com a API compatível com OpenAI. Consulte API compatível com OpenAI.

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/api/v1/services/rerank/text-rerank/text-rerank \
      --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
      --header "Content-Type: application/json" \
      --data '{
            "model": "qwen3-rerank",
            "input": {
                "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?"
            },
            "parameters": {
                "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.
Aninhe query e documents no objeto input.

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.
Aninhe top_n e instruct no objeto parameters.

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, qwen3-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)Somente qwen3-vl-rerank aceita este parâmetro. Ele controla o número de quadros extraídos por segundo de vídeo. Valores menores extraem menos quadros. Intervalo: (0, 5]. Padrão: 1,0.

Response

  • Successful response
  • Failed response
{
    "output": {
        "results": [
            {
                "index": 0,
                "relevance_score": 0.9334521178273196
            },
            {
                "index": 2,
                "relevance_score": 0.34100082626411193
            }
        ]
    },
    "request_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.

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.

API compatível com OpenAI

qwen3-rerank e qwen3.7-text-rerank podem ser chamados por meio da API compatível com OpenAI. gte-rerank-v2 e qwen3-vl-rerank não são compatíveis e retornam o erro model_not_supported. Endpoint: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-api/v1/reranks Diferenças em relação à API HTTP DashScope:
  • O corpo da requisição é plano. query, documents, top_n, instruct e return_documents ficam no mesmo nível de model, sem aninhamento em input ou parameters.
  • Os resultados ordenados ficam no array results da resposta. Cada item contém index (posição do documento na requisição) e relevance_score (pontuação de relevância). Quando return_documents é true, document.text também é retornado.

Exemplo de requisição

curl --request POST \
  --url https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-api/v1/reranks \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "qwen3-rerank",
    "query": "What is a rerank model",
    "documents": [
      "Rerank models are widely used in search engines and recommendation systems",
      "Quantum computing is a frontier field of computer science"
    ],
    "top_n": 2,
    "return_documents": true
}'

Exemplo de resposta

{
  "object": "list",
  "results": [
    {
      "document": {
        "text": "Rerank models are widely used in search engines and recommendation systems"
      },
      "index": 0,
      "relevance_score": 0.8369123119638817
    },
    {
      "document": {
        "text": "Quantum computing is a frontier field of computer science"
      },
      "index": 1,
      "relevance_score": 0.2453528429428607
    }
  ],
  "model": "qwen3-rerank",
  "id": "f55bad52-5f1a-9db2-a915-57ef33e94664",
  "usage": {
    "total_tokens": 66
  }
}
Para exemplos de chamada em Python e Node.js, consulte Rerank.

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 os
import dashscope

# 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 a variável de ambiente não estiver configurada, 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",
)

def text_rerank():
    resp = client.rerank.create(
        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 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 a variável de ambiente não estiver configurada, 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",
)

def vl_rerank():
    resp = client.rerank.create(
        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
    )
    print(json.dumps(resp.model_dump(), ensure_ascii=False, indent=4))

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.
{
    "request_id": "4b0805c0-6b36-490d-8bc1-4365f4c89905",
    "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.