Sur la plupart des plateformes, la clé d'une API Embedding ne diffère pas de celle d'un modèle de conversation : c'est un simple justificatif d'identité, et ce sont les droits du compte et le paramètre model de la requête qui déterminent réellement ce que vous pouvez appeler. Mais les tâches de vectorisation tournent souvent en arrière-plan, par lots sur de nombreux documents : une clé divulguée ou mal configurée entraîne des pertes et un coût de diagnostic non négligeables.

Cet article suit un ordre précis : où s'inscrire, que renseigner à la création, comment répartir les permissions, où stocker les variables d'environnement, comment diagnostiquer un 401, comment choisir entre clé de l'éditeur et clé de passerelle, puis la rotation et le traitement d'une fuite.

Remarque : OpenAI et les marques citées sont des marques de leurs détenteurs respectifs. Cet article a une vocation technique et n'a aucun lien de rattachement avec les fournisseurs mentionnés ; interfaces, permissions et prix sont ceux de la documentation de chaque plateforme et des pages du site.

1. Vérifier d'abord : une clé distincte est-elle nécessaire pour Embedding ?

La plupart des plateformes compatibles OpenAI utilisent la même authentification : une même clé appelle à la fois /v1/chat/completions et /v1/embeddings. La disponibilité dépend du solde du compte, des droits sur le modèle et de la politique de la plateforme, non du type de clé.

Quelques plateformes facturent ou autorisent le service vectoriel séparément. Avant de créer la clé, vérifiez trois points dans la console :

  • le forfait ou le solde actuel couvre-t-il le modèle d'embedding ;
  • la clé est-elle soumise à une liste blanche de modèles ou à un périmètre de projet ;
  • embedding et chat partagent-ils le même quota.

Si la console n'offre pas de permissions fines, isolez par le principe « une clé par usage », ne serait-ce que pour pouvoir limiter le quota et désactiver séparément.

2. Inscription et accès à la console

Prenons l'exemple de ZSQH AI Gateway :

  1. Ouvrez https://ai.zhongshangqihang.com, inscrivez-vous par e-mail et validez votre adresse.
  2. Après connexion, accédez à la console et ouvrez la page « Clés API ».
  3. Dans la page « Portefeuille » ou « Recharge », vérifiez le solde ; un petit montant suffit pour la phase de test.
  4. Ouvrez le « Journal d'usage » et vérifiez que les modèles, les tokens et les frais sont visibles.

L'inscription est aussi accessible par le lien d'inscription. Si vous voulez seulement valider l'interface sans recharger tout de suite, créez une clé de test à faible quota et ajustez ensuite.

3. Que renseigner à la création de la clé

Après avoir cliqué sur « Nouvelle clé », vous voyez généralement les champs suivants :

  1. Nom : indiquez l'usage et l'environnement, par exemple rag-prod-backend ou embedding-batch-dev. Évitez les noms du type « test1 ».
  2. Plafond de quota : commencez bas, puis augmentez après avoir constaté la consommation réelle des tâches par lots.
  3. Date d'expiration : 7 ou 30 jours pour un script temporaire ; même une clé de production doit avoir un cycle de rotation fixe.
  4. Périmètre de modèle ou de projet : si la plateforme le permet, ne cochez que le modèle d'embedding et les projets nécessaires.
  5. Enregistrer et copier : la clé complète n'est généralement affichée qu'une fois ; sans sauvegarde, il faut la supprimer et la recréer.

Les clés commencent souvent par sk-, mais ce préfixe ne prouve pas leur authenticité. À la copie, vérifiez l'absence d'espaces en début ou en fin et de saut de ligne : c'est l'une des causes fréquentes de 401.

4. Concevoir les permissions et les quotas

Les tâches de vectorisation se caractérisent par « beaucoup de lectures, peu d'écritures, des lots et des reprises fréquentes ». L'objectif des permissions n'est pas de se protéger d'une attaque externe, mais d'éviter qu'une seule clé n'affecte tous les environnements.

Contexte Nom de clé Quota Emplacement Rotation
Développement local emb-dev-nom Minimal .env local 30 jours
Environnement de test emb-staging Faible Secrets CI/CD 60 jours
Lots de production emb-prod-batch Selon budget Gestionnaire de secrets 90 jours
Requêtes de production emb-prod-query Selon budget Gestionnaire de secrets 90 jours

Quelques principes :

  • Séparer développement et production : une fuite de clé de test n'affecte pas la facture de production.
  • Séparer lots et requêtes : les tâches par lots sont sujettes aux reprises ; un quota distinct facilite l'identification d'une consommation anormale.
  • Moindre privilège : si seul embedding est nécessaire, n'ouvrez pas les modèles de chat ; si un projet peut être limité, ne donnez pas de droit au niveau du compte.
  • Jamais dans le front-end : une clé présente dans un navigateur, une application ou un mini-programme sera extraite ; les requêtes de vectorisation doivent passer par votre propre backend.
  • Pas de clé personnelle partagée : au départ d'un collègue ou en cas de perte d'appareil, une clé partagée ne peut pas être désactivée isolément.

5. Placer la clé dans une variable d'environnement

Ne l'inscrivez pas en dur dans le code. Un projet Python peut la lire ainsi :

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.embeddings.create(
    model="text-embedding-3-small",
    input=["Premier texte", "Deuxième texte"],
)
print(len(resp.data[0].embedding))

En local, avec un fichier .env, ajoutez ce fichier au .gitignore et ne versionnez que .env.example. En production, privilégiez les secrets de conteneur, la gestion de clés du fournisseur cloud ou un service comme Vault ; n'écrivez pas la clé dans un Dockerfile, une couche d'image, un artefact de build front-end ou un journal CI.

