קבלת הטמעות טקסט

במאמר הזה מוסבר איך יוצרים הטמעת טקסט באמצעות Text embeddings API של Gemini Enterprise Agent Platform.

‫Gemini Enterprise Agent Platform text embeddings API משתמש בייצוגים של וקטורים דחוסים: לדוגמה, gemini-embedding-001 משתמש בווקטורים עם 3, 072 ממדים. מודלים של הטמעת וקטורים דחוסים משתמשים בשיטות למידה עמוקה שדומות לאלה שמשמשות מודלי שפה גדולים (LLM). בניגוד לווקטורים דלילים, שבדרך כלל ממפים מילים ישירות למספרים, וקטורים צפופים נועדו לייצג טוב יותר את המשמעות של קטע טקסט. היתרון של שימוש בהטמעות וקטורים דחוסים ב-AI גנרטיבי הוא שבמקום לחפש התאמות ישירות של מילים או תחביר, אפשר לחפש קטעים שמתאימים למשמעות של השאילתה, גם אם הקטעים לא משתמשים באותה שפה.

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

לפני שמתחילים

  1. נכנסים לחשבון Google Cloud . אנחנו ממליצים למשתמשים חדשים ב- Google Cloud ליצור חשבון כדי שיוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  6. בוחרים סוג משימה למשימת ההטמעה.

מגבלות על ממשקי API

בכל בקשה אפשר לשלוח עד 250 טקסטים. ל-API יש מגבלה של 20,000 טוקנים לקלט. אם הקלט חורג מהמגבלה הזו, תתקבל שגיאה 400. כל טקסט קלט בודד מוגבל ל-2,048 אסימונים. כל חריגה נחתכת בלי הודעה. אפשר גם להשבית את החיתוך השקט על ידי הגדרת autoTruncate לערך false.

מידע נוסף זמין במאמר מגבלות על הטמעת טקסט.

איך מקבלים הטמעות טקסט לקטע טקסט

כדי לקבל הטמעות טקסט לקטע טקסט, אתם יכולים להשתמש ב-Agent Platform API או ב-Agent Platform SDK ל-Python.

בחירת מאפיין הטמעה

כברירת מחדל, כל המודלים יוצרים וקטור הטמעה באורך מלא. ב-gemini-embedding-001, לווקטור הזה יש 3,072 מימדים, ובמודלים אחרים נוצרים וקטורים עם 768 מימדים. עם זאת, באמצעות הפרמטר output_dimensionality, המשתמשים יכולים לשלוט בגודל של וקטור ההטמעה בפלט. בחירה במאפיין פלט קטן יותר יכולה לחסוך מקום באחסון ולהגביר את יעילות החישוב באפליקציות במורד הזרם, בלי לפגוע באיכות.

הדוגמאות הבאות משתמשות במודל gemini-embedding-001.

Python

התקנה

pip install --upgrade google-genai

מידע נוסף זמין ב מאמרי העזרה של ה-SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

from google import genai
from google.genai.types import EmbedContentConfig

client = genai.Client()
response = client.models.embed_content(
    model="gemini-embedding-001",
    contents=[
        "How do I get a driver's license/learner's permit?",
        "How long is my driver's license valid for?",
        "Driver's knowledge test study guide",
    ],
    config=EmbedContentConfig(
        task_type="RETRIEVAL_DOCUMENT",  # Optional
        output_dimensionality=3072,  # Optional
        title="Driver's License",  # Optional
    ),
)
print(response)
# Example response:
# embeddings=[ContentEmbedding(values=[-0.06302902102470398, 0.00928034819662571, 0.014716853387653828, -0.028747491538524628, ... ],
# statistics=ContentEmbeddingStatistics(truncated=False, token_count=13.0))]
# metadata=EmbedContentMetadata(billable_character_count=112)

Go

thought איך מתקינים או מעדכנים את Go

מידע נוסף זמין ב מאמרי העזרה של ה-SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

import (
	"context"
	"fmt"
	"io"

	"google.golang.org/genai"
)

// generateEmbedContentWithText shows how to embed content with text.
func generateEmbedContentWithText(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	outputDimensionality := int32(3072)
	config := &genai.EmbedContentConfig{
		TaskType:             "RETRIEVAL_DOCUMENT",  //optional
		Title:                "Driver's License",    //optional
		OutputDimensionality: &outputDimensionality, //optional
	}

	contents := []*genai.Content{
		{
			Parts: []*genai.Part{
				{
					Text: "How do I get a driver's license/learner's permit?",
				},
				{
					Text: "How long is my driver's license valid for?",
				},
				{
					Text: "Driver's knowledge test study guide",
				},
			},
			Role: genai.RoleUser,
		},
	}

	modelName := "gemini-embedding-001"
	resp, err := client.Models.EmbedContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	fmt.Fprintln(w, resp)

	// Example response:
	// embeddings=[ContentEmbedding(values=[-0.06302902102470398, 0.00928034819662571, 0.014716853387653828, -0.028747491538524628, ... ],
	// statistics=ContentEmbeddingStatistics(truncated=False, token_count=13.0))]
	// metadata=EmbedContentMetadata(billable_character_count=112)

	return nil
}

Node.js

התקנה

npm install @google/genai

מידע נוסף זמין ב מאמרי העזרה של ה-SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;

