API penyematan teks

Text embeddings API mengonversi data tekstual menjadi vektor numerik. Representasi vektor ini dirancang untuk menangkap makna semantik dan konteks kata-kata yang direpresentasikannya.

Model yang Didukung:

Anda bisa mendapatkan embedding teks dengan menggunakan model berikut:

Nama model Deskripsi Dimensi Output Panjang urutan maksimum Bahasa teks yang didukung
gemini-embedding-001 Performa canggih untuk tugas bahasa Inggris, multibahasa, dan kode. Model ini menyatukan model khusus sebelumnya seperti text-embedding-005 dan text-multilingual-embedding-002 serta mencapai performa yang lebih baik di domain masing-masing. Baca Laporan Teknis kami untuk mengetahui detail selengkapnya. hingga 3072 2048 token Bahasa teks yang didukung
text-embedding-005 Khusus dalam tugas bahasa Inggris dan kode. hingga 768 2048 token Inggris
text-multilingual-embedding-002 Khusus dalam tugas multibahasa. hingga 768 2048 token Bahasa teks yang didukung

Untuk kualitas embedding yang lebih unggul, gemini-embedding-001 adalah model besar kami yang dirancang untuk memberikan performa tertinggi. Perhatikan bahwa gemini-embedding-001 mendukung satu instance per permintaan.

Sintaks

curl

PROJECT_ID = PROJECT_ID
REGION = us-central1
MODEL_ID = MODEL_ID

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

Python

PROJECT_ID = PROJECT_ID
REGION = us-central1
MODEL_ID = MODEL_ID

import vertexai
from vertexai.language_models import TextEmbeddingModel

vertexai.init(project=PROJECT_ID, location=REGION)

model = TextEmbeddingModel.from_pretrained(MODEL_ID)
embeddings = model.get_embeddings(...)

Daftar parameter

Kolom tingkat teratas

instances

Daftar objek yang berisi kolom berikut:

  • content

  • title (opsional)

  • task_type (opsional)

parameters

Objek yang berisi kolom berikut:

  • autoTruncate (opsional)

  • outputDimensionality (opsional)

instance kolom

content

string

Teks yang ingin Anda buatkan embedding-nya.

task_type

Opsional: string

Digunakan untuk menyampaikan aplikasi downstream yang dimaksudkan untuk membantu model menghasilkan embedding yang lebih baik. Jika dibiarkan kosong, default yang digunakan adalah RETRIEVAL_QUERY.

  • RETRIEVAL_QUERY
  • RETRIEVAL_DOCUMENT
  • SEMANTIC_SIMILARITY
  • CLASSIFICATION
  • CLUSTERING
  • QUESTION_ANSWERING
  • FACT_VERIFICATION
  • CODE_RETRIEVAL_QUERY

Untuk mengetahui informasi selengkapnya tentang jenis tugas, lihat Memilih jenis tugas embedding.

title

Opsional: string

Digunakan untuk membantu model menghasilkan embedding yang lebih baik. Hanya valid dengan task_type=RETRIEVAL_DOCUMENT.

task_type

Tabel berikut mendeskripsikan nilai parameter task_type dan kasus penggunaannya:

task_type Deskripsi
RETRIEVAL_QUERY Menentukan bahwa teks yang diberikan merupakan kueri dalam setelan penelusuran atau pengambilan. Gunakan RETRIEVAL_DOCUMENT untuk sisi dokumen.
RETRIEVAL_DOCUMENT Menentukan bahwa teks yang diberikan adalah dokumen dalam setelan penelusuran atau pengambilan.
SEMANTIC_SIMILARITY Menentukan bahwa teks yang diberikan digunakan untuk Kemiripan Teks Semantik (STS).
CLASSIFICATION Menentukan bahwa embedding digunakan untuk klasifikasi.
CLUSTERING Menentukan bahwa embedding digunakan untuk pengelompokan.
QUESTION_ANSWERING Menentukan bahwa embedding kueri digunakan untuk menjawab pertanyaan. Gunakan RETRIEVAL_DOCUMENT untuk sisi dokumen.
FACT_VERIFICATION Menentukan bahwa embedding kueri digunakan untuk verifikasi fakta. Gunakan RETRIEVAL_DOCUMENT untuk sisi dokumen.
CODE_RETRIEVAL_QUERY Menentukan bahwa embedding kueri digunakan untuk pengambilan kode untuk Java dan Python. Gunakan RETRIEVAL_DOCUMENT untuk sisi dokumen.

