Embeddings

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

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

روش: 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

اختیاری. ابعاد کاهش یافته اختیاری برای جاسازی خروجی. اگر تنظیم شود، مقادیر بیش از حد در جاسازی خروجی از انتها کوتاه می شوند. فقط از سال 2024 توسط مدل های جدیدتر پشتیبانی می شود. در صورت استفاده از مدل قبلی ( 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)

Node.js

// 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)

Node.js

// 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 را برای پردازش دسته ای در صف قرار می دهد. ما یک handler 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 نرمال می شود و از 0، 3، 6 یا 9 رقم کسری استفاده می کند. افست های غیر از "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 نرمال می شود و از 0، 3، 6 یا 9 رقم کسری استفاده می کند. افست های غیر از "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 نرمال می شود و از 0، 3، 6 یا 9 رقم کسری استفاده می کند. افست های غیر از "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)

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

بدن پاسخگو

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

EmbedContentRequest

درخواست حاوی Content برای جاسازی مدل.

فیلدها
string model

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

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

قالب: models/{model}

شی content object ( Content )

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

taskType enum ( TaskType )

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

string title

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

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

outputDimensionality integer

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

نمایندگی JSON
{
  "model": string,
  "content": {
    object (Content)
  },
  "taskType": enum (TaskType),
  "title": string,
  "outputDimensionality": integer
}

EmbedContentResponse

پاسخ به EmbedContentRequest .

فیلدها
embedding object ( ContentEmbedding )

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

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

ContentEmbedding

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

فیلدها
values[] number

مقادیر تعبیه شده

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

نوع وظیفه

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

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

EmbedContentBatch

منبعی که مجموعه ای از درخواست های 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 نرمال می شود و از 0، 3، 6 یا 9 رقم کسری استفاده می کند. افست های غیر از "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 نرمال می شود و از 0، 3، 6 یا 9 رقم کسری استفاده می کند. افست های غیر از "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 نرمال می شود و از 0، 3، 6 یا 9 رقم کسری استفاده می کند. افست های غیر از "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)

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

نمایندگی 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
}

InputEmbedContentConfig

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

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

نام File حاوی درخواست های ورودی.

شی requests object ( InlinedEmbedContentRequests )

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

نمایندگی JSON
{

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

InlinedEmbedContentRequests

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

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

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

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

InlinedEmbedContentRequest

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

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

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

شیء metadata object ( Struct format)

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

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

EmbedContentBatchOutput

خروجی درخواست دسته ای این در قسمت AsyncBatchEmbedContentResponse یا قسمت EmbedContentBatch.output برگردانده می شود.

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

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

شی inlinedResponses object ( InlinedEmbedContentResponses )

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

نمایندگی JSON
{

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

InlinedEmbedContentResponses

پاسخ به درخواست های دسته ای

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

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

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

InlinedEmbedContentResponse

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

فیلدها
شیء 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)

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

string ( int64 format) failedRequestCount (فرمت int64)

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

string ( int64 format) pendingRequestCount (فرمت int64)

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

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