Yerleştirmeler

Gemini API; metin, resim, video ve diğer içerikler için yerleştirme oluşturmak üzere yerleştirme modelleri sunar. Elde edilen yerleştirmeler daha sonra semantik arama, sınıflandırma ve kümeleme gibi görevlerde kullanılabilir. Bu sayede, anahtar kelimeye dayalı yaklaşımlara kıyasla daha doğru ve bağlama duyarlı sonuçlar elde edilir.

En yeni model olan gemini-embedding-2, Gemini API'deki ilk çok formatlı yerleştirme modelidir. Metin, resim, video, ses ve belgeleri birleştirilmiş bir yerleştirme alanına eşleyerek 100'den fazla dilde çapraz modlu arama, sınıflandırma ve kümeleme yapmanıza olanak tanır. Daha fazla bilgi edinmek için çok formatlı yerleştirmeler bölümünü inceleyin. Yalnızca metin içeren kullanım alanları için gemini-embedding-001 kullanılabilir.

Veriyle Artırılmış Üretim (RAG) sistemleri oluşturmak, yapay zeka ürünlerinin yaygın kullanım alanlarından biridir. Yerleştirmeler, model çıktılarının doğruluğunu, tutarlılığını ve bağlamsal zenginliğini artırarak önemli ölçüde iyileştirilmesinde önemli bir rol oynar. Yönetilen bir RAG çözümü kullanmayı tercih ediyorsanız RAG'yi daha kolay yönetilebilir ve daha uygun maliyetli hale getiren Dosya Arama aracını geliştirdik.

Yerleştirilmiş öğeler oluşturma

Metin yerleştirmeleri oluşturmak için embedContent yöntemini kullanın:

Python

from google import genai

client = genai.Client()

result = client.models.embed_content(
        model="gemini-embedding-2",
        contents="What is the meaning of life?"
)

print(result.embeddings)

JavaScript

import { GoogleGenAI } from "@google/genai";

async function main() {

    const ai = new GoogleGenAI({});

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: 'What is the meaning of life?',
    });

    console.log(response.embeddings);
}

main();

Java

import com.google.genai.Client;
import com.google.genai.types.EmbedContentResponse;

Client client = new Client();

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", "What is the meaning of life?", null);

System.out.println(response.embeddings().orElse(null));

Go

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    contents := []*genai.Content{
        genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),
    }
    result, err := client.Models.EmbedContent(ctx,
        "gemini-embedding-2",
        contents,
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }

    embeddings, err := json.MarshalIndent(result.Embeddings, "", "  ")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(string(embeddings))
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "model": "models/gemini-embedding-2",
        "content": {
        "parts": [{
            "text": "What is the meaning of life?"
        }]
        }
    }'

Performansı artırmak için görev türünü belirtin

Yerleştirmeleri, sınıflandırmadan doküman aramaya kadar çok çeşitli görevler için kullanabilirsiniz. Doğru görev türünü belirtmek, yerleştirmeleri amaçlanan ilişkiler için optimize ederek doğruluğu ve verimliliği en üst düzeye çıkarır.

Embeddings 2 ile görev türleri

gemini-embedding-2 ile yalnızca metin içeren görevlerde, görev talimatını isteminize eklemenizi önemle tavsiye ederiz. Bunun için sorguyu ve dokümanı doğru görev önekiyle biçimlendirebilirsiniz.

Çok formatlı girişe dayalı tek bir yerleştirme oluştururken genellikle girişin metin kısmına görev talimatı eklemenizi önermeyiz. Bazı durumlarda performansı artırırken bazı durumlarda performansı düşürür.

Aşağıdaki tablolarda, gemini-embedding-2 modelini kullanarak simetrik ve asimetrik kullanım alanları için sorguların ve dokümanların nasıl biçimlendirileceğine dair örnekler gösterilmektedir.

Bilgi alma kullanım alanları (Asimetrik biçim)

Asimetrik kullanım alanlarında, sorguya görev önekini ekleyin ve yerleştirmek ve almak istediğiniz içerik için belge yapısını uygulayın.

Kullanım alanı Sorgu yapısı Belge yapısı
Arama sorgusu task: search result | query: {content} title: {title} | text: {content}
Başlık yoksa title: none kullanın.
Soru yanıtlama task: question answering | query: {content} title: {title} | text: {content}
Doğruluk kontrolü task: fact checking | query: {content} title: {title} | text: {content}
Kod alma task: code retrieval | query: {content} title: {title} | text: {content}

Örnek kullanım

Python

# Generate embedding for a task's query. Use your correct task here:
def prepare_query(query):
    # return f"task: question answering | query: {query}"
    # return f"task: fact checking | query: {query}"
    # return f"task: code retrieval | query: {query}"
    return f"task: search result | query: {query}"

