Embeddings

جاسازی‌ها (Embeddings) نمایش عددی از ورودی متن هستند که تعدادی از موارد استفاده منحصر به فرد، مانند خوشه‌بندی، اندازه‌گیری شباهت و بازیابی اطلاعات را فراهم می‌کنند. برای آشنایی با این موضوع، راهنمای جاسازی‌ها (Embeddings) را بررسی کنید.

برخلاف مدل‌های هوش مصنوعی مولد که محتوای جدید ایجاد می‌کنند، مدل جاسازی Gemini فقط برای تبدیل قالب داده‌های ورودی شما به یک نمایش عددی در نظر گرفته شده است. در حالی که گوگل مسئول ارائه یک مدل جاسازی است که قالب داده‌های ورودی شما را به قالب عددی درخواستی تبدیل می‌کند، کاربران مسئولیت کامل داده‌هایی را که وارد می‌کنند و جاسازی‌های حاصل از آن را بر عهده دارند. با استفاده از مدل جاسازی Gemini، شما تأیید می‌کنید که از حقوق لازم برای هر محتوایی که آپلود می‌کنید، برخوردار هستید. محتوایی تولید نکنید که حقوق مالکیت معنوی یا حریم خصوصی دیگران را نقض کند. استفاده شما از این سرویس تابع سیاست استفاده ممنوعه ما و شرایط خدمات گوگل است.

روش: models.embedContent

با استفاده از مدل Gemini Embedding مشخص شده، یک بردار جاسازی متن از ورودی Content تولید می‌کند.

نقطه پایانی

