API de Rerank de Texto - qwen3-rerank, gte-rerank-v2, qwen3-vl-rerank | Model Studio - Alibaba Cloud Model Studio: Central de Documentação do Alibaba Cloud

Visão geral dos modelos

Importante

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

Singapore

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

Beijing

Model

Max documents

Max input tokens per item

Max input tokens per request

Supported languages

Scenarios

qwen3-vl-rerank

Texto: 100

Imagem: 40

Vídeo: 4

8.000

120.000

33 idiomas principais, incluindo chinês, inglês, japonês, coreano, francês e alemão

Clusterização de imagens
Busca multimodal
Recuperação de imagens
Recuperação de vídeos

gte-rerank-v2

500

4.000

30.000

Mais de 50 idiomas, incluindo chinês, inglês, japonês, coreano, tailandês, espanhol, francês, português, alemão, indonésio e árabe

Recuperação semântica de texto
Aplicações RAG

Máximo de tokens de entrada por item: Limite de tokens por consulta ou documento. Exceder esse valor causa truncamento e pode reduzir a precisão da classificação.
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 # 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. qwen3-vl-rerank Text query curl --location '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-vl-rerank", "input":{ "query": {"text": "What is a rerank model?"}, "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"} ] }, "parameters": { "return_documents": true, "top_n": 2, "fps": 1,0 } }' Image query curl --location '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-vl-rerank", "input":{ "query": {"image": "https://img.alicdn.com/imgextra/i3/O1CN01rdstgY1uiZWt8gqSL_!!6000000006071-0-tps-1970-356.jpg"}, "documents": [ {"text": "Text rerank models are widely used in search engines and recommendation systems to sort candidate captions 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"} ] }, "parameters": { "return_documents": true, "top_n": 2, "fps": 1,0 } }' gte-rerank-v2 curl --location '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": "gte-rerank-v2", "input":{ "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." ] }, "parameters": { "return_documents": true, "top_n": 2 } }'
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 qwen3-rerank `{ "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 } }` qwen3-vl-rerank / gte-rerank-v2 { "output": { "results": [ { "document": { "text": "Rerank models are widely used in search engines and recommendation systems. They sort candidate documents based on text relevance." }, "index": 0, "relevance_score": 0.9334521178273196 }, { "document": { "text": "The development of pre-trained language models has brought new advancements to rerank models." }, "index": 2, "relevance_score": 0.34100082626411193 } ] }, "usage": { "total_tokens": 79 }, "request_id": "85ba5752-1900-47d2-8896-23f99b13f6e1" } Failed response Se a requisição falhar, `code` e `message` indicam a causa do erro. `{ "code":"InvalidApiKey", "message":"Invalid API-key provided.", "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1" }`
request_id `string` Identificador exclusivo da requisição para rastreamento e solução de problemas.
output `object` Saí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 `array` Resultados da ordenação, classificados por `relevance_score` em ordem decrescente. Properties document `dict` Objeto 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 `double` Relevância semântica entre o documento e a consulta. Intervalo: 0,0-1,0 (quanto maior, mais relevante). Nota As pontuações são relativas à requisição atual e não podem ser comparadas entre requisições.
usage `object` Estatísticas de uso de tokens. Properties total_tokens `int` Total de tokens consumidos pela requisição.
code `string` Código de erro. Retornado apenas em requisições com falha. Consulte Error codes.
message `string` Mensagem 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

Nota

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.

Visão geral dos modelos

Singapore

Beijing

Limitações de entrada

Pré-requisitos

HTTP

Request

qwen3-rerank

qwen3-vl-rerank

gte-rerank-v2

Request headers

Request body

Response

Successful response

qwen3-rerank

qwen3-vl-rerank / gte-rerank-v2

Failed response

Uso do SDK

Exemplo

Saída de exemplo

Códigos de erro