API Open AI Embeddings : créer et vérifier une recherche sémantique

Vous recherchez l’API Open AI embeddings ? Le point de terminaison d’embeddings d’OpenAI convertit du texte en vecteurs numériques afin qu’une application puisse récupérer des passages associés. La requête n’est que la première étape : une fonctionnalité de recherche utile nécessite également des identifiants de document stables, un espace vectoriel cohérent et un test indiquant si la récupération s’est améliorée.

Ce guide crée un petit exemple de recherche en Python, montre quoi stocker avec chaque vecteur et vous propose une liste de contrôle pour faire passer l’expérimentation dans un produit. Il utilise OpenAI directement. La compatibilité des passerelles et la disponibilité des modèles doivent être vérifiées séparément pour chaque fournisseur.

API Open AI embeddings : la requête dont vous avez besoin

Envoyez du texte à POST https://api.openai.com/v1/embeddings avec un modèle d’embedding et une clé API. Choisissez encoding_format="float" lorsque votre application attend des tableaux numériques. Pour un lot, utilisez l’index de chaque élément de réponse afin de reconnecter le vecteur à son entrée. La réponse inclut également l’utilisation des jetons. L’option dimensions est prise en charge par les modèles d’embedding de troisième génération. Référence de l’API OpenAI.

Un embedding n’est pas une réponse générée. Dans une application augmentée par récupération, la recherche sélectionne d’abord les passages sources ; un appel de génération distinct peut ensuite répondre à l’aide de ces passages. Le fait de séparer les étapes vous permet de diagnostiquer un mauvais résultat : la recherche a-t-elle récupéré les mauvaises preuves, ou le modèle de réponse a-t-il mal exploité de bonnes preuves ?

Choisissez un modèle et conservez une configuration fixe

Les longueurs de vecteur documentées par défaut sont de 1 536 pour text-embedding-3-small et de 3 072 pour text-embedding-3-large. Ces modèles prennent en charge des vecteurs de sortie plus courts via dimensions. Un vecteur plus court modifie les compromis entre stockage et récupération ; ce n’est pas une raison pour ne pas effectuer d’évaluation. Guide des embeddings OpenAI.

Commencez avec une configuration et un petit ensemble de requêtes représentatives. Enregistrez le modèle, le nombre de dimensions demandé et la version de traitement du texte avec l’index. Le fait que deux vecteurs aient la même longueur ne permet pas d’établir qu’ils proviennent d’un modèle compatible. Lorsque vous modifiez des modèles ou des règles de traitement, créez un index distinct et comparez-le avant de basculer le trafic de production.

Un exemple minimal de recherche sémantique en Python

Installez openai dans votre environnement Python et rendez OPENAI_API_KEY disponible via votre gestionnaire de secrets habituel ou la configuration de l’environnement. Ne placez pas la clé dans le contrôle de version ni dans du code navigateur. Le SDK Python officiel lit cette variable lors de la construction de OpenAI().

Enregistrez ce qui suit sous search_demo.py. Il utilise trois documents de support fictifs, génère les embeddings du corpus et d’une requête, puis classe les documents selon la similarité cosinus. Son exécution effectue des requêtes API facturables. La sortie dépend de la réponse du service ; l’exemple ne garantit ni un score ni un classement particulier.

import math
from openai import OpenAI

client = OpenAI(timeout=30.0, max_retries=2)
model = "text-embedding-3-small"
dimensions = 1536

documents = [
    {"id": "key-rotation", "text": "Replace an exposed API key and revoke the old credential."},
    {"id": "invoice-export", "text": "Download a monthly invoice from the billing workspace."},
    {"id": "request-timeout", "text": "Record the request ID and retry temporary upstream timeouts."},
]
query = "What should I do after accidentally sharing a secret key?"


def embed(texts):
    response = client.embeddings.create(
        model=model, input=texts,
        dimensions=dimensions, encoding_format="float",
    )
    ordered = sorted(response.data, key=lambda item: item.index)
    if [item.index for item in ordered] != list(range(len(texts))):
        raise ValueError("Unexpected embedding response indices")
    vectors = [item.embedding for item in ordered]
    if any(len(vector) != dimensions for vector in vectors):
        raise ValueError("Unexpected vector dimensions")
    print("Input tokens:", response.usage.prompt_tokens)
    return vectors


