التضمينات

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

يُعدّ أحدث نموذج، وهو gemini-embedding-2، أول نموذج تضمين متعدد الوسائط في Gemini API. فهو يربط النصوص والصور والفيديوهات والمحتوى الصوتي والمستندات في مساحة تضمين موحّدة، ما يتيح البحث والتصنيف والتجميع على مستوى الوسائط المتعددة بأكثر من 100 لغة. لمزيد من المعلومات، يُرجى الاطّلاع على قسم التضمينات المتعددة الوسائط. بالنسبة إلى حالات الاستخدام التي تتطلّب معالجة النصوص فقط، يظلّ gemini-embedding-001 متاحًا.

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

جارٍ إنشاء التضمينات

استخدِم طريقة embedContent لإنشاء تضمينات نصية:

Python

from google import genai

client = genai.Client()

result = client.models.embed_content(
        model="gemini-embedding-2",
        contents="What is the meaning of life?"
)

print(result.embeddings)

JavaScript

import { GoogleGenAI } from "@google/genai";

async function main() {

    const ai = new GoogleGenAI({});

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: 'What is the meaning of life?',
    });

    console.log(response.embeddings);
}

main();

جافا

import com.google.genai.Client;
import com.google.genai.types.EmbedContentResponse;

Client client = new Client();

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", "What is the meaning of life?", null);

System.out.println(response.embeddings().orElse(null));

Go

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    contents := []*genai.Content{
        genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),
    }
    result, err := client.Models.EmbedContent(ctx,
        "gemini-embedding-2",
        contents,
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }

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

REST

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

تحديد نوع المهمة لتحسين الأداء

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

أنواع المهام في Embeddings 2

بالنسبة إلى المهام النصية فقط باستخدام gemini-embedding-2، ننصحك بشدة بإضافة تعليمات المهمة في طلبك. ويمكن إجراء ذلك من خلال تنسيق طلب البحث والمستند باستخدام بادئة المهمة الصحيحة.

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

توضّح الجداول التالية أمثلة على كيفية تنسيق طلبات البحث والمستندات لحالات الاستخدام المتماثلة وغير المتماثلة باستخدام نموذج gemini-embedding-2.

حالات استخدام الاسترجاع (تنسيق غير متماثل)

في حالات الاستخدام غير المتماثلة، أضِف بادئة المهمة إلى طلب البحث وطبِّق بنية المستند على المحتوى الذي تريد تضمينه واسترداده.

حالة الاستخدام بنية طلب البحث بنية المستند
طلب البحث task: search result | query: {content} title: {title} | text: {content}
في حال عدم توفّر عنوان، استخدِم title: none.
الإجابة عن الأسئلة task: question answering | query: {content} title: {title} | text: {content}
التحقّق من صحة الأخبار task: fact checking | query: {content} title: {title} | text: {content}
استرداد الرمز task: code retrieval | query: {content} title: {title} | text: {content}

مثال على الاستخدام

Python

# Generate embedding for a task's query. Use your correct task here:
def prepare_query(query):
    # return f"task: question answering | query: {query}"
    # return f"task: fact checking | query: {query}"
    # return f"task: code retrieval | query: {query}"
    return f"task: search result | query: {query}"

# Generate embedding for document of an asymmetric retrieval task:
def prepare_document(content, title=None):
    if title is None:
        title = "none"
    return f"title: {title} | text: {content}"

حالات الاستخدام التي تتطلّب إدخالاً واحدًا (التنسيق المتماثل)

In symmetric use cases, for the same task, use the same formatting for the query and the document.

حالة الاستخدام بنية الإدخال
التصنيف task: classification | query: {content}
التجميع task: clustering | query: {content}
التشابه الدلالي task: sentence similarity | query: {content}
لا تستخدِم هذا الحقل للبحث أو الاسترداد. وهو مخصّص للتشابه النصي الدلالي.

مثال على الاستخدام

Python

# Generate embedding for query & document of your task.
def prepare_query_and_document(content):
    # return f'task: clustering | query: {content}'
    # return f'task: sentence similarity | query: {content}'
    return f'task: classification | query: {content}'

