Skip to main content

Rerank de texte

Un modèle de rerank réévalue les documents issus d'une recherche initiale pour placer les résultats les plus pertinents en tête de liste.

Présentation des modèles

Le modèle gte-rerank sera abandonné le 30 mai 2026. Migrez vers qwen3-rerank.
  • Singapore
  • Beijing
ModèleDocuments max.Tokens d'entrée max. par élémentTokens d'entrée max. par requêteLangues prises en chargeCas d'usage
qwen3-rerank5004 000120 000Plus de 100 langues principales, dont le chinois, l'anglais, l'espagnol, le français, le portugais, l'indonésien, le japonais, le coréen, l'allemand et le russe
  • Recherche sémantique de texte
  • Applications RAG
  • Tokens d'entrée max. par élément : nombre maximal de tokens par requête ou document. Le dépassement de cette limite entraîne une troncature susceptible de réduire la précision du classement.
  • Documents max. : nombre maximal de documents par requête. Pour qwen3-vl-rerank, cette limite varie selon le type de document (texte, image, vidéo ou mixte).
  • Tokens d'entrée max. par requête : valeur calculée selon la formule Query Tokens × Number of documents + Total document tokens. Cette valeur ne doit pas excéder la limite par requête.

Limitations d'entrée

Modèle

Image

Vidéo

qwen3-vl-rerank

JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS et SGI (URL ou Base64 pris en charge)

MP4, AVI et MOV (URL uniquement)

Prérequis

Obtenez une clé API et définissez-la comme variable d'environnement. Pour utiliser le SDK, installez le DashScope SDK.

HTTP

Remplacez {WorkspaceId} par votre ID d'espace de travail.
Cette section décrit l'API HTTP DashScope. En outre, qwen3-rerank et qwen3.7-text-rerank prennent également en charge l'API compatible OpenAI. Voir API compatible OpenAI.

Requête

  • 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.

En-têtes de requête

Content-Type string (Obligatoire)Type de contenu de la requête. Doit être application/json.
Authorization string (Obligatoire)Authentifie la requête avec une clé API Model Studio. Exemple : Bearer sk-xxxx.

Corps de la requête

model string (Obligatoire)Nom du modèle. Valeurs prises en charge : qwen3-rerank, gte-rerank-v2, qwen3-vl-rerank.
input object (Obligatoire)Contenu d'entrée.
Imbriquez query et documents dans l'objet input.

Propriétés

query string | object (Obligatoire)Texte de la requête (4 000 tokens maximum).qwen3-vl-rerank accepte deux formats de query :
  • Format chaîne : passez directement une chaîne de texte, par exemple "query": "What is a rerank model?".
  • Format objet : passez un dictionnaire spécifiant le type de modalité et la valeur sous la forme {"modality type": "input content"}. Types pris en charge : text et image.
    • Requête texte : "query": {"text": "What is a text rerank model?"}
    • Requête image : "query": {"image": "Image URL or Base64-encoded string"}
documents array (Obligatoire)Documents candidats à trier. Chaque élément est une chaîne.qwen3-vl-rerank accepte un dictionnaire ou une chaîne par élément : {"modality type": "text/image URL/video URL"}. Types pris en charge : text, image, video.
  • Texte : la clé est text, la valeur est une chaîne. Une chaîne simple sans encapsulation dans un dictionnaire fonctionne également.
  • Image : la clé est image, la valeur est une URL ou un Data URI Base64 (data:image/{format};base64,{data}, où {format} est jpeg/png et {data} est la chaîne encodée).
  • Vidéo : la clé est video, la valeur doit être une URL accessible publiquement.
parameters object (Facultatif)Paramètres facultatifs.
Imbriquez top_n et instruct dans l'objet parameters.

Propriétés

top_n int (Facultatif)Nombre de documents les mieux classés à retourner. Par défaut : tous les documents. Si la valeur dépasse le nombre total de documents, tous sont retournés.return_documents bool (Facultatif)Indique si le texte des documents doit être inclus dans les résultats. Par défaut : false. Modèles pris en charge : gte-rerank-v2, qwen3-vl-rerank, qwen3-rerank.instruct string (Facultatif)Instruction de tri personnalisée. S'applique à qwen3-rerank et qwen3-vl-rerank. Guide le modèle pour appliquer différentes politiques de tri. Exemples :
  • Tâche de récupération Q&A (par défaut) : "Given a web search query, retrieve relevant passages that answer the query."
    • Objectif : trouver des réponses. Le modèle privilégie les documents qui répondent directement à la requête.
    • Exemple : pour la requête « Comment prévenir un rhume ? », le document « Se laver fréquemment les mains prévient les rhumes » obtient un score élevé, tandis que « Le rhume est une maladie courante » obtient un score faible (pertinent thématiquement mais sans réponse directe).
  • Tâche de tri par similarité sémantique : "Retrieve semantically similar text."
    • Objectif : déterminer l'équivalence sémantique. Le modèle évalue si la requête et le document partagent le même sens fondamental, indépendamment de la formulation ou de la structure.
    • Exemple : dans une FAQ, « Comment changer mon mot de passe ? » et « Que faire si j'oublie mon mot de passe ? » sont sémantiquement similaires (score élevé). Le modèle se concentre sur l'intention utilisateur commune.
