Embeddings

הטמעה היא ייצוג מספרי של קלט טקסט, שמאפשר מספר תרחישי שימוש ייחודיים, כמו סידור באשכולות, מדידת דמיון ואחזור מידע. למבוא, אפשר לעיין במדריך להטמעות.

בניגוד למודלים של AI גנרטיבי שיוצרים תוכן חדש, מודל Gemini Embedding נועד רק להמיר את הפורמט של נתוני הקלט לייצוג מספרי. ‫Google אחראית לספק מודל הטמעה שממיר את הפורמט של נתוני הקלט לפורמט המספרי המבוקש, אבל המשתמשים נושאים באחריות מלאה לנתונים שהם מזינים ולהטמעות שמתקבלות. השימוש במודל Gemini Embedding מבטא את האישור שלכם לכך שיש לכם את הזכויות הנדרשות על התוכן שאתם מעלים. אסור ליצור תוכן שמפר את זכויות הקניין הרוחני או זכויות הפרטיות של אחרים. השימוש בשירות הזה כפוף למדיניות שלנו בנושא שימוש אסור ולתנאים ולהגבלות של Google.

שיטה: models.embedContent

יוצר וקטור הטמעת טקסט מהקלט Content באמצעות מודל ההטמעה של Gemini שצוין.

נקודת קצה

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

פרמטרים של נתיב

model string

חובה. שם המשאב של המודל. המזהה הזה משמש את המודל.

השם הזה צריך להיות זהה לשם של מודל שמוחזר על ידי השיטה models.list.

פורמט: models/{model} הוא מקבל את הצורה models/{model}.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

Fields
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}.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

Fields
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.

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל נתונים במבנה הבא:

Fields
embeddings[] object (ContentEmbedding)

פלט בלבד. ההטמעות של כל בקשה, באותו סדר שבו הן סופקו בבקשת Batch.

ייצוג ב-JSON
{
  "embeddings": [
    {
      object (ContentEmbedding)
    }
  ]
}

שיטה: models.asyncBatchEmbedContent

הבקשה מוסיפה לאצווה קבוצה של models.embedContent בקשות לעיבוד באצווה. יש לנו handler ב-models.batchEmbedContents ב-GenerativeService, אבל הוא סונכרן. לכן, כדי למנוע בלבול, ניתן לו את השם Async.

נקודת קצה

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

פרמטרים של נתיב

batch.model string

חובה. השם של Model שבו רוצים להשתמש כדי ליצור את ההשלמה.

פורמט: models/{model} הוא מקבל את הצורה models/{model}.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

Fields
batch.name string

פלט בלבד. מזהה. שם המשאב של הקבוצה.

פורמט: batches/{batchId}

batch.displayName string

חובה. השם שהמשתמש נתן לקבוצה הזו.

batch.inputConfig object (InputEmbedContentConfig)

חובה. הגדרת הקלט של המופעים שבהם מתבצע עיבוד באצווה.

batch.output object (EmbedContentBatchOutput)

פלט בלבד. הפלט של בקשת Batch.

batch.createTime string (Timestamp format)

פלט בלבד. השעה שבה נוצרת הקבוצה.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-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)

פלט בלבד. השעה שבה הסתיים עיבוד ברצף (batch processing).

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-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 ושימוש ב-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.

EmbedContentResponse

התשובה לEmbedContentRequest.

Fields
embedding object (ContentEmbedding)

פלט בלבד. ההטמעה שנוצרה מתוכן הקלט.

ייצוג ב-JSON
{
  "embedding": {
    object (ContentEmbedding)
  }
}

ContentEmbedding

רשימה של מספרים ממשיים שמייצגים הטמעה.

Fields
values[] number

ערכי ההטמעה.

shape[] integer

בשדה הזה מאוחסן טנזור של צורת מסגרת של טוקנים רכים (למשל, [1, 1, 256, 2048]).

ייצוג ב-JSON
{
  "values": [
    number
  ],
  "shape": [
    integer
  ]
}

TaskType

סוג המשימה שבה ייעשה שימוש בהטמעה.