# Generate embedding for document of an asymmetric retrieval task:
def prepare_document(content, title=None):
    if title is None:
        title = "none"
    return f"title: {title} | text: {content}"

Tek girişli kullanım alanları (simetrik biçim)

Simetrik kullanım alanlarında, aynı görev için sorgu ve dokümanda aynı biçimlendirmeyi kullanın.

Kullanım alanı Giriş yapısı
Sınıflandırma task: classification | query: {content}
Kümeleme task: clustering | query: {content}
Semantik benzerlik task: sentence similarity | query: {content}
Bu özelliği arama veya veri alma için kullanmayın. Anlamsal metin benzerliği için tasarlanmıştır.

Örnek kullanım

Python

# Generate embedding for query & document of your task.
def prepare_query_and_document(content):
    # return f'task: clustering | query: {content}'
    # return f'task: sentence similarity | query: {content}'
    return f'task: classification | query: {content}'

Görevin tutarlı bir şekilde kullanılması önemlidir. Örneğin, dokümanlar f'task: classification | query: {content}' ile yerleştirilmişse sorgu da bu görev biçimine göre yerleştirilmelidir.

Yerleştirmelerle görev türleri 1

gemini-embedding-001 için embedContent yönteminde task_type değerini belirtebilirsiniz. Desteklenen görev türlerinin tam listesi için Desteklenen görev türleri tablosuna bakın.

Aşağıdaki örnekte, metin dizelerinin anlam bakımından ne kadar benzer olduğunu kontrol etmek için SEMANTIC_SIMILARITY işlevini nasıl kullanabileceğiniz gösterilmektedir.

Python

from google import genai
from google.genai import types
import pandas as pd
from sklearn.metrics.pairwise import cosine_similarity

client = genai.Client()

texts = [
    "What is the meaning of life?",
    "What is the purpose of existence?",
    "How do I bake a cake?",
]

result = client.models.embed_content(
    model="gemini-embedding-001",
    contents=texts,
    config=types.EmbedContentConfig(task_type="SEMANTIC_SIMILARITY")
)

# Create a 3x3 table to show the similarity matrix
df = pd.DataFrame(
    cosine_similarity([e.values for e in result.embeddings]),
    index=texts,
    columns=texts,
)

print(df)

JavaScript

import { GoogleGenAI } from "@google/genai";
// npm i compute-cosine-similarity
import * as cosineSimilarity from "compute-cosine-similarity";

async function main() {
    const ai = new GoogleGenAI({});

    const texts = [
        "What is the meaning of life?",
        "What is the purpose of existence?",
        "How do I bake a cake?",
    ];

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-001',
        contents: texts,
        config: { taskType: 'SEMANTIC_SIMILARITY' },
    });

    const embeddings = response.embeddings.map(e => e.values);

    for (let i = 0; i < texts.length; i++) {
        for (let j = i + 1; j < texts.length; j++) {
            const text1 = texts[i];
            const text2 = texts[j];
            const similarity = cosineSimilarity(embeddings[i], embeddings[j]);
            console.log(`Similarity between '${text1}' and '${text2}': ${similarity.toFixed(4)}`);
        }
    }
}

main();

Java

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

Client client = new Client();

List<String> texts =
    Arrays.asList(
        "What is the meaning of life?",
        "What is the purpose of existence?",
        "How do I bake a cake?");

EmbedContentConfig config =
    EmbedContentConfig.builder().taskType("SEMANTIC_SIMILARITY").build();

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-001", texts, config);

List<ContentEmbedding> embeddings = response.embeddings().get();

for (int i = 0; i < texts.size(); i++) {
  for (int j = i + 1; j < texts.size(); j++) {
    List<Float> v1 = embeddings.get(i).values().get();
    List<Float> v2 = embeddings.get(j).values().get();
    double dotProduct = 0.0;
    double normA = 0.0;
    double normB = 0.0;
    for (int k = 0; k < v1.size(); k++) {
      dotProduct += v1.get(k) * v2.get(k);
      normA += v1.get(k) * v1.get(k);
      normB += v2.get(k) * v2.get(k);
    }
    double similarity = dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
    System.out.printf(
        "Similarity between '%s' and '%s': %.4f%n", texts.get(i), texts.get(j), similarity);
  }
}

Go

package main

import (
    "context"
    "fmt"
    "log"
    "math"

    "google.golang.org/genai"
)

// cosineSimilarity calculates the similarity between two vectors.
func cosineSimilarity(a, b []float32) (float64, error) {
    if len(a) != len(b) {
        return 0, fmt.Errorf("vectors must have the same length")
    }

    var dotProduct, aMagnitude, bMagnitude float64
    for i := 0; i < len(a); i++ {
        dotProduct += float64(a[i] * b[i])
        aMagnitude += float64(a[i] * a[i])
        bMagnitude += float64(b[i] * b[i])
    }

    if aMagnitude == 0 || bMagnitude == 0 {
        return 0, nil
    }

    return dotProduct / (math.Sqrt(aMagnitude) * math.Sqrt(bMagnitude)), nil
}

