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": "baai/bge-m3", "input": "متن نمونه برای تبدیل به بردار" }'پارامترهای درخواست
| پارامتر | نوع | الزامی | توضیح |
|---|---|---|---|
| model | string | بله | نام مدل embedding (مثال: baai/bge-m3) |
| input | string | array | multimodal items | بله | متن ورودی به صورت رشته، آرایه‌ای از رشته‌ها برای ارسال دسته‌ای، یا آرایه‌ای از آیتم‌های { content: [...] } برای embedding تصویر — جزئیات در embedding تصویر. |
| dimensions | integer | خیر | کوتاه کردن طول بردار خروجی (مثلاً ۲۵۶ یا ۷۶۸)، اگر مدل پشتیبانی کند. توجه: baai/bge-m3 برای بردار کوتاه‌شده آموزش ندیده و کیفیت جست‌وجو با آن افت می‌کند. |
فیلدهای پاسخ
| فیلد | نوع | توضیح |
|---|---|---|
| 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 |
| usage.prompt_tokens_details | object | فقط وقتی درخواست شامل تصویر بود: text_tokens و image_tokens. جزئیات در embedding تصویر. |
ترتیب خروجی‌ها تضمین‌شده نیست؛ برای تطبیق هر بردار با ورودی‌اش از data[].index استفاده کنید، نه از جای آن در آرایه.
embedding تصویر
این قابلیت در حال انتشار است. اگر همین حالا تصویری بفرستید ممکن است با خطا مواجه شوید، بدون آنکه علتش این توضیحات باشد.
در کنار متن ساده، پارامتر input آیتم‌های چندرسانه‌ای هم می‌پذیرد: هر آیتم یک شیء { content: [...] } است که آرایه‌ای از بخش‌های متن و تصویر را کنار هم می‌گذارد — درست مثل content در Chat Completions.
یک آیتم، یک بردار
متن و تصویر داخل همان یک آیتم با هم embed می‌شوند و یک بردار خروجی می‌دهند — نه دو بردار جدا. برای دریافت چند بردار جدا، چند آیتم جدا در آرایهٔ input بگذارید. یک رشتهٔ ساده هم می‌تواند کنار آیتم‌ها بیاید؛ درگاه آن را خودش به یک آیتم متنی تبدیل می‌کند.
{ "model": "google/gemini-embedding-2", "input": [ { "content": [ { "type": "text", "text": "a red square" }, { "type": "image_url", "image_url": { "url": "data:image/png;base64,..." } } ] } ]}فیلد image_url می‌تواند یک شیء { url: "..." } باشد یا مستقیماً یک رشته.
| محدودیت | توضیح |
|---|---|
| تعداد تصویر | حداکثر ۱۰۰ تصویر در هر درخواست. |
| تعداد آیتم | حداکثر ۲۰۴۸ آیتم در آرایهٔ input (رشته یا آیتم چندرسانه‌ای، هرکدام یک بردار خروجی). |
| حجم هر تصویر | حداکثر ۸ مگابایت، روی فایل خام (نه رشتهٔ Base64). |
| نوع تصویر | PNG، JPEG، GIF یا WebP. |
| نشانی تصویر | یک data URI با Base64، یا نشانی https که خودِ درگاه دانلودش می‌کند (فقط پورت‌های ۸۰ و ۴۴۳). |
| مدل | فقط مدل‌هایی با قابلیت ورودی تصویر روی embedding (فهرست پایین)؛ روی مدل دیگری خطای image_input_not_supported برمی‌گردد. |
امروز فقط این مدل embedding ورودی تصویر می‌پذیرد؛ فهرست زیر مستقیم از کاتالوگ مدل‌ها خوانده می‌شود و همیشه به‌روز است:
در حال بارگذاری فهرست مدل‌ها… فهرست به‌روز همیشه در لیست مدل‌ها با فیلتر «ورودی تصویر» هست، جایی که قیمت‌ها هم کنارش است.
هزینه: هر تصویر، صرف‌نظر از اندازه‌اش، ۲۵۸ توکن ثابت حساب می‌شود و به نرخ ورودی تصویر مدل قیمت‌گذاری می‌شود — نه نرخ متنی، که ارزان‌تر است. بقیهٔ متن آیتم با نرخ معمول ورودی حساب می‌شود. وقتی درخواست تصویر داشته باشد، پاسخ یک usage.prompt_tokens_details هم برمی‌گرداند:
{ "prompt_tokens": 261, "total_tokens": 261, "prompt_tokens_details": { "text_tokens": 3, "image_tokens": 258 }, "cost_rial": 347}نرخ ورودی تصویر هر مدل کنار قیمت متنی‌اش در لیست مدل‌ها و صفحهٔ هر مدل دیده می‌شود.
نمونه‌کد یک درخواست embedding با متن و تصویر:
curl https://api-ai.hibanacloud.ir/v1/embeddings \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "google/gemini-embedding-2", "input": [ { "content": [ {"type": "text", "text": "a red square"}, {"type": "image_url", "image_url": {"url": "https://raw.githubusercontent.com/python-pillow/Pillow/main/Tests/images/hopper.png"}} ] } ] }'| کد | معنی |
|---|---|
| image_input_not_supported | مدل انتخاب‌شده تصویر نمی‌پذیرد؛ از فهرست بالا یک مدل بردارید. |
| unsupported_image_type | نوع تصویر PNG، JPEG، GIF یا WebP نیست. |
| image_too_large | تصویر از سقف ۸ مگابایت بزرگ‌تر است. |
| image_fetch_failed | دانلود نشانی تصویر ناموفق بود. |
| invalid_value | شکل input نامعتبر است (مثلاً آیتمی بدون content، یا بیش از حد مجاز آیتم/تصویر). |
فهرست کامل خطاها در مدیریت خطاها آمده است.
گام بعدی
وقتی چند هزار متن دارید، آن‌ها را دسته‌ای بفرستید: پارامتر input آرایه هم می‌پذیرد، و یک درخواست با ۱۰۰ متن به‌مراتب سریع‌تر از ۱۰۰ درخواست است، و کمتر به سقف نرخ درخواست می‌خورد.
- لیست مدل‌ها، کدام مدل‌های embedding در دسترس‌اند.
- قیمت‌گذاری، هزینه بر پایهٔ
prompt_tokensحساب می‌شود و درcost_rialبرمی‌گردد. - محدودیت نرخ درخواست، قبل از ساختن یک حلقهٔ ایندکس‌سازی این را بخوانید.
از بلاگ هیبانا
- ساخت RAG فارسی با bge-m3؛ جست‌وجوی معنایی در اسناد با API هیبانا
آموزش گام‌به‌گام RAG فارسی روی اسناد خودتان با مدل امبدینگ bge-m3 و کد پایتون؛ تکه‌بندی، بردارسازی، جست‌وجوی معنایی و پاسخ مدل روی سرورهای داخلی.