임베딩

Gemini API는 텍스트, 이미지, 동영상, 기타 콘텐츠의 임베딩을 생성하는 임베딩 모델을 제공합니다. 이렇게 생성된 임베딩은 시맨틱 검색, 분류, 클러스터링과 같은 태스크에 사용되어 키워드 기반 접근 방식보다 더 정확하고 컨텍스트를 인식하는 결과를 제공할 수 있습니다.

최신 모델인 gemini-embedding-2은 Gemini API의 첫 번째 멀티모달 임베딩 모델입니다. 텍스트, 이미지, 동영상, 오디오, 문서를 통합 임베딩 공간에 매핑하여 100개 이상의 언어로 교차 모달 검색, 분류, 클러스터링을 지원합니다. 자세한 내용은 멀티모달 임베딩 섹션을 참조하세요. 텍스트 전용 사용 사례의 경우 gemini-embedding-001를 계속 사용할 수 있습니다.

검색 증강 생성 (RAG) 시스템을 빌드하는 것은 AI 제품의 일반적인 사용 사례입니다. 임베딩은 사실 기반 정확성, 일관성, 문맥적 풍부함을 개선하여 모델 출력을 크게 향상시키는 데 중요한 역할을 합니다. 관리형 RAG 솔루션을 사용하려면 RAG를 더 쉽게 관리하고 비용 효율적으로 수행할 수 있는 파일 검색 도구를 빌드했습니다.

임베딩 생성

embedContent 메서드를 사용하여 텍스트 임베딩을 생성합니다.

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

자바

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

성능 개선을 위한 작업 유형 지정

임베딩은 분류부터 문서 검색까지 다양한 작업에 사용할 수 있습니다. 올바른 태스크 유형을 지정하면 의도한 관계에 맞게 임베딩을 최적화하여 정확성과 효율성을 극대화할 수 있습니다.

임베딩 2의 태스크 유형

gemini-embedding-2를 사용하는 텍스트 전용 태스크의 경우 프롬프트에 태스크 안내를 추가하는 것이 좋습니다. 올바른 태스크 프리픽스로 쿼리와 문서의 형식을 지정하면 됩니다.

멀티모달 입력을 기반으로 단일 임베딩을 생성할 때는 일반적으로 입력의 텍스트 부분에 작업 안내를 프리픽스로 추가하지 않는 것이 좋습니다. 경우에 따라 성능이 향상되지만 성능이 저하되는 경우도 있습니다.

다음 표에서는 gemini-embedding-2 모델을 사용하여 대칭 및 비대칭 사용 사례의 쿼리와 문서 형식을 지정하는 방법의 예를 보여줍니다.

검색 사용 사례 (비대칭 형식)

비대칭 사용 사례에서는 쿼리에 태스크 프리픽스를 추가하고 임베딩 및 검색하려는 콘텐츠에 문서 구조를 적용합니다.

사용 사례 쿼리 구조 문서 구조
검색어 task: search result | query: {content} title: {title} | text: {content}
제목이 없으면 title: none를 사용합니다.
질의 응답 task: question answering | query: {content} title: {title} | text: {content}
사실확인 task: fact checking | query: {content} title: {title} | text: {content}
코드 검색 task: code retrieval | query: {content} title: {title} | text: {content}

사용 예시

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}"

단일 입력 사용 사례 (대칭 형식)

대칭 사용 사례에서는 동일한 태스크에 대해 쿼리와 문서에 동일한 형식을 사용합니다.

사용 사례 입력 구조
분류 task: classification | query: {content}
클러스터링 task: clustering | query: {content}
의미론적 유사도 task: sentence similarity | query: {content}
검색 또는 가져오기에 사용하지 마세요. 시맨틱 텍스트 유사성을 위해 사용됩니다.

사용 예시

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}'

작업을 일관되게 사용하는 것이 중요합니다. 예를 들어 문서가 f'task: classification | query: {content}'로 임베딩된 경우 쿼리도 이 태스크 형식에 따라 임베딩되어야 합니다.

임베딩 1의 태스크 유형

gemini-embedding-001의 경우 embedContent 메서드에서 task_type를 지정할 수 있습니다. 지원되는 태스크 유형의 전체 목록은 지원되는 태스크 유형 표를 참조하세요.

