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

انتقال

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?"}]}
    }'

نص الاستجابة

الردّ على EmbedContentRequest

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

الحقول
embedding object (ContentEmbedding)

النتائج فقط. التمثيل المتّجهي الذي تم إنشاؤه من المحتوى المُدخَل

تمثيل JSON
{
  "embedding": {
    object (ContentEmbedding)
  }
}

الطريقة: 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);

انتقال

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)
    }
  ]
}

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
}

ContentEmbedding

قائمة بالأرقام العشرية التي تمثّل تضمينًا

الحقول
values[] number

قيم التضمين

تمثيل JSON
{
  "values": [
    number
  ]
}

TaskType

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

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