func main() {
    ctx := context.Background()
    client, _ := genai.NewClient(ctx, nil)
    defer client.Close()

    texts := []string{
        "What is the meaning of life?",
        "What is the purpose of existence?",
        "How do I bake a cake?",
    }

    var contents []*genai.Content
    for _, text := range texts {
        contents = append(contents, genai.NewContentFromText(text, genai.RoleUser))
    }

    result, _ := client.Models.EmbedContent(ctx,
        "gemini-embedding-001",
        contents,
        &genai.EmbedContentRequest{TaskType: genai.TaskTypeSemanticSimilarity},
    )

    embeddings := result.Embeddings

    for i := 0; i < len(texts); i++ {
        for j := i + 1; j < len(texts); j++ {
            similarity, _ := cosineSimilarity(embeddings[i].Values, embeddings[j].Values)
            fmt.Printf("Similarity between '%s' and '%s': %.4f\n", texts[i], texts[j], similarity)
        }
    }
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -d '{
    "taskType": "SEMANTIC_SIMILARITY",
    "content": {
        "parts": [
        {
            "text": "What is the meaning of life?"
        },
        {
            "text": "How much wood would a woodchuck chuck?"
        },
        {
            "text": "How does the brain work?"
        }
        ]
    }
    }'

Kod snippet'leri, çalıştırıldığında farklı metin parçalarının birbirine ne kadar benzediğini gösterir.

Desteklenen görev türleri

gemini-embedding-001 için desteklenen görev türleri:

Görev türü Açıklama Örnekler
SEMANTIC_SIMILARITY Metin benzerliğini değerlendirmek için optimize edilmiş yerleştirmeler. Öneri sistemleri, kopya algılama
SINIFLANDIRMA Metinleri önceden ayarlanmış etiketlere göre sınıflandırmak için optimize edilmiş yerleştirmeler. Duygu analizi, spam yakalama
KÜMELEME Metinleri benzerliklerine göre gruplandırmak için optimize edilmiş yerleştirmeler. Belge düzenleme, pazar araştırması, anormallik algılama
RETRIEVAL_DOCUMENT Doküman araması için optimize edilmiş yerleştirmeler. Arama için makaleleri, kitapları veya web sayfalarını dizine ekleme
RETRIEVAL_QUERY Genel arama sorguları için optimize edilmiş yerleştirmeler. Sorgular için RETRIEVAL_QUERY, alınacak belgeler için RETRIEVAL_DOCUMENT kullanın. Özel arama ağı
CODE_RETRIEVAL_QUERY Doğal dil sorgularına dayalı kod bloklarının alınması için optimize edilmiş yerleştirmeler. Sorgular için CODE_RETRIEVAL_QUERY, alınacak kod blokları için RETRIEVAL_DOCUMENT kullanın. Kod önerileri ve arama
QUESTION_ANSWERING Soru-cevap sistemindeki sorular için yerleştirmeler, soruyu yanıtlayan dokümanları bulmak için optimize edilmiştir. Sorular için QUESTION_ANSWERING, alınacak belgeler için RETRIEVAL_DOCUMENT kullanın. Sohbet kutusu
FACT_VERIFICATION Doğrulanması gereken ifadeler için yerleştirmeler, ifadeyi destekleyen veya çürüten kanıtlar içeren dokümanları almak üzere optimize edilmiştir. Hedef metin için FACT_VERIFICATION, alınacak dokümanlar için RETRIEVAL_DOCUMENT kullanın. Otomatik doğruluk kontrolü sistemleri

Yerleştirme boyutunu kontrol etme

Hem gemini-embedding-001 hem de gemini-embedding-2, Matryoshka Gösterim Öğrenimi (MRL) tekniği kullanılarak eğitilir. Bu teknik, bir modele aynı verilerin daha basit ve kullanışlı sürümleri olan ilk segmentlere (veya ön eklere) sahip yüksek boyutlu yerleştirmeleri öğrenmeyi öğretir.

Çıkış yerleştirme vektörünün boyutunu kontrol etmek için output_dimensionality parametresini kullanın. Daha küçük bir çıkış boyutu seçmek, kaliteden çok az ödün vererek depolama alanından tasarruf sağlayabilir ve sonraki uygulamalar için hesaplama verimliliğini artırabilir. Varsayılan olarak her iki model de 3072 boyutlu bir yerleştirme üretir ancak depolama alanından tasarruf etmek için kaliteyi düşürmeden daha küçük bir boyuta kısaltabilirsiniz. 768, 1536 veya 3072 çıkış boyutlarını kullanmanızı öneririz.

