Endpointy

Embeddings

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

Zobrazit jako Markdown

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

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
}