Autre point : après modification d'une variable d'environnement, redémarrez le processus. Beaucoup de cas « 401 en ligne, tout va bien en local » viennent d'un service qui lit encore l'ancienne variable, ou d'une plateforme de déploiement qui ne l'a pas injectée dans l'environnement d'exécution.

6. Ordre de diagnostic d'une erreur 401

En cas d'erreur 401 d'authentification, suivez cet ordre ; le diagnostic prend généralement quelques minutes :

  1. Vérifiez que l'en-tête est bien Authorization: Bearer sk-..., avec un seul espace entre Bearer et la clé.
  2. Recopiez la clé et vérifiez l'absence d'espace, de saut de ligne, de guillemet ou de caractère invisible.
  3. Confirmez que la clé n'a pas été supprimée, désactivée ou expirée.
  4. Vérifiez que la clé appartient bien à la plateforme correspondant au Base URL ; n'envoyez pas une clé de la plateforme A vers la plateforme B.
  5. Confirmez que le processus lit réellement la variable d'environnement, et non une chaîne vide.
  6. Vérifiez si un reverse proxy, une passerelle ou le SDK réécrit l'en-tête Authorization.
  7. Si seules certaines requêtes échouent, vérifiez si une clé exposée dans du code front-end a été désactivée par le contrôle des risques.

Précision utile : 401 est un problème d'identité, 403 relève le plus souvent des permissions ou d'une restriction géographique, 429 des limites de fréquence ou de quota. N'imputez pas tous les échecs à la clé.

7. Clé de l'éditeur ou clé de passerelle

Les deux voies fonctionnent ; la différence porte surtout sur l'achat, le réseau et la maintenance :

  • Accès direct à l'éditeur : compte, facture et modèles sont gérés par l'éditeur, ce qui convient aux équipes capables de payer à l'étranger et de gérer elles-mêmes réseau et conformité. Inconvénient : les modèles sont répartis entre plusieurs plateformes, tout comme les clés et le rapprochement.
  • Accès par passerelle : un seul Base URL et une seule clé pour plusieurs modèles, un accès plus simple depuis la Chine et un règlement en yuan, avec journaux et quotas centralisés. En contrepartie, une dépendance supplémentaire : vérifiez la politique de données, la disponibilité et le traitement des incidents du fournisseur.

Ne choisissez pas uniquement sur le prix. Vérifiez au minimum : conservation des données, facturation, mode de notification en cas d'incident, annonce préalable des fins de modèle et export des relevés d'usage. Les modèles et prix applicables sont ceux affichés sur la page Tarifs des modèles ; les prix évoluent, ne budgétez pas sur des chiffres d'anciens articles.

8. Rotation et traitement d'une fuite

Faites de la rotation une opération planifiée, et non une réaction à un incident :

  1. Créez sur la plateforme d'origine une nouvelle clé aux mêmes permissions.
  2. Mettez à jour la variable d'environnement ou la valeur dans le gestionnaire de secrets.
  3. Redémarrez ou redéployez le service, puis appelez une fois l'interface embedding pour confirmer.
  4. Surveillez le journal d'usage pendant 24 à 48 heures pour détecter toute anomalie.
  5. Supprimez l'ancienne clé et consignez la date de rotation.

En cas de fuite suspectée, inversez l'ordre : désactivez d'abord l'ancienne clé, examinez ensuite le journal d'usage et l'historique du dépôt, puis seulement créez la nouvelle clé. Supprimer la chaîne du code ne suffit pas : la clé a pu passer dans des journaux CI, une couche d'image ou un cache tiers.

Questions fréquentes

Une clé distincte est-elle obligatoire pour Embedding ?

Pas nécessairement. La plupart des plateformes compatibles OpenAI permettent à une même clé d'appeler embedding et chat. La création d'une clé distincte dépend du besoin de quotas séparés, d'audit séparé ou de désactivation isolée.

Peut-on revoir la clé complète après sa création ?

En général non. La clé complète n'est affichée qu'à la création, puis seul le préfixe ou un masque est conservé. Si vous ne l'avez pas sauvegardée, supprimez-la et recréez-la ; ne cherchez pas à la retrouver dans les journaux.

Une clé peut-elle appeler plusieurs modèles d'embedding ?

Généralement oui : le modèle est indiqué dans le champ model de la requête. Les modèles disponibles et leurs dimensions sont ceux de la documentation de la plateforme et de la page Tarifs des modèles.

curl fonctionne en local, mais la production renvoie 401 : pourquoi ?

Vérifiez en priorité trois choses : la variable d'environnement est-elle injectée en production, le reverse proxy conserve-t-il l'en-tête Authorization, et une autre clé supprimée ou expirée est-elle utilisée en ligne. Vérifiez ensuite si le Base URL pointe vers la mauvaise plateforme.

Supprimer la clé suffit-il après une fuite ?

Non. Désactivez d'abord la clé, consultez le journal d'usage pour détecter des appels anormaux, examinez le dépôt de code, les journaux CI et l'historique des images, puis renouvelez toutes les clés potentiellement concernées. Si la clé portait un solde, évaluez aussi l'ajustement des quotas.

Pour aller plus loin

Si vous n'avez pas encore de compte, commencez par la page d'inscription, créez une clé à faible quota et validez /v1/embeddings avec un seul texte. Consultez ensuite la page Tarifs des modèles pour choisir le modèle de production. Pour le processus de vectorisation lui-même, poursuivez avec les guides ci-dessous.

Pour aller plus loin :