Python

from google import genai
from google.genai import types

client = genai.Client()

result = client.models.embed_content(
    model="gemini-embedding-2",
    contents="What is the meaning of life?",
    config=types.EmbedContentConfig(output_dimensionality=768)
)

[embedding_obj] = result.embeddings
embedding_length = len(embedding_obj.values)

print(f"Length of embedding: {embedding_length}")

JavaScript

import { GoogleGenAI } from "@google/genai";

async function main() {
    const ai = new GoogleGenAI({});

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: 'What is the meaning of life?',
        config: { outputDimensionality: 768 },
    });

    const embeddingLength = response.embeddings[0].values.length;
    console.log(`Length of embedding: ${embeddingLength}`);
}

main();

Java

import com.google.genai.Client;
import com.google.genai.types.ContentEmbedding;
import com.google.genai.types.EmbedContentConfig;
import com.google.genai.types.EmbedContentResponse;

Client client = new Client();

EmbedContentConfig config =
    EmbedContentConfig.builder().outputDimensionality(768).build();

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", "What is the meaning of life?", config);

ContentEmbedding embeddingObj = response.embeddings().get().get(0);
int embeddingLength = embeddingObj.values().get().size();

System.out.println("Length of embedding: " + embeddingLength);

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    // The client uses Application Default Credentials.
    // Authenticate with 'gcloud auth application-default login'.
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    contents := []*genai.Content{
        genai.NewContentFromText("What is the meaning of life?", genai.RoleUser),
    }

    result, err := client.Models.EmbedContent(ctx,
        "gemini-embedding-2",
        contents,
        &genai.EmbedContentRequest{OutputDimensionality: 768},
    )
    if err != nil {
        log.Fatal(err)
    }

    embedding := result.Embeddings[0]
    embeddingLength := len(embedding.Values)
    fmt.Printf("Length of embedding: %d\n", embeddingLength)
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H 'Content-Type: application/json' \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -d '{
        "content": {"parts":[{ "text": "What is the meaning of life?"}]},
        "output_dimensionality": 768
    }'

Kod snippet'inden örnek çıkış:

Length of embedding: 768

Daha küçük boyutlar için kaliteyi sağlama

Varsayılan 3072 boyutlu yerleştirmeler her zaman normalleştirilirken Gemini Embedding 2, kesilmiş boyutları da (ör. 768, 1536) otomatik olarak normalleştirir. Bu sayede, semantik benzerlik büyüklük yerine vektör yönü üzerinden hesaplanır ve daha doğru sonuçlar elde edilir.

Eski Modeller: gemini-embedding-001 kullanıyorsanız 3072 olmayan boyutları aşağıdaki gibi manuel olarak normalleştirmeniz gerekir:

Python

import numpy as np
from numpy.linalg import norm

# Only for embeddings from `gemini-embedding-001`
embedding_values_np = np.array(embedding_obj.values)
normed_embedding = embedding_values_np / np.linalg.norm(embedding_values_np)

print(f"Normed embedding length: {len(normed_embedding)}")
print(f"Norm of normed embedding: {np.linalg.norm(normed_embedding):.6f}") # Should be very close to 1

Bu kod snippet'inden elde edilen örnek çıkış:

Normed embedding length: 768
Norm of normed embedding: 1.000000

Aşağıdaki tabloda, yerleştirmeler için en çok tercih edilen bir karşılaştırma olan MTEB puanları farklı boyutlar için gösterilmektedir. Sonuç, performansın yerleştirme boyutunun büyüklüğüne sıkı sıkıya bağlı olmadığını, daha düşük boyutların daha yüksek boyutlu muadilleriyle karşılaştırılabilir puanlar elde ettiğini gösteriyor.

MRL Boyutu MTEB Puanı (Gemini Embedding 001)
2048 68,16
1536 68,17
768 67,99
512 67,55
256 66,19
128 63,31

Çok formatlı yerleştirmeler

gemini-embedding-2 modeli, çok formatlı girişi destekler. Bu sayede metnin yanı sıra resim, video, ses ve belge içerikleri de yerleştirebilirsiniz. Tüm modaliteler aynı yerleştirme alanına eşlenir. Bu sayede modaliteler arası arama ve karşılaştırma yapılabilir.

Desteklenen modaliteler ve sınırlar

Genel maksimum giriş jetonu sınırı 8.192 jetondur.