def cosine(a, b):
    if len(a) != len(b):
        raise ValueError("Vector dimensions do not match")
    denominator = math.sqrt(sum(x*x for x in a) * sum(y*y for y in b))
    if not denominator:
        raise ValueError("Cannot compare a zero vector")
    return sum(x*y for x, y in zip(a, b)) / denominator


vectors = embed([document["text"] for document in documents])
query_vector = embed([query])[0]
ranked = sorted(
    ((cosine(query_vector, vector), document["id"])
     for document, vector in zip(documents, vectors)),
    reverse=True,
)
for score, document_id in ranked:
    print(document_id, round(score, 4))

Exécutez python search_demo.py. Vérifiez que les trois identifiants apparaissent chacun une fois et que chaque embedding a la longueur configurée. Modifiez ensuite la requête afin qu’elle porte sur les factures. Il s’agit d’un test de bon fonctionnement du flux de données, et non d’une preuve que le système est prêt pour un trafic réel d’assistance. Par souci de clarté, l’exemple génère à nouveau les embeddings du corpus à chaque exécution ; un service déployé devrait normalement conserver les vecteurs de document et ne générer les embeddings que du contenu nouveau ou modifié.

Transformez la démo en un index de documents fiable

La disposition d’enregistrement suivante constitue un point de départ pratique. Il s’agit d’un exemple de conception d’application, et non d’un schéma de champs exigé par OpenAI.

Découpez les documents à des limites pertinentes, puis vérifiez la longueur en tokens. Une section contenant la réponse à la question doit rester compréhensible lorsqu’elle est récupérée seule. Évaluez délibérément le chevauchement : un chevauchement excessif peut remplir l’ensemble de résultats de versions répétées du même passage.

Pour la première expérience, la boucle en mémoire ci-dessus suffit. À mesure que le corpus grandit, utilisez un index ou un magasin vectoriel prenant en charge le filtrage, la suppression et le comportement de récupération requis. Testez ces opérations avant de vous fier aux scores de similarité. Un passage très similaire provenant du mauvais client ne doit jamais être renvoyé simplement parce qu’il est classé premier.

Vérifiez séparément les limites d’entrée et de lot

La référence actuelle de l’endpoint OpenAI indique un maximum de 8 192 tokens par entrée et un maximum agrégé de 300 000 tokens sur les entrées d’une même requête ; elle documente également un maximum de 2 048 entrées par lot. Le texte vide n’est pas valide. Comptez les tokens plutôt que les caractères et gardez une marge sous les limites lors de la construction des lots. Contraintes de l’endpoint.

Si vous utilisez Azure OpenAI, la configuration de l’endpoint, l’authentification et la dénomination des déploiements nécessitent leur propre configuration. Suivez les instructions Azure relatives aux embeddings pour ce service au lieu de supposer qu’une requête OpenAI directe peut être copiée sans modification. Appliquez la même séparation lorsque vous utilisez une passerelle : vérifiez d’abord son endpoint, l’accès aux modèles, les paramètres pris en charge et le compte de facturation.

Estimez le coût sans masquer les reconstructions d’index

Le coût des embeddings dépend des tokens d’entrée ; comptez donc séparément l’ingestion des documents, les segments modifiés et les embeddings de requêtes. Utilisez le prix actuel indiqué sur la page du modèle concerné, par exemple text-embedding-3-small, et vérifiez si le tarif indiqué s’applique à votre mode de requête.

Pour un exemple de planification, soit P votre prix vérifié par million de tokens d’entrée :

Ingestion initiale : 50 000 segments × 400 tokens = 20 millions de tokens
Modifications mensuelles : 5 000 segments × 400 tokens =  2 millions de tokens
Requêtes mensuelles :  200 000 requêtes × 20 tokens =  4 millions de tokens

