Service d'embeddings — référence

Ce qu'est le composant

Microservice HTTP qui transforme du texte en vecteurs d'embedding (représentation numérique dense de dimension fixe). Il joue le rôle de producteur d'embeddings d'un cœur de recherche sémantique (RAG) : on lui donne des textes, il rend des vecteurs comparables entre eux.

Propriétés structurantes :

• Stateless — aucune persistance, aucune session ; chaque requête est autonome.
• Synchrone — la réponse HTTP contient directement les vecteurs calculés ; pas de file d'attente ni de traitement asynchrone.
• Mono-modèle — un seul modèle d'embedding, chargé une fois au démarrage et réutilisé pour toutes les requêtes.

Le composant produit des vecteurs ; il ne les stocke pas, n'entretient aucun index et n'effectue aucune recherche. Indexation et recherche sont la responsabilité du consommateur.

Interfaces publiques (contrat HTTP)

Deux endpoints, exposés à la racine (aucun préfixe de chemin). Corps JSON, validés côté service.

POST /embed — produire des embeddings

Vectorise une liste de textes selon un type d'usage.

Entrée (JSON) :

Le type distingue les deux moments d'un pipeline de recherche sémantique :

• passage — vectoriser les documents à indexer (côté ingestion) ;
• query — vectoriser une requête utilisateur au moment de la recherche.

Exemple :

{ "type": "passage", "texts": ["premier texte", "second texte"] }

Sortie (200 OK, JSON) :

Garanties observables sur la sortie :

• len(vectors) == len(texts) — autant de vecteurs que de textes, dans l'ordre d'entrée ;
• chaque vecteur a exactement dim composantes ;
• vecteurs normalisés L2 (norme ≈ 1), de sorte que le produit scalaire en aval équivaut à la similarité cosinus.

Exemple (tronqué) :

{
  "model": "<identifiant-modèle>",
  "dim": 768,
  "vectors": [[0.01, -0.03, "..."], [0.02, 0.00, "..."]]
}

GET /health — état et métadonnées

Confirme que le service est prêt (modèle chargé) et rappelle le modèle servi et la dimension des vecteurs.

• Entrée : aucune.
• Sortie (200 OK, JSON) :

{ "status": "ok", "model": "<identifiant-modèle>", "dim": 768 }

Le service ne renvoie pas d'état « dégradé » ou « not ready » distinct : un modèle non chargeable se manifeste au démarrage, pas par un status alternatif.

Codes d'erreur

Le corps d'une erreur 422 suit le format de validation standard du framework (structure detail), non personnalisé. Une entrée invalide est rejetée sans calcul.

Formats et conventions

Modèle et dimension

• Le modèle est un modèle d'embedding multilingue de la famille e5 (sentence-transformers), fixé dans le code (non configurable par le consommateur).
• Dimension des vecteurs : 768 — dérivée dynamiquement du modèle et exposée à la fois par /health et par la réponse /embed. Un intégrateur doit lire dim plutôt que de coder cette valeur en dur.

Préfixage e5 (transparent pour le consommateur)

Les modèles e5 attendent un préfixe selon l'usage du texte. Le service applique ce préfixe côté serveur, avant l'encodage :

Le consommateur envoie du texte brut ; il n'a pas à préparer ou préfixer le texte lui-même — il indique seulement s'il s'agit d'un passage ou d'une requête.

Architecture interne (vue synthétique)

• Framework HTTP : FastAPI ; serveur ASGI : uvicorn ; validation / sérialisation : Pydantic (modèles de requête/réponse) ; moteur d'embedding : sentence-transformers ; backend de calcul : torch en variante CPU-only.
• Application définie en un point d'entrée unique. Le service est stateless et mono-processus applicatif.
• Cycle de vie du modèle : le modèle est instancié une seule fois (fonction mémoïsée) et préchargé au démarrage via un hook de cycle de vie, et non à la première requête. Le chargement du modèle est injecté dans les endpoints (injection de dépendance), ce qui facilite la substitution par un faux modèle dans les tests.
• Premier démarrage : sur une machine neuve, le modèle doit être téléchargé/mis en cache avant que le service soit prêt ; le packaging prévoit une large fenêtre de grâce au démarrage (healthcheck à start-period long).

Points de contrat pour un intégrateur

• Appeler /embed avec le même modèle (donc le même service) pour indexer et pour interroger : passages et requêtes doivent partager l'espace vectoriel.
• Utiliser type: "passage" à l'ingestion, type: "query" à la recherche.
• Lire dim depuis la réponse plutôt que de présumer une dimension.
• Les vecteurs étant normalisés L2, comparer via produit scalaire / cosinus.
• Prévoir le rejet 422 sur entrée invalide (liste vide, texte vide, type inconnu) comme partie normale du contrat.
• Le service est synchrone et stateless : la mise en lots, la reprise sur erreur et la persistance des vecteurs sont à la charge du consommateur.

Sécurité et exposition (posture observable)

• Le service est conçu pour n'être joignable qu'en local (bind sur la boucle locale de l'hôte) ; aucune exposition publique n'est configurée.
• Aucune authentification applicative : l'isolation repose sur la frontière réseau/hôte, pas sur un contrôle applicatif. Un intégrateur qui l'exposerait au-delà du local devrait ajouter lui-même une couche d'accès.
• Exécution en utilisateur non-root (image conteneur) et durcissement au niveau du déploiement hôte (privilèges restreints, système de fichiers en lecture seule hors répertoire de cache).
• Le modèle de menace assumé est celui d'un service interne derrière une frontière réseau/hôte, non exposé.