Yöntem Spesifikasyonlar ve sınırlar
Metin 8.192 parçaya kadar destekler.
Resim İstek başına en fazla 6 resim. Desteklenen biçimler: PNG, JPEG.
Ses Maksimum süre 180 saniyedir. Desteklenen biçimler: MP3, WAV.
Video Maksimum süre 120 saniyedir. Desteklenen biçimler: MP4, MOV. Desteklenen codec'ler: H264, H265, AV1, VP9.
Sistem, video başına en fazla 32 kare işler: Kısa videolar (≤32 sn.) 1 fps'de örneklenirken daha uzun videolar 32 kareye eşit olarak örneklenir. Video dosyalarındaki ses parçaları işlenmez.
Belgeler (PDF) İstek başına en fazla 1 dosya (6 sayfaya kadar) yüklenebilir.

Resim yerleştirme

Aşağıdaki örnekte, gemini-embedding-2 kullanarak bir resmin nasıl yerleştirileceği gösterilmektedir.

Görüntüler, satır içi veri olarak veya Files API aracılığıyla yüklenen dosyalar olarak sağlanabilir.

Python

from google import genai
from google.genai import types

with open('example.png', 'rb') as f:
    image_bytes = f.read()

client = genai.Client()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        types.Part.from_bytes(
            data=image_bytes,
            mime_type='image/png',
        ),
    ]
)

print(result.embeddings)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const imgBase64 = fs.readFileSync("example.png", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [{
            inlineData: {
                mimeType: 'image/png',
                data: imgBase64,
            },
        }],
    });

    console.log(response.embeddings);
}

main();

Java

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("example.png"));

Content content = Content.fromParts(Part.fromBytes(imageBytes, "image/png"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

System.out.println(response.embeddings().orElse(null));

REST

IMG_PATH="/path/to/your/image.png"
IMG_BASE64=$(base64 -w0 "${IMG_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [{
                "inline_data": {
                    "mime_type": "image/png",
                    "data": "'"${IMG_BASE64}"'"
                }
            }]
        }
    }'

Yerleştirme toplama

Çok formatlı içeriklerle çalışırken girişinizi nasıl yapılandırdığınız, yerleştirme çıkışını etkiler:

  • Birden fazla parça (toplu): contents parametresine doğrudan birden fazla giriş eklemek, tüm girişler için tek bir toplu yerleştirme oluşturur.
  • Birden fazla Content nesnesi (ayrı): Her girişi bir Content nesnesine sarmalayıp contents parametresine ilettiğinizde her giriş için ayrı yerleştirmeler döndürülür.
  • Yayın düzeyinde temsil: Birden fazla medya öğesi içeren sosyal medya yayınları gibi karmaşık nesneler için ayrı yerleştirmeleri birleştirerek (ör. ortalamasını alarak) tutarlı bir yayın düzeyinde temsil oluşturmanızı öneririz.

Aşağıdaki örnekte, metin ve resim girişi için birleştirilmiş bir yerleştirmenin nasıl oluşturulacağı gösterilmektedir. contents parametresine birden fazla giriş eklemeniz yeterlidir:

Python

from google import genai
from google.genai import types

client = genai.Client()

with open('dog.png', 'rb') as f:
    image_bytes = f.read()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        "An image of a dog",
        types.Part.from_bytes(
            data=image_bytes,
            mime_type='image/png',
        ),
    ]
)

# This produces one embedding
for embedding in result.embeddings:
    print(embedding.values)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const imgBase64 = fs.readFileSync("dog.png", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [
            'An image of a dog',
            {
                inlineData: {
                    mimeType: 'image/png',
                    data: imgBase64,
                },
            },
        ],
    });

    // This produces one embedding
    for (const embedding of response.embeddings) {
        console.log(embedding.values);
    }
}

main();

Java

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.ContentEmbedding;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Collections;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("dog.png"));

Content content =
    Content.fromParts(
        Part.fromText("An image of a dog"),
        Part.fromBytes(imageBytes, "image/png"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

// This produces one embedding
for (ContentEmbedding embedding : response.embeddings().orElse(Collections.emptyList())) {
  System.out.println(embedding.values().orElse(Collections.emptyList()));
}

REST

IMG_PATH="/path/to/your/dog.png"
IMG_BASE64=$(base64 -w0 "${IMG_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [
                {"text": "An image of a dog"},
                {
                    "inline_data": {
                        "mime_type": "image/png",
                        "data": "'"${IMG_BASE64}"'"
                    }
                }
            ]
        }
    }'

Öte yandan, contents parametresinde Content nesneleri kullanırsanız ayrı yerleştirmeler döndürülür. Bu örnekte, tek bir yerleştirme çağrısında birden fazla yerleştirme oluşturulur:

Python

from google import genai
from google.genai import types

client = genai.Client()

with open('dog.png', 'rb') as f:
    image_bytes = f.read()

result = client.models.embed_content(
    model="gemini-embedding-2",
    contents=[
        types.Content(parts=[types.Part.from_text(text="task: classification | query: An image of a dog")]),
        types.Content(
            parts=[
                types.Part.from_bytes(
                    data=image_bytes,
                    mime_type="image/png",
                ),
            ]
        ),
    ],
)