Tugas Pengambilan:

Kueri: Gunakan task_type=RETRIEVAL_QUERY untuk menunjukkan bahwa teks input adalah kueri penelusuran. Corpus: Gunakan task_type=RETRIEVAL_DOCUMENT untuk menunjukkan bahwa teks input adalah bagian dari koleksi dokumen yang sedang ditelusuri.

Tugas Kesamaan:

Kesamaan semantik: Gunakan task_type= SEMANTIC_SIMILARITY untuk kedua teks input guna menilai kesamaan makna keseluruhannya.

parameters kolom

autoTruncate

Opsional: bool

Jika disetel ke true, teks input akan dipangkas. Jika disetel ke salah (false), error akan ditampilkan jika teks input lebih panjang daripada panjang maksimum yang didukung oleh model. Nilai defaultnya adalah benar (true).

outputDimensionality

Opsional: int

Digunakan untuk menentukan ukuran penyematan output. Jika disetel, sematan output akan dipangkas ke ukuran yang ditentukan.

Isi permintaan

{
  "instances": [
    {
      "task_type": "RETRIEVAL_DOCUMENT",
      "title": "document title",
      "content": "I would like embeddings for this text!"
    },
  ]
}

Isi respons

{
  "predictions": [
    {
      "embeddings": {
        "statistics": {
          "truncated": boolean,
          "token_count": integer
        },
        "values": [ number ]
      }
    }
  ]
}
Elemen respons

predictions

Daftar objek dengan kolom berikut:

  • embeddings: Hasil yang dihasilkan dari teks input. Berisi kolom berikut:

    • values

    • statistics

embeddings kolom

values

Daftar float. Kolom values berisi encoding numerik (vektor embedding) dari konten semantik yang ada dalam teks input yang diberikan.

statistics

Statistik yang dihitung dari teks input. Berisi:

  • truncated: Menunjukkan apakah teks input terpotong karena lebih panjang dari jumlah maksimum token yang diizinkan oleh model.

  • token_count: Jumlah token teks input.

Contoh respons

{
  "predictions": [
    {
      "embeddings": {
        "values": [
          0.0058424929156899452,
          0.011848051100969315,
          0.032247550785541534,
          -0.031829461455345154,
          -0.055369812995195389,
          ...
        ],
        "statistics": {
          "token_count": 4,
          "truncated": false
        }
      }
    }
  ]
}

Contoh

Menyematkan string teks

Contoh berikut menunjukkan cara mendapatkan embedding string teks.

REST

Setelah menyiapkan lingkungan, Anda dapat menggunakan REST untuk menguji perintah teks. Contoh berikut mengirim permintaan ke endpoint model penayang.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Anda.
  • TEXT: Teks yang ingin Anda buatkan embedding-nya. Batas: lima teks dengan maksimal 2.048 token per teks untuk semua model kecuali textembedding-gecko@001. Panjang token input maksimum untuk textembedding-gecko@001 adalah 3072. Untuk gemini-embedding-001, setiap permintaan hanya dapat menyertakan satu teks input. Untuk mengetahui informasi selengkapnya, lihat Batas embedding teks.
  • AUTO_TRUNCATE: Jika ditetapkan ke false, teks yang melebihi batas token akan menyebabkan permintaan gagal. Nilai defaultnya adalah true.

Metode HTTP dan URL:

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

Isi JSON permintaan:

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

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

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

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut:

$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

Anda akan menerima respons JSON yang mirip dengan yang berikut ini: Perhatikan bahwa values telah dipotong untuk menghemat ruang penyimpanan.

Perhatikan hal berikut di URL untuk sampel ini:
  • Gunakan metode generateContent untuk meminta agar respons ditampilkan setelah dibuat sepenuhnya. Untuk mengurangi persepsi latensi bagi audiens manusia, streaming respons saat respons dibuat menggunakan metode streamGenerateContent.
  • ID model multimodal terletak di akhir URL sebelum metode (misalnya, gemini-2.0-flash). Contoh ini mungkin mendukung model lain juga.

