Rerank

Informations communes

• Base URL : https://api.routeapi.ai
• Authentification : Authorization: Bearer $ROUTEAPI_KEY avec une clé API commençant par sk- (à créer sur la page API Keys de la console). Les clés de gestion commençant par rat_ ne peuvent pas appeler les modèles.
• Format d’erreur : {"error": {"message": "...", "type": "...", "code": "..."}}. Voir Erreurs courantes pour la signification de chaque code d’état.

Rerank prend une requête et une liste de documents, et renvoie les documents réordonnés selon la pertinence de chacun vis-à-vis de la requête. Contrairement aux embeddings, qui notent la requête et le document indépendamment, un modèle reranker lit la paire ensemble ; il constitue donc généralement la seconde étape d’un pipeline de récupération : une recherche vectorielle peu coûteuse réduit des milliers de candidats, puis le rerank retient la poignée de documents qui répondent réellement à la question.

Le format de requête et de réponse suit la convention rerank de Jina / Cohere, de sorte que le même appel fonctionne avec les modèles reranker de différents fournisseurs.

Point de terminaison

POST /v1/rerank

URL complète :

https://api.routeapi.ai/v1/rerank

Si la Base URL de votre client est configurée sans /v1, POST /rerank fonctionne également ; la requête est réécrite en interne vers /v1/rerank. Il n’existe pas de variante en streaming : la réponse est un unique corps JSON.

Paramètres de requête

Champ	Type	Requis	Description
model	string	Oui	ID du modèle reranker. Il doit s’agir d’un modèle auquel votre clé a accès et qui dispose d’un canal amont compatible rerank — voir Modèles pris en charge
query	string	Oui	La requête par rapport à laquelle les documents sont notés
documents	array	Oui	Les documents candidats. Chaque élément est normalement une chaîne ; certains amonts acceptent aussi des objets tels que {"text": "..."}. Ne doit pas être vide
top_n	integer	Non	Ne renvoyer que ce nombre de résultats. S’il est omis, la valeur par défaut de l’amont s’applique (l’adaptateur de style Cohere utilise 1 par défaut)
return_documents	boolean	Non	Inclure le document correspondant dans chaque résultat. S’il est omis, les adaptateurs qui transmettent le corps tel quel laissent la décision à l’amont
max_chunk_per_doc	integer	Non	Indication de découpage pour les documents longs. Transmise telle quelle par les adaptateurs qui font passer le corps (Jina, SiliconFlow, compatible OpenAI / Xinference) ; supprimée par les adaptateurs Cohere et DashScope, qui reconstruisent la requête
overlap_tokens	integer	Non	Chevauchement de tokens entre les fragments pour la même indication de découpage. Mêmes règles de transmission que max_chunk_per_doc

RouteAPI lui-même vérifie uniquement que model n’est pas vide (l’ID est nécessaire pour choisir un canal) et que query et documents sont présents et non vides. Tout le reste est transmis au modèle amont, et un amont peut rejeter une valeur qu’il ne prend pas en charge.

Exemples

curl

curl https://api.routeapi.ai/v1/rerank \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jina-reranker-v2-base-multilingual",
    "query": "How do I handle rate limits?",
    "documents": [
      "Authentication uses a Bearer token in the Authorization header.",
      "Rate limited requests return 429; back off and retry.",
      "RouteAPI aggregates 40+ AI providers behind one API.",
      "Section 4.2 covers rate limits and retries."
    ],
    "top_n": 2,
    "return_documents": true
  }'

Python (requests)

Le SDK Python OpenAI n’a pas de méthode rerank ; appelez donc le point de terminaison directement :

import os
import requests