من المهم استخدام المهمة بشكل متّسق. على سبيل المثال، إذا كانت المستندات مضمّنة مع f'task: classification | query: {content}'، يجب أيضًا تضمين طلب البحث باتّباع تنسيق المهمة هذا.

أنواع المهام مع Embeddings 1

بالنسبة إلى gemini-embedding-001، يمكنك تحديد task_type في طريقة embedContent. للحصول على قائمة كاملة بأنواع المهام المتوافقة، يُرجى الاطّلاع على جدول أنواع المهام المتوافقة.

يوضّح المثال التالي كيفية استخدام SEMANTIC_SIMILARITY للتحقّق من مدى تشابه سلاسل النصوص في المعنى.

Python

from google import genai
from google.genai import types
import pandas as pd
from sklearn.metrics.pairwise import cosine_similarity

client = genai.Client()

texts = [
    "What is the meaning of life?",
    "What is the purpose of existence?",
    "How do I bake a cake?",
]

result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=texts,
    config=types.EmbedContentConfig(task_type="SEMANTIC_SIMILARITY")
)

# Create a 3x3 table to show the similarity matrix
df = pd.DataFrame(
    cosine_similarity([e.values for e in result.embeddings]),
    index=texts,
    columns=texts,
)

print(df)

JavaScript

import { GoogleGenAI } from "@google/genai";
// npm i compute-cosine-similarity
import * as cosineSimilarity from "compute-cosine-similarity";

async function main() {
    const ai = new GoogleGenAI({});

    const texts = [
        "What is the meaning of life?",
        "What is the purpose of existence?",
        "How do I bake a cake?",
    ];

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-001',
        contents: texts,
        config: { taskType: 'SEMANTIC_SIMILARITY' },
    });

    const embeddings = response.embeddings.map(e => e.values);

    for (let i = 0; i < texts.length; i++) {
        for (let j = i + 1; j < texts.length; j++) {
            const text1 = texts[i];
            const text2 = texts[j];
            const similarity = cosineSimilarity(embeddings[i], embeddings[j]);
            console.log(`Similarity between '${text1}' and '${text2}': ${similarity.toFixed(4)}`);
        }
    }
}

main();

جافا

import java.util.Arrays;
import com.google.genai.Client;
import com.google.genai.types.ContentEmbedding;
import com.google.genai.types.EmbedContentConfig;
import com.google.genai.types.EmbedContentResponse;
import java.util.List;

Client client = new Client();

List<String> texts =
    Arrays.asList(
        "What is the meaning of life?",
        "What is the purpose of existence?",
        "How do I bake a cake?");

EmbedContentConfig config =
    EmbedContentConfig.builder().taskType("SEMANTIC_SIMILARITY").build();

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-001", texts, config);

List<ContentEmbedding> embeddings = response.embeddings().get();

for (int i = 0; i < texts.size(); i++) {
  for (int j = i + 1; j < texts.size(); j++) {
    List<Float> v1 = embeddings.get(i).values().get();
    List<Float> v2 = embeddings.get(j).values().get();
    double dotProduct = 0.0;
    double normA = 0.0;
    double normB = 0.0;
    for (int k = 0; k < v1.size(); k++) {
      dotProduct += v1.get(k) * v2.get(k);
      normA += v1.get(k) * v1.get(k);
      normB += v2.get(k) * v2.get(k);
    }
    double similarity = dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
    System.out.printf(
        "Similarity between '%s' and '%s': %.4f%n", texts.get(i), texts.get(j), similarity);
  }
}

Go

package main

import (
    "context"
    "fmt"
    "log"
    "math"

    "google.golang.org/genai"
)

// cosineSimilarity calculates the similarity between two vectors.
func cosineSimilarity(a, b []float32) (float64, error) {
    if len(a) != len(b) {
        return 0, fmt.Errorf("vectors must have the same length")
    }

    var dotProduct, aMagnitude, bMagnitude float64
    for i := 0; i < len(a); i++ {
        dotProduct += float64(a[i] * b[i])
        aMagnitude += float64(a[i] * a[i])
        bMagnitude += float64(b[i] * b[i])
    }

    if aMagnitude == 0 || bMagnitude == 0 {
        return 0, nil
    }

    return dotProduct / (math.Sqrt(aMagnitude) * math.Sqrt(bMagnitude)), nil
}

