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

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

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

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

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

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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

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

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

מגבלות 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

כאן מוסבר איך להתקין או לעדכן את 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

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

מודלים פתוחים

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

שם הדגם תיאור מידות הפלט אורך הרצף המקסימלי שפות הטקסט הנתמכות
multilingual-e5-small חלק ממשפחת מודלים להטמעת טקסט E5. הגרסה הקטנה מכילה 12 שכבות. עד 384 ‫512 טוקנים שפות נתמכות
multilingual-e5-large חלק ממשפחת מודלים להטמעת טקסט E5. גרסת Large מכילה 24 שכבות. עד 1,024 ‫512 טוקנים שפות נתמכות

כדי להתחיל, אפשר לעיין בכרטיס המודל של משפחת E5. מידע נוסף על מודלים פתוחים זמין במאמר מודלים פתוחים ל-MaaS

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

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

מידע נוסף על Vector Search זמין במאמר סקירה כללית על Vector Search.

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