Embeddings
POST /v1/embeddings
مستندات
معرفی
embedding یعنی تبدیل یک متن به فهرستی از اعداد (یک «بردار») که معنای آن متن را نمایندگی میکند. دو متنی که معنای نزدیکی دارند بردارهای نزدیکی میگیرند، حتی اگر هیچ کلمهٔ مشترکی نداشته باشند. این همان چیزی است که جستوجو را از «تطبیق کلمه» به «تطبیق معنا» تبدیل میکند.
با استفاده از این endpoint میتوانید بردارهای embedding برای متنهای ورودی دریافت کنید. از embeddingها میتوان برای جستجوی معنایی، خوشهبندی، سیستمهای توصیهگر و RAG استفاده کرد.
این endpoint چت نیست
هیچ messagesای در کار نیست و چیزی «تولید» نمیشود. متن میفرستید و عدد میگیرید. بردارها را خودتان جایی ذخیره میکنید (پایگاهداده یا فایل) و بعداً برای پیدا کردن نزدیکترین متنها با هم مقایسه میکنید.
RAG هم بر همین پایه است: پرسش کاربر را embed میکنید، نزدیکترین تکههای سند خودتان را پیدا میکنید، و آنها را همراه پرسش به Chat Completions میدهید تا پاسخ بر اساس دادههای شما نوشته شود.
نمونهها
curl https://api-ai.hibanacloud.ir/v1/embeddings \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "bge-m3", "input": "متن نمونه برای تبدیل به بردار" }'پارامترهای درخواست
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
| model | string | بله | نام مدل embedding (مثال: bge-m3) |
| input | string | array | بله | متن ورودی به صورت رشته یا آرایهای از رشتهها برای ارسال دستهای |
فیلدهای پاسخ
| فیلد | نوع | توضیح |
|---|---|---|
| object | string | نوع شیء (list) |
| data | array | آرایهای از بردارهای embedding، هر کدام شامل index و آرایه embedding |
| data[].embedding | array[float] | بردار embedding به صورت آرایهای از اعداد اعشاری |
| data[].index | integer | اندیس ورودی متناظر |
| model | string | نام مدل استفاده شده |
| usage | object | شامل: prompt_tokens, total_tokens, cost_rial |
ترتیب خروجیها تضمینشده نیست؛ برای تطبیق هر بردار با ورودیاش از data[].index استفاده کنید، نه از جای آن در آرایه.
گام بعدی
وقتی چند هزار متن دارید، آنها را دستهای بفرستید: پارامتر input آرایه هم میپذیرد، و یک درخواست با ۱۰۰ متن بهمراتب سریعتر از ۱۰۰ درخواست است، و کمتر به سقف نرخ درخواست میخورد.
- لیست مدلها، کدام مدلهای embedding در دسترساند.
- قیمتگذاری، هزینه بر پایهٔ
prompt_tokensحساب میشود و درcost_rialبرمیگردد. - محدودیت نرخ درخواست، قبل از ساختن یک حلقهٔ ایندکسسازی این را بخوانید.