# This produces two embeddings
for embedding in result.embeddings:
    print(embedding.values)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const imgBase64 = fs.readFileSync("dog.png", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [
            { parts: [{ text: 'task: classification | query: An image of a dog' }] },
            {
                parts: [{
                    inlineData: {
                        mimeType: 'image/png',
                        data: imgBase64,
                    },
                }],
            },
        ],
    });

    // This produces two embeddings
    for (const embedding of response.embeddings) {
        console.log(embedding.values);
    }
}

main();

Java

import java.util.Arrays;
import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.ContentEmbedding;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Collections;
import java.util.List;

Client client = new Client();

byte[] imageBytes = Files.readAllBytes(Paths.get("dog.png"));

List<Content> contents =
    Arrays.asList(
        Content.fromParts(Part.fromText("task: classification | query: An image of a dog")),
        Content.fromParts(Part.fromBytes(imageBytes, "image/png")));

// Embed each Content object separately to produce separate embeddings
for (Content content : contents) {
  EmbedContentResponse response =
      client.models.embedContent("gemini-embedding-2", content, null);
  for (ContentEmbedding embedding : response.embeddings().orElse(Collections.emptyList())) {
    System.out.println(embedding.values().orElse(Collections.emptyList()));
  }
}

REST

IMG_PATH="/path/to/your/dog.png"
IMG_BASE64=$(base64 -w0 "${IMG_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:batchEmbedContents" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "requests": [
            {
                "model": "models/gemini-embedding-2",
                "content": {"parts": [{"text": "task: classification | query: An image of a dog"}]}
            },
            {
                "model": "models/gemini-embedding-2",
                "content": {"parts": [{"inline_data": {"mime_type": "image/png", "data": "'"${IMG_BASE64}"'"}}]}
            }
        ]
    }'

Ses yerleştirme

Aşağıdaki örnekte, gemini-embedding-2 kullanarak bir ses dosyasının nasıl yerleştirileceği gösterilmektedir.

Ses dosyaları, satır içi veri olarak veya Files API aracılığıyla yüklenen dosyalar olarak sağlanabilir.

Python

from google import genai
from google.genai import types

with open('example.mp3', 'rb') as f:
    audio_bytes = f.read()

client = genai.Client()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        types.Part.from_bytes(
            data=audio_bytes,
            mime_type='audio/mpeg',
        ),
    ]
)

print(result.embeddings)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const audioBase64 = fs.readFileSync("example.mp3", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [{
            inlineData: {
                mimeType: 'audio/mpeg',
                data: audioBase64,
            },
        }],
    });

    console.log(response.embeddings);
}

main();

Java

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;

Client client = new Client();

byte[] audioBytes = Files.readAllBytes(Paths.get("example.mp3"));

Content content = Content.fromParts(Part.fromBytes(audioBytes, "audio/mpeg"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

System.out.println(response.embeddings().orElse(null));

REST

AUDIO_PATH="/path/to/your/example.mp3"
AUDIO_BASE64=$(base64 -w0 "${AUDIO_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [{
                "inline_data": {
                    "mime_type": "audio/mpeg",
                    "data": "'"${AUDIO_BASE64}"'"
                }
            }]
        }
    }'

Video yerleştirme

Aşağıdaki örnekte, gemini-embedding-2 kullanarak bir videonun nasıl yerleştirileceği gösterilmektedir.

Videolar, satır içi veri olarak veya Files API aracılığıyla yüklenen dosyalar olarak sağlanabilir.

Python

from google import genai
from google.genai import types

client = genai.Client()

with open('example.mp4', 'rb') as f:
    video_bytes = f.read()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        types.Part.from_bytes(
            data=video_bytes,
            mime_type='video/mp4',
        ),
    ]
)

print(result.embeddings[0].values)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const videoBase64 = fs.readFileSync("example.mp4", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [{
            inlineData: {
                mimeType: 'video/mp4',
                data: videoBase64,
            },
        }],
    });

    console.log(response.embeddings);
}

main();

Java

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Collections;

Client client = new Client();

byte[] videoBytes = Files.readAllBytes(Paths.get("example.mp4"));

Content content = Content.fromParts(Part.fromBytes(videoBytes, "video/mp4"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

System.out.println(
    response.embeddings().get().get(0).values().orElse(Collections.emptyList()));

REST

VIDEO_PATH="/path/to/your/video.mp4"
VIDEO_BASE64=$(base64 -w0 "${VIDEO_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [{
                "inline_data": {
                    "mime_type": "video/mp4",
                    "data": "'"${VIDEO_BASE64}"'"
                }
            }]
        }
    }'