Coût initial des embeddings = 20 × P
Coût récurrent des embeddings = (2 + 4) × P = 6 × P

Il s’agit d’hypothèses de charge illustratives, et non des prix de Flatkey ou d’OpenAI. Ajoutez séparément le stockage vectoriel, l’infrastructure de recherche et les éventuels appels de génération de réponses. Si vous changez de modèle d’embedding, incluez une réintégration complète dans le budget de migration. Un pipeline qui réintègre des documents inchangés peut coûter plus cher que la même charge de travail avec un modèle plus grand mais correctement mis en cache.

Diagnostiquez les erreurs avant d’ajouter des tentatives

Les quatre premiers contrôles suivent le guide des erreurs d’OpenAI. Les deux derniers concernent votre application et votre index. Respectez les recommandations du serveur concernant les nouvelles tentatives et tenez compte des tentatives du SDK avant d’ajouter une autre boucle de tentatives. Consignez les métadonnées opérationnelles sans enregistrer d’identifiants ni de texte privé de document inutile.

Évaluez la récupération avant de choisir un modèle de réponse

Créez un petit ensemble étiqueté à partir de vraies questions d’utilisateurs, incluant des paraphrases, des noms de produits exacts, des questions ambiguës et des questions auxquelles votre corpus ne peut pas répondre. Notez le document source attendu pour chaque requête pouvant recevoir une réponse avant d’ajuster le système.

Pour chaque configuration candidate, consignez si une source acceptable apparaît parmi les premiers résultats, la quantité de contenu dupliqué renvoyée, la latence de récupération et le coût par requête. Examinez les échecs individuellement. Si une requête demande un code d’erreur exact, une correspondance par mot-clé peut compléter la similarité sémantique. Si la source est absente, modifier les dimensions des embeddings ne peut pas l’inventer.

Conservez une partie des questions à l’écart pour la comparaison finale. Ne choisissez pas un seuil de similarité à partir de la démonstration à trois documents en le traitant comme un score de confiance universel. Un test d’acceptation utile reflète les conséquences d’une récupération erronée dans votre propre application.

Où Flatkey s’intègre dans l’application

Flatkey propose un routeur de modèles compatible avec OpenAI et un répertoire de modèles à jour. Utilisez la documentation d’intégration de Flatkey pour évaluer la partie génération de modèles de votre application. Les exemples ci-dessus appellent OpenAI directement ; ils n’établissent pas qu’un modèle d’embeddings ou que tous les paramètres d’embeddings sont disponibles via Flatkey.

Pour une application multi-fournisseurs, gardez la configuration de récupération indépendante de la configuration de votre modèle de réponse. Cela vous permet de comparer des modèles de réponse sans reconstruire l’index de documents pour chaque expérience. Consultez les guides d’architecture d’API de Flatkey lors de la planification du routage, des contrôles de compte et des vérifications opérationnelles.

Questions fréquentes

L’API d’embeddings répond-elle elle-même aux questions ?

Elle renvoie des vecteurs. Votre application les utilise pour sélectionner du contenu associé ; un modèle de réponse est un composant distinct si vous avez besoin d’une réponse rédigée.

Puis-je comparer des vecteurs provenant de différents modèles d’embeddings ?

Ne supposez pas qu’ils partagent un espace de coordonnées pertinent, même si leurs dimensions correspondent. Conservez des index spécifiques à chaque modèle et évaluez les migrations en utilisant les mêmes questions et documents sources.

Dois-je choisir immédiatement le plus grand modèle d’embeddings ?

Commencez par une configuration que vous pouvez mesurer. Comparez la qualité de récupération, la latence, le stockage et le coût sur vos propres requêtes avant d’accepter un index plus volumineux ou un modèle différent.

Que dois-je construire en premier ?

Utilisez l’API Open AI embeddings pour intégrer un petit corpus dont les autorisations sont sûres, vérifier le mappage entre documents et vecteurs, et tester la récupération avec des questions étiquetées. Étendez ensuite le corpus une fois que cette boucle aura produit des preuves fiables.