Python

Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Python.

from __future__ import annotations

from vertexai.language_models import TextEmbeddingInput, TextEmbeddingModel


def embed_text() -> list[list[float]]:
    """Embeds texts with a pre-trained, foundational model.

    Returns:
        A list of lists containing the embedding vectors for each input text
    """

    # A list of texts to be embedded.
    texts = ["banana muffins? ", "banana bread? banana muffins?"]
    # The dimensionality of the output embeddings.
    dimensionality = 3072
    # The task type for embedding. Check the available tasks in the model's documentation.
    task = "RETRIEVAL_DOCUMENT"

    model = TextEmbeddingModel.from_pretrained("gemini-embedding-001")
    kwargs = dict(output_dimensionality=dimensionality) if dimensionality else {}

    embeddings = []
    # gemini-embedding-001 takes one input at a time
    for text in texts:
        text_input = TextEmbeddingInput(text, task)
        embedding = model.get_embeddings([text_input], **kwargs)
        print(embedding)
        # Example response:
        # [[0.006135190837085247, -0.01462465338408947, 0.004978656303137541, ...]]
        embeddings.append(embedding[0].values)

    return embeddings

Go

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Go Vertex AI.

Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

import (
	"context"
	"fmt"
	"io"

	aiplatform "cloud.google.com/go/aiplatform/apiv1"
	"cloud.google.com/go/aiplatform/apiv1/aiplatformpb"

	"google.golang.org/api/option"
	"google.golang.org/protobuf/types/known/structpb"
)

// embedTexts shows how embeddings are set for gemini-embedding-001 model
func embedTexts(w io.Writer, project, location string) error {
	// location := "us-central1"
	ctx := context.Background()

	apiEndpoint := fmt.Sprintf("%s-aiplatform.googleapis.com:443", location)
	dimensionality := 3072
	model := "gemini-embedding-001"
	texts := []string{"banana muffins? ", "banana bread? banana muffins?"}

	client, err := aiplatform.NewPredictionClient(ctx, option.WithEndpoint(apiEndpoint))
	if err != nil {
		return err
	}
	defer client.Close()

	endpoint := fmt.Sprintf("projects/%s/locations/%s/publishers/google/models/%s", project, location, model)
	allEmbeddings := make([][]float32, 0, len(texts))
	// gemini-embedding-001 takes 1 input at a time
	for _, text := range texts {
		instances := make([]*structpb.Value, 1)
		instances[0] = structpb.NewStructValue(&structpb.Struct{
			Fields: map[string]*structpb.Value{
				"content":   structpb.NewStringValue(text),
				"task_type": structpb.NewStringValue("QUESTION_ANSWERING"),
			},
		})

		params := structpb.NewStructValue(&structpb.Struct{
			Fields: map[string]*structpb.Value{
				"outputDimensionality": structpb.NewNumberValue(float64(dimensionality)),
			},
		})

		req := &aiplatformpb.PredictRequest{
			Endpoint:   endpoint,
			Instances:  instances,
			Parameters: params,
		}
		resp, err := client.Predict(ctx, req)
		if err != nil {
			return err
		}

		// Process the prediction for the single text
		// The response will contain one prediction because we sent one instance.
		if len(resp.Predictions) == 0 {
			return fmt.Errorf("no predictions returned for text \"%s\"", text)
		}

		prediction := resp.Predictions[0]
		embeddingValues := prediction.GetStructValue().Fields["embeddings"].GetStructValue().Fields["values"].GetListValue().Values

		currentEmbedding := make([]float32, len(embeddingValues))
		for j, value := range embeddingValues {
			currentEmbedding[j] = float32(value.GetNumberValue())
		}
		allEmbeddings = append(allEmbeddings, currentEmbedding)
	}

	if len(allEmbeddings) > 0 {
		fmt.Fprintf(w, "Dimensionality: %d. Embeddings length: %d", len(allEmbeddings[0]), len(allEmbeddings))
	} else {
		fmt.Fprintln(w, "No texts were processed.")
	}
	return nil
}

Java

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Java Vertex AI.

Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

import static java.util.stream.Collectors.toList;

