Embeddings

Embedding adalah representasi numerik dari input teks yang membuka sejumlah kasus penggunaan unik, seperti pengelompokan, pengukuran kemiripan, dan pengambilan informasi. Untuk pengantar, lihat Panduan embedding.

Tidak seperti model AI generatif yang membuat konten baru, model Embedding Gemini hanya ditujukan untuk mengubah format data input Anda menjadi representasi numerik. Meskipun Google bertanggung jawab untuk menyediakan model penyematan yang mengubah format data input Anda ke format numerik yang diminta, pengguna tetap bertanggung jawab sepenuhnya atas data yang mereka masukkan dan penyematan yang dihasilkan. Dengan menggunakan model Embedding Gemini, Anda mengonfirmasi bahwa Anda memiliki hak yang diperlukan atas konten apa pun yang Anda upload. Jangan membuat konten yang melanggar hak atas kekayaan intelektual atau hak privasi orang lain. Penggunaan layanan ini oleh Anda tunduk pada Kebijakan Penggunaan Terlarang dan Persyaratan Layanan Google kami.

Metode: models.embedContent

Membuat vektor embedding teks dari input Content menggunakan model Embedding Gemini yang ditentukan.

Endpoint

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

Parameter jalur

model string

Wajib. Nama resource model. Ini berfungsi sebagai ID yang akan digunakan Model.

Nama ini harus cocok dengan nama model yang ditampilkan oleh metode models.list.

Format: models/{model} Formatnya adalah models/{model}.

Isi permintaan

Isi permintaan memuat data dengan struktur berikut:

Kolom
content object (Content)

Wajib. Konten yang akan disematkan. Hanya kolom parts.text yang akan dihitung.

taskType enum (TaskType)

Opsional. Jenis tugas opsional yang akan menggunakan embedding. Tidak didukung di model sebelumnya (models/embedding-001).

title string

Opsional. Judul opsional untuk teks. Hanya berlaku jika TaskType adalah RETRIEVAL_DOCUMENT.

Catatan: Menentukan title untuk RETRIEVAL_DOCUMENT memberikan embedding berkualitas lebih baik untuk pengambilan.

outputDimensionality integer

Opsional. Dimensi yang dikurangi opsional untuk penyematan output. Jika disetel, nilai berlebihan dalam sematan output akan dipangkas dari akhir. Hanya didukung oleh model yang lebih baru sejak tahun 2024. Anda tidak dapat menetapkan nilai ini jika menggunakan model sebelumnya (models/embedding-001).

Contoh permintaan

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))

Shell

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?"}]}
    }'

Isi respons

Jika berhasil, isi respons memuat instance EmbedContentResponse.

Metode: models.batchEmbedContents

Menghasilkan beberapa vektor embedding dari input Content yang terdiri dari batch string yang direpresentasikan sebagai objek EmbedContentRequest.

Endpoint

postingan https://generativelanguage.googleapis.com/v1beta/{model=models/*}:batchEmbedContents

Parameter jalur

model string

Wajib. Nama resource model. Ini berfungsi sebagai ID yang akan digunakan Model.

Nama ini harus cocok dengan nama model yang ditampilkan oleh metode models.list.

Format: models/{model} Formatnya adalah models/{model}.

Isi permintaan

Isi permintaan memuat data dengan struktur berikut:

Kolom
requests[] object (EmbedContentRequest)

Wajib. Sematkan permintaan untuk batch. Model dalam setiap permintaan ini harus cocok dengan model yang ditentukan BatchEmbedContentsRequest.model.

Contoh permintaan

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))

Shell

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

Isi respons

Respons terhadap BatchEmbedContentsRequest.

Jika berhasil, isi respons memuat data dengan struktur berikut:

Kolom
embeddings[] object (ContentEmbedding)

Hanya output. Penyematan untuk setiap permintaan, dalam urutan yang sama seperti yang diberikan dalam permintaan batch.

Representasi JSON
{
  "embeddings": [
    {
      object (ContentEmbedding)
    }
  ]
}

Metode: models.asyncBatchEmbedContent

Mengantrekan batch permintaan models.embedContent untuk batch processing. Kita memiliki handler models.batchEmbedContents di GenerativeService, tetapi disinkronkan. Jadi, kita beri nama yang ini Async untuk menghindari kebingungan.

Endpoint

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

Parameter jalur

batch.model string

Wajib. Nama Model yang akan digunakan untuk membuat penyelesaian.

Format: models/{model}. Formatnya adalah models/{model}.

Isi permintaan

Isi permintaan memuat data dengan struktur berikut:

Kolom
batch.name string

Hanya output. ID. Nama resource batch.

Format: batches/{batchId}.

batch.displayName string

Wajib. Nama batch yang ditentukan pengguna.

batch.inputConfig object (InputEmbedContentConfig)

Wajib. Konfigurasi input instance tempat pemrosesan batch dilakukan.

batch.output object (EmbedContentBatchOutput)

Hanya output. Output permintaan batch.

batch.createTime string (Timestamp format)

Hanya output. Waktu saat batch dibuat.