func main() {
    ctx := context.Background()
    client, _ := genai.NewClient(ctx, nil)
    defer client.Close()

    texts := []string{
        "What is the meaning of life?",
        "What is the purpose of existence?",
        "How do I bake a cake?",
    }

    var contents []*genai.Content
    for _, text := range texts {
        contents = append(contents, genai.NewContentFromText(text, genai.RoleUser))
    }

    result, _ := client.Models.EmbedContent(ctx,
        "gemini-embedding-001",
        contents,
        &genai.EmbedContentRequest{TaskType: genai.TaskTypeSemanticSimilarity},
    )

    embeddings := result.Embeddings

    for i := 0; i < len(texts); i++ {
        for j := i + 1; j < len(texts); j++ {
            similarity, _ := cosineSimilarity(embeddings[i].Values, embeddings[j].Values)
            fmt.Printf("Similarity between '%s' and '%s': %.4f\n", texts[i], texts[j], similarity)
        }
    }
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -d '{
    "taskType": "SEMANTIC_SIMILARITY",
    "content": {
        "parts": [
        {
            "text": "What is the meaning of life?"
        },
        {
            "text": "How much wood would a woodchuck chuck?"
        },
        {
            "text": "How does the brain work?"
        }
        ]
    }
    }'

ستوضّح مقتطفات الرموز مدى تشابه أجزاء النص المختلفة مع بعضها البعض عند تشغيلها.

أنواع المهام المتوافقة

أنواع المهام المتوافقة مع "gemini-embedding-001":

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

التحكّم في حجم التضمين

يتم تدريب كل من gemini-embedding-001 وgemini-embedding-2 باستخدام تقنية Matryoshka Representation Learning (MRL) التي تعلّم النموذج كيفية تعلُّم التضمينات العالية الأبعاد التي تحتوي على أجزاء أولية (أو بادئات) مفيدة أيضًا، وهي نُسخ أبسط من البيانات نفسها.

استخدِم المَعلمة output_dimensionality للتحكّم في حجم متجه التضمين الناتج. يؤدي اختيار بُعد أصغر للمخرجات إلى توفير مساحة التخزين وزيادة كفاءة العمليات الحسابية للتطبيقات اللاحقة، مع التضحية بالقليل من حيث الجودة. يُخرج كلا النموذجين تلقائيًا تضمينًا بأبعاد 3072، ولكن يمكنك اقتطاعه إلى حجم أصغر بدون فقدان الجودة لتوفير مساحة تخزين. ننصح باستخدام أبعاد الإخراج 768 أو 1536 أو 3072.

Python

from google import genai
from google.genai import types

client = genai.Client()

result = client.models.embed_content(
    model="gemini-embedding-2",
    contents="What is the meaning of life?",
    config=types.EmbedContentConfig(output_dimensionality=768)
)

[embedding_obj] = result.embeddings
embedding_length = len(embedding_obj.values)

print(f"Length of embedding: {embedding_length}")

JavaScript

import { GoogleGenAI } from "@google/genai";

async function main() {
    const ai = new GoogleGenAI({});

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: 'What is the meaning of life?',
        config: { outputDimensionality: 768 },
    });

    const embeddingLength = response.embeddings[0].values.length;
    console.log(`Length of embedding: ${embeddingLength}`);
}

main();

جافا

import com.google.genai.Client;
import com.google.genai.types.ContentEmbedding;
import com.google.genai.types.EmbedContentConfig;
import com.google.genai.types.EmbedContentResponse;

Client client = new Client();

EmbedContentConfig config =
    EmbedContentConfig.builder().outputDimensionality(768).build();

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", "What is the meaning of life?", config);

ContentEmbedding embeddingObj = response.embeddings().get().get(0);
int embeddingLength = embeddingObj.values().get().size();

System.out.println("Length of embedding: " + embeddingLength);

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    // The client uses Application Default Credentials.
    // Authenticate with 'gcloud auth application-default login'.
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    contents := []*genai.Content{
        genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),
    }

    result, err := client.Models.EmbedContent(ctx,
        "gemini-embedding-2",
        contents,
        &genai.EmbedContentRequest{OutputDimensionality: 768},
    )
    if err != nil {
        log.Fatal(err)
    }

    embedding := result.Embeddings[0]
    embeddingLength := len(embedding.Values)
    fmt.Printf("Length of embedding: %d\n", embeddingLength)
}

