Embeddings

التمثيلات المضمّنة هي تمثيل رقمي لإدخال نصي يتيح عددًا من حالات الاستخدام الفريدة، مثل التجميع والقياس حسب التشابه واسترجاع المعلومات. للحصول على مقدمة، يمكنك الاطّلاع على دليل التضمين.

على عكس نماذج الذكاء الاصطناعي التوليدي التي تنشئ محتوًى جديدًا، يهدف نموذج Gemini Embedding إلى تحويل تنسيق بيانات الإدخال إلى تمثيل رقمي فقط. في حين أنّ Google مسؤولة عن توفير نموذج تضمين يحوّل تنسيق بيانات الإدخال إلى التنسيق الرقمي المطلوب، يحتفظ المستخدمون بالمسؤولية الكاملة عن البيانات التي يدخلونها وعمليات التضمين الناتجة. يشير استخدامك لنموذج Gemini Embedding إلى تأكيدك على امتلاك الحقوق اللازمة لأي محتوى يتم تحميله. ويجب عدم إنشاء محتوى ينتهك حقوق الملكية الفكرية أو حقوق الخصوصية للآخرين. يخضع استخدامك لهذه الخدمة لسياسة الاستخدام المحظور وبنود خدمة Google.

الطريقة: models.embedContent

تنشئ هذه الدالة متّجه تضمين نصي من الإدخال Content باستخدام نموذج Gemini Embedding المحدّد.

نقطة نهاية

post https://generativelanguage.googleapis.com/v1beta/{model=models/*}:embedContent

مَعلمات المسار

model string

مطلوب. اسم المورد الخاص بالنموذج. ويُستخدَم هذا المعرّف في النموذج.

يجب أن يتطابق هذا الاسم مع اسم نموذج يعرضه الأسلوب models.list.

التنسيق: models/{model} يتّخذ الشكل models/{model}.

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

الحقول
content object (Content)

مطلوب. المحتوى المطلوب تضمينه سيتم احتساب حقول parts.text فقط.

taskType enum (TaskType)

اختياريّ. نوع المهمة الاختياري الذي سيتم استخدام التضمينات فيه لا تتوفّر هذه الميزة على الطُرز القديمة (models/embedding-001).

title string

اختياريّ. عنوان اختياري للنص لا يمكن استخدامها إلا عندما تكون قيمة TaskType هي RETRIEVAL_DOCUMENT.

ملاحظة: يؤدي تحديد title لـ RETRIEVAL_DOCUMENT إلى توفير تضمينات ذات جودة أفضل لاسترجاع البيانات.

outputDimensionality integer

اختياريّ. سمة اختيارية مخفَّضة لتضمين الناتج. في حال ضبط هذا الخيار، يتم اقتطاع القيم الزائدة في التضمين الناتج من النهاية. تتوفّر هذه الميزة على الطُرز الأحدث منذ عام 2024 فقط. لا يمكنك ضبط هذه القيمة في حال استخدام النموذج السابق (models/embedding-001).

مثال على الطلب

Python

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

Go

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.

نقطة نهاية

post https://generativelanguage.googleapis.com/v1beta/{model=models/*}:batchEmbedContents

مَعلمات المسار

model string

مطلوب. اسم المورد الخاص بالنموذج. ويُستخدَم هذا المعرّف في النموذج.

يجب أن يتطابق هذا الاسم مع اسم نموذج يعرضه الأسلوب models.list.

التنسيق: models/{model} يتّخذ الشكل models/{model}.

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

الحقول
requests[] object (EmbedContentRequest)

مطلوب. تضمين الطلبات في الدفعة يجب أن يتطابق النموذج في كل من هذه الطلبات مع النموذج المحدّد BatchEmbedContentsRequest.model.

مثال على الطلب

Python

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

Go

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 لتجنُّب حدوث أي التباس.

نقطة نهاية

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

مَعلمات المسار

batch.model string

مطلوب. اسم Model المطلوب استخدامه لإنشاء الإكمال.

التنسيق: models/{model} تتّخذ الشكل models/{model}.

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

الحقول
batch.name string

النتائج فقط. المعرّف اسم المورد الخاص بالدفعة.

