Reclassificação

Melhore a precisão da pesquisa

Os sistemas de recuperação priorizam a velocidade, portanto os resultados podem não ter precisão. Os modelos de reclassificação reclassificam os documentos recuperados para colocar os resultados mais relevantes no topo, melhorando significativamente a precisão da pesquisa.

O modelo gte-rerank será descontinuado em 30 de maio de 2026. Mude para qwen3-rerank para serviço continuado.

Quando a reclassificação ajuda mais: A reclassificação oferece o maior aumento de precisão quando sua recuperação inicial retorna de 20 a 100+ candidatos com relevância mista. Se a sua recuperação já retorna resultados altamente relevantes (como correspondência exata de palavras-chave), a reclassificação agrega menos valor. Um pipeline RAG típico: recupere de 50 a 100 candidatos com incorporações, reclassifique para os 5 a 10 primeiros e depois passe-os para o LLM.

Pré-requisitos

Obtenha uma chave de API e defini-lo como uma variável de ambiente. Para usar o SDK, instale-o.

Reclassificar documentos

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

OpenAI compatible

  ```python Python
  import os
  from openai import OpenAI

  client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://maas.qwencloudapi.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 rank candidate texts by relevance",
        "Quantum computing is a frontier field of computational science",
        "The development of pre-trained language models has brought new advances to reranking models"
      ],
      "top_n": 2
    },
    cast_to=object
  )

  print(results)
  ```

  ```javascript Node.js
  const OpenAI = require("openai");

  const openai = new OpenAI({
    apiKey: process.env.DASHSCOPE_API_KEY,
    baseURL: "https://maas.qwencloudapi.com/compatible-api/v1",
  });

  async function rerank() {
    const results = await openai.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 rank candidate texts by relevance",
          "Quantum computing is a frontier field of computational science",
          "The development of pre-trained language models has brought new advances to reranking models",
        ],
        top_n: 2,
      },
    });

    console.log(JSON.stringify(results, null, 2));
  }

  rerank();
  ```

  ```bash curl
  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",
      "query": "What is a reranking model",
      "documents": [
        "Reranking models are widely used in search engines and recommendation systems to rank candidate texts by relevance",
        "Quantum computing is a frontier field of computational science",
        "The development of pre-trained language models has brought new advances to reranking models"
      ],
      "top_n": 2
  }'
  ```

DashScope

  ```python Python
  import dashscope
  from http import HTTPStatus

  dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1'

  resp = dashscope.TextReRank.call(
    model="qwen3-rerank",
    query="What is a reranking model",
    documents=[
      "Reranking models are widely used in search engines and recommendation systems to rank candidate texts by relevance",
      "Quantum computing is a frontier field of computational science",
      "The development of pre-trained language models has brought new advances to reranking models"
    ],
    top_n=2,
    return_documents=True
  )

  if resp.status_code == HTTPStatus.OK:
    print(resp)
  ```

  ```bash curl
  curl --request POST \
    --url https://maas.qwencloudapi.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": {
      "query": "What is a reranking model",
      "documents": [
        "Reranking models are widely used in search engines and recommendation systems to rank candidate texts by relevance",
        "Quantum computing is a frontier field of computational science",
        "The development of pre-trained language models has brought new advances to reranking models"
      ]
    },
    "parameters": {
      "top_n": 2,
      "return_documents": true
    }
  }'
  ```

Recursos principais

Use instruções para melhorar a classificação (instruir)

O instruct parâmetro orienta o modelo para usar diferentes estratégias de classificação. Escreva instruções em inglês.

• Recuperação de controle de qualidade (padrão): "Given a web search query, retrieve relevant passages that answer the query."

  • Foco: encontrar respostas. Para a pergunta “Como prevenir resfriados?”, “Lavar as mãos com frequência evita resfriados” tem pontuações mais altas do que “O resfriado comum é uma doença generalizada” (relacionada topicamente, mas não responde à pergunta).

• Semelhança semântica: "Retrieve semantically similar text."

  • Foco: equivalência semântica independente da redação. Exemplo: "Como alterar minha senha?" corresponde a "E se eu esquecer minha senha?" em um cenário de perguntas frequentes.

Se não for definido, o modelo assumirá como padrão a recuperação de controle de qualidade. Para obter mais exemplos de instruções de tarefas, consulte o repositório de modelo.

OpenAI compatible

```bash curl
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",
    "query": "How to change my password?",
    "documents": [
      "Click 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."
}'
```

DashScope

```python Python
import dashscope
from http import HTTPStatus

dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1'

resp = dashscope.TextReRank.call(
  model="qwen3-rerank",
  query="How to change my password?",
  documents=[
    "Click 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."
)

if resp.status_code == HTTPStatus.OK:
  print(resp)
```

Retorna os melhores resultados (top_n)

Usar top_n para retornar apenas os documentos com classificação mais alta. Se omitido, todos os documentos serão retornados classificados por relevância. Se top_n exceder a contagem total de documentos, todos os documentos serão devolvidos.

Modelos suportados

Termos-chave:

• Max tokens per document: 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.
• Máximo de tokens por solicitação: calculado como Query Tokens x Document Count + Total Document Tokens. Este valor não deve exceder o limite por solicitação.

Referência de API

• Endpoint compatível com OpenAI
• ponto final do DashScope

Códigos de erro

Se uma chamada falhar, consulte Mensagens de erro.

Limites de taxa

Consulte Limites de taxa.