Skip to main content

Reordenamiento de texto

Un modelo de reordenamiento vuelve a puntuar los documentos devueltos por la recuperación inicial, mostrando los resultados más relevantes en la parte superior.

Resumen de modelos

El modelo gte-rerank se descontinuará el 30 de mayo de 2026. Cambie a qwen3-rerank.
  • Singapore
  • Beijing

Modelo

Máximo de documentos

Máximo de tokens de entrada por elemento

Máximo de tokens de entrada por solicitud

Idiomas admitidos

Escenarios

qwen3-rerank

500

4,000

120,000

Más de 100 idiomas principales, como chino, inglés, español, francés, portugués, indonesio, japonés, coreano, alemán y ruso

  • Recuperación semántica de texto

  • Aplicaciones RAG

  • Máximo de tokens de entrada por elemento: Máximo de tokens por consulta o documento. Si una consulta o documento excede este límite, la API devuelve un error HTTP 400 y no trunca la entrada.
  • Máximo de documentos: Máximo de documentos por solicitud. Para qwen3-vl-rerank, el límite varía según el tipo de documento (texto, imagen, video o mixto).
  • Máximo de tokens de entrada por solicitud: Calculado como Query Tokens × Number of documents + Total document tokens. No debe exceder el límite por solicitud.

Limitaciones de entrada

Modelo

Imagen

Video

qwen3-vl-rerank

JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS y SGI (compatible con URL o Base64)

MP4, AVI y MOV (solo URL)

Requisitos previos

Obtener una clave de API y configurar la clave de API como variable de entorno. Para usar el SDK: instalar el SDK de DashScope.

HTTP

Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
Esta sección describe la API HTTP de DashScope. Además, qwen3-rerank y qwen3.7-text-rerank también admiten la API compatible con OpenAI. Consulte API compatible con OpenAI.

Solicitud

Encabezados de solicitud

Content-Type string (Requerido)El tipo de contenido de la solicitud. Debe ser application/json.Authorization string (Requerido)Autentica la solicitud con una clave API de Model Studio. Ejemplo: Bearer sk-xxxx.

Cuerpo de la solicitud

model string (Obligatorio)El nombre del modelo. Valores admitidos: qwen3-rerank, gte-rerank-v2, qwen3-vl-rerank.input object (Obligatorio)Contenido de entrada.
Anide query y documents en el objeto input.

Propiedades

query string | object (Requerido)Texto de consulta (máx. 4,000 tokens).qwen3-vl-rerank admite dos formatos de query:
  • Formato de cadena: Pase una cadena de texto directamente, p. ej., "query": "What is a rerank model?".
  • Formato de objeto: Pase un diccionario especificando el tipo de modalidad y el valor como {"modality type": "input content"}. Tipos admitidos: text y image.
    • Consulta de texto: "query": {"text": "What is a text rerank model?"}
    • Consulta de imagen: "query": {"image": "Image URL or Base64-encoded string"}
documents array (Requerido)Documentos candidatos a ordenar. Cada elemento es una cadena.qwen3-vl-rerank acepta un diccionario o cadena por elemento: {"modality type": "text/image URL/video URL"}. Tipos admitidos: text, image, video.
  • Texto: La clave es text, el valor es una cadena. Una cadena simple sin envoltura de diccionario también funciona.
  • Imagen: La clave es image, el valor es una URL o URI de datos Base64 (data:image/{format};base64,{data}, donde {format} es jpeg/png y {data} es la cadena codificada).
  • Video: La clave es video, el valor debe ser una URL accesible públicamente.
parameters object (Opcional)Parámetros opcionales.
Anide top_n y instruct en el objeto parameters.

Propiedades

top_n int (Opcional)Número de documentos mejor clasificados para devolver. Predeterminado: todos los documentos. Los valores que exceden el total de documentos devuelven todos.return_documents bool (Opcional)Indica si se incluye el texto del documento en los resultados. Predeterminado: false. Modelos admitidos: gte-rerank-v2, qwen3-vl-rerank, qwen3-rerank.instruct string (Opcional)Instrucción de ordenamiento personalizada. Aplica a qwen3-rerank y qwen3-vl-rerank. Guía al modelo para aplicar diferentes políticas de ordenamiento. Ejemplos:
  • Tarea de recuperación de preguntas y respuestas (predeterminado): "Given a web search query, retrieve relevant passages that answer the query."
    • Enfoque: Encontrar respuestas. El modelo prioriza si un documento responde a la consulta.
    • Ejemplo: Consulta "¿Cómo prevenir un resfriado?" - El documento "Lavarse las manos frecuentemente previene resfriados" obtiene una puntuación alta; "El resfriado es una enfermedad común" obtiene una puntuación baja (temáticamente relevante pero no responde).
  • Tarea de ordenamiento por similitud semántica: "Retrieve semantically similar text."
    • Enfoque: Determinar equivalencia semántica. El modelo evalúa si la consulta y el documento tienen un significado central consistente, independientemente de la redacción o estructura.
    • Ejemplo: En escenarios de preguntas frecuentes, "¿Cómo cambio mi contraseña?" y "¿Qué pasa si olvido mi contraseña?" son semánticamente similares (puntuación alta). El modelo se enfoca en si ambos reflejan la misma intención del usuario.
