توفّر واجهة 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}"'"
}
}]
}
}'
حالات الاستخدام
تُعدّ تضمينات النصوص مهمة لمجموعة متنوعة من حالات استخدام الذكاء الاصطناعي الشائعة، مثل:
- التوليد المعزّز بالاسترجاع (RAG): تعمل التضمينات على تحسين جودة النص الذي يتم إنشاؤه من خلال استرداد المعلومات ذات الصلة ودمجها في سياق النموذج.
استرجاع المعلومات: البحث عن النص أو المستندات الأكثر تشابهًا من حيث المعنى مع نص الإدخال
إعادة ترتيب نتائج البحث: يمكنك إعطاء الأولوية للعناصر الأكثر صلة من خلال تقييم النتائج الأولية دلاليًا مقارنةً بطلب البحث.
رصد القيم الشاذة: يمكن أن تساعد مقارنة مجموعات التضمينات في تحديد المؤشرات المخفية أو القيم الشاذة.
التصنيف: تصنيف النص تلقائيًا استنادًا إلى محتواه، مثل تحليل المشاعر أو رصد الرسائل غير المرغوب فيها
التجميع: يمكنك فهم العلاقات المعقّدة بفعالية من خلال إنشاء مجموعات وتصورات للتضمينات.
تخزين التضمينات
عند استخدام التضمينات في مرحلة الإنتاج، من الشائع استخدام قواعد بيانات المتّجهات لتخزين وفهرسة واسترداد التضمينات العالية الأبعاد بكفاءة. تقدّم Google Cloud خدمات بيانات مُدارة يمكن استخدامها لهذا الغرض، بما في ذلك الإصدار 2.0 من ميزة "البحث بالمتّجه" في منصة وكيل Gemini Enterprise وBigQuery وAlloyDB وCloud SQL.
توضّح البرامج التعليمية التالية كيفية استخدام قواعد بيانات المتجهات التابعة لجهات خارجية أخرى مع Gemini Embedding.
إصدارات النماذج
Gemini Embedding 2
| الموقع | الوصف |
|---|---|
| رمز الطراز |
Gemini API
|
| أنواع البيانات المتوافقة |
الإدخال نصوص وصور وفيديوهات وملفات صوتية وملفات PDF الناتج تضمينات النص |
| الحدود القصوى للرموز المميّزة[*] |
الحدّ الأقصى لعدد الرموز المميّزة المدخَلة 8,192 حجم سمة الإخراج مرنة، وتدعم: 128 - 3072، المقترَحة: 768، 1536، 3072 |
| الإصدارات |
|
| آخر تعديل | أبريل 2026 |
Gemini Embedding
| الموقع | الوصف |
|---|---|
| رمز الطراز |
Gemini API
|
| أنواع البيانات المتوافقة |
الإدخال نص الناتج تضمينات النص |
| الحدود القصوى للرموز المميّزة[*] |
الحدّ الأقصى لعدد الرموز المميّزة المدخَلة 2,048 حجم سمة الإخراج مرنة، وتدعم: 128 - 3072، المقترَحة: 768، 1536، 3072 |
| الإصدارات |
|
| آخر تعديل | يونيو 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.
بدء الإنشاء باستخدام التضمينات
اطّلِع على دفتر ملاحظات البدء السريع الخاص بالتضمينات لاستكشاف إمكانات النموذج ومعرفة كيفية تخصيص التضمينات وعرضها.