پست https: / /generativelanguage.googleapis.com /v1beta /{model=models /*}:embedContent

پارامترهای مسیر

string model

الزامی. نام منبع مدل. این به عنوان شناسه‌ای برای استفاده مدل عمل می‌کند.

این نام باید با نام مدلی که توسط متد models.list برگردانده می‌شود، مطابقت داشته باشد.

قالب: models/{model} به شکل models/{model} است.

درخواست بدنه

بدنه درخواست شامل داده‌هایی با ساختار زیر است:

فیلدها
شیء content object ( Content )

الزامی. محتوایی که باید جاسازی شود. فقط فیلدهای parts.text شمارش خواهند شد.

شمارشگر taskType enum ( TaskType )

اختیاری. نوع وظیفه‌ای که جاسازی‌ها برای آن استفاده خواهند شد اختیاری است. در مدل‌های قبلی ( models/embedding-001 ) پشتیبانی نمی‌شود.

string title

اختیاری. یک عنوان اختیاری برای متن. فقط زمانی قابل اجرا است که TaskType RETRIEVAL_DOCUMENT باشد.

نکته: تعیین title برای RETRIEVAL_DOCUMENT جاسازی‌های با کیفیت‌تری را برای بازیابی فراهم می‌کند.

outputDimensionality integer

اختیاری. ابعاد کاهش‌یافته‌ی اختیاری برای جاسازی خروجی. در صورت تنظیم، مقادیر اضافی در جاسازی خروجی از انتها کوتاه می‌شوند. فقط از سال ۲۰۲۴ توسط مدل‌های جدیدتر پشتیبانی می‌شود. در صورت استفاده از مدل قبلی ( models/embedding-001 ) نمی‌توانید این مقدار را تنظیم کنید.

درخواست نمونه

پایتون

from google import genai
from google.genai import types

client = genai.Client()
text = "Hello World!"
result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=text,
    config=types.EmbedContentConfig(output_dimensionality=10),
)
print(result.embeddings)

نود جی اس

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const text = "Hello World!";
const result = await ai.models.embedContent({
  model: "gemini-embedding-001",
  contents: text,
  config: { outputDimensionality: 10 },
});
console.log(result.embeddings);

برو

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

text := "Hello World!"
outputDim := int32(10)
contents := []*genai.Content{
	genai.NewContentFromText(text, genai.RoleUser),
}
result, err := client.Models.EmbedContent(ctx, "gemini-embedding-001", 
	contents, &genai.EmbedContentConfig{
		OutputDimensionality: &outputDim,
})
if err != nil {
	log.Fatal(err)
}

embeddings, err := json.MarshalIndent(result.Embeddings, "", "  ")
if err != nil {
	log.Fatal(err)
}
fmt.Println(string(embeddings))

پوسته

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model": "models/gemini-embedding-001",
     "content": {
     "parts":[{
     "text": "What is the meaning of life?"}]}
    }'

بدنه پاسخ

در صورت موفقیت، بدنه پاسخ شامل نمونه‌ای از EmbedContentResponse است.

روش: models.batchEmbedContents

چندین بردار جاسازی از ورودی Content تولید می‌کند که شامل دسته‌ای از رشته‌ها است که به صورت اشیاء EmbedContentRequest نمایش داده می‌شوند.

نقطه پایانی

پست https: / /generativelanguage.googleapis.com /v1beta /{model=models /*}:batchEmbedContents

پارامترهای مسیر

string model

الزامی. نام منبع مدل. این به عنوان شناسه‌ای برای استفاده مدل عمل می‌کند.

این نام باید با نام مدلی که توسط متد models.list برگردانده می‌شود، مطابقت داشته باشد.

قالب: models/{model} به شکل models/{model} است.

درخواست بدنه

بدنه درخواست شامل داده‌هایی با ساختار زیر است:

فیلدها
شیء requests[] object ( EmbedContentRequest )

الزامی. درخواست‌های جاسازی برای دسته. مدل در هر یک از این درخواست‌ها باید با مدل مشخص شده در BatchEmbedContentsRequest.model مطابقت داشته باشد.

درخواست نمونه

پایتون

from google import genai
from google.genai import types

client = genai.Client()
texts = [
    "What is the meaning of life?",
    "How much wood would a woodchuck chuck?",
    "How does the brain work?",
]
result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=texts,
    config=types.EmbedContentConfig(output_dimensionality=10),
)
print(result.embeddings)

نود جی اس

// Make sure to include the following import:
// import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const texts = [
  "What is the meaning of life?",
  "How much wood would a woodchuck chuck?",
  "How does the brain work?",
];
const result = await ai.models.embedContent({
  model: "gemini-embedding-001",
  contents: texts,
  config: { outputDimensionality: 10 },
});
console.log(result.embeddings);

برو

ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
	APIKey:  os.Getenv("GEMINI_API_KEY"),
	Backend: genai.BackendGeminiAPI,
})
if err != nil {
	log.Fatal(err)
}

contents := []*genai.Content{
	genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),
	genai.NewContentFromText("How much wood would a woodchuck chuck?", genai.RoleUser),
	genai.NewContentFromText("How does the brain work?", genai.RoleUser),
}

outputDim := int32(10)
result, err := client.Models.EmbedContent(ctx, "gemini-embedding-001", contents, &genai.EmbedContentConfig{
	OutputDimensionality: &outputDim,
})
if err != nil {
	log.Fatal(err)
}

embeddings, err := json.MarshalIndent(result.Embeddings, "", "  ")
if err != nil {
	log.Fatal(err)
}
fmt.Println(string(embeddings))

پوسته

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:batchEmbedContents" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"requests": [{
      "model": "models/gemini-embedding-001",
      "content": {
      "parts":[{
        "text": "What is the meaning of life?"}]}, },
      {
      "model": "models/gemini-embedding-001",
      "content": {
      "parts":[{
        "text": "How much wood would a woodchuck chuck?"}]}, },
      {
      "model": "models/gemini-embedding-001",
      "content": {
      "parts":[{
        "text": "How does the brain work?"}]}, }, ]}' 2> /dev/null | grep -C 5 values

بدنه پاسخ

پاسخ به یک BatchEmbedContentsRequest .

در صورت موفقیت، بدنه پاسخ شامل داده‌هایی با ساختار زیر است:

فیلدها
شیء embeddings[] object ( ContentEmbedding )

فقط خروجی. جاسازی‌ها برای هر درخواست، به همان ترتیبی که در درخواست دسته‌ای ارائه شده است.

نمایش JSON
{
  "embeddings": [
    {
      object (ContentEmbedding)
    }
  ]
}

روش: models.asyncBatchEmbedContent

دسته‌ای از درخواست‌های models.embedContent را برای پردازش دسته‌ای در صف قرار می‌دهد. ما یک هندلر models.batchEmbedContents در GenerativeService داریم، اما همگام‌سازی شده است. بنابراین برای جلوگیری از سردرگمی، نام آن را Async می‌گذاریم.

نقطه پایانی

پست https: / /generativelanguage.googleapis.com /v1beta /{batch.model=models /*}:asyncBatchEmbedContent

پارامترهای مسیر

string batch.model

الزامی. نام Model که برای تولید تکمیل استفاده می‌شود.

قالب: models/{model} . این قالب به صورت models/{model} است.

درخواست بدنه

بدنه درخواست شامل داده‌هایی با ساختار زیر است:

فیلدها
string batch.name

فقط خروجی. شناسه. نام منبع دسته.

قالب: batches/{batchId} .

string batch.displayName

الزامی. نام تعریف‌شده توسط کاربر برای این دسته.

شیء batch.inputConfig object ( InputEmbedContentConfig )

الزامی. پیکربندی ورودی نمونه‌هایی که پردازش دسته‌ای روی آنها انجام می‌شود.

شیء batch.output object ( EmbedContentBatchOutput )

فقط خروجی. خروجی درخواست دسته‌ای.

رشته batch.createTime string ( Timestamp format)

فقط خروجی. زمانی که دسته ایجاد شده است.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

رشته batch.endTime string ( Timestamp format)

فقط خروجی. زمانی که پردازش دسته‌ای تکمیل شده است.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

رشته batch.updateTime string ( Timestamp format)

فقط خروجی. زمانی که دسته آخرین بار به‌روزرسانی شده است.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

شیء batch.batchStats object ( EmbedContentBatchStats )

فقط خروجی. آمار مربوط به دسته.

شمارشی batch.state enum ( BatchState )

فقط خروجی. وضعیت دسته.

رشته batch.priority string ( int64 format)

اختیاری. اولویت دسته. دسته‌هایی با مقدار اولویت بالاتر قبل از دسته‌هایی با مقدار اولویت پایین‌تر پردازش می‌شوند. مقادیر منفی مجاز هستند. پیش‌فرض ۰ است.

بدنه پاسخ

در صورت موفقیت، بدنه پاسخ شامل نمونه‌ای از Operation است.

پاسخ محتوا را جاسازی کنید

پاسخ به یک EmbedContentRequest .

فیلدها
embedding object ( ContentEmbedding )

فقط خروجی. جاسازی تولید شده از محتوای ورودی.

نمایش JSON
{
  "embedding": {
    object (ContentEmbedding)
  }
}

جاسازی محتوا

فهرستی از اعداد اعشاری که نشان‌دهنده‌ی یک جاسازی هستند.

فیلدها
values[] number

مقادیر جاسازی شده.

نمایش JSON
{
  "values": [
    number
  ]
}

نوع وظیفه

نوع وظیفه‌ای که از جاسازی برای آن استفاده خواهد شد.

انوم‌ها
TASK_TYPE_UNSPECIFIED مقدار را غیرفعال کنید، که به طور پیش‌فرض روی یکی از مقادیر enum دیگر قرار می‌گیرد.
RETRIEVAL_QUERY مشخص می‌کند که متن داده شده، یک پرس‌وجو در تنظیمات جستجو/بازیابی است.
RETRIEVAL_DOCUMENT مشخص می‌کند که متن داده شده، سندی از مجموعه‌ی مورد جستجو است.
SEMANTIC_SIMILARITY مشخص می‌کند که متن داده شده برای STS استفاده خواهد شد.
CLASSIFICATION مشخص می‌کند که متن داده شده طبقه‌بندی خواهد شد.
CLUSTERING مشخص می‌کند که از جاسازی‌ها برای خوشه‌بندی استفاده خواهد شد.
QUESTION_ANSWERING مشخص می‌کند که متن داده شده برای پاسخ به سوال استفاده خواهد شد.
FACT_VERIFICATION مشخص می‌کند که متن داده شده برای تأیید صحت استفاده خواهد شد.
CODE_RETRIEVAL_QUERY مشخص می‌کند که متن داده شده برای بازیابی کد استفاده خواهد شد.

جاسازی دسته‌ای محتوا

منبعی که نشان‌دهنده‌ی مجموعه‌ای از درخواست‌های EmbedContent است.

فیلدها
string model

الزامی. نام Model که برای تولید تکمیل استفاده می‌شود.

قالب: models/{model} .

string name

فقط خروجی. شناسه. نام منبع دسته.

قالب: batches/{batchId} .

string displayName

الزامی. نام تعریف‌شده توسط کاربر برای این دسته.

شیء inputConfig object ( InputEmbedContentConfig )

الزامی. پیکربندی ورودی نمونه‌هایی که پردازش دسته‌ای روی آنها انجام می‌شود.

شیء output object ( EmbedContentBatchOutput )

فقط خروجی. خروجی درخواست دسته‌ای.

رشته‌ی createTime string ( Timestamp format)

فقط خروجی. زمانی که دسته ایجاد شده است.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

رشته endTime string ( Timestamp format)

فقط خروجی. زمانی که پردازش دسته‌ای تکمیل شده است.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

رشته updateTime string ( Timestamp format)

فقط خروجی. زمانی که دسته آخرین بار به‌روزرسانی شده است.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

شیء batchStats object ( EmbedContentBatchStats )

فقط خروجی. آمار مربوط به دسته.

شمارشگر state enum ( BatchState )

فقط خروجی. وضعیت دسته.

رشته priority string ( int64 format)

اختیاری. اولویت دسته. دسته‌هایی با مقدار اولویت بالاتر قبل از دسته‌هایی با مقدار اولویت پایین‌تر پردازش می‌شوند. مقادیر منفی مجاز هستند. پیش‌فرض ۰ است.

نمایش JSON
{
  "model": string,
  "name": string,
  "displayName": string,
  "inputConfig": {
    object (InputEmbedContentConfig)
  },
  "output": {
    object (EmbedContentBatchOutput)
  },
  "createTime": string,
  "endTime": string,
  "updateTime": string,
  "batchStats": {
    object (EmbedContentBatchStats)
  },
  "state": enum (BatchState),
  "priority": string
}

پیکربندی محتوا/ورودی/جاسازی

ورودی درخواست دسته‌ای را پیکربندی می‌کند.

فیلدها
نوع source Union type
الزامی. منبع ورودی. source می‌تواند فقط یکی از موارد زیر باشد:
string fileName

نام File که شامل درخواست‌های ورودی است.

شیء requests object ( InlinedEmbedContentRequests )

درخواست‌هایی که قرار است در یک دسته پردازش شوند.

نمایش JSON
{

  // source
  "fileName": string,
  "requests": {
    object (InlinedEmbedContentRequests)
  }
  // Union type
}

درخواست‌های درون‌خطی جاسازی محتوا

درخواست‌هایی که قرار است در دسته پردازش شوند، در صورتی که به عنوان بخشی از درخواست ایجاد دسته ارائه شده باشند.

فیلدها
شیء requests[] object ( InlinedEmbedContentRequest )

الزامی. درخواست‌هایی که باید در دسته پردازش شوند.

نمایش JSON
{
  "requests": [
    {
      object (InlinedEmbedContentRequest)
    }
  ]
}

درخواست محتوای جاسازی‌شده‌ی درون‌خطی

درخواستی که قرار است در دسته پردازش شود.

فیلدها
شیء request object ( EmbedContentRequest )

الزامی. درخواستی که قرار است در دسته پردازش شود.

شیء metadata object ( Struct format)

اختیاری. فراداده‌ای که قرار است به درخواست مرتبط شود.

نمایش JSON
{
  "request": {
    object (EmbedContentRequest)
  },
  "metadata": {
    object
  }
}

خروجی دسته‌ای محتوا (EmbedContentBatchOutput)

خروجی یک درخواست دسته‌ای. این خروجی در AsyncBatchEmbedContentResponse یا فیلد EmbedContentBatch.output برگردانده می‌شود.

فیلدها
Union type output اتحادیه
خروجی درخواست دسته‌ای. output می‌تواند فقط یکی از موارد زیر باشد:
string responsesFile

فقط خروجی. شناسه فایل حاوی پاسخ‌ها. این فایل یک فایل JSONL با یک پاسخ در هر خط خواهد بود. پاسخ‌ها پیام‌های EmbedContentResponse با فرمت JSON خواهند بود. پاسخ‌ها به همان ترتیب درخواست‌های ورودی نوشته می‌شوند.

شیء inlinedResponses object ( InlinedEmbedContentResponses )

فقط خروجی. پاسخ‌ها به درخواست‌های موجود در دسته. هنگام ساخت دسته با استفاده از درخواست‌های درون‌خطی، بازگردانده می‌شود. پاسخ‌ها به همان ترتیب درخواست‌های ورودی خواهند بود.

نمایش JSON
{

  // output
  "responsesFile": string,
  "inlinedResponses": {
    object (InlinedEmbedContentResponses)
  }
  // Union type
}

پاسخ‌های درون‌خطی EmbedContent

پاسخ به درخواست‌های موجود در دسته.

فیلدها
شیء inlinedResponses[] object ( InlinedEmbedContentResponse )

فقط خروجی. پاسخ‌ها به درخواست‌های موجود در دسته.

نمایش JSON
{
  "inlinedResponses": [
    {
      object (InlinedEmbedContentResponse)
    }
  ]
}

پاسخ درون‌خطی EmbedContent

پاسخ به یک درخواست واحد در دسته.

فیلدها
شیء metadata object ( Struct format)

فقط خروجی. فراداده مرتبط با درخواست.

Union type output اتحادیه
خروجی درخواست. output فقط می‌تواند یکی از موارد زیر باشد:
شیء error object ( Status )

فقط خروجی. خطایی که هنگام پردازش درخواست رخ داده است.

شیء response object ( EmbedContentResponse )

فقط خروجی. پاسخ به درخواست.

نمایش JSON
{
  "metadata": {
    object
  },

  // output
  "error": {
    object (Status)
  },
  "response": {
    object (EmbedContentResponse)
  }
  // Union type
}

آمار دسته‌ای محتوا (EmbedContentBatchStats)

آمار مربوط به دسته.

فیلدها
رشته requestCount string ( int64 format)

فقط خروجی. تعداد درخواست‌های موجود در دسته.

رشته‌ی successfulRequestCount string ( int64 format)

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

رشته failedRequestCount string ( int64 format)

فقط خروجی. تعداد درخواست‌هایی که پردازش نشده‌اند.

رشته‌ی pendingRequestCount string ( int64 format)

فقط خروجی. تعداد درخواست‌هایی که هنوز در انتظار پردازش هستند.

نمایش JSON
{
  "requestCount": string,
  "successfulRequestCount": string,
  "failedRequestCount": string,
  "pendingRequestCount": string
}