REST

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

مثال على الناتج من مقتطف الرمز:

Length of embedding: 768

ضمان الجودة للأبعاد الأصغر

While the default 3072-dimension embeddings are always normalized, Gemini Embedding 2 also auto-normalizes truncated dimensions (e.g., 768, 1536). يضمن ذلك احتساب التشابه الدلالي من خلال اتجاه المتجه بدلاً من المقدار، ما يوفّر نتائج أكثر دقة على الفور.

النماذج القديمة: إذا كنت تستخدم gemini-embedding-001، عليك تسوية الأبعاد غير 3072 يدويًا على النحو التالي:

Python

import numpy as np
from numpy.linalg import norm

# Only for embeddings from `gemini-embedding-001`
embedding_values_np = np.array(embedding_obj.values)
normed_embedding = embedding_values_np / np.linalg.norm(embedding_values_np)

print(f"Normed embedding length: {len(normed_embedding)}")
print(f"Norm of normed embedding: {np.linalg.norm(normed_embedding):.6f}") # Should be very close to 1

مثال على الناتج من مقتطف الرمز هذا:

Normed embedding length: 768
Norm of normed embedding: 1.000000

يعرض الجدول التالي نتائج MTEB، وهو مقياس أداء شائع الاستخدام للتضمينات، لمختلف الأبعاد. وتُظهر النتيجة أنّ الأداء لا يرتبط بشكل صارم بحجم بُعد التضمين، إذ تحقّق الأبعاد المنخفضة نتائج مماثلة لنظيراتها ذات الأبعاد الأعلى.

سمة MRL نتيجة MTEB ‏ (Gemini Embedding 001)
2048 68.16
1536 68.17
768 67.99
512 67.55
256 66.19
128 63.31

التضمينات المتعددة الوسائط

يتيح نموذج gemini-embedding-2 إدخال بيانات متعددة الوسائط، ما يسمح لك بتضمين محتوى الصور والفيديو والصوت والمستندات إلى جانب النص. يتم ربط جميع الأنماط بمساحة التضمين نفسها، ما يتيح البحث والمقارنة بين الأنماط المختلفة.

الوسائط والحدود المسموح بها

الحد الأقصى الإجمالي لعدد الرموز المميّزة في الإدخال هو 8,192 رمزًا.

نمط البيانات المواصفات والحدود
Text يمكنه معالجة ما يصل إلى 8,192 رمز مميّز.
صورة يمكنك إرسال 6 صور كحدّ أقصى في كل طلب. التنسيقات المتوافقة: PNG وJPEG.
الصوت الحدّ الأقصى للمدّة هو 180 ثانية. التنسيقات المتوافقة: MP3 وWAV.
الفيديو الحدّ الأقصى للمدّة هو 120 ثانية. التنسيقات المتوافقة: MP4 وMOV. برامج الترميز المتوافقة: H264 وH265 وAV1 وVP9
يعالج النظام 32 لقطة كحدّ أقصى لكل فيديو: يتم أخذ عيّنات من الفيديوهات القصيرة (أقل من أو تساوي 32 ثانية) بمعدّل لقطة واحدة في الثانية، بينما يتم أخذ عيّنات من الفيديوهات الأطول بشكل موحّد لتصل إلى 32 لقطة. لا تتم معالجة المقاطع الصوتية في ملفات الفيديو.
المستندات (PDF) يمكنك إرسال ملف واحد كحد أقصى لكل طلب، على ألّا يتجاوز 6 صفحات.

تضمين الصور

يوضّح المثال التالي كيفية تضمين صورة باستخدام gemini-embedding-2.

يمكن تقديم الصور كبيانات مضمّنة أو كملفات تم تحميلها من خلال Files API.

Python

from google import genai
from google.genai import types

with open('example.png', 'rb') as f:
    image_bytes = f.read()

client = genai.Client()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        types.Part.from_bytes(
            data=image_bytes,
            mime_type='image/png',
        ),
    ]
)

print(result.embeddings)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const imgBase64 = fs.readFileSync("example.png", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [{
            inlineData: {
                mimeType: 'image/png',
                data: imgBase64,
            },
        }],
    });

    console.log(response.embeddings);
}

