Pour une équipe en Chine qui intègre une API Embedding, la difficulté ne vient généralement pas du SDK. Ce qui consume du temps, c'est la stabilité de la liaison, le mode de paiement, l'établissement des factures, et la conduite à tenir quand une vectorisation par lots de plusieurs centaines de milliers de textes échoue à mi-parcours. Les requêtes Embedding sont courtes, à forte concurrence et en grand volume : la logique de choix diffère de celle d'une API de chat.

Cet article compare trois routes courantes — accès direct à l'éditeur, proxy auto-hébergé et passerelle IA locale — et détaille la conception de la fiabilité des tâches par lots, les limites de la bascule et la liste de vérification avant mise en production. Les modèles, dimensions et tarifs de référence sont ceux de la page Tarifs des modèles.

Remarque : OpenAI et les autres noms de modèles et de services sont des marques de leurs détenteurs respectifs ; cet article n'a aucun lien de rattachement avec les fournisseurs cités. Les réseaux transfrontaliers, les transferts de données hors du territoire et les règlements doivent respecter la législation locale et les conditions des plateformes ; consultez les services juridiques et conformité avant toute mise en œuvre.

1. Les trois routes, posées clairement

Accès direct à l'éditeur : appel direct à l'interface du fournisseur de modèles. La liaison est la plus courte, la documentation et les fonctionnalités sont synchronisées rapidement ; cette voie convient aux équipes disposant déjà d'un réseau transfrontalier, d'un moyen de paiement à l'étranger et d'un circuit de remboursement. En contrepartie, la qualité réseau, la facture en dollars, le change et les justificatifs restent à votre charge.

Proxy auto-hébergé : déploiement d'un reverse proxy ou d'une passerelle sur un serveur conforme, qui centralise authentification, journaux, reprises et limitation de débit. Le contrôle est fort, mais serveurs, certificats, mises à jour et astreinte sont à votre charge ; monté uniquement pour simplifier, son coût d'exploitation dépasse souvent les prévisions.

Passerelle IA locale : point d'entrée compatible OpenAI, règlement en yuan, généralement avec console, statistiques d'usage et facturation. Le coût d'intégration est faible et plusieurs modèles sont unifiés ; vérifiez l'entité de service, les clauses de données, les règles de quota et la réponse aux incidents.

Critère Accès direct Proxy auto-hébergé Passerelle IA locale
Réseau et accès Dépend de la liaison transfrontalière, à optimiser Ligne au choix, exploitation interne Point d'entrée local, généralement prêt à l'emploi
Paiement et facture Règlement en dollars, circuit de remboursement long Selon le compte et l'entité du serveur Règlement en yuan, facture possible
Débit par lots Limité par le compte File possible, mais limite amont Selon quotas et ordonnancement de la passerelle
Périmètre des données Évaluation des transferts et conditions Emplacement des données sous votre responsabilité Conditions et qualifications à auditer
Coût d'exploitation Moyen, surtout réseau et comptes Élevé : serveurs, certificats, supervision Faible, gestion centralisée dans la console
Couverture des modèles Principalement un éditeur Extensible Généralement plusieurs éditeurs

Aucune route ne convient à toutes les équipes. Si vous n'utilisez qu'un modèle et que réseau et paiement fonctionnent, l'accès direct est le plus simple ; si vous avez besoin d'une sortie fixe et d'un audit, choisissez le proxy interne ; sans personnel d'exploitation et avec besoin de facturation unifiée multi-modèles, évaluez la passerelle locale.

2. Tests réseau : pour Embedding, regarder le débit, pas seulement la latence

Une API de chat se juge sur la latence du premier token ; une API Embedding sur le débit par lots et la stabilité. Une requête peut contenir des dizaines ou des centaines de textes et renvoyer des centaines ou des milliers de nombres flottants : les problèmes de liaison se manifestent par des délais dépassés, des troncatures et des 5xx.

