# Embeddings

> Převod dávky textů na embedding vektory pro vyhledávání, shlukování a klasifikaci.

Embedding je seznam čísel (vektor), který vyjadřuje význam textu: texty s podobným
významem mají vektory blízko sebe. Postavíte na nich vlastní sémantické vyhledávání,
deduplikaci, shlukování nebo klasifikaci. Endpoint přijme dávku textů a vrátí pro každý
jeden vektor.

## Vytvoření embeddings

| | |
|---|---|
| Endpoint | `POST /api/v3/embeddings` |
| Rozsah | `ayeto.embeddings` |
| Limit požadavků | [high](conventions.md#limity-pozadavku) |

Texty pošlete v `input`; `data` v odpovědi obsahuje jeden vektor na text, ve stejném
pořadí. Posílejte v jednom požadavku tolik textů, kolik limity dovolí, ne jeden požadavek
na text: je to rychlejší a do limitu požadavků se počítá jednou.

### Modely a velikost vektoru

| `model` | Největší vektor | Použití |
|---|---|---|
| `small` (výchozí) | 1 536 | Rychlý a levný, stačí na většinu vyhledávání a shlukování. |
| `large` | 3 072 | Přesnější, za vyšší cenu. |

`dimensions` určuje délku vrácených vektorů, od 1 do největšího vektoru modelu. Kratší
vektory zaberou méně místa a rychleji se porovnávají, za cenu určité ztráty přesnosti.
Bez `dimensions` se použije výchozí hodnota serveru; skutečně použitou velikost vrací
`dimensions` v odpovědi. Vektory jsou porovnatelné jen s vektory stejného modelu a stejné
velikosti, proto si obojí ukládejte k vektorům a `dimensions` posílejte výslovně, když na
velikosti závisíte.

Vektory jsou normalizované na délku 1, takže skalární součin dvou vektorů je jejich
kosinová podobnost.

### Limity

| Limit | Výchozí |
|---|---|
| Textů v požadavku | 256 |
| Znaků v jednom textu | 16 000 |
| Znaků v požadavku (všechny texty dohromady) | 1 000 000 |

Server může mít nastavené jiné limity. Požadavek nad limit je odmítnut s `422` a nic se
neúčtuje. Text nesmí být prázdný. Nezávisle na limitu znaků čtou modely zhruba 8 000
tokenů na text; text, který je v tokenech delší (může se stát u hustého textu, třeba
kódu nebo některých jazyků), je odmítnut také. Dlouhé dokumenty před převodem rozdělte
na pasáže, vyhledávání pak dává i lepší výsledky.

### Účtování

Požadavek se účtuje cenou embedding modelu podle množství poslaného textu. Spotřebované
kredity vrací `credits`, tokeny, které model napočítal, `tokens`. Kredity se kontrolují
před zpracováním textů, viz [kredity](account.md#kredity).

S `organization_id` běží požadavek v této organizaci a platí se z kreditu uživatele
v ní, stejně jako u [souborů a médií](files-and-media.md#organizace-a-kredity). Uživatel
klíče musí být administrátor nebo člen organizace, ne host.

Požadavek je vše, nebo nic: když selže, nevrátí se žádné vektory. Velmi velké požadavky
se zpracovávají po částech a část, která se stihla zpracovat před chybou, zůstane
naúčtovaná.

### Požadavek

| Pole | Typ | Povinné | Popis |
|---|---|---|---|
| `input` | pole řetězců | Ano | Texty, alespoň jeden, žádný prázdný. |
| `model` | řetězec | Ne | `small` nebo `large`. Výchozí: `small`. |
| `dimensions` | celé číslo | Ne | Délka vektorů, 1 až největší vektor modelu. Výchozí: výchozí hodnota serveru. |
| `organization_id` | UUID | Ne | Spustí požadavek v této organizaci a naúčtuje ho z kreditu uživatele v ní. Výchozí: žádná (osobní kredity). |

### Odpověď

`200 OK` s:

| Pole | Typ | Popis |
|---|---|---|
| `data` | pole | Jedna položka na text, v pořadí `input`. |
| `data[].index` | celé číslo | Pozice textu v `input`, od 0. |
| `data[].embedding` | pole čísel | Vektor. |
| `model` | řetězec | Použitý model, `small` nebo `large`. |
| `dimensions` | celé číslo | Délka každého vektoru. |
| `tokens` | celé číslo | Tokeny, které model v textech napočítal. |
| `credits` | číslo | Kredity, které požadavek spotřeboval. |

### Chyby

| Stav | `detail` | Příčina |
|---|---|---|
| `401` | `API key is invalid` | Klíči chybí rozsah `ayeto.embeddings`, viz [autentizace](authentication.md#chyby-autentizace). |
| `403` | `User is not a member of the organization` | `organization_id` není mezi organizacemi uživatele. |
| `403` | `User does not have write permissions in the organization` | Uživatel je v organizaci host. |
| `422` | `too many inputs (<count>, at most <limit>)` | `input` má víc textů, než je povoleno. |
| `422` | `input <index> is empty` | Text na dané pozici je prázdný nebo jen z bílých znaků. |
| `422` | `input <index> is too long (<length> characters, at most <limit>)` | Text na dané pozici překračuje limit znaků. |
| `422` | `the inputs are too long together (<length> characters, at most <limit>)` | Texty dohromady překračují limit požadavku. |
| `422` | `dimensions must be at most <limit> for this model` | `dimensions` je větší než největší vektor modelu. |
| `422` | `the embedding model refused the input, a text is probably too long` | Některý text je delší, než model přečte (zhruba 8 000 tokenů). |
| `422` | `not enough user credit` | Osobní kredity uživatele jsou vyčerpané. |
| `422` | `not enough organization credit` | S `organization_id`: kredit uživatele v organizaci je vyčerpaný. |
| `422` | chyba validace | `input` chybí nebo je prázdné, `model` není `small` ani `large`, nebo je `dimensions` menší než 1. |
| `500` | `Failed to generate embeddings` | Model požadavek nezpracoval. Zkuste to později. |

Chyby autentizace, limitů požadavků a serveru jsou popsány v
[konvencích](conventions.md#chyby).

### Příklad

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