resp = requests.post(
    "https://api.routeapi.ai/v1/rerank",
    headers={
        "Authorization": f"Bearer {os.environ['ROUTEAPI_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "jina-reranker-v2-base-multilingual",
        "query": "How do I handle rate limits?",
        "documents": [
            "Authentication uses a Bearer token in the Authorization header.",
            "Rate limited requests return 429; back off and retry.",
            "RouteAPI aggregates 40+ AI providers behind one API.",
            "Section 4.2 covers rate limits and retries.",
        ],
        "top_n": 2,
        "return_documents": True,
    },
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

for item in data["results"]:
    print(f"{item['relevance_score']:.4f}  [{item['index']}]")

Réponse

{
  "results": [
    {
      "document": "Section 4.2 covers rate limits and retries.",
      "index": 3,
      "relevance_score": 0.9134
    },
    {
      "document": "Rate limited requests return 429; back off and retry.",
      "index": 1,
      "relevance_score": 0.7781
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 0,
    "total_tokens": 42
  }
}

L’exemple ci-dessus est une réponse du chemin Jina avec des entrées de type chaîne. La valeur document est ce que l’amont a renvoyé : certains fournisseurs enveloppent chaque document dans un objet tel que { "text": "..." }, et la passerelle ne le remodèle pas.

Champ	Description
results	Les résultats classés renvoyés par l’amont, du plus pertinent au moins pertinent pour les rerankers standard. La passerelle ne les retrie ni ne les tronque ; top_n est transmis à l’amont
results[].index	Position du document dans le tableau documents de la requête, à partir de zéro — utilisez-la pour rattacher un résultat à l’élément d’origine
results[].relevance_score	Score de pertinence. Plus il est élevé, plus le document est pertinent. La passerelle transmet le score de l’amont tel quel, donc l’échelle dépend du modèle ; ne supposez pas 0–1 sauf si le modèle le documente
results[].document	Le document correspondant, présent uniquement lorsque l’amont le renvoie (normalement quand return_documents vaut true). Il est repris tel quel : un document de type chaîne revient sous forme de chaîne, un objet sous forme d’objet
usage.prompt_tokens	Tokens d’entrée facturés pour la requête plus les documents
usage.total_tokens	Total des tokens facturés

Remarques sur la réponse :

• Pas de champ model. La passerelle ne renvoie que results et usage ; elle ne répercute pas l’ID de modèle. Gardez-en la trace côté client si vous en avez besoin.
• usage reprend la structure d’usage partagée de la passerelle, l’objet contient donc aussi des champs tels que les objets de détail des tokens (prompt_tokens_details, completion_tokens_details, etc.). Pour le rerank, ils valent zéro — lisez prompt_tokens et total_tokens. Lequel des deux est fiable dépend du canal : sur le chemin Jina / compatible OpenAI, la passerelle copie le total_tokens de l’amont dans prompt_tokens, donc prompt_tokens est la valeur qui a survécu ; sur SiliconFlow et Cohere, les comptes d’entrée et de sortie sont mappés séparément.
• La présence de document dépend de l’amont. L’adaptateur Cohere envoie toujours return_documents: true en amont, et l’adaptateur DashScope le fait lorsque le champ est absent ; un document peut donc revenir même si vous ne l’avez pas demandé. Considérez document comme une commodité facultative et conservez le tableau documents d’origine indexé par index.
• Les scores ne sont pas comparables d’un modèle à l’autre. Ils proviennent de la tête de scoring propre au modèle ; comparez les rangs au sein d’une même réponse, pas les scores bruts entre requêtes ou entre modèles.

Modèles pris en charge

GET /v1/models renvoie un tableau supported_endpoint_types pour chaque modèle. Seuls les modèles servis via un canal Jina portent l’étiquette jina-rerank ; les modèles reranker atteints via les autres canaux listés ci-dessous portent l’étiquette openai à la place. Ainsi, un modèle dont la liste ne contient pas jina-rerank n’est pas automatiquement inutilisable pour le rerank — ce qui compte, c’est que le modèle figure dans votre liste et qu’un canal compatible rerank se trouve derrière lui. Confirmez-le avec la place des modèles de la console, ou en envoyant une requête de test. Voir Modèles pour le tableau des types de point de terminaison et les filtres qui déterminent le contenu de votre liste.

Les modèles reranker atteignent RouteAPI via plusieurs types de canaux, et chaque adaptateur mappe la même requête JSON sur un protocole amont différent :

Famille de canaux	Appel amont	Remarques
Jina	POST {base}/v1/rerank	Corps de requête transmis tel quel ; réponse analysée au format Jina results / usage
Cohere	POST {base}/v1/rerank	Requête reconstruite au format rerank de Cohere ; top_n vaut 1 par défaut ; les documents reviennent tels que Cohere les renvoie
SiliconFlow	POST {base}/v1/rerank	Requête transmise telle quelle ; usage de tokens lu dans le meta.tokens de l’amont
Alibaba DashScope (Ali)	.../api/v1/services/rerank/text-rerank/text-rerank	Requête reconstruite en input / parameters ; return_documents vaut true par défaut ; les erreurs amont remontent avec le code DashScope
Compatible OpenAI	POST {base}/v1/rerank	Requête transmise telle quelle ; la réponse doit être au format Jina (results / usage) car elle est analysée directement
Xinference	POST {base}/v1/rerank	Requête transmise telle quelle ; l’usage est toujours une estimation de RouteAPI ; lorsque return_documents est activé et que l’amont renvoie une chaîne de document vide, le document d’origine à cet index est réinjecté

Comme la passerelle renvoie tout sous la forme results[].index / relevance_score, changer de modèle reranker ne demande généralement qu’un changement d’ID de modèle. max_chunk_per_doc et overlap_tokens n’atteignent que les amonts dont l’adaptateur transmet le corps tel quel.

Utiliser le rerank dans un pipeline RAG

Un pipeline de récupération typique en deux étapes :

1. Découpez votre base de connaissances en fragments et calculez les intégrations une seule fois avec un modèle d’intégration, en stockant les vecteurs. Voir Embeddings.
2. Au moment de la requête, calculez l’intégration de la question avec le même modèle d’intégration et récupérez les 20 à 100 fragments les plus proches par similarité vectorielle.
3. Envoyez la question comme query et les fragments récupérés comme documents à /v1/rerank, avec top_n réglé sur le nombre de fragments que votre fenêtre de contexte peut contenir.
4. Ne placez que les fragments rerankés dans le prompt de /v1/chat/completions.

import os
import requests

ROUTEAPI = "https://api.routeapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['ROUTEAPI_KEY']}"}

def rerank(query: str, candidates: list[str], top_n: int = 5) -> list[str]:
    resp = requests.post(
        f"{ROUTEAPI}/rerank",
        headers=HEADERS,
        json={
            "model": "jina-reranker-v2-base-multilingual",
            "query": query,
            "documents": candidates,
            "top_n": top_n,
        },
        timeout=30,
    )
    resp.raise_for_status()
    return [candidates[r["index"]] for r in resp.json()["results"]]

Conservez les fragments récupérés indexés par position : c’est index qui relie un résultat à votre texte source, en particulier lorsque vous choisissez de ne pas demander return_documents.

Facturation

Les requêtes rerank sont facturées en tokens d’entrée : prompt_tokens couvre la requête et tous les documents envoyés dans un même appel. return_documents n’ajoute pas de tokens — les documents étaient déjà comptés en entrée. Les prix proviennent de la tarification au token du modèle, comme pour les modèles de texte ; voir Tarification des modèles et confirmez le tarif du modèle dans la place des modèles.

RouteAPI pré-réserve le montant d’après les tokens d’entrée estimés (tous les documents plus la requête), puis règle après la réponse de l’amont. L’origine des comptes de tokens finaux dépend du canal : les chemins de style Jina, SiliconFlow, DashScope et compatible OpenAI générique utilisent l’usage rapporté par l’amont ; le chemin Cohere retombe sur l’estimation lorsque l’amont ne rapporte aucune unité facturée ; le chemin Xinference utilise toujours l’estimation. Si un amont ne rapporte aucun usage sur un chemin qui en dépend, aucun règlement n’est possible : cet appel est journalisé avec zéro token — consultez le journal d’utilisation si un appel rerank semble sous-facturé.

Envoyer moins de documents, et plus courts, coûte moins cher, et top_n ne limite que la taille de la réponse — il ne réduit pas les tokens d’entrée, car chaque document doit quand même être noté.

Erreurs

Les erreurs utilisent le corps standard { "error": { ... } }, et le message contient un ID de requête que vous pouvez rechercher dans les journaux de la console. Voir Erreurs courantes pour la liste complète.

Code d’état	Message / code	Cause
400	Missing required field: query (invalid_request)	query est vide ou absent
400	Missing required field: documents (invalid_request)	documents est absent ou est un tableau vide
400	Model name not specified, model name cannot be empty	model est vide
403	This token has no access to model {model}	Le modèle est en dehors de la liste blanche de modèles de la clé
403	insufficient_user_quota / pre_consume_token_quota_failed	Le solde du compte ou le quota de la clé ne couvre pas la pré-réservation
503	No valid upstream service (model_not_found)	Aucun canal utilisable pour le modèle, ou le modèle n’est pas routable du tout
4xx / 5xx	Message de l’amont	Le fournisseur a rejeté la requête ; le code d’état et le message sont transmis tels quels

Exemple :

{
  "error": {
    "message": "Missing required field: documents (request id: 20261023153000123456789AbCdEfGh)",
    "type": "error",
    "code": "invalid_request"
  }
}

Les messages de validation de la passerelle sont localisés : la langue suit celle définie sur votre compte, sinon l’en-tête Accept-Language, sinon l’anglais. Les valeurs de code ne changent pas.

Lorsqu’une requête échoue, aucun résultat n’est renvoyé et le montant pré-réservé est remboursé.

Pour aller plus loin

• Embeddings — construire la récupération vectorielle de première étape qui alimente le rerank.
• Modèles — types de point de terminaison et modèles que votre clé peut appeler.
• Tarification des modèles — tarification au token des modèles reranker.
• Erreurs courantes — codes d’état, corps d’erreur et ordre de dépannage.