main();

جافا

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("example.png"));

Content content = Content.fromParts(Part.fromBytes(imageBytes, "image/png"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

System.out.println(response.embeddings().orElse(null));

REST

IMG_PATH="/path/to/your/image.png"
IMG_BASE64=$(base64 -w0 "${IMG_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [{
                "inline_data": {
                    "mime_type": "image/png",
                    "data": "'"${IMG_BASE64}"'"
                }
            }]
        }
    }'

تجميع التضمينات

عند العمل مع محتوى متعدد الوسائط، تؤثر طريقة تنظيم الإدخال في مخرجات التضمين:

  • أجزاء متعددة (مجمّعة): تؤدي إضافة إدخالات متعددة مباشرةً إلى المَعلمة contents إلى إنشاء تضمين مجمّع واحد لجميع الإدخالات.
  • كائنات Content متعددة (منفصلة): يؤدي تضمين كل إدخال في كائن Content وتمريره في المَعلمة contents إلى عرض تضمينات منفصلة لكل إدخال.
  • التمثيل على مستوى المنشور: بالنسبة إلى العناصر المعقّدة، مثل منشورات وسائل التواصل الاجتماعي التي تتضمّن ملفات وسائط متعددة، ننصح بتجميع تضمينات منفصلة (على سبيل المثال، من خلال حساب المتوسط) لإنشاء تمثيل متسق على مستوى المنشور.

يوضّح المثال التالي كيفية إنشاء تضمين مجمّع واحد لإدخال النص والصورة. ما عليك سوى إضافة إدخالات متعددة إلى المَعلمة contents:

Python

from google import genai
from google.genai import types

client = genai.Client()

with open('dog.png', 'rb') as f:
    image_bytes = f.read()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        "An image of a dog",
        types.Part.from_bytes(
            data=image_bytes,
            mime_type='image/png',
        ),
    ]
)

# This produces one embedding
for embedding in result.embeddings:
    print(embedding.values)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const imgBase64 = fs.readFileSync("dog.png", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [
            'An image of a dog',
            {
                inlineData: {
                    mimeType: 'image/png',
                    data: imgBase64,
                },
            },
        ],
    });

    // This produces one embedding
    for (const embedding of response.embeddings) {
        console.log(embedding.values);
    }
}

main();

جافا

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.ContentEmbedding;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Collections;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("dog.png"));

Content content =
    Content.fromParts(
        Part.fromText("An image of a dog"),
        Part.fromBytes(imageBytes, "image/png"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

// This produces one embedding
for (ContentEmbedding embedding : response.embeddings().orElse(Collections.emptyList())) {
  System.out.println(embedding.values().orElse(Collections.emptyList()));
}

REST

IMG_PATH="/path/to/your/dog.png"
IMG_BASE64=$(base64 -w0 "${IMG_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [
                {"text": "An image of a dog"},
                {
                    "inline_data": {
                        "mime_type": "image/png",
                        "data": "'"${IMG_BASE64}"'"
                    }
                }
            ]
        }
    }'

في المقابل، إذا استخدمت عناصر Content داخل المَعلمة contents، ستعرض الدالة تضمينات منفصلة. ينشئ هذا المثال تضمينات متعددة في طلب تضمين واحد:

Python

from google import genai
from google.genai import types

client = genai.Client()

with open('dog.png', 'rb') as f:
    image_bytes = f.read()

result = client.models.embed_content(
    model="gemini-embedding-2",
    contents=[
        types.Content(parts=[types.Part.from_text(text="task: classification | query: An image of a dog")]),
        types.Content(
            parts=[
                types.Part.from_bytes(
                    data=image_bytes,
                    mime_type="image/png",
                ),
            ]
        ),
    ],
)

# This produces two embeddings
for embedding in result.embeddings:
    print(embedding.values)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const imgBase64 = fs.readFileSync("dog.png", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [
            { parts: [{ text: 'task: classification | query: An image of a dog' }] },
            {
                parts: [{
                    inlineData: {
                        mimeType: 'image/png',
                        data: imgBase64,
                    },
                }],
            },
        ],
    });

    // This produces two embeddings
    for (const embedding of response.embeddings) {
        console.log(embedding.values);
    }
}