טיפוסים בני מנייה (enum)
TASK_TYPE_UNSPECIFIED ערך לא מוגדר, שברירת המחדל שלו היא אחד מערכי ה-enum האחרים.
RETRIEVAL_QUERY מציינת שהטקסט שצוין הוא שאילתה בהגדרה של חיפוש או אחזור.
RETRIEVAL_DOCUMENT מציינים שהטקסט שצוין הוא מסמך מתוך מאגר המידע שנערך בו החיפוש.
SEMANTIC_SIMILARITY מציינת שהטקסט שצוין ישמש ל-STS.
CLASSIFICATION מציין שהטקסט הנתון יסווג.
CLUSTERING מציינת שההטמעות ישמשו לאשכולות.
QUESTION_ANSWERING מציין שהטקסט שצוין ישמש למענה לשאלות.
FACT_VERIFICATION המדיניות קובעת שהטקסט שצוין ישמש לאימות עובדות.
CODE_RETRIEVAL_QUERY מציין שהטקסט שצוין ישמש לאחזור קוד.

EmbedContentBatch

משאב שמייצג אצווה של בקשות EmbedContent.

Fields
model string

חובה. השם של Model שבו רוצים להשתמש כדי ליצור את ההשלמה.

פורמט: models/{model}

name string

פלט בלבד. מזהה. שם המשאב של הקבוצה.

פורמט: batches/{batchId}

displayName string

חובה. השם שהמשתמש נתן לקבוצה הזו.

inputConfig object (InputEmbedContentConfig)

חובה. הגדרת הקלט של המופעים שבהם מתבצע עיבוד באצווה.

output object (EmbedContentBatchOutput)

פלט בלבד. הפלט של בקשת Batch.

createTime string (Timestamp format)

פלט בלבד. השעה שבה נוצרת הקבוצה.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-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)

פלט בלבד. השעה שבה הסתיים עיבוד ברצף (batch processing).

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-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 ושימוש ב-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

הגדרת הקלט לבקשת Batch.

שדות
source Union type
חובה. המקור של הקלט. הערך source יכול להיות רק אחד מהבאים:
fileName string

שם הקטגוריה File שמכילה את בקשות הקלט.

requests object (InlinedEmbedContentRequests)

הבקשות שיעובדו באצווה.

ייצוג ב-JSON
{

  // source
  "fileName": string,
  "requests": {
    object (InlinedEmbedContentRequests)
  }
  // Union type
}

InlinedEmbedContentRequests

הבקשות שיעובדו באצווה, אם הן צוינו כחלק מבקשת יצירת האצווה.

Fields
requests[] object (InlinedEmbedContentRequest)

חובה. הבקשות שיעובדו באצווה.

ייצוג ב-JSON
{
  "requests": [
    {
      object (InlinedEmbedContentRequest)
    }
  ]
}

InlinedEmbedContentRequest

הבקשה שצריך לעבד ב-Batch.

Fields
request object (EmbedContentRequest)

חובה. הבקשה שצריך לעבד ב-Batch.

metadata object (Struct format)

אופציונלי. המטא-נתונים שמשויכים לבקשה.

ייצוג ב-JSON
{
  "request": {
    object (EmbedContentRequest)
  },
  "metadata": {
    object
  }
}

EmbedContentBatchOutput

הפלט של בקשת Batch. הערך הזה מוחזר בשדה AsyncBatchEmbedContentResponse או בשדה EmbedContentBatch.output.

שדות
output Union type
הפלט של בקשת Batch. הערך output יכול להיות רק אחד מהבאים:
responsesFile string

פלט בלבד. מזהה הקובץ שמכיל את התשובות. הקובץ יהיה קובץ JSONL עם תגובה אחת בכל שורה. התשובות יהיו EmbedContentResponse הודעות בפורמט JSON. התשובות ייכתבו באותו סדר של בקשות הקלט.

inlinedResponses object (InlinedEmbedContentResponses)

פלט בלבד. התשובות לבקשות באצווה. התשובה הזו מוחזרת כשהאצווה נוצרה באמצעות בקשות מוטבעות. סדר התשובות יהיה זהה לסדר הבקשות שהוזנו.

ייצוג ב-JSON
{

  // output
  "responsesFile": string,
  "inlinedResponses": {
    object (InlinedEmbedContentResponses)
  }
  // Union type
}

InlinedEmbedContentResponses

התשובות לבקשות באצווה.

Fields
inlinedResponses[] object (InlinedEmbedContentResponse)

פלט בלבד. התשובות לבקשות באצווה.

ייצוג ב-JSON
{
  "inlinedResponses": [
    {
      object (InlinedEmbedContentResponse)
    }
  ]
}

InlinedEmbedContentResponse

התשובה לבקשה יחידה באצווה.

Fields
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

נתונים סטטיסטיים על האצווה.

Fields
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
}