# Embeddings

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

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](conventions.md#limites-de-debit) |

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](account.md#credits).

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](files-and-media.md#organisations-et-credits).
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](authentication.md#erreurs-dauthentification). |
| `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](conventions.md#erreurs).

### 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
}
```