import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.PredictRequest;
import com.google.cloud.aiplatform.v1.PredictResponse;
import com.google.cloud.aiplatform.v1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1.PredictionServiceSettings;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import java.util.OptionalInt;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class PredictTextEmbeddingsSample {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    // Details about text embedding request structure and supported models are available in:
    // https://cloud.google.com/vertex-ai/docs/generative-ai/embeddings/get-text-embeddings
    String endpoint = "us-central1-aiplatform.googleapis.com:443";
    String project = "YOUR_PROJECT_ID";
    String model = "gemini-embedding-001";
    predictTextEmbeddings(
        endpoint,
        project,
        model,
        List.of("banana bread?", "banana muffins?"),
        "QUESTION_ANSWERING",
        OptionalInt.of(3072));
  }

  // Gets text embeddings from a pretrained, foundational model.
  public static List<List<Float>> predictTextEmbeddings(
      String endpoint,
      String project,
      String model,
      List<String> texts,
      String task,
      OptionalInt outputDimensionality)
      throws IOException {
    PredictionServiceSettings settings =
        PredictionServiceSettings.newBuilder().setEndpoint(endpoint).build();
    Matcher matcher = Pattern.compile("^(?<Location>\\w+-\\w+)").matcher(endpoint);
    String location = matcher.matches() ? matcher.group("Location") : "us-central1";
    EndpointName endpointName =
        EndpointName.ofProjectLocationPublisherModelName(project, location, "google", model);

    List<List<Float>> floats = new ArrayList<>();
    // You can use this prediction service client for multiple requests.
    try (PredictionServiceClient client = PredictionServiceClient.create(settings)) {
      // gemini-embedding-001 takes one input at a time.
      for (int i = 0; i < texts.size(); i++) {
        PredictRequest.Builder request = 
            PredictRequest.newBuilder().setEndpoint(endpointName.toString());
        if (outputDimensionality.isPresent()) {
          request.setParameters(
              Value.newBuilder()
                  .setStructValue(
                      Struct.newBuilder()
                          .putFields(
                              "outputDimensionality", valueOf(outputDimensionality.getAsInt()))
                          .build()));
        }
        request.addInstances(
            Value.newBuilder()
                .setStructValue(
                    Struct.newBuilder()
                        .putFields("content", valueOf(texts.get(i)))
                        .putFields("task_type", valueOf(task))
                        .build()));
        PredictResponse response = client.predict(request.build());

        for (Value prediction : response.getPredictionsList()) {
          Value embeddings = prediction.getStructValue().getFieldsOrThrow("embeddings");
          Value values = embeddings.getStructValue().getFieldsOrThrow("values");
          floats.add(
              values.getListValue().getValuesList().stream()
                  .map(Value::getNumberValue)
                  .map(Double::floatValue)
                  .collect(toList()));
        }
      }
      return floats;
    }
  }

  private static Value valueOf(String s) {
    return Value.newBuilder().setStringValue(s).build();
  }

  private static Value valueOf(int n) {
    return Value.newBuilder().setNumberValue(n).build();
  }
}

Node.js

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Node.js Vertex AI.

Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

async function main(
  project,
  model = 'gemini-embedding-001',
  texts = 'banana bread?;banana muffins?',
  task = 'QUESTION_ANSWERING',
  dimensionality = 0,
  apiEndpoint = 'us-central1-aiplatform.googleapis.com'
) {
  const aiplatform = require('@google-cloud/aiplatform');
  const {PredictionServiceClient} = aiplatform.v1;
  const {helpers} = aiplatform; // helps construct protobuf.Value objects.
  const clientOptions = {apiEndpoint: apiEndpoint};
  const location = 'us-central1';
  const endpoint = `projects/${project}/locations/${location}/publishers/google/models/${model}`;

  async function callPredict() {
    const instances = texts
      .split(';')
      .map(e => helpers.toValue({content: e, task_type: task}));

    const client = new PredictionServiceClient(clientOptions);
    const parameters = helpers.toValue(
      dimensionality > 0 ? {outputDimensionality: parseInt(dimensionality)} : {}
    );
    const allEmbeddings = []
    // gemini-embedding-001 takes one input at a time.
    for (const instance of instances) {
      const request = {endpoint, instances: [instance], parameters};
      const [response] = await client.predict(request);
      const predictions = response.predictions;

      const embeddings = predictions.map(p => {
        const embeddingsProto = p.structValue.fields.embeddings;
        const valuesProto = embeddingsProto.structValue.fields.values;
        return valuesProto.listValue.values.map(v => v.numberValue);
      });

      allEmbeddings.push(embeddings[0])
    }


    console.log('Got embeddings: \n' + JSON.stringify(allEmbeddings));
  }

  callPredict();
}

