Embeddings

Embeddings متن را به بردار عددی تبدیل می‌کند. این بردارها معنی تقریبی متن را به شکلی قابل محاسبه نمایش می‌دهند؛ بنابراین می‌توانید شباهت معنایی، جست‌وجوی دانش، خوشه‌بندی یا حذف موارد تکراری را در محصول خود بسازید.

POST /v1/embeddings

این API چه زمانی لازم است؟

از Embeddings استفاده کنید وقتی می‌خواهید:

در اسناد فارسی یا چندزبانه جست‌وجوی معنایی بسازید.
برای RAG، بخش‌های مرتبط دانش را پیدا کنید.
پرسش کاربر را با محتوای موجود مقایسه کنید.
متن‌های مشابه یا تکراری را شناسایی کنید.
داده متنی را برای مخزن برداری آماده کنید.

اگر می‌خواهید پاسخ متنی نهایی بسازید، Embeddings کافی نیست؛ معمولاً نتیجه بازیابی را به Chat Completions یا Responses API می‌دهید.

شروع سریع

Python
NodeJS
REST API
OpenAI Python SDK
OpenAI NodeJS SDK

import requests

response = requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/embeddings",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_TOKEN",
        "Content-Type": "application/json",
    },
    json={
  "model": "openai:default:text-embedding-3-small",
  "input": "گدارAI یک درگاه یکپارچه برای کار با مدل‌های زبانی است."
},
    timeout=60,
)

response.raise_for_status()
print(response.json())

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/embeddings", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_GODARAI_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "openai:default:text-embedding-3-small",
  "input": "گدارAI یک درگاه یکپارچه برای کار با مدل‌های زبانی است."
}),
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/embeddings" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "openai:default:text-embedding-3-small",
  "input": "گدارAI یک درگاه یکپارچه برای کار با مدل‌های زبانی است."
}'

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GODARAI_TOKEN",
    base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

response = client.embeddings.create(
    "model": "openai:default:text-embedding-3-small",
    input="گدارAI یک درگاه یکپارچه برای کار با مدل‌های زبانی است."

)

print(response)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_GODARAI_TOKEN",
  baseURL: "https://YOUR_WORKSPACE.godarai.ir/v1",
});

const response = await client.embeddings.create({
  "model": "openai:default:text-embedding-3-small",
  "input": "گدارAI یک درگاه یکپارچه برای کار با مدل‌های زبانی است."
});

console.log(response);

مدل باید از نوع embedding باشد و در دسترسی فضای کاری شما مجاز شده باشد. اگر از مدل چت برای این API استفاده کنید، درخواست رد می‌شود.

ساختار درخواست

حداقل درخواست:

{
  "model": "openai:default:text-embedding-3-small",
  "input": "راهنمای فعال‌سازی بودجه برای تیم فنی"
}

input می‌تواند یک رشته یا آرایه‌ای از رشته‌ها باشد:

Python
NodeJS
REST API
OpenAI Python SDK
OpenAI NodeJS SDK

import requests

response = requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/embeddings",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_TOKEN",
        "Content-Type": "application/json",
    },
    json={
  "model": "openai:default:text-embedding-3-small",
  "input": [
    "راهنمای ساخت توکن دسترسی",
    "مستندات سقف نرخ",
    "تنظیم بودجه برای فضای کاری"
  ]
},
    timeout=60,
)

response.raise_for_status()
print(response.json())

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/embeddings", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_GODARAI_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "openai:default:text-embedding-3-small",
  "input": [
    "راهنمای ساخت توکن دسترسی",
    "مستندات سقف نرخ",
    "تنظیم بودجه برای فضای کاری"
  ]
}),
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/embeddings" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "openai:default:text-embedding-3-small",
  "input": [
    "راهنمای ساخت توکن دسترسی",
    "مستندات سقف نرخ",
    "تنظیم بودجه برای فضای کاری"
  ]
}'

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GODARAI_TOKEN",
    base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

response = client.embeddings.create(
    "model": "openai:default:text-embedding-3-small",
    input=[
        "راهنمای ساخت توکن دسترسی",
        "مستندات سقف نرخ",
        "تنظیم بودجه برای فضای کاری"
      ]

)

print(response)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_GODARAI_TOKEN",
  baseURL: "https://YOUR_WORKSPACE.godarai.ir/v1",
});

const response = await client.embeddings.create({
  "model": "openai:default:text-embedding-3-small",
  "input": [
    "راهنمای ساخت توکن دسترسی",
    "مستندات سقف نرخ",
    "تنظیم بودجه برای فضای کاری"
  ]
});

console.log(response);

نکته آموزشی: برای ورود اولیه حجم زیادی سند، آرایه‌ای از رشته‌ها معمولاً از ارسال تک‌به‌تک درخواست‌ها ساده‌تر است. با این حال اندازه هر دسته را کنترل کنید تا خطا، زمان پاسخ و هزینه قابل پیش‌بینی بماند.

`encoding_format`

اگر encoding_format را ارسال نکنید، خروجی معمولاً به شکل float برمی‌گردد. مقدارهای رایج:

float
base64

Python
NodeJS
REST API
OpenAI Python SDK
OpenAI NodeJS SDK

import requests

response = requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/embeddings",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_TOKEN",
        "Content-Type": "application/json",
    },
    json={
  "model": "openai:default:text-embedding-3-small",
  "input": "مستندات چندمستاجری در گدارAI",
  "encoding_format": "float"
},
    timeout=60,
)

response.raise_for_status()
print(response.json())

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/embeddings", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_GODARAI_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "openai:default:text-embedding-3-small",
  "input": "مستندات چندمستاجری در گدارAI",
  "encoding_format": "float"
}),
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/embeddings" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "openai:default:text-embedding-3-small",
  "input": "مستندات چندمستاجری در گدارAI",
  "encoding_format": "float"
}'

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GODARAI_TOKEN",
    base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

response = client.embeddings.create(
    "model": "openai:default:text-embedding-3-small",
    input="مستندات چندمستاجری در گدارAI",
    encoding_format="float"

)

print(response)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_GODARAI_TOKEN",
  baseURL: "https://YOUR_WORKSPACE.godarai.ir/v1",
});

const response = await client.embeddings.create({
  "model": "openai:default:text-embedding-3-small",
  "input": "مستندات چندمستاجری در گدارAI",
  "encoding_format": "float"
});

console.log(response);

float برای بیشتر مخزن‌های برداری و پردازش مستقیم مناسب‌تر است. base64 وقتی مفید است که بخواهید بردار را فشرده‌تر منتقل یا ذخیره کنید.

`dimensions`

بعضی مدل‌های Embedding اجازه می‌دهند اندازه بردار خروجی را با dimensions تنظیم کنید:

Python
NodeJS
REST API
OpenAI Python SDK
OpenAI NodeJS SDK

import requests

response = requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/embeddings",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_TOKEN",
        "Content-Type": "application/json",
    },
    json={
  "model": "openai:default:text-embedding-3-large",
  "input": "راهنمای مدیریت نقش‌ها و دسترسی‌ها",
  "dimensions": 1024
},
    timeout=60,
)

response.raise_for_status()
print(response.json())

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/embeddings", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_GODARAI_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "openai:default:text-embedding-3-large",
  "input": "راهنمای مدیریت نقش‌ها و دسترسی‌ها",
  "dimensions": 1024
}),
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/embeddings" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "openai:default:text-embedding-3-large",
  "input": "راهنمای مدیریت نقش‌ها و دسترسی‌ها",
  "dimensions": 1024
}'

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GODARAI_TOKEN",
    base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

response = client.embeddings.create(
    "model": "openai:default:text-embedding-3-large",
    input="راهنمای مدیریت نقش‌ها و دسترسی‌ها",
    dimensions=1024

)

print(response)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_GODARAI_TOKEN",
  baseURL: "https://YOUR_WORKSPACE.godarai.ir/v1",
});

const response = await client.embeddings.create({
  "model": "openai:default:text-embedding-3-large",
  "input": "راهنمای مدیریت نقش‌ها و دسترسی‌ها",
  "dimensions": 1024
});

console.log(response);

این پارامتر برای همه مدل‌ها معتبر نیست. اگر مدل انتخابی آن را پشتیبانی نکند، باید مدل یا تنظیمات خود را تغییر دهید.

چه پارامترهایی اینجا معنا ندارند؟

Embeddings برای تولید بردار است، نه تولید متن. بنابراین پارامترهایی مانند این‌ها را از درخواست حذف کنید:

messages
temperature
max_tokens
stream
tools
tool_choice
response_format

اگر قبلاً با Chat Completions کار کرده‌اید، همان داده درخواست را با تغییر مسیر به /v1/embeddings نفرستید؛ مسئله و قرارداد این API متفاوت است.

شکل پاسخ

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [-0.018, 0.0021, 0.0314, -0.0079]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

usage را برای تحلیل هزینه و ظرفیت نگه دارید. در پردازش‌های حجیم، مصرف Embedding می‌تواند بخش مهمی از بودجه شما باشد.

الگوی رایج برای RAG

اسناد را به بخش‌های کوچک و معنادار تقسیم کنید.
برای هر بخش Embedding بسازید.
بردارها را در مخزن برداری خود ذخیره کنید.
هنگام دریافت پرسش کاربر، برای پرسش هم Embedding بسازید.
نزدیک‌ترین بخش‌ها را بازیابی کنید.
چند بخش برتر را همراه پرسش به Chat Completions بدهید.

کیفیت RAG فقط به مدل چت وابسته نیست؛ اندازه بخش‌ها، تمیزبودن متن فارسی، مدل Embedding و روش رتبه‌بندی هم به همان اندازه مهم‌اند.

خطاهای رایج

model is required: شناسه مدل ارسال نشده است.
input is required and must be a non-empty string or a non-empty array of strings: ورودی خالی یا نامعتبر است.
encoding_format must be either 'float' or 'base64': فرمت کدگذاری پشتیبانی نمی‌شود.
dimensions is not supported for the selected embedding model: مدل انتخابی اندازه سفارشی بردار را نمی‌پذیرد.
Model access denied or unsupported for embeddings: مدل در دسترسی شما مجاز نیست یا از نوع Embedding نیست.

جمع‌بندی

Embeddings پایه جست‌وجوی معنایی و RAG است. آن را برای تولید پاسخ نهایی استفاده نکنید؛ از آن برای پیدا کردن و امتیازدهی معنایی داده‌ها استفاده کنید و سپس نتیجه را به API تولید پاسخ بدهید.

این API چه زمانی لازم است؟​

شروع سریع​

ساختار درخواست​

encoding_format​

dimensions​

چه پارامترهایی اینجا معنا ندارند؟​

شکل پاسخ​

الگوی رایج برای RAG​

خطاهای رایج​

جمع‌بندی​