Menggunakan RFC 3339, dengan output yang dihasilkan akan selalu dinormalisasi Z dan menggunakan 0, 3, 6, atau 9 digit pecahan. Offset selain "Z" juga diterima. Contoh: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z", atau "2014-10-02T15:01:23+05:30".

batch.endTime string (Timestamp format)

Hanya output. Waktu saat pemrosesan batch selesai.

Menggunakan RFC 3339, dengan output yang dihasilkan akan selalu dinormalisasi Z dan menggunakan 0, 3, 6, atau 9 digit pecahan. Offset selain "Z" juga diterima. Contoh: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z", atau "2014-10-02T15:01:23+05:30".

batch.updateTime string (Timestamp format)

Hanya output. Waktu saat batch terakhir diperbarui.

Menggunakan RFC 3339, dengan output yang dihasilkan akan selalu dinormalisasi Z dan menggunakan 0, 3, 6, atau 9 digit pecahan. Offset selain "Z" juga diterima. Contoh: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z", atau "2014-10-02T15:01:23+05:30".

batch.batchStats object (EmbedContentBatchStats)

Hanya output. Statistik tentang batch.

batch.state enum (BatchState)

Hanya output. Status batch.

batch.priority string (int64 format)

Opsional. Prioritas batch. Batch dengan nilai prioritas yang lebih tinggi akan diproses sebelum batch dengan nilai prioritas yang lebih rendah. Nilai negatif diizinkan. Defaultnya adalah 0.

Isi respons

Jika berhasil, isi respons memuat instance Operation.

EmbedContentRequest

Permintaan yang berisi Content untuk model yang akan disematkan.

Kolom
model string

Wajib. Nama resource model. Ini berfungsi sebagai ID yang akan digunakan Model.

Nama ini harus cocok dengan nama model yang ditampilkan oleh metode models.list.

Format: models/{model}

content object (Content)

Wajib. Konten yang akan disematkan. Hanya kolom parts.text yang akan dihitung.

taskType enum (TaskType)

Opsional. Jenis tugas opsional yang akan menggunakan embedding. Tidak didukung di model sebelumnya (models/embedding-001).

title string

Opsional. Judul opsional untuk teks. Hanya berlaku jika TaskType adalah RETRIEVAL_DOCUMENT.

Catatan: Menentukan title untuk RETRIEVAL_DOCUMENT memberikan embedding berkualitas lebih baik untuk pengambilan.

outputDimensionality integer

Opsional. Dimensi yang dikurangi opsional untuk penyematan output. Jika disetel, nilai berlebihan dalam sematan output akan dipangkas dari akhir. Hanya didukung oleh model yang lebih baru sejak tahun 2024. Anda tidak dapat menetapkan nilai ini jika menggunakan model sebelumnya (models/embedding-001).

Representasi JSON
{
  "model": string,
  "content": {
    object (Content)
  },
  "taskType": enum (TaskType),
  "title": string,
  "outputDimensionality": integer
}

EmbedContentResponse

Respons terhadap EmbedContentRequest.

Kolom
embedding object (ContentEmbedding)

Hanya output. Penyematan yang dihasilkan dari konten input.

Representasi JSON
{
  "embedding": {
    object (ContentEmbedding)
  }
}

ContentEmbedding

Daftar float yang mewakili penyematan.

Kolom
values[] number

Nilai embedding.

Representasi JSON
{
  "values": [
    number
  ]
}

TaskType

Jenis tugas yang akan menggunakan embedding.

Enum
TASK_TYPE_UNSPECIFIED Nilai yang tidak ditetapkan, yang secara default akan menjadi salah satu nilai enum lainnya.
RETRIEVAL_QUERY Menentukan bahwa teks yang diberikan merupakan kueri dalam setelan penelusuran/pengambilan.
RETRIEVAL_DOCUMENT Menentukan bahwa teks yang diberikan adalah dokumen dari korpus yang ditelusuri.
SEMANTIC_SIMILARITY Menentukan bahwa teks yang diberikan akan digunakan untuk STS.
CLASSIFICATION Menentukan bahwa teks yang diberikan akan diklasifikasikan.
CLUSTERING Menentukan bahwa embedding akan digunakan untuk pengelompokan.
QUESTION_ANSWERING Menentukan bahwa teks yang diberikan akan digunakan untuk menjawab pertanyaan.
FACT_VERIFICATION Menentukan bahwa teks yang diberikan akan digunakan untuk verifikasi fakta.
CODE_RETRIEVAL_QUERY Menentukan bahwa teks yang diberikan akan digunakan untuk pengambilan kode.

EmbedContentBatch

Resource yang mewakili batch permintaan EmbedContent.

Kolom
model string

Wajib. Nama Model yang akan digunakan untuk membuat penyelesaian.

Format: models/{model}.

name string

Hanya output. ID. Nama resource batch.

Format: batches/{batchId}.

displayName string

Wajib. Nama batch yang ditentukan pengguna.

inputConfig object (InputEmbedContentConfig)

Wajib. Konfigurasi input instance tempat pemrosesan batch dilakukan.

output object (EmbedContentBatchOutput)

Hanya output. Output permintaan batch.

