API publiqueRerank

Rerank

Re-note finement une liste de documents par pertinence vis-à-vis d'une requête, grâce à un modèle de reranking (cross-encodeur). C'est le second étage d'un pipeline RAG retrieve-then-rerank : la recherche vectorielle remonte un large lot de candidats, le reranker les classe et garde les meilleurs.

stablev1forme Cohere / Jina

Endpoint#endpoint

POSThttps://ai.3gks.cloud/v1/rerankauth : Bearer sk-3gk-…

Ce n'est PAS l'API OpenAI. Le reranking n'a pas de standard OpenAI : notre endpoint suit la forme Cohere / Jina (également compatible avec vLLM). Le SDK openai ne couvre donc pas le rerank — appelez l'endpoint en HTTP direct, ou via le SDK Cohere/Jina pointé sur notre base URL.

Pipeline retrieve-then-rerank. Étape 1, la recherche vectorielle (Embeddings) remonte un large lot de candidats (top 50-100) à partir d'une similarité approximative. Étape 2, le reranker joint query et chaque document dans un cross-encodeur et les re-note finement, puis on garde le top N. Gain de précision notable, surtout sur des requêtes juridiques nuancées (négation, sens inverse).

Backend dédié. Le reranking est servi par une instance vLLM en mode --task score (cross-encodeur), distincte des modèles de chat. Plusieurs instances peuvent tourner (une par GPU), avec round-robin transparent côté passerelle. Si l'administrateur n'a configuré aucun reranker, la requête renvoie 503.

Paramètres requête#params

Champ	Description
model string requis	Identifiant du modèle de reranking : <code>3gk-rerank</code> (alias stable, découplé du modèle sous-jacent). ex. "3gk-rerank"
query string requis	La requête de référence. Le reranker note chaque document selon sa pertinence vis-à-vis de cette requête.
documents string[] requis	Les passages à re-noter (max 2048 entrées). Des objets <code>{ "text": "…" }</code> sont aussi acceptés à la place des chaînes brutes.
top_n integer · > 0	Ne renvoyer que les <code>N</code> meilleurs résultats. Par défaut, tous les documents sont renvoyés, triés par pertinence décroissante.
return_documents boolean défaut false	Réinclure le texte de chaque document dans la réponse, sous <code>document.text</code>. Pratique pour éviter de remapper les <code>index</code> côté client.

Lots de documents. Le champ documents accepte jusqu'à 2048 passages en un seul appel. Chaque résultat est identifié par son index, qui réfère à la position dans le tableau documents d'entrée — pensez à conserver ce mapping côté client, ou activez return_documents.

Exemples#exemples

shell

curl https://ai.3gks.cloud/v1/rerank \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-3gk-7XQp4kL8…" \
  -d '{
    "model": "3gk-rerank",
    "query": "Quelle est la franchise en cas de sinistre ?",
    "documents": [
      "La franchise s'\''élève à 300 € par sinistre.",
      "Le contrat couvre la responsabilité civile.",
      "Aucune franchise ne s'\''applique aux dégâts des eaux."
    ],
    "top_n": 2
  }'

Format de réponse#response

Réponse JSON à la forme Cohere / Jina / vLLM : un tableau results trié par relevance_score décroissant. Chaque entrée porte l'index du document dans le tableau d'entrée et son score de pertinence (entre 0 et 1). Le champ usage indique le nombre de tokens consommés.

application/json

{
  "id": "rerank-9f2c…",
  "model": "3gk-rerank",
  "results": [
    { "index": 0, "relevance_score": 0.984 },
    { "index": 2, "relevance_score": 0.512 }
  ],
  "usage": {
    "total_tokens": 287
  }
}

Avec return_documents: true, chaque résultat réinclut le texte source sous document.text — utile pour reconstruire le contexte sans remapper les index :

application/json

{
  "id": "rerank-9f2c…",
  "model": "3gk-rerank",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.984,
      "document": { "text": "La franchise s'élève à 300 € par sinistre." }
    }
  ],
  "usage": { "total_tokens": 287 }
}

Codes de réponse#status

200 OK

Succès · La réponse JSON contient le tableau results, trié par relevance_score décroissant.

400

invalid_request · Corps invalide : query ou documents manquant, format incorrect, ou plus de 2048 documents.

400

model_not_supported · L'identifiant demandé n'est pas un modèle de reranking. Utilisez 3gk-rerank.

401

auth_error · Clé absente, mal formée, révoquée ou compte suspendu.

502

upstream_error · L'instance vLLM de reranking a renvoyé une erreur, un JSON invalide ou est injoignable.

503

upstream_error · Aucun modèle de reranking n'est configuré côté admin.

Mêmes conventions que Embeddings. Pour le détail du format d'erreur et des stratégies de retry, voir Codes d'erreur.

← Embeddings Models →