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 |
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.
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í. 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. |
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.
Příklad
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
}