Escriba las instrucciones en inglés. Predeterminado: Tarea de recuperación de preguntas y respuestas. Hay más instrucciones disponibles en el repositorio del modelo.fps float (Opcional)Solo qwen3-vl-rerank. Controla la cantidad de extracción de fotogramas de video. Valores más pequeños = menos fotogramas. Rango: 0-1 (predeterminado: 1.0).
  • qwen3-rerank
  • qwen3-vl-rerank
  • gte-rerank-v2
  • CLI de dashscope
# 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."
        }
}'
Reemplace WorkspaceId con su ID de espacio de trabajo real.

Respuesta

request_id stringIdentificador único de solicitud para rastreo y solución de problemas.output objectSalida de la tarea.

Propiedades

results arrayResultados de ordenamiento, ordenados por relevance_score descendente.

Propiedades

document dictObjeto de documento original. Se devuelve solo cuando return_documents es true. Formato: {"text": "Original document text"}.index intÍndice del documento en el array de entrada documents.relevance_score doubleRelevancia semántica entre el documento y la consulta. Rango: 0.0-1.0 (mayor = más relevante).
Las puntuaciones son relativas a la solicitud actual y no se pueden comparar entre solicitudes.
usage objectEstadísticas de uso de tokens.

Propiedades

total_tokens intTotal de tokens consumidos por la solicitud.
code stringCódigo de error. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.message stringMensaje de error detallado. Se devuelve solo para solicitudes fallidas. Consulte Códigos de error.
  • Respuesta exitosa
  • Respuesta fallida
{
    "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
    }
}

API compatible con OpenAI

qwen3-rerank y qwen3.7-text-rerank se pueden llamar a través de la API compatible con OpenAI. gte-rerank-v2 y qwen3-vl-rerank no son compatibles y devuelven el error model_not_supported. Endpoint: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-api/v1/reranks Diferencias con la API HTTP de DashScope:
  • El cuerpo de la solicitud es plano. query, documents, top_n, instruct y return_documents van al mismo nivel que model, sin anidarse en input ni parameters.
  • Los resultados ordenados se devuelven en el array results de la respuesta. Cada elemento incluye index (posición del documento en la solicitud) y relevance_score (puntuación de relevancia). Si return_documents es true, también se devuelve document.text.

Ejemplo de solicitud 

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
}'

Ejemplo de respuesta 

{
  "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 ver ejemplos de llamada con Python y Node.js, consulte Rerank.

Uso del SDK

Ejemplo

Llame a la API del modelo rerank.
Los nombres de los parámetros del SDK coinciden con la API HTTP, pero la estructura difiere. HTTP utiliza objetos anidados input y parameters; el SDK utiliza una estructura plana. 
import os
import dashscope

# La siguiente configuración corresponde a la región de China (Pekín). Sustituya {WorkspaceId} por el ID real de su espacio de trabajo. El valor de region varía según la región.
client = dashscope.Client(
    # Si no se ha configurado la variable de entorno, sustituya la siguiente línea por su API Key de Model Studio: api_key="sk-xxx"
    # Las API Key son específicas de cada región. Para obtener una 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()
Utilice qwen3-vl-rerank para reordenamiento multimodal con una consulta de imagen. 
import os
import dashscope
import json

# La siguiente configuración corresponde a la región de China (Pekín). Sustituya {WorkspaceId} por el ID real de su espacio de trabajo. El valor de region varía según la región.
client = dashscope.Client(
    # Si no se ha configurado la variable de entorno, sustituya la siguiente línea por su API Key de Model Studio: api_key="sk-xxx"
    # Las API Key son específicas de cada región. Para obtener una 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()

Salida de ejemplo

El SDK 2.0 devuelve un objeto de respuesta estructurado; los resultados del reordenamiento se acceden mediante resp.results (resp.results[i].index / .relevance_score / .document). Si la solicitud falla, se lanza una excepción DashScopeError.
{
    "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 error

Si la llamada al modelo falla y devuelve un mensaje de error, consulte Códigos de error para su resolución.