다음 예시에서는 SEMANTIC_SIMILARITY를 사용하여 텍스트 문자열의 의미가 얼마나 유사한지 확인하는 방법을 보여줍니다.

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

자바

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

코드 스니펫은 실행 시 서로 다른 텍스트 청크가 얼마나 유사한지 보여줍니다.

지원되는 태스크 유형

gemini-embedding-001에 지원되는 작업 유형:

작업 유형 설명 예
SEMANTIC_SIMILARITY 텍스트 유사성을 평가하도록 최적화된 임베딩입니다. 추천 시스템, 중복 감지
분류 사전 설정된 라벨에 따라 텍스트를 분류하도록 최적화된 임베딩입니다. 감정 분석, 스팸 감지
CLUSTERING 유사성을 기반으로 텍스트를 클러스터링하는 데 최적화된 임베딩입니다. 문서 정리, 시장 조사, 이상 감지
RETRIEVAL_DOCUMENT 문서 검색에 최적화된 임베딩입니다. 검색을 위해 기사, 도서 또는 웹페이지의 색인을 생성합니다.
RETRIEVAL_QUERY 일반 검색어에 최적화된 임베딩입니다. 쿼리에는 RETRIEVAL_QUERY를 사용하고 검색할 문서에는 RETRIEVAL_DOCUMENT를 사용합니다. 맞춤검색
CODE_RETRIEVAL_QUERY 자연어 쿼리를 기반으로 코드 블록을 검색하는 데 최적화된 임베딩입니다. 쿼리에는 CODE_RETRIEVAL_QUERY를, 검색할 코드 블록에는 RETRIEVAL_DOCUMENT를 사용합니다. 코드 추천 및 검색
QUESTION_ANSWERING 질문에 답하는 문서를 찾도록 최적화된 질의 응답 시스템의 질문 임베딩입니다. 질문에는 QUESTION_ANSWERING를, 검색할 문서에는 RETRIEVAL_DOCUMENT를 사용합니다. 채팅 상자
FACT_VERIFICATION 검증이 필요한 문장의 임베딩으로, 문장을 뒷받침하거나 반박하는 증거가 포함된 문서를 검색하는 데 최적화되어 있습니다. 타겟 텍스트에는 FACT_VERIFICATION를 사용하고 검색할 문서에는 RETRIEVAL_DOCUMENT를 사용합니다. 자동 사실확인 시스템

임베딩 크기 제어

gemini-embedding-001 및 gemini-embedding-2는 모두 Matryoshka Representation Learning (MRL) 표현 학습 기법을 사용하여 학습됩니다. 이 기법은 동일한 데이터의 더 간단하고 유용한 버전인 초기 세그먼트 (또는 프리픽스)가 있는 고차원 임베딩을 학습하도록 모델을 가르칩니다.

output_dimensionality 파라미터를 사용하여 출력 임베딩 벡터의 크기를 제어합니다. 더 작은 출력 크기를 선택하면 저장공간을 절약하고 다운스트림 애플리케이션의 계산 효율성을 높일 수 있으며 품질 면에서는 거의 손실이 없습니다. 기본적으로 두 모델 모두 3072차원 임베딩을 출력하지만 품질 저하 없이 더 작은 크기로 잘라 저장공간을 절약할 수 있습니다. 768, 1536 또는 3072 출력 차원을 사용하는 것이 좋습니다.

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

자바

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
    }'

코드 스니펫의 출력 예시:

Length of embedding: 768

작은 크기의 품질 보장

기본 3072 차원 임베딩은 항상 정규화되지만 Gemini Embedding 2는 잘린 차원 (예: 768, 1536)도 자동으로 정규화합니다. 이렇게 하면 크기가 아닌 벡터 방향을 통해 시맨틱 유사성이 계산되므로 기본적으로 더 정확한 결과를 얻을 수 있습니다.

이전 모델: gemini-embedding-001를 사용하는 경우 다음과 같이 3072가 아닌 차원을 수동으로 정규화해야 합니다.

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

이 코드 스니펫의 출력 예시:

Normed embedding length: 768
Norm of normed embedding: 1.000000