Rédigez les instructions en anglais. Par défaut : tâche de récupération Q&A. D'autres instructions sont disponibles dans le référentiel du modèle.fps float (Facultatif)Seul qwen3-vl-rerank prend en charge ce paramètre. Il contrôle le nombre de frames extraites par seconde de vidéo. Des valeurs plus faibles extraient moins de frames. Plage : (0, 5]. Valeur par défaut : 1,0.

Réponse

  • Réponse réussie
  • Réponse d'échec
{
    "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 stringIdentifiant unique de la requête pour le suivi et le dépannage.
output objectSortie de la tâche.

Propriétés

results arrayRésultats du tri, classés par ordre décroissant de relevance_score.

Propriétés

document dictObjet document original. Retourné uniquement lorsque return_documents est true. Format : {"text": "Original document text"}.index intIndex du document dans le tableau documents d'entrée.relevance_score doublePertinence sémantique entre le document et la requête. Plage : 0,0-1,0 (plus le score est élevé, plus la pertinence est forte).
Les scores sont relatifs à la requête en cours et ne peuvent pas être comparés entre différentes requêtes.
usage objectStatistiques d'utilisation des tokens.

Propriétés

total_tokens intNombre total de tokens consommés par la requête.
code stringCode d'erreur. Retourné uniquement pour les requêtes échouées. Consultez Codes d'erreur.
message stringMessage d'erreur détaillé. Retourné uniquement pour les requêtes échouées. Consultez Codes d'erreur.

API compatible OpenAI

qwen3-rerank et qwen3.7-text-rerank peuvent être appelés via l'API compatible OpenAI. gte-rerank-v2 et qwen3-vl-rerank ne sont pas pris en charge et renvoient une erreur model_not_supported. Endpoint : POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-api/v1/reranks Différences avec l'API HTTP DashScope :
  • Le corps de la requête est plat. query, documents, top_n, instruct et return_documents sont au même niveau que model, sans imbrication dans input ou parameters.
  • Les résultats triés se trouvent dans le tableau results de la réponse. Chaque élément contient index (position du document dans la requête) et relevance_score (score de pertinence). Lorsque return_documents vaut true, document.text est également renvoyé.

Exemple de requête

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

Exemple de réponse

{
  "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
  }
}
Pour des exemples d'appel en Python et Node.js, consultez Rerank.

Utilisation du SDK

Exemple

Appelez l'API du modèle de rerank.
Les noms de paramètres du SDK correspondent à ceux de l'API HTTP, mais leur structure diffère. L'API HTTP utilise des objets imbriqués input et parameters , tandis que le SDK emploie une structure plate.
import os
import dashscope

# Voici la configuration de la région Chine (Pékin). Remplacez {WorkspaceId} par l'ID de votre workspace. La valeur de region varie selon la région.
client = dashscope.Client(
    # Si la variable d'environnement n'est pas configurée, remplacez la ligne suivante par votre API Key de Model Studio : api_key="sk-xxx"
    # Les API Key sont spécifiques à chaque région. Pour obtenir une API Key, consultez 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()
Utilisez qwen3-vl-rerank pour un rerank multimodal avec une requête image.
import os
import dashscope
import json

# Voici la configuration de la région Chine (Pékin). Remplacez {WorkspaceId} par l'ID de votre workspace. La valeur de region varie selon la région.
client = dashscope.Client(
    # Si la variable d'environnement n'est pas configurée, remplacez la ligne suivante par votre API Key de Model Studio : api_key="sk-xxx"
    # Les API Key sont spécifiques à chaque région. Pour obtenir une API Key, consultez 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()

Exemple de sortie

Le SDK 2.0 renvoie un objet de réponse structuré ; les résultats du rerank sont accessibles via resp.results (resp.results[i].index / .relevance_score / .document). En cas d'échec de la requête, une exception DashScopeError est levée.
{
    "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
    }
}

Codes d'erreur

Si l'appel du modèle échoue et renvoie un message d'erreur, consultez Codes d'erreur pour résoudre le problème.