120 saniyeden uzun videolar yerleştirmeniz gerekiyorsa videoyu birbiriyle örtüşen segmentlere bölüp bu parçaları ayrı ayrı yerleştirebilirsiniz.

Doküman yerleştirme

PDF biçimindeki belgeler doğrudan yerleştirilebilir. Model, her sayfanın görsel ve metin içeriğini işler.

PDF'ler, satır içi veri olarak veya Files API aracılığıyla yüklenen dosyalar olarak sağlanabilir.

Model, PDF'leri nasıl işler?

Bir PDF'yi yerleştirdiğinizde model, hem görsel hem de metin özelliklerini kullanarak dokümanı işler:

  • Görsel temsil: Model, her sayfayı resim olarak oluşturur. Bu işlem, sayfa başına 258 parça kullanır.
  • Metin ayıklama: Model, dokümandan metin ayıklar. Yerel PDF'lerde (dijital metin içeren) model, metni doğrudan ayıklar. Taranmış PDF'lerde (metin resimleri içeren) model, metni ayıklamak için otomatik olarak optik karakter tanıma (OCR) özelliğini çalıştırır.

Bir PDF'nin toplam parça sayısını hesaplamak için görsel parçaları (sayfa başına 258) metin parçalarına ekleyin. Girişleriniz,modelin 8.192 jeton sınırına (tüm modalitelerde paylaşılır) uymalıdır. Sistem, bu sınırı aşan girişleri sessizce kısaltır.

PDF sınırları

  • İstek başına dosya sayısı: En fazla 1 PDF dosyası gönderebilirsiniz.
  • Sayfa sınırı: Dosya başına en fazla 6 sayfa gönderebilirsiniz. En iyi kalite için PDF başına 1 sayfa kullanmanızı önemle tavsiye ederiz.

Aşağıdaki örnekte, gemini-embedding-2 kullanarak PDF'nin nasıl yerleştirileceği gösterilmektedir:

Python

from google import genai
from google.genai import types

with open('example.pdf', 'rb') as f:
    pdf_bytes = f.read()

client = genai.Client()

result = client.models.embed_content(
    model='gemini-embedding-2',
    contents=[
        types.Part.from_bytes(
            data=pdf_bytes,
            mime_type='application/pdf',
        ),
    ]
)

print(result.embeddings)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

async function main() {
    const ai = new GoogleGenAI({});

    const pdfBase64 = fs.readFileSync("example.pdf", { encoding: "base64" });

    const response = await ai.models.embedContent({
        model: 'gemini-embedding-2',
        contents: [{
            inlineData: {
                mimeType: 'application/pdf',
                data: pdfBase64,
            },
        }],
    });

    console.log(response.embeddings);
}

main();

Java

import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.EmbedContentResponse;
import com.google.genai.types.Part;
import java.nio.file.Files;
import java.nio.file.Paths;

Client client = new Client();

byte[] pdfBytes = Files.readAllBytes(Paths.get("example.pdf"));

Content content = Content.fromParts(Part.fromBytes(pdfBytes, "application/pdf"));

EmbedContentResponse response =
    client.models.embedContent("gemini-embedding-2", content, null);

System.out.println(response.embeddings().orElse(null));

REST

PDF_PATH="/path/to/your/example.pdf"
PDF_BASE64=$(base64 -w0 "${PDF_PATH}")

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-2:embedContent" \
    -H "Content-Type: application/json" \
    -H "x-goog-api-key: ${GEMINI_API_KEY}" \
    -d '{
        "content": {
            "parts": [{
                "inline_data": {
                    "mime_type": "application/pdf",
                    "data": "'"${PDF_BASE64}"'"
                }
            }]
        }
    }'

Kullanım alanları

Metin yerleştirmeler, yaygın olarak kullanılan çeşitli yapay zeka kullanım alanları için çok önemlidir. Örneğin:

Yerleştirmeleri depolama

Yerleştirmeleri üretime geçirirken yüksek boyutlu yerleştirmeleri verimli bir şekilde depolamak, dizine eklemek ve almak için vektör veritabanları kullanılır. Google Cloud, bu amaçla kullanılabilecek yönetilen veri hizmetleri sunar. Bu hizmetler arasında Gemini Enterprise Agent Platform Vector Search 2.0, BigQuery, AlloyDB ve Cloud SQL yer alır.

Aşağıdaki eğitimlerde, Gemini Embedding ile diğer üçüncü taraf vektör veritabanlarının nasıl kullanılacağı gösterilmektedir.

Model sürümleri

Gemini Embedding 2

Mülk Açıklama
Model kodu

Gemini API

gemini-embedding-2
Desteklenen veri türleri

Giriş

Metin, resim, video, ses, PDF

Çıkış

Metin yerleştirmeleri
Token sınırları[*]

Giriş jetonu sınırı

8.192

Çıkış boyutu büyüklüğü