다음 표에는 다양한 차원에 대해 흔히 사용되는 임베딩 벤치마크인 MTEB 점수가 나와 있습니다. 특히 결과는 성능이 임베딩 차원의 크기와 엄격하게 연결되지 않으며, 낮은 차원이 높은 차원과 비슷한 점수를 달성한다는 것을 보여줍니다.

MRL 측정기준 MTEB 점수 (Gemini 임베딩 001)
2048 68.16
1536 68.17
768 67.99
512 67.55
256 66.19
128 63.31

멀티모달 임베딩

gemini-embedding-2 모델은 멀티모달 입력을 지원하므로 텍스트와 함께 이미지, 동영상, 오디오, 문서 콘텐츠를 임베딩할 수 있습니다. 모든 모달리티는 동일한 임베딩 공간에 매핑되어 교차 모달 검색 및 비교가 가능합니다.

지원되는 형식 및 한도

전체 최대 입력 토큰 한도는 8,192개 토큰입니다.

형식 사양 및 한도
텍스트 토큰을 최대 8,192개까지 지원합니다.
이미지 요청당 최대 6개의 이미지를 포함할 수 있습니다. 지원되는 형식: PNG, JPEG
오디오 최대 길이는 180초입니다. 지원되는 형식: MP3, WAV
동영상 최대 길이는 120초입니다. 지원되는 형식: MP4, MOV 지원되는 코덱: H264, H265, AV1, VP9
시스템은 동영상당 최대 32개의 프레임을 처리합니다. 짧은 동영상 (32초 이하)은 1fps로 샘플링되고, 긴 동영상은 32개 프레임으로 균일하게 샘플링됩니다. 오디오 트랙은 동영상 파일에서 처리되지 않습니다.
문서 (PDF) 요청당 최대 1개 파일, 최대 6페이지

이미지 삽입

다음 예시에서는 gemini-embedding-2를 사용하여 이미지를 삽입하는 방법을 보여줍니다.

이미지는 인라인 데이터로 제공하거나 Files API를 통해 업로드된 파일로 제공할 수 있습니다.

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

자바

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

임베딩 집계

멀티모달 콘텐츠로 작업할 때 입력 구조화 방식은 임베딩 출력에 영향을 미칩니다.

  • 여러 부분 (집계): contents 매개변수에 여러 입력을 직접 추가하면 모든 입력에 대해 하나의 집계된 임베딩이 생성됩니다.
  • 여러 Content 객체 (개별): 각 입력을 Content 객체로 래핑하고 contents 매개변수에 전달하면 각 항목에 대해 개별 임베딩이 반환됩니다.
  • 게시물 수준 표현: 여러 미디어 항목이 있는 소셜 미디어 게시물과 같은 복잡한 객체의 경우 별도의 임베딩을 집계(예: 평균화)하여 일관된 게시물 수준 표현을 만드는 것이 좋습니다.

다음 예시에서는 텍스트 및 이미지 입력에 대해 하나의 집계된 임베딩을 만드는 방법을 보여줍니다. contents 매개변수에 여러 입력을 추가하기만 하면 됩니다.

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

자바

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

반면에 contents 매개변수 내에서 Content 객체를 사용하면 별도의 임베딩이 반환됩니다. 이 예시에서는 하나의 임베딩 호출에서 여러 임베딩을 만듭니다.

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

자바

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

오디오 삽입

다음 예시에서는 gemini-embedding-2를 사용하여 오디오 파일을 삽입하는 방법을 보여줍니다.

오디오 파일은 인라인 데이터로 제공하거나 Files API를 통해 업로드된 파일로 제공할 수 있습니다.

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

자바

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

동영상 삽입 중

다음 예시에서는 gemini-embedding-2를 사용하여 동영상을 삽입하는 방법을 보여줍니다.

동영상은 인라인 데이터로 제공하거나 Files API를 통해 업로드된 파일로 제공할 수 있습니다.

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

자바

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초가 넘는 동영상을 삽입해야 하는 경우 동영상을 겹치는 세그먼트로 분할하고 이러한 청크를 개별적으로 삽입할 수 있습니다.

문서 임베딩