async function generateEmbeddingsForRetrieval(
  projectId = GOOGLE_CLOUD_PROJECT
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
  });

  const prompt = [
    "How do I get a driver's license/learner's permit?",
    "How long is my driver's license valid for?",
    "Driver's knowledge test study guide",
  ];

  const response = await client.models.embedContent({
    model: 'gemini-embedding-001',
    contents: prompt,
    config: {
      taskType: 'RETRIEVAL_DOCUMENT', // Optional
      outputDimensionality: 3072, // Optional
      title: "Driver's License", // Optional
    },
  });

  console.log(response);

  // Example response:
  //  embeddings=[ContentEmbedding(values=[-0.06302902102470398, 0.00928034819662571, 0.014716853387653828, -0.028747491538524628, ... ],
  //  statistics=ContentEmbeddingStatistics(truncated=False, token_count=13.0))]
  //  metadata=EmbedContentMetadata(billable_character_count=112)

  return response;
}

Java

thought איך מתקינים או מעדכנים את Java

מידע נוסף זמין ב מאמרי העזרה של ה-SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True


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

public class EmbeddingsDocRetrievalWithTxt {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-embedding-001";
    embedContent(modelId);
  }

  // Shows how to embed content with text.
  public static EmbedContentResponse embedContent(String modelId) {
    // Client Initialization. Once created, it can be reused for multiple requests.
    try (Client client = Client.builder().location("global").vertexAI(true).build()) {

      EmbedContentResponse response =
          client.models.embedContent(
              modelId,
              List.of(
                  "How do I get a driver's license/learner's permit?",
                  "How long is my driver's license valid for?",
                  "Driver's knowledge test study guide"),
              EmbedContentConfig.builder()
                  .taskType("RETRIEVAL_DOCUMENT")
                  .outputDimensionality(3072)
                  .title("Driver's License")
                  .build());

      System.out.println(response);
      // Example response:
      // embeddings=Optional[[ContentEmbedding{values=Optional[[-0.035855383, 0.008127963, ... ]]
      // statistics=Optional[ContentEmbeddingStatistics{truncated=Optional[false],
      // tokenCount=Optional[11.0]}]}]],
      // metadata=Optional[EmbedContentMetadata{billableCharacterCount=Optional[153]}]}
      return response;
    }
  }
}

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט. .
  • ‫TEXT: הטקסט שרוצים ליצור לו הטמעות. מגבלה: חמישה טקסטים של עד 2,048 אסימונים לכל טקסט לכל המודלים, חוץ מ-textembedding-gecko@001. האורך המקסימלי של טוקן קלט ב-textembedding-gecko@001 הוא 3,072. ב-gemini-embedding-001, כל בקשה יכולה לכלול רק טקסט קלט אחד. מידע נוסף זמין במאמר מגבלות על הטמעת טקסט.
  • AUTO_TRUNCATE: אם הערך הוא false, טקסט שחורג ממגבלת הטוקנים גורם לבקשה להיכשל. ערך ברירת המחדל הוא true.

ה-method של ה-HTTP וכתובת ה-URL:

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict

גוף בקשת JSON:

{
  "instances": [
    { "content": "TEXT"}
  ],
  "parameters": { 
    "autoTruncate": AUTO_TRUNCATE 
  }
}

כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:

curl

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict"

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו: שימו לב שהערך של values נחתך כדי לחסוך במקום.

דוגמה לפקודת curl

MODEL_ID="gemini-embedding-001"
PROJECT_ID=PROJECT_ID

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/${MODEL_ID}:predict -d \
$'{
  "instances": [
    { "content": "What is life?"}
  ],
}'

מודלים נתמכים

בטבלה הבאה מפורטים המודלים הזמינים של Google להטמעת טקסט.

המודלים של Google

אפשר לקבל הטמעות טקסט באמצעות המודלים הבאים:

שם הדגם תיאור מידות הפלט אורך הרצף המקסימלי שפות נתמכות לטקסט
gemini-embedding-001 ביצועים המתקדם ביותר (SOTA) במשימות באנגלית, במשימות בכמה שפות ובמשימות קוד. הוא מאחד את המודלים שהיו קודם לכן, כמו text-embedding-005 ו-text-multilingual-embedding-002, ומשיג ביצועים טובים יותר בתחומים שלהם. לפרטים נוספים, קראו את הדוח הטכני שלנו. עד 3,072 ‫2,048 טוקנים שפות נתמכות לטקסט
gemini-embedding-2 הכי מתאים להטמעת מחרוזות ארוכות, כולל נתונים לא מובְנים ונתונים בכמה שפות. תמיכה בשילוב של טקסט, תמונות, אודיו, וידאו וקובצי PDF. עד 3,072 ‫8,192 טוקנים שפות נתמכות לטקסט
text-embedding-005 מתמחה במשימות באנגלית ובמשימות שקשורות לקוד. עד 768 ‫2,048 טוקנים אנגלית
text-multilingual-embedding-002 מתמחה במשימות בכמה שפות. עד 768 ‫2,048 טוקנים שפות נתמכות לטקסט

‫gemini-embedding-001 הוא המודל הגדול שלנו, שנועד לספק את הביצועים הטובים ביותר לאיכות הטמעה מעולה.

הוספת הטמעה למסד נתונים וקטורי

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

למידע נוסף על חיפוש וקטורי, קראו את הסקירה הכללית על חיפוש וקטורי.

המאמרים הבאים