Embeddings

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

الطريقة: models.embedContent

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

نقطة نهاية

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

import google.generativeai as genai

text = "Hello World!"
result = genai.embed_content(
    model="models/text-embedding-004", content=text, output_dimensionality=10
)
print(result["embedding"])

Node.js

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({
  model: "text-embedding-004",
});

const result = await model.embedContent("Hello world!");

console.log(result.embedding);

صَدفة

curl "https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:embedContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model": "models/text-embedding-004",
    "content": {
    "parts":[{
      "text": "Hello world"}]}, }' 2> /dev/null | head

نص الاستجابة

الردّ على 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

import google.generativeai as genai

texts = [
    "What is the meaning of life?",
    "How much wood would a woodchuck chuck?",
    "How does the brain work?",
]
result = genai.embed_content(
    model="models/text-embedding-004", content=texts, output_dimensionality=10
)
print(result)

Node.js

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({
  model: "text-embedding-004",
});

function textToRequest(text) {
  return { content: { role: "user", parts: [{ text }] } };
}

const result = await model.batchEmbedContents({
  requests: [
    textToRequest("What is the meaning of life?"),
    textToRequest("How much wood would a woodchuck chuck?"),
    textToRequest("How does the brain work?"),
  ],
});

console.log(result.embeddings);

صَدفة

curl "https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:batchEmbedContents?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"requests": [{
      "model": "models/text-embedding-004",
      "content": {
      "parts":[{
        "text": "What is the meaning of life?"}]}, },
      {
      "model": "models/text-embedding-004",
      "content": {
      "parts":[{
        "text": "How much wood would a woodchuck chuck?"}]}, },
      {
      "model": "models/text-embedding-004",
      "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 تشير هذه العلامة إلى أنّ النص المقدَّم سيُستخدم للتحقق من صحة الأخبار.