Bahasa teks yang didukung

Semua model embedding teks mendukung dan telah dievaluasi pada teks berbahasa Inggris. Model text-multilingual-embedding-002 juga mendukung dan telah dievaluasi dalam bahasa berikut:

  • Bahasa yang dievaluasi: Arabic (ar), Bengali (bn), English (en), Spanish (es), German (de), Persian (fa), Finnish (fi), French (fr), Hindi (hi), Indonesian (id), Japanese (ja), Korean (ko), Russian (ru), Swahili (sw), Telugu (te), Thai (th), Yoruba (yo), Chinese (zh)
  • Bahasa yang didukung: Afrikaans, Albanian, Amharic, Arabic, Armenian, Azerbaijani, Basque, Belarusiasn, Bengali, Bulgarian, Burmese, Catalan, Cebuano, Chichewa, Chinese, Corsican, Czech, Danish, Dutch, English, Esperanto, Estonian, Filipino, Finnish, French, Galician, Georgian, German, Greek, Gujarati, Haitian Creole, Hausa, Hawaiian, Hebrew, Hindi, Hmong, Hungarian, Icelandic, Igbo, Indonesian, Irish, Italian, Japanese, Javanese, Kannada, Kazakh, Khmer, Korean, Kurdish, Kyrgyz, Lao, Latin, Latvian, Lithuanian, Luxembourgish, Macedonian, Malagasy, Malay, Malayalam, Maltese, Maori, Marathi, Mongolian, Nepali, Norwegian, Pashto, Persian, Polish, Portuguese, Punjabi, Romanian, Russian, Samoan, Scottish Gaelic, Serbian, Shona, Sindhi, Sinhala, Slovak, Slovenian, Somali, Sotho, Spanish, Sundanese, Swahili, Swedish, Tajik, Tamil, Telugu, Thai, Turkish, Ukrainian, Urdu, Uzbek, Vietnamese, Welsh, West Frisian, Xhosa, Yiddish, Yoruba, Zulu.

Model gemini-embedding-001 mendukung bahasa berikut:

Arabic, Bengali, Bulgarian, Chinese (Simplified and Traditional), Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Latvian, Lithuanian, Norwegian, Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovenian, Spanish, Swahili, Swedish, Thai, Turkish, Ukrainian, Vietnamese, Afrikaans, Amharic, Assamese, Azerbaijani, Belarusian, Bosnian, Catalan, Cebuano, Corsican, Welsh, Dhivehi, Esperanto, Basque, Persian, Filipino (Tagalog), Frisian, Irish, Scots Gaelic, Galician, Gujarati, Hausa, Hawaiian, Hmong, Haitian Creole, Armenian, Igbo, Icelandic, Javanese, Georgian, Kazakh, Khmer, Kannada, Krio, Kurdish, Kyrgyz, Latin, Luxembourgish, Lao, Malagasy, Maori, Macedonian, Malayalam, Mongolian, Meiteilon (Manipuri), Marathi, Malay, Maltese, Myanmar (Burmese), Nepali, Nyanja (Chichewa), Odia (Oriya), Punjabi, Pashto, Sindhi, Sinhala (Sinhalese), Samoan, Shona, Somali, Albanian, Sesotho, Sundanese, Tamil, Telugu, Tajik, Uyghur, Urdu, Uzbek, Xhosa, Yiddish, Yoruba, Zulu.

Versi model

Untuk menggunakan model stabil saat ini, tentukan nomor versi model, misalnya gemini-embedding-001. Menentukan model tanpa nomor versi tidak direkomendasikan, karena hanya merupakan pointer lama ke model lain dan tidak stabil.

Untuk mengetahui informasi selengkapnya, baca Versi dan siklus proses model.

Langkah berikutnya

Untuk dokumentasi mendetail, lihat berikut ini: