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
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}'
{
"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
}