التنسيق: batches/{batchId}

batch.displayName string

مطلوب. اسم هذه الدفعة الذي حدّده المستخدم

batch.inputConfig object (InputEmbedContentConfig)

مطلوب. إدخال إعدادات المثيلات التي يتم إجراء المعالجة المجمّعة عليها

batch.output object (EmbedContentBatchOutput)

النتائج فقط. ناتج طلب الدفعة

batch.createTime string (Timestamp format)

النتائج فقط. الوقت الذي تم فيه إنشاء الدفعة

يستخدم RFC 3339، حيث سيكون الناتج الذي يتم إنشاؤه دائمًا Z-normalized وسيستخدم 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-normalized وسيستخدم 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-normalized وسيستخدم 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 للنموذج المراد تضمينه

الحقول
model string

مطلوب. اسم المورد الخاص بالنموذج. ويُستخدَم هذا المعرّف في النموذج.

يجب أن يتطابق هذا الاسم مع اسم نموذج يعرضه الأسلوب models.list.

التنسيق: models/{model}

content object (Content)

مطلوب. المحتوى المطلوب تضمينه سيتم احتساب حقول parts.text فقط.

taskType enum (TaskType)

اختياريّ. نوع المهمة الاختياري الذي سيتم استخدام التضمينات فيه لا تتوفّر هذه الميزة على الطُرز القديمة (models/embedding-001).

title string

اختياريّ. عنوان اختياري للنص لا يمكن استخدامها إلا عندما تكون قيمة 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
  ]
}

TaskType

نوع المهمة التي سيتم استخدام التضمين فيها.

عمليات التعداد
TASK_TYPE_UNSPECIFIED قيمة غير مضبوطة، وسيتم ضبطها تلقائيًا على إحدى قيم التعداد الأخرى.
RETRIEVAL_QUERY تحدّد هذه السمة أنّ النص المحدّد هو طلب بحث في إعداد بحث/استرجاع.
RETRIEVAL_DOCUMENT تحدّد هذه السمة أنّ النص المحدّد هو مستند من مجموعة المستندات التي يتم البحث فيها.
SEMANTIC_SIMILARITY تحدّد هذه السمة أنّ النص المحدّد سيُستخدَم في البحث الذكي.
CLASSIFICATION تحدّد هذه السمة أنّ النص المحدّد سيتم تصنيفه.
CLUSTERING تحدِّد هذه السمة أنّه سيتم استخدام التضمينات للتجميع.
QUESTION_ANSWERING تحدّد هذه السمة أنّ النص المحدّد سيُستخدم للإجابة عن الأسئلة.
FACT_VERIFICATION تحدّد هذه السمة أنّ النص المحدّد سيُستخدَم للتحقّق من صحة المعلومات.
CODE_RETRIEVAL_QUERY تحدّد هذه السمة أنّه سيتم استخدام النص المحدّد لاسترداد الرمز.

EmbedContentBatch

مورد يمثّل مجموعة من طلبات EmbedContent.

الحقول
model string

مطلوب. اسم Model المطلوب استخدامه لإنشاء الإكمال.

التنسيق: models/{model}

name string

النتائج فقط. المعرّف اسم المورد الخاص بالدفعة.

التنسيق: batches/{batchId}

displayName string

مطلوب. اسم هذه الدفعة الذي حدّده المستخدم

inputConfig object (InputEmbedContentConfig)

مطلوب. إدخال إعدادات المثيلات التي يتم إجراء المعالجة المجمّعة عليها

output object (EmbedContentBatchOutput)

النتائج فقط. ناتج طلب الدفعة

createTime string (Timestamp format)

النتائج فقط. الوقت الذي تم فيه إنشاء الدفعة

يستخدم RFC 3339، حيث سيكون الناتج الذي يتم إنشاؤه دائمًا Z-normalized وسيستخدم 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-normalized وسيستخدم 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-normalized وسيستخدم 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 إحدى القيم التالية فقط:
fileName string

اسم 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.

الحقول
output Union type
ناتج طلب الدفعة يمكن أن تكون 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)

النتائج فقط. البيانات الوصفية المرتبطة بالطلب

output Union type
ناتج الطلب يمكن أن تكون 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
}