Endpoints

Embeddings

Transformer un lot de textes en vecteurs d'embedding pour la recherche, le regroupement et la classification.

Afficher en Markdown

Un embedding est une liste de nombres (un vecteur) qui représente le sens d'un texte : des textes de sens proche ont des vecteurs proches l'un de l'autre. Ils servent à construire votre propre recherche sémantique, la déduplication, le regroupement ou la classification. L'endpoint prend un lot de textes et renvoie un vecteur pour chacun.

Créer des embeddings

Endpoint POST /api/v3/embeddings
Portée ayeto.embeddings
Limite de débit high

Envoyez les textes dans input ; data de la réponse contient un vecteur par texte, dans le même ordre. Envoyez autant de textes par requête que les limites le permettent plutôt qu'une requête par texte : c'est plus rapide et cela ne compte qu'une fois dans la limite de débit.

Modèles et taille des vecteurs

model Plus grand vecteur Usage
small (par défaut) 1 536 Rapide et économique, suffisant pour la plupart des recherches et regroupements.
large 3 072 Plus précis, à un prix plus élevé.

dimensions fixe la longueur des vecteurs renvoyés, de 1 au plus grand vecteur du modèle. Des vecteurs plus courts prennent moins de place et se comparent plus vite, au prix d'une certaine perte de précision. Sans dimensions, la valeur par défaut du serveur est utilisée ; la taille réellement utilisée est renvoyée dans dimensions de la réponse. Les vecteurs ne sont comparables qu'avec des vecteurs du même modèle et de la même taille : conservez les deux avec vos vecteurs et envoyez dimensions explicitement lorsque vous dépendez d'une taille.

Les vecteurs sont normalisés à la longueur 1 : le produit scalaire de deux vecteurs est donc leur similarité cosinus.

Limites

Limite Par défaut
Textes par requête 256
Caractères par texte 16 000
Caractères par requête (tous les textes ensemble) 1 000 000

Le serveur peut être configuré avec d'autres limites. Une requête qui dépasse une limite est refusée avec 422 et rien n'est facturé. Un texte ne doit pas être vide. Indépendamment de la limite de caractères, les modèles lisent environ 8 000 tokens par texte ; un texte plus long en tokens (possible pour un texte dense comme du code ou certaines langues) est refusé lui aussi. Découpez les longs documents en passages avant de les convertir, ce qui améliore aussi les résultats de recherche.

Facturation

La requête est facturée au prix du modèle d'embedding, selon la quantité de texte envoyée. Les crédits consommés sont renvoyés dans credits, les tokens comptés par le modèle dans tokens. Les crédits sont vérifiés avant le traitement des textes, voir crédits.

Avec organization_id, la requête s'exécute dans cette organisation et est payée avec le crédit de l'utilisateur dans celle-ci, comme pour fichiers et médias. L'utilisateur de la clé doit être administrateur ou membre de l'organisation, pas invité.

Une requête est tout ou rien : lorsqu'elle échoue, aucun vecteur n'est renvoyé. Les très grandes requêtes sont traitées en plusieurs parties, et une partie déjà traitée avant l'échec reste facturée.

Requête

Champ Type Requis Description
input tableau de chaînes Oui Les textes, au moins un, aucun vide.
model chaîne Non small ou large. Par défaut : small.
dimensions entier Non Longueur des vecteurs, de 1 au plus grand vecteur du modèle. Par défaut : la valeur par défaut du serveur.
organization_id UUID Non Exécute la requête dans cette organisation et la débite du crédit de l'utilisateur dans celle-ci. Par défaut : aucune (crédits personnels).

Réponse

200 OK avec :

Champ Type Description
data tableau Un élément par texte, dans l'ordre de input.
data[].index entier Position du texte dans input, à partir de 0.
data[].embedding tableau de nombres Le vecteur.
model chaîne Le modèle utilisé, small ou large.
dimensions entier Longueur de chaque vecteur.
tokens entier Tokens comptés par le modèle dans les textes.
credits nombre Crédits consommés par la requête.

Erreurs

Statut detail Cause
401 API key is invalid La clé n'a pas la portée ayeto.embeddings, voir authentification.
403 User is not a member of the organization organization_id ne fait pas partie des organisations de l'utilisateur.
403 User does not have write permissions in the organization L'utilisateur est invité dans l'organisation.
422 too many inputs (<count>, at most <limit>) input contient plus de textes qu'autorisé.
422 input <index> is empty Le texte à cette position est vide ou ne contient que des espaces.
422 input <index> is too long (<length> characters, at most <limit>) Le texte à cette position dépasse la limite de caractères.
422 the inputs are too long together (<length> characters, at most <limit>) Les textes dépassent ensemble la limite de la requête.
422 dimensions must be at most <limit> for this model dimensions est supérieur au plus grand vecteur du modèle.
422 the embedding model refused the input, a text is probably too long Un texte est plus long que ce que le modèle lit (environ 8 000 tokens).
422 not enough user credit Les crédits personnels de l'utilisateur sont épuisés.
422 not enough organization credit Avec organization_id : le crédit de l'utilisateur dans l'organisation est épuisé.
422 erreur de validation input est absent ou vide, model n'est ni small ni large, ou dimensions est inférieur à 1.
500 Failed to generate embeddings Le modèle n'a pas pu traiter la requête. Réessayez plus tard.

Les erreurs d'authentification, de limite de débit et du serveur sont décrites dans les conventions.

Exemple

bash
curl -X POST "https://ayeto.ai/api/v3/embeddings" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": ["How do I reset my password?", "Opening hours of the Prague office"], "dimensions": 4}'
json
{
  "data": [
    {"index": 0, "embedding": [0.0213, -0.5132, 0.7411, 0.4326]},
    {"index": 1, "embedding": [-0.3391, 0.1207, 0.6614, -0.6579]}
  ],
  "model": "small",
  "dimensions": 4,
  "tokens": 14,
  "credits": 0.0001
}