Une clé API Rerank ressemble à une clé de conversation ordinaire, mais le risque est plus élevé : chaque requête transporte la question de l'utilisateur et le texte d'un lot de documents candidats, et la facturation suit le volume d'appels. Si la clé fuit, un tiers peut consommer votre solde et faire apparaître de nombreuses requêtes inconnues sur votre facture.
Cet article présente deux voies d'obtention : la plateforme du fournisseur et une passerelle IA locale ; puis la configuration des permissions et quotas à la création, l'écriture des variables d'environnement, le diagnostic des 401 et la procédure de rotation. Le périmètre des modèles et les prix de référence figurent dans les tarifs des modèles.
Remarque : Cohere, Jina AI, Alibaba Cloud, SiliconFlow, Volcengine et les autres noms cités appartiennent à leurs détenteurs respectifs et ne servent ici qu'à la description technique. ZSQH AI Gateway n'a aucun lien de subordination avec ces fournisseurs ; les interfaces et modèles applicables sont ceux décrits sur le site.
1. Différence entre une clé Rerank et une clé de conversation
Une clé de conversation appelle un modèle de génération : l'entrée est un message, la sortie est du texte. Une clé Rerank appelle un modèle de reranking : l'entrée est une requête plus un lot de documents candidats, la sortie est un score de pertinence et un classement par document.
Trois différences principales :
- Données plus sensibles : les documents candidats viennent souvent de la base de connaissances interne et peuvent contenir des contrats, des règles internes ou des données clients.
- Facturation différente : elle se fait généralement sur les tokens de la requête et des documents ; les documents longs et les lots volumineux amplifient la consommation.
- Permissions plus étroites : beaucoup de plateformes permettent de limiter une clé à certains modèles ; n'ouvrir que le modèle rerank réduit le risque de mauvaise utilisation.
Ne mélangez donc pas une clé rerank et une clé de conversation, et n'envoyez pas la même clé à plusieurs projets. La granularité correcte est « environnement + projet ».
2. Voie A : passer par la plateforme du fournisseur
Cohere, Jina AI, Alibaba Cloud Bailian, SiliconFlow, Volcengine et d'autres proposent des services de reranking. Les points d'entrée et les champs diffèrent, mais la procédure est similaire :
- Choisir la plateforme : vérifier d'abord les langues prises en charge, la longueur maximale des documents, la gestion du chinois et la localisation des données.
- Créer un compte : les plateformes locales demandent souvent un numéro de téléphone ou une vérification d'entreprise ; les plateformes étrangères demandent un e-mail et un moyen de paiement.
- Activer le service : trouver le service Rerank ou reranking dans la console et confirmer que le modèle visé est activé.
- Créer une clé : ouvrir la page API Keys, créer une clé et la nommer selon le schéma « projet-environnement », par exemple
rag-prod. - Poser des limites : quota si disponible, date d'expiration si disponible, et restriction au seul modèle rerank si l'option existe.
- Tester immédiatement : après avoir copié la clé, lancer une requête minimale pour vérifier l'authentification, le nom du modèle et la structure de réponse.
Les en-têtes d'authentification ne sont pas identiques partout. Cohere et Jina utilisent couramment Authorization: Bearer <key> ; certaines plateformes locales ont leur propre schéma de signature. Ne reconstruisez pas l'en-tête de mémoire : recopiez la documentation actuelle du fournisseur.
3. Voie B : passer par ZSQH AI Gateway
Si l'équipe n'a pas de moyen de paiement international, ou souhaite regrouper la facturation de plusieurs modèles, la passerelle est une option :
- Ouvrir ZSQH AI Gateway et terminer l'inscription.
- Aller dans la page « Clés API » de la console et créer une clé.
- Renseigner un nom, choisir le projet ou le groupe, fixer le quota et la date d'expiration.
- Recharger le portefeuille et vérifier que le solde suffit au test.
- Copier la clé, la ranger dans un gestionnaire de mots de passe, ne pas la laisser dans l'historique de discussion.
La passerelle expose le reranking via POST /v1/rerank, avec compatibilité /rerank ; l'URL de base est https://ai.zhongshangqihang.com/v1. Attention : Rerank ne fait pas partie de la spécification Chat Completions d'OpenAI ; c'est un point d'entrée distinct, et les méthodes SDK prévues pour le chat ne s'appliquent pas directement.
| Critère | Plateforme du fournisseur | ZSQH AI Gateway |
|---|---|---|
| Inscription et paiement | Plateformes étrangères : carte en devise ; plateformes locales : vérification d'identité | Inscription et recharge locales, modalités selon la page de règlement |
| Réseau | Points d'entrée étrangers parfois instables | Accès direct local, moins de diagnostic réseau |
| Périmètre de modèles | Uniquement les modèles du fournisseur | Point d'entrée unifié multi-amont, selon la liste de modèles |
| Facturation | Rapprochement séparé par fournisseur | Facture consolidée multi-modèles, plus simple à rembourser |
| Chemin des données | Requête directe au fournisseur | Transit par la passerelle, clauses de traitement à vérifier |
| Public visé | Fournisseur unique, besoin de support éditeur | Multi-modèles, équipes locales, exploitation unifiée |
Les deux voies peuvent coexister. Il est courant de garder un compte fournisseur en secours pour la production et de faire passer les équipes locales et les tests par la passerelle. Avant de choisir, vérifiez l'entité contractuelle, le type de facture et les clauses de données.
4. Quatre réglages de sécurité à la création
Obtenir la clé n'est que le début ; les réglages de création déterminent l'étendue des dégâts en cas d'incident.
Premier : séparer par environnement. Une clé pour le développement, une pour les tests, une pour la production, avec projet et date dans le nom. Le rapprochement de facture identifie alors la source, et une fuite n'impose que la suspension d'une clé.
Deuxième : fixer un quota. Donnez à chaque clé un quota journalier ou mensuel, avec au moins un seuil d'alerte. La consommation Rerank dépend directement du nombre et de la longueur des documents ; une boucle de script peut générer beaucoup d'appels en peu de temps.
Troisième : fixer une expiration. Une clé de test doit expirer vite ; les clés de production suivent la politique de l'équipe. Pour une clé ouverte temporairement à un prestataire ou partenaire, l'expiration automatique est plus fiable qu'une récupération manuelle.
Quatrième : moindre privilège. Si la plateforme gère le périmètre de modèles, une liste d'IP ou des groupes de projets, n'ouvrez que le modèle rerank et les adresses sources nécessaires. N'accordez pas tous les modèles par commodité.
5. Variables d'environnement et lecture dans le code
La clé ne doit exister que dans les variables d'environnement du serveur ou dans un service de gestion de secrets ; jamais dans le dépôt de code, jamais dans un bundle front-end. Configuration minimale :
RERANK_API_KEY=sk-votre-cle
RERANK_BASE_URL=https://ai.zhongshangqihang.com/v1
Ajoutez .env au .gitignore et injectez les valeurs via le panneau de variables d'environnement de la plateforme de déploiement. Lecture en Python :
import os
import requests
api_key = os.environ["RERANK_API_KEY"]
base_url = os.environ.get("RERANK_BASE_URL", "https://ai.zhongshangqihang.com/v1")
resp = requests.post(
f"{base_url}/rerank",
headers={"Authorization": f"Bearer {api_key}"},
json={
"model": "nom-de-votre-modele-rerank",
"query": "Quelle est la durée de la période d'essai ?",
"documents": ["La période d'essai est de 14 jours.", "Le virement d'entreprise est accepté."],
"top_n": 2,
},
timeout=20,
)
resp.raise_for_status()
print(resp.json()["results"])
Le nom du modèle de référence figure sur la page des tarifs des modèles. Si l'équipe utilise un gestionnaire de secrets, stockez la clé chiffrée et injectez-la à l'exécution ; ne l'imprimez jamais dans les logs. Pour diagnostiquer, imprimez l'ID de requête et le code de statut, jamais l'en-tête Authorization complet.
6. Diagnostic 401 : distinguer authentification et permissions
401 signifie que l'identité n'est pas reconnue ; 403 signifie que l'identité est reconnue mais n'a pas les droits. Beaucoup de passerelles unifient les deux dans une même structure d'erreur : lisez le corps de réponse et le code d'erreur, pas seulement le statut HTTP.
| Symptôme | Cause fréquente | Traitement |
|---|---|---|
| 401 Unauthorized | Clé mal copiée, espace avant/après, copie tronquée | Recopier et vérifier l'absence de saut de ligne |
| 401 invalid token | Clé supprimée, expirée ou appartenant à un autre projet | Vérifier l'état dans la console et recréer |
| 401 alors que la clé semble correcte | Mauvais champ d'en-tête ou URL de base pointant vers un autre service | Vérifier Authorization et le chemin dans la documentation |
| 403 Forbidden | Clé sans droit sur ce modèle, ou compte gelé | Contrôler le périmètre de modèles et l'état du compte |
| 404 Not Found | Nom de modèle ou chemin de point d'entrée erroné | Vérifier /v1/rerank et la liste des modèles |
| 429 Too Many Requests | Concurrence trop élevée ou quota atteint | Retry avec backoff exponentiel, vérifier quota et débit |
Fixez un ordre de diagnostic : URL et en-têtes, puis état de la clé, puis nom du modèle, enfin solde et limitation de débit. Transformez ces quatre étapes en checklist ; c'est plus rapide que de procéder au hasard.
7. Rotation et gestion d'une fuite
La rotation ne se fait pas seulement après incident. Prévoyez un cycle régulier, et agissez immédiatement en cas de départ d'un collaborateur, de commit accidentel ou d'apparition d'une clé complète dans les logs.
- Créer une nouvelle clé dans la console, avec la date de rotation dans le nom.
- L'écrire d'abord dans l'environnement de test et lancer une requête minimale.
- Mettre à jour la variable de production et redémarrer le service en surveillant erreurs et volume.
- Une fois l'ancienne clé sans trafic, la désactiver ou la supprimer.
- Consulter les logs récents pour détecter une source inconnue ou un pic anormal.
- Noter la date de rotation et inscrire la suivante dans le calendrier de l'équipe.
En cas de suspicion de fuite, désactivez d'abord l'ancienne clé, puis examinez facture et logs ; ne supprimez pas les logs en premier. Conserver les preuves aide à évaluer l'étendue. Après rotation, vérifiez l'historique du dépôt, les variables CI et les historiques de discussion pour trouver d'autres copies.
8. Questions fréquentes
Une clé API Rerank peut-elle appeler un modèle de conversation ?
Cela dépend des droits accordés par la plateforme. Même si c'est techniquement possible, ce n'est pas recommandé. Une clé de reranking doit servir uniquement au point d'entrée rerank, pour éviter qu'une même clé porte à la fois la facture de génération et celle de recherche.
Peut-on placer la clé dans le front-end ou une mini-application ?
Non. Le code front-end et les requêtes réseau sont visibles par l'utilisateur : la clé serait publique. La bonne pratique est un appel du front-end vers votre propre back-end, qui détient la clé et relaie la requête.
Quelle différence entre 401 et 403 ?
401 est un échec d'authentification : clé invalide, expirée ou en-tête incorrect. 403 est un manque de droits : la clé peut être valide mais n'a pas accès à ce modèle ou à ce projet. Lisez d'abord le code et le message du corps de réponse.
Une clé peut-elle être partagée entre plusieurs projets ?
Techniquement, souvent oui ; opérationnellement, non. Une clé partagée rend la facture impossible à ventiler et élargit l'impact d'une fuite. Séparez au minimum par environnement et par projet.
À quelle fréquence faire tourner une clé ?
Selon la politique de sécurité de l'équipe. La pratique courante est une rotation régulière, plus une rotation immédiate en cas de changement de personnel, de suspicion de fuite ou de commit accidentel. Il n'existe pas de fréquence universelle ; l'essentiel est que la procédure soit applicable.