main();

جافا

import java.util.Arrays;
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.ContentEmbedding;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Collections;
import java.util.List;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("dog.png"));

List<Content> contents =
    Arrays.asList(
        Content.fromParts(Part.fromText("task: classification | query: An image of a dog")),
        Content.fromParts(Part.fromBytes(imageBytes, "image/png")));

// Embed each Content object separately to produce separate embeddings
for (Content content : contents) {
  EmbedContentResponse response =
      client.models.embedContent("gemini-embedding-2", content, null);
  for (ContentEmbedding embedding : response.embeddings().orElse(Collections.emptyList())) {
    System.out.println(embedding.values().orElse(Collections.emptyList()));
  }
}

REST

IMG_PATH="/path/to/your/dog.png"
IMG_BASE64=$(base64 -w0 "${IMG_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:batchEmbedContents" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "requests": [
            {
                "model": "models/gemini-embedding-2",
                "content": {"parts": [{"text": "task: classification | query: An image of a dog"}]}
            },
            {
                "model": "models/gemini-embedding-2",
                "content": {"parts": [{"inline_data": {"mime_type": "image/png", "data": "'"${IMG_BASE64}"'"}}]}
            }
        ]
    }'

تضمين الصوت

يوضّح المثال التالي كيفية تضمين ملف صوتي باستخدام gemini-embedding-2.

يمكن تقديم الملفات الصوتية كبيانات مضمّنة أو كملفات تم تحميلها من خلال Files API.

Python

from google import genai
from google.genai import types

with open('example.mp3', 'rb') as f:
    audio_bytes = f.read()

client = genai.Client()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        types.Part.from_bytes(
            data=audio_bytes,
            mime_type='audio/mpeg',
        ),
    ]
)

print(result.embeddings)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const audioBase64 = fs.readFileSync("example.mp3", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [{
            inlineData: {
                mimeType: 'audio/mpeg',
                data: audioBase64,
            },
        }],
    });

    console.log(response.embeddings);
}

main();

جافا

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;

Client client = new Client();

byte[] audioBytes = Files.readAllBytes(Paths.get("example.mp3"));

Content content = Content.fromParts(Part.fromBytes(audioBytes, "audio/mpeg"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

System.out.println(response.embeddings().orElse(null));

REST

AUDIO_PATH="/path/to/your/example.mp3"
AUDIO_BASE64=$(base64 -w0 "${AUDIO_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [{
                "inline_data": {
                    "mime_type": "audio/mpeg",
                    "data": "'"${AUDIO_BASE64}"'"
                }
            }]
        }
    }'

تضمين الفيديو

يوضّح المثال التالي كيفية تضمين فيديو باستخدام gemini-embedding-2.

يمكن تقديم الفيديوهات كبيانات مضمّنة أو كملفات تم تحميلها من خلال Files API.

Python

from google import genai
from google.genai import types

client = genai.Client()

with open('example.mp4', 'rb') as f:
    video_bytes = f.read()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        types.Part.from_bytes(
            data=video_bytes,
            mime_type='video/mp4',
        ),
    ]
)

print(result.embeddings[0].values)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const videoBase64 = fs.readFileSync("example.mp4", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [{
            inlineData: {
                mimeType: 'video/mp4',
                data: videoBase64,
            },
        }],
    });

    console.log(response.embeddings);
}

main();

جافا

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Collections;

Client client = new Client();

byte[] videoBytes = Files.readAllBytes(Paths.get("example.mp4"));

Content content = Content.fromParts(Part.fromBytes(videoBytes, "video/mp4"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

System.out.println(
    response.embeddings().get().get(0).values().orElse(Collections.emptyList()));

REST

VIDEO_PATH="/path/to/your/video.mp4"
VIDEO_BASE64=$(base64 -w0 "${VIDEO_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [{
                "inline_data": {
                    "mime_type": "video/mp4",
                    "data": "'"${VIDEO_BASE64}"'"
                }
            }]
        }
    }'

إذا أردت تضمين فيديوهات تزيد مدتها عن 120 ثانية، يمكنك تقسيم الفيديو إلى مقاطع متداخلة وتضمين هذه المقاطع بشكل فردي.

تضمين المستندات