Esnek, desteklenenler: 128 - 3072, Önerilen: 768, 1536, 3072
Sürümler
Daha fazla bilgi için model sürümü kalıplarını okuyun.
  • Kararlı: gemini-embedding-2
Son güncelleme Nisan 2026

Gemini Embedding

Mülk Açıklama
Model kodu

Gemini API

gemini-embedding-001
Desteklenen veri türleri

Giriş

Metin

Çıkış

Metin yerleştirmeleri
Token sınırları[*]

Giriş jetonu sınırı

2.048

Çıkış boyutu

Esnek, desteklenenler: 128 - 3072, Önerilen: 768, 1536, 3072
Sürümler
Daha fazla bilgi için model sürümü kalıplarını okuyun.
  • Kararlı: gemini-embedding-001
Son güncelleme Haziran 2025

Desteği sonlandırılan Embeddings modelleri için Desteği sonlandırılan özellikler sayfasını ziyaret edin.

gemini-embedding-001'den taşıma

gemini-embedding-001 ve gemini-embedding-2 arasındaki yerleştirme alanları uyumsuz. Bu nedenle, bir model tarafından oluşturulan yerleştirmeleri diğer model tarafından oluşturulan yerleştirmelerle doğrudan karşılaştıramazsınız. gemini-embedding-2 sürümüne yükseltme yapıyorsanız mevcut tüm verilerinizi yeniden yerleştirmeniz gerekir.

Uyumsuzluğun yanı sıra iki model arasında dikkate değer başka farklar da vardır:

  • Görev türü spesifikasyonu: gemini-embedding-001 ile görev türünü task_type parametresini kullanarak belirtirsiniz (ör. SEMANTIC_SIMILARITY, RETRIEVAL_DOCUMENT). gemini-embedding-2 ile task_type parametresi desteklenmez. Bunun yerine, yalnızca metin içeren görevler için görev talimatlarını doğrudan isteme eklemeniz gerekir. İstemleri farklı kullanım alanları için nasıl biçimlendireceğinizle ilgili ayrıntılı bilgi edinmek üzere Embeddings 2 ile görev türleri bölümünü inceleyin.

  • Yerleştirme toplama: gemini-embedding-001, giriş listesindeki her dize için ayrı yerleştirmeler oluşturur. Buna karşılık, gemini-embedding-2, birden fazla giriş (metin ve resim gibi) doğrudan tek bir istekte sağlandığında tek bir birleştirilmiş yerleştirme üretir. Her bir giriş için ayrı yerleştirmeler oluşturmak istiyorsanız her girişi bir Content nesnesine sarmalayın veya Batch API'yi kullanın. Daha fazla bilgi için Yerleştirme toplama bölümüne bakın.

  • Normalleştirme: 3.072'den az boyuta sahip yerleştirmeler istemek için output_dimensionality kullanırsanız gemini-embedding-2, bu kısaltılmış yerleştirmeleri otomatik olarak normalleştirir. gemini-embedding-001 ile 3072 dışındaki boyutlar için manuel normalleştirme yapmanız gerekir. Ayrıntılar için Daha küçük boyutlar için kaliteyi sağlama başlıklı makaleyi inceleyin.

Toplu yerleştirmeler

Gecikme süresi önemli değilse Gemini Embeddings modellerini Batch API ile kullanmayı deneyin. Bu sayede, varsayılan Embedding fiyatının% 50'si karşılığında çok daha yüksek işleme kapasitesi elde edebilirsiniz. Batch API çözüm kitabında nasıl başlayacağınıza dair örnekler bulabilirsiniz.

Sorumlu kullanım bildirimi

Yeni içerik oluşturan üretken yapay zeka modellerinin aksine Gemini Embedding modeli, yalnızca giriş verilerinizin biçimini sayısal bir temsile dönüştürmek için tasarlanmıştır. Google, giriş verilerinizin biçimini istenen sayısal biçime dönüştüren bir yerleştirme modeli sağlamaktan sorumludur. Ancak kullanıcılar, girdikleri veriler ve elde edilen yerleştirmelerle ilgili tüm sorumluluğu üstlenir. Gemini Embedding modelini kullanarak, yüklediğiniz tüm içeriklerle ilgili gerekli haklara sahip olduğunuzu onaylarsınız. Başkalarının fikri mülkiyet veya gizlilik haklarını ihlal eden içerikler üretmeyin. Bu hizmeti kullanımınız Yasaklanan Kullanım Politikamıza ve Google'ın Hizmet Şartları'na tabidir.

Yerleştirmelerle oluşturmaya başlama

Model özelliklerini keşfetmek ve yerleştirmelerinizi nasıl özelleştirip görselleştireceğinizi öğrenmek için yerleştirmelerle ilgili hızlı başlangıç not defterine göz atın.