PDF 형식의 문서는 직접 삽입할 수 있습니다. 모델은 각 페이지의 시각적 콘텐츠와 텍스트 콘텐츠를 처리합니다.

PDF는 인라인 데이터로 제공하거나 Files API를 통해 업로드된 파일로 제공할 수 있습니다.

모델이 PDF를 처리하는 방식

PDF를 임베딩하면 모델은 시각적 특성과 텍스트 특성을 모두 사용하여 문서를 처리합니다.

  • 시각적 표현: 모델은 각 페이지를 이미지로 렌더링하며, 페이지당 258개의 토큰을 사용합니다.
  • 텍스트 추출: 모델이 문서에서 텍스트를 추출합니다. 기본 PDF (디지털 텍스트 포함)의 경우 모델이 텍스트를 직접 추출합니다. 스캔된 PDF (텍스트 이미지가 포함된 PDF)의 경우 모델이 자동으로 광학 문자 인식 (OCR)을 실행하여 텍스트를 추출합니다.

PDF의 총 토큰 수를 계산하려면 시각적 토큰 (페이지당 258개)을 텍스트 토큰에 더합니다. 입력은 모델의 8,192 토큰 한도 (모든 형식에서 공유됨) 내에 맞아야 합니다. 시스템은 이 한도를 초과하는 입력을 자동으로 자릅니다.

PDF 한도

  • 요청당 파일 수: 최대 1개의 PDF 파일을 제출할 수 있습니다.
  • 페이지 제한: 파일당 최대 6페이지를 제출할 수 있습니다. 최상의 품질을 위해 PDF당 1페이지를 사용하는 것이 좋습니다.

다음 예시에서는 gemini-embedding-2를 사용하여 PDF를 삽입하는 방법을 보여줍니다.

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

자바

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

사용 사례

텍스트 임베딩은 다음과 같은 다양한 일반적인 AI 사용 사례에 매우 중요합니다.

  • 검색 증강 생성 (RAG): 임베딩은 관련 정보를 검색하고 모델의 컨텍스트에 통합하여 생성된 텍스트의 품질을 향상시킵니다.
  • 정보 검색: 입력 텍스트가 주어지면 의미상 가장 유사한 텍스트 또는 문서를 검색합니다.

    문서 검색 튜토리얼

  • 검색 순위 재조정: 쿼리에 대한 초기 결과의 시맨틱 점수를 매겨 가장 관련성이 높은 항목에 우선순위를 지정합니다.

    검색 순위 재지정 튜토리얼

  • 이상 감지: 임베딩 그룹을 비교하면 숨겨진 트렌드나 이상치를 식별하는 데 도움이 될 수 있습니다.

    이상 감지 튜토리얼

  • 분류: 감정 분석 또는 스팸 감지와 같이 콘텐츠를 기반으로 텍스트를 자동으로 분류합니다.

    분류 튜토리얼

  • 클러스터링: 임베딩의 클러스터와 시각화를 만들어 복잡한 관계를 효과적으로 파악합니다.

    클러스터링 시각화 튜토리얼

임베딩 저장

임베딩을 프로덕션으로 가져갈 때는 벡터 데이터베이스를 사용하여 고차원 임베딩을 효율적으로 저장, 색인 생성, 검색하는 것이 일반적입니다. Google Cloud는 이 용도로 사용할 수 있는 관리형 데이터 서비스를 제공합니다. 여기에는 Gemini Enterprise Agent Platform 벡터 검색 2.0, BigQuery, AlloyDB, Cloud SQL이 포함됩니다.

다음 튜토리얼에서는 Gemini 임베딩과 함께 다른 서드 파티 벡터 데이터베이스를 사용하는 방법을 보여줍니다.

모델 버전

Gemini Embedding 2

속성 설명
모델 코드

Gemini API

gemini-embedding-2

지원되는 데이터 유형

입력

텍스트, 이미지, 동영상, 오디오, PDF

출력

텍스트 임베딩

토큰 한도[*]

입력 토큰 한도

8,192

출력 측정기준 크기

유연함, 지원: 128~3072, 권장: 768, 1536, 3072

버전
자세한 내용은 모델 버전 패턴을 참조하세요.
  • 안정화 버전: gemini-embedding-2