يمكن تضمين المستندات بتنسيق PDF مباشرةً. يعالج النموذج المحتوى المرئي والنصي لكل صفحة.

يمكن تقديم ملفات PDF كبيانات مضمّنة أو كملفات محمّلة من خلال Files API.

كيفية معالجة النموذج لملفات PDF

عند تضمين ملف PDF، يعالج النموذج المستند باستخدام الميزات المرئية والنصية:

  • التمثيل المرئي: يعرض النموذج كل صفحة كصورة، ما يستهلك 258 رمزًا مميزًا لكل صفحة.
  • استخراج النص: يستخرج النموذج النص من المستند. بالنسبة إلى ملفات PDF الأصلية (التي تحتوي على نص رقمي)، يستخرج النموذج النص مباشرةً. بالنسبة إلى ملفات PDF الممسوحة ضوئيًا (التي تحتوي على صور للنص)، يشغّل النموذج تلقائيًا تقنية التعرّف البصري على الأحرف (OCR) لاستخراج النص.

لاحتساب إجمالي عدد الرموز المميّزة لملف PDF، أضِف الرموز المميّزة المرئية (258 لكل صفحة) إلى الرموز المميّزة النصية. يجب أن تتوافق الإدخالات مع الحدّ الأقصى لعدد الرموز المميّزة في النموذج وهو 8,192 (مشترَك بين جميع الأساليب). يقتطع النظام تلقائيًا المدخلات التي تتجاوز هذا الحدّ.

الحدود القصوى لملفات PDF

  • عدد الملفات لكل طلب: يمكنك إرسال ملف PDF واحد كحدّ أقصى.
  • الحدّ الأقصى لعدد الصفحات: يمكنكم إرسال 6 صفحات كحدّ أقصى لكل ملف. للحصول على أفضل جودة، ننصح بشدة باستخدام صفحة واحدة لكل ملف PDF.

يوضّح المثال التالي كيفية تضمين ملف PDF باستخدام gemini-embedding-2:

Python

from google import genai
from google.genai import types

with open('example.pdf', 'rb') as f:
    pdf_bytes = f.read()

client = genai.Client()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        types.Part.from_bytes(
            data=pdf_bytes,
            mime_type='application/pdf',
        ),
    ]
)

print(result.embeddings)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const pdfBase64 = fs.readFileSync("example.pdf", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [{
            inlineData: {
                mimeType: 'application/pdf',
                data: pdfBase64,
            },
        }],
    });

    console.log(response.embeddings);
}

main();

جافا

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;

Client client = new Client();

byte[] pdfBytes = Files.readAllBytes(Paths.get("example.pdf"));

Content content = Content.fromParts(Part.fromBytes(pdfBytes, "application/pdf"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

System.out.println(response.embeddings().orElse(null));

REST

PDF_PATH="/path/to/your/example.pdf"
PDF_BASE64=$(base64 -w0 "${PDF_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [{
                "inline_data": {
                    "mime_type": "application/pdf",
                    "data": "'"${PDF_BASE64}"'"
                }
            }]
        }
    }'

حالات الاستخدام

تُعدّ تضمينات النصوص مهمة لمجموعة متنوعة من حالات استخدام الذكاء الاصطناعي الشائعة، مثل:

تخزين التضمينات

عند استخدام التضمينات في مرحلة الإنتاج، من الشائع استخدام قواعد بيانات المتّجهات لتخزين وفهرسة واسترداد التضمينات العالية الأبعاد بكفاءة. تقدّم Google Cloud خدمات بيانات مُدارة يمكن استخدامها لهذا الغرض، بما في ذلك الإصدار 2.0 من ميزة "البحث بالمتّجه" في منصة وكيل Gemini Enterprise وBigQuery وAlloyDB وCloud SQL.

توضّح البرامج التعليمية التالية كيفية استخدام قواعد بيانات المتجهات التابعة لجهات خارجية أخرى مع Gemini Embedding.

إصدارات النماذج

Gemini Embedding 2

الموقع الوصف
رمز الطراز

Gemini API

gemini-embedding-2

أنواع البيانات المتوافقة

الإدخال

نصوص وصور وفيديوهات وملفات صوتية وملفات PDF

الناتج

تضمينات النص