Ne testez pas avec un simple « bonjour ». Utilisez des fragments de documents de longueur réelle et assemblez les requêtes aux tailles de production, en observant au moins quatre éléments : durée par lot, latence P50/P95, taux d'erreur et comportement aux heures de pointe. Vérifiez aussi la limite de taille du corps, la réutilisation des connexions et les délais configurés sur le proxy ou la passerelle ; quand une grosse requête est tronquée par une couche intermédiaire, le message d'erreur est rarement explicite.

Les tâches longues doivent pouvoir reprendre après interruption. Numérotez les entrées par hachage du contenu, enregistrez chaque lot réussi sur disque et ne relancez que les parties manquantes, sans repartir de toute la base.

3. Paiement, contrat et facture

Le point de blocage courant pour une équipe en Chine est l'entité de paiement. Une recharge par carte personnelle, un paiement pour compte de tiers et des justificatifs incohérents empêchent souvent la comptabilité d'enregistrer la dépense. Avant de choisir, demandez : avec qui le contrat est-il signé, quelle est la devise de règlement, quel type de facture est disponible, le prépaiement a-t-il une durée de validité, quelles sont les règles de remboursement.

Pour la facturation à l'usage, vérifiez aussi la base de calcul : tokens d'entrée ou nombre de requêtes, prise en compte des échecs, double facturation éventuelle des reprises, ventilation de l'usage par projet ou par clé. Inscrivez ces points dans le tableau comparatif d'achat et testez avec les mêmes données pour obtenir le coût réel. Les tarifs de référence sont ceux de la page Tarifs des modèles et du contrat.

4. Concevoir la fiabilité des tâches par lots

La vectorisation est généralement un traitement hors ligne ; le pire scénario est un échec à 80 % sans possibilité de reprise. Concevez dans cet ordre :

  1. Générez un hachage du contenu de chaque texte comme clé d'idempotence ; une soumission répétée écrase sans dupliquer.
  2. Découpez d'abord selon une estimation en tokens, en respectant trois limites : nombre d'éléments par requête, longueur d'une entrée et total de tokens.
  3. Augmentez la concurrence progressivement en observant la proportion de 429, sans ouvrir tous les slots d'emblée.
  4. Appliquez un backoff exponentiel avec gigue sur les 429 et 5xx, avec un nombre maximal de tentatives.
  5. Après chaque lot, enregistrez le nombre de succès, les tokens consommés et la durée ; conservez à part les échantillons en échec.
  6. Avant l'indexation, validez dimension, vecteurs vides et NaN ; isolez les données anormales au lieu de les écrire silencieusement.
  7. À la fin, comparez par échantillonnage le nombre d'éléments, les dimensions et les statistiques d'index.

Ce processus est simple, mais il évite le scénario « tout semble terminé alors qu'un lot manque ».

5. Limitation, reprises et bascule

L'interface Embedding limite généralement selon deux axes : nombre de requêtes et tokens. Une limitation renvoie un 429 ; une passerelle surchargée peut produire des 5xx ou des délais dépassés. La stratégie de reprise doit distinguer les types d'erreur : 429 et 5xx transitoires peuvent être réessayés avec backoff ; 401, 403 et erreurs de paramètre ne servent à rien à réessayer, il faut corriger la configuration.

import os
import time
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url=os.environ["ZSQH_BASE_URL"],
    timeout=60.0,
    max_retries=0,
)

def embed_batch(texts, model, attempts=4):
    for i in range(attempts):
        try:
            resp = client.embeddings.create(model=model, input=texts)
            vectors = [item.embedding for item in resp.data]
            dims = {len(v) for v in vectors}
            if len(dims) != 1 or len(vectors) != len(texts):
                raise ValueError("Dimensions ou nombre d'éléments incohérents")
            return vectors, resp.usage
        except Exception as exc:
            if i == attempts - 1:
                raise
            wait = min(2 ** i, 30) + 0.5 * (i + 1)
            print(type(exc).__name__, "nouvelle tentative dans", wait)
            time.sleep(wait)