최신 업데이트 2026년 4월

Gemini 임베딩

속성 설명
모델 코드

Gemini API

gemini-embedding-001

지원되는 데이터 유형

입력

텍스트

출력

텍스트 임베딩

토큰 한도[*]

입력 토큰 한도

2,048

출력 측정기준 크기

유연함, 지원: 128~3072, 권장: 768, 1536, 3072

버전
자세한 내용은 모델 버전 패턴을 참조하세요.
  • 안정화 버전: gemini-embedding-001
최신 업데이트 2025년 6월

지원 중단된 임베딩 모델은 지원 중단 페이지를 참조하세요.

gemini-embedding-001에서 마이그레이션

gemini-embedding-001와 gemini-embedding-2 사이의 임베딩 공간은 호환되지 않습니다. 즉, 한 모델에서 생성된 임베딩을 다른 모델에서 생성된 임베딩과 직접 비교할 수 없습니다. gemini-embedding-2로 업그레이드하는 경우 기존 데이터를 모두 다시 삽입해야 합니다.

비호환성 외에도 두 모델 간에는 다음과 같은 몇 가지 주목할 만한 차이점이 있습니다.

  • 태스크 유형 사양: gemini-embedding-001에서는 task_type 파라미터 (예: SEMANTIC_SIMILARITY, RETRIEVAL_DOCUMENT)를 사용하여 태스크 유형을 지정합니다. gemini-embedding-2에서는 task_type 파라미터가 지원되지 않습니다. 대신 텍스트 전용 작업의 프롬프트에 작업 요청 사항을 직접 포함해야 합니다. 다양한 사용 사례에 맞게 프롬프트 형식을 지정하는 방법에 대한 자세한 내용은 Embeddings 2의 태스크 유형을 참조하세요.

  • 임베딩 집계: gemini-embedding-001는 입력 목록의 각 문자열에 대해 개별 임베딩을 생성합니다. 반면 gemini-embedding-2은 여러 입력 (예: 텍스트 및 이미지)이 하나의 요청에 직접 제공될 때 단일 집계 임베딩을 생성합니다. 개별 입력에 대해 별도의 임베딩을 생성하려면 각 입력을 Content 객체로 래핑하거나 Batch API를 사용합니다. 자세한 내용은 임베딩 집계를 참조하세요.

  • 정규화: output_dimensionality를 사용하여 3,072개 미만의 차원으로 임베딩을 요청하면 gemini-embedding-2에서 이러한 잘린 임베딩을 자동으로 정규화합니다. gemini-embedding-001를 사용하면 3072 이외의 차원에 대해 수동 정규화를 수행해야 합니다. 자세한 내용은 작은 크기의 품질 보장을 참고하세요.

일괄 임베딩

지연 시간이 문제가 되지 않는다면 Batch API와 함께 Gemini 임베딩 모델을 사용해 보세요. 이를 통해 기본 임베딩 가격의 50% 로 훨씬 더 높은 처리량을 얻을 수 있습니다. Batch API 설명서에서 시작하는 방법에 관한 예시를 확인하세요.

책임감 있는 사용에 관한 고지

새로운 콘텐츠를 만드는 생성형 AI 모델과 달리 Gemini 임베딩 모델은 입력 데이터 형식을 수치 표현으로 변환하는 용도로만 사용됩니다. Google은 입력 데이터 형식을 요청된 숫자 형식으로 변환하는 임베딩 모델을 제공할 책임이 있지만, 사용자는 입력하는 데이터와 결과 임베딩에 대한 모든 책임을 집니다. Gemini 임베딩 모델을 사용하면 업로드하는 모든 콘텐츠에 필요한 권리가 있음을 확인하는 것으로 간주됩니다. 타인의 지식 재산 및 개인 정보 보호 권리를 침해하는 콘텐츠를 생성해서는 안 됩니다. 이 서비스를 사용하면 Google의 금지된 사용 정책 및 Google 서비스 약관이 적용됩니다.

임베딩으로 빌드 시작하기

임베딩 빠른 시작 노트북을 확인하여 모델 기능을 살펴보고 임베딩을 맞춤설정하고 시각화하는 방법을 알아보세요.