الحدود القصوى للرموز المميّزة[*]

الحدّ الأقصى لعدد الرموز المميّزة المدخَلة

8,192

حجم سمة الإخراج

مرنة، وتدعم: 128 - 3072، المقترَحة: 768، 1536، 3072

الإصدارات
يمكنك الاطّلاع على أنماط إصدارات النماذج لمزيد من التفاصيل.
  • الإصدار الثابت: gemini-embedding-2
آخر تعديل أبريل 2026

Gemini Embedding

الموقع الوصف
رمز الطراز

Gemini API

gemini-embedding-001

أنواع البيانات المتوافقة

الإدخال

نص

الناتج

تضمينات النص

الحدود القصوى للرموز المميّزة[*]

الحدّ الأقصى لعدد الرموز المميّزة المدخَلة

2,048

حجم سمة الإخراج

مرنة، وتدعم: 128 - 3072، المقترَحة: 768، 1536، 3072

الإصدارات
يمكنك الاطّلاع على أنماط إصدارات النماذج لمزيد من التفاصيل.
  • الإصدار الثابت: gemini-embedding-001
آخر تعديل يونيو 2025

للاطّلاع على نماذج التضمينات التي تم إيقافها نهائيًا، يُرجى الانتقال إلى صفحة النماذج التي تم إيقافها نهائيًا

نقل البيانات من gemini-embedding-001

مساحات التضمين بين gemini-embedding-001 وgemini-embedding-2 غير متوافقة. هذا يعني أنّه لا يمكنك مقارنة التضمينات التي ينشئها أحد النماذج مباشرةً بالتضمينات التي ينشئها النموذج الآخر. في حال الترقية إلى gemini-embedding-2، عليك إعادة تضمين جميع بياناتك الحالية.

بالإضافة إلى عدم التوافق، هناك العديد من الاختلافات الملحوظة الأخرى بين النموذجين:

  • تحديد نوع المهمة: في gemini-embedding-001، يمكنك تحديد نوع المهمة باستخدام المَعلمة task_type (مثل SEMANTIC_SIMILARITY وRETRIEVAL_DOCUMENT). أمّا في gemini-embedding-2، فلا يمكن استخدام المَعلمة task_type. بدلاً من ذلك، يجب تضمين تعليمات المهمة مباشرةً في الطلب للمهام النصية فقط. يمكنك الاطّلاع على أنواع المهام باستخدام Embeddings 2 للحصول على تفاصيل حول كيفية تنسيق الطلبات لحالات الاستخدام المختلفة.

  • تجميع التضمينات: تنشئ دالة gemini-embedding-001 تضمينات فردية لكل سلسلة في قائمة من المدخلات. في المقابل، ينشئ gemini-embedding-2 تضمينًا واحدًا مجمّعًا عند تقديم عدة مدخلات (مثل النصوص والصور) مباشرةً في طلب واحد. لإنشاء تضمينات منفصلة لكل إدخال، يمكنك تضمين كل إدخال في عنصر Content أو استخدام Batch API. لمزيد من المعلومات، يُرجى الاطّلاع على تجميع التضمينات.

  • التسوية: إذا كنت تستخدم output_dimensionality لطلب تضمينات بأقل من 3072 سمة، يعمل gemini-embedding-2 تلقائيًا على تسوية هذه التضمينات المقتطعة. باستخدام gemini-embedding-001، عليك إجراء تسوية يدوية للأبعاد التي تختلف عن 3072. لمزيد من التفاصيل، يُرجى الاطّلاع على ضمان الجودة للأبعاد الأصغر حجمًا.

التضمينات المجمّعة

إذا لم يكن وقت الاستجابة مهمًا، يمكنك استخدام نماذج تضمينات Gemini مع Batch API. يتيح ذلك معدّل نقل بيانات أعلى بكثير بنسبة% 50 من سعر التضمين التلقائي. يمكنك العثور على أمثلة حول كيفية البدء في دليل Batch API.

إشعار الاستخدام المسؤول

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

بدء الإنشاء باستخدام التضمينات

اطّلِع على دفتر ملاحظات البدء السريع الخاص بالتضمينات لاستكشاف إمكانات النموذج ومعرفة كيفية تخصيص التضمينات وعرضها.