Embeddings

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

בניגוד למודלים של AI גנרטיבי שיוצרים תוכן חדש, מודל ה-Embedding של Gemini נועד רק להמיר את פורמט נתוני הקלט לייצוג מספרי. ‫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)

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

ייצוג ב-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.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)

פלט בלבד. השעה שבה הסתיים עיבוד האצווה.

הפונקציה משתמשת ב-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.

EmbedContentRequest

בקשה שמכילה את Content של המודל להטמעה.

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

EmbedContentResponse

התשובה לEmbedContentRequest.

Fields
embedding object (ContentEmbedding)

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

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

ContentEmbedding

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

Fields
values[] number

ערכי ההטמעה.

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

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)

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

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)

פלט בלבד. השעה שבה הסתיים עיבוד האצווה.

הפונקציה משתמשת ב-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

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

שדות
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

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

Fields
request object (EmbedContentRequest)

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

metadata object (Struct format)

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

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

EmbedContentBatchOutput

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

שדות
output Union type
הפלט של הבקשה באצווה. הערך 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
}