createTime string (Timestamp format)

Hanya output. Waktu saat batch dibuat.

Menggunakan RFC 3339, dengan output yang dihasilkan akan selalu dinormalisasi Z dan menggunakan 0, 3, 6, atau 9 digit pecahan. Offset selain "Z" juga diterima. Contoh: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z", atau "2014-10-02T15:01:23+05:30".

endTime string (Timestamp format)

Hanya output. Waktu saat pemrosesan batch selesai.

Menggunakan RFC 3339, dengan output yang dihasilkan akan selalu dinormalisasi Z dan menggunakan 0, 3, 6, atau 9 digit pecahan. Offset selain "Z" juga diterima. Contoh: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z", atau "2014-10-02T15:01:23+05:30".

updateTime string (Timestamp format)

Hanya output. Waktu saat batch terakhir diperbarui.

Menggunakan RFC 3339, dengan output yang dihasilkan akan selalu dinormalisasi Z dan menggunakan 0, 3, 6, atau 9 digit pecahan. Offset selain "Z" juga diterima. Contoh: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z", atau "2014-10-02T15:01:23+05:30".

batchStats object (EmbedContentBatchStats)

Hanya output. Statistik tentang batch.

state enum (BatchState)

Hanya output. Status batch.

priority string (int64 format)

Opsional. Prioritas batch. Batch dengan nilai prioritas yang lebih tinggi akan diproses sebelum batch dengan nilai prioritas yang lebih rendah. Nilai negatif diizinkan. Defaultnya adalah 0.

Representasi 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

Mengonfigurasi input ke permintaan batch.

Kolom
source Union type
Wajib. Sumber input. source hanya dapat berupa salah satu dari hal berikut:
fileName string

Nama File yang berisi permintaan input.

requests object (InlinedEmbedContentRequests)

Permintaan yang akan diproses dalam batch.

Representasi JSON
{

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

InlinedEmbedContentRequests

Permintaan yang akan diproses dalam batch jika diberikan sebagai bagian dari permintaan pembuatan batch.

Kolom
requests[] object (InlinedEmbedContentRequest)

Wajib. Permintaan yang akan diproses dalam batch.

Representasi JSON
{
  "requests": [
    {
      object (InlinedEmbedContentRequest)
    }
  ]
}

InlinedEmbedContentRequest

Permintaan yang akan diproses dalam batch.

Kolom
request object (EmbedContentRequest)

Wajib. Permintaan yang akan diproses dalam batch.

metadata object (Struct format)

Opsional. Metadata yang akan dikaitkan dengan permintaan.

Representasi JSON
{
  "request": {
    object (EmbedContentRequest)
  },
  "metadata": {
    object
  }
}

EmbedContentBatchOutput

Output permintaan batch. Ini ditampilkan di kolom AsyncBatchEmbedContentResponse atau EmbedContentBatch.output.

Kolom
output Union type
Output permintaan batch. output hanya dapat berupa salah satu dari hal berikut:
responsesFile string

Hanya output. ID file yang berisi respons. File ini akan berupa file JSONL dengan satu respons per baris. Respons akan berupa pesan EmbedContentResponse yang diformat sebagai JSON. Respons akan ditulis dalam urutan yang sama dengan permintaan input.

inlinedResponses object (InlinedEmbedContentResponses)

Hanya output. Respons terhadap permintaan dalam batch. Ditampilkan saat batch dibuat menggunakan permintaan inline. Respons akan memiliki urutan yang sama dengan permintaan input.

Representasi JSON
{

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

InlinedEmbedContentResponses

Respons terhadap permintaan dalam batch.

Kolom
inlinedResponses[] object (InlinedEmbedContentResponse)

Hanya output. Respons terhadap permintaan dalam batch.

Representasi JSON
{
  "inlinedResponses": [
    {
      object (InlinedEmbedContentResponse)
    }
  ]
}

InlinedEmbedContentResponse

Respons terhadap satu permintaan dalam batch.

Kolom
metadata object (Struct format)

Hanya output. Metadata yang terkait dengan permintaan.

output Union type
Output permintaan. output hanya dapat berupa salah satu dari hal berikut:
error object (Status)

Hanya output. Error yang terjadi saat memproses permintaan.

response object (EmbedContentResponse)

Hanya output. Respons terhadap permintaan.

Representasi JSON
{
  "metadata": {
    object
  },

  // output
  "error": {
    object (Status)
  },
  "response": {
    object (EmbedContentResponse)
  }
  // Union type
}

EmbedContentBatchStats

Statistik tentang batch.

Kolom
requestCount string (int64 format)

Hanya output. Jumlah permintaan dalam batch.

successfulRequestCount string (int64 format)

Hanya output. Jumlah permintaan yang berhasil diproses.

failedRequestCount string (int64 format)

Hanya output. Jumlah permintaan yang gagal diproses.

pendingRequestCount string (int64 format)

Hanya output. Jumlah permintaan yang masih menunggu pemrosesan.

Representasi JSON
{
  "requestCount": string,
  "successfulRequestCount": string,
  "failedRequestCount": string,
  "pendingRequestCount": string
}