vectors, usage = embed_batch(
    ["Premier texte", "Deuxième texte"],
    os.environ["EMBEDDING_MODEL"],
)
print(len(vectors), len(vectors[0]), usage)

La bascule comporte une limite souvent négligée : les vecteurs de modèles d'embedding différents ne peuvent pas être mélangés. Même à dimensions égales, les espaces vectoriels diffèrent ; écrire les vecteurs de deux modèles dans le même index dégrade nettement la recherche. Lors d'un changement d'amont, vérifiez donc en priorité qu'il s'agit du même modèle et de la même version ; s'il faut réellement changer de modèle, créez un nouvel index, recalculez tout et comparez avant de basculer, plutôt que de modifier le nom du modèle dans l'urgence.

6. Liste de vérification avant mise en production

  • Dimension : cohérente avec la configuration de l'index, nombre d'éléments renvoyés identique à l'entrée.
  • Référence : sur un jeu de textes fixe, comparer la similarité cosinus avec le résultat en accès direct ; elle doit être très proche.
  • Usage : le champ usage des réponses correspond-il à la facture, lot par lot.
  • Limitation : plafond de concurrence, proportion de 429 et taux de succès après reprise acceptables.
  • Délais : le plus gros lot passe-t-il dans le délai imparti aux heures de pointe.
  • Données : les entrées contiennent-elles des données personnelles ; les politiques de conservation, de journalisation et de suppression du fournisseur sont-elles claires.
  • Sortie : la clé peut-elle être renouvelée, le solde remboursé, l'ancien index et la voie de repli conservés.

Si un point reste flou, testez d'abord à faible volume ; ne migrez pas directement l'index de production.

7. Choisir selon les contraintes

Examinez d'abord la stabilité durable du réseau et du paiement, puis le besoin d'une sortie fixe et d'un audit, enfin la couverture des modèles et les capacités de facturation. Pour un point d'entrée unifié, un règlement en yuan et une comparaison multi-modèles, créez une clé de test sur ZSQH AI Gateway, validez avec un petit lot de données, puis augmentez progressivement le volume ; les modèles disponibles et la facturation figurent sur la page Tarifs des modèles.

Pour aller plus loin :

Questions fréquentes

Quelle différence entre les solutions d'accès pour Embedding et pour le chat ?

Une API de chat privilégie la latence du premier token et la stabilité du flux ; Embedding fonctionne par lots, avec des réponses courtes et un volume élevé, et privilégie le débit, les plafonds par requête et la reprise après échec. Intégrez tests de charge par lots et reprise après interruption dans votre choix.

L'accès direct à l'API Embedding depuis la Chine est-il stable ?

Cela dépend de la sortie locale, de l'heure et des quotas du compte ; on ne peut pas généraliser. Observez dans la durée avec des lots et une concurrence réels, en notant taux d'erreur et latence P95, puis comparez avec une passerelle. Ne concluez pas sur une seule requête réussie.

Que faire si une vectorisation par lots est interrompue ?

Utilisez un hachage du contenu comme clé d'idempotence, enregistrez lot par lot et ne complétez que les parties manquantes. Avant de relancer, vérifiez le nombre d'éléments déjà indexés et leur dimension, pour éviter les doublons ou de prendre un demi-lot pour un résultat complet.

Les anciens vecteurs restent-ils utilisables après un changement de passerelle ?

Avec le même modèle et la même version, généralement oui ; avec un autre modèle, la reconstruction de l'index est obligatoire. Avant la migration, comparez la similarité cosinus des anciens et nouveaux vecteurs sur un échantillon fixe et conservez l'ancien index comme repli.

Peut-on ventiler factures et usage par projet ?

Cela dépend du fournisseur. Avant de signer, vérifiez l'export de l'usage par projet, clé ou modèle, si la base de facturation inclut les échecs et reprises, et si le contenu de la facture répond aux exigences d'achat.