Embeddings

임베딩은 클러스터링, 유사성 측정, 정보 검색과 같은 다양한 고유한 사용 사례를 지원하는 텍스트 입력의 수치 표현입니다. 소개는 임베딩 가이드를 참고하세요.

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

메서드: models.embedContent

지정된 Gemini 임베딩 모델을 사용하여 입력 Content에서 텍스트 임베딩 벡터를 생성합니다.

엔드포인트

게시물 https://generativelanguage.googleapis.com/v1beta/{model=models/*}:embedContent

경로 매개변수

model string

필수 항목입니다. 모델의 리소스 이름입니다. 이는 모델에서 사용할 ID 역할을 합니다.

이 이름은 models.list 메서드에서 반환된 모델 이름과 일치해야 합니다.

형식: models/{model} models/{model} 형식이 사용됩니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

필드
content object (Content)

필수 항목입니다. 삽입할 콘텐츠입니다. parts.text 필드만 집계됩니다.

taskType enum (TaskType)

선택사항입니다. 임베딩이 사용될 선택적 태스크 유형입니다. 이전 모델 (models/embedding-001)에서는 지원되지 않습니다.

title string

선택사항입니다. 텍스트의 제목(선택사항)입니다. TaskType이 RETRIEVAL_DOCUMENT인 경우에만 적용됩니다.

참고: RETRIEVAL_DOCUMENTtitle를 지정하면 검색을 위한 더 나은 품질의 임베딩이 제공됩니다.

outputDimensionality integer

선택사항입니다. 출력 임베딩의 선택적 축소된 차원입니다. 설정하면 출력 임베딩의 과도한 값이 끝에서 잘립니다. 2024년 이후의 최신 모델에서만 지원됩니다. 이전 모델 (models/embedding-001)을 사용하는 경우 이 값을 설정할 수 없습니다.

요청 예시

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

응답 본문

성공한 경우 응답 본문에 EmbedContentResponse의 인스턴스가 포함됩니다.

메서드: models.batchEmbedContents

EmbedContentRequest 객체로 표현된 문자열 배치로 구성된 입력 Content에서 여러 임베딩 벡터를 생성합니다.

엔드포인트

게시물 https://generativelanguage.googleapis.com/v1beta/{model=models/*}:batchEmbedContents

경로 매개변수

model string

필수 항목입니다. 모델의 리소스 이름입니다. 이는 모델에서 사용할 ID 역할을 합니다.

이 이름은 models.list 메서드에서 반환된 모델 이름과 일치해야 합니다.

형식: models/{model} models/{model} 형식이 사용됩니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

필드
requests[] object (EmbedContentRequest)

필수 항목입니다. 배치의 삽입 요청입니다. 이러한 각 요청의 모델은 지정된 모델 BatchEmbedContentsRequest.model과 일치해야 합니다.

요청 예시

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

응답 본문

BatchEmbedContentsRequest에 대한 응답입니다.

성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.

필드
embeddings[] object (ContentEmbedding)

출력 전용입니다. 각 요청의 삽입으로, 배치 요청에 제공된 순서와 동일합니다.

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

메서드: models.asyncBatchEmbedContent

일괄 처리를 위해 models.embedContent 요청을 대기열에 추가합니다. GenerativeServicemodels.batchEmbedContents 핸들러가 있지만 동기화되었습니다. 혼동을 방지하기 위해 이 이름을 Async로 지정합니다.

엔드포인트

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

경로 매개변수

batch.model string

필수 항목입니다. 완료를 생성하는 데 사용할 Model의 이름입니다.

형식: models/{model} models/{model} 형식이 사용됩니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

필드
batch.name string

출력 전용입니다. 식별자. 일괄 처리의 리소스 이름입니다.

형식: batches/{batchId}

batch.displayName string

필수 항목입니다. 이 배치에 사용자가 정의한 이름입니다.

batch.inputConfig object (InputEmbedContentConfig)

필수 항목입니다. 일괄 처리가 실행되는 인스턴스의 입력 구성입니다.

batch.output object (EmbedContentBatchOutput)

출력 전용입니다. 일괄 요청의 출력입니다.

batch.createTime string (Timestamp format)

출력 전용입니다. 배치가 생성된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.

batch.endTime string (Timestamp format)

출력 전용입니다. 일괄 처리가 완료된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.

batch.updateTime string (Timestamp format)

출력 전용입니다. 배치가 마지막으로 업데이트된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.

batch.batchStats object (EmbedContentBatchStats)

출력 전용입니다. 배치에 관한 통계입니다.

batch.state enum (BatchState)

출력 전용입니다. 배치의 상태입니다.

batch.priority string (int64 format)

선택사항입니다. 배치의 우선순위입니다. 우선순위 값이 높은 일괄 처리는 우선순위 값이 낮은 일괄 처리보다 먼저 처리됩니다. 음수 값을 사용할 수 있습니다. 기본값은 0입니다.

응답 본문

성공한 경우 응답 본문에 Operation의 인스턴스가 포함됩니다.

EmbedContentRequest

모델이 삽입할 Content이 포함된 요청입니다.

필드
model string

필수 항목입니다. 모델의 리소스 이름입니다. 이는 모델에서 사용할 ID 역할을 합니다.

이 이름은 models.list 메서드에서 반환된 모델 이름과 일치해야 합니다.

형식: models/{model}

content object (Content)

필수 항목입니다. 삽입할 콘텐츠입니다. parts.text 필드만 집계됩니다.

taskType enum (TaskType)

선택사항입니다. 임베딩이 사용될 선택적 태스크 유형입니다. 이전 모델 (models/embedding-001)에서는 지원되지 않습니다.

title string

선택사항입니다. 텍스트의 제목(선택사항)입니다. TaskType이 RETRIEVAL_DOCUMENT인 경우에만 적용됩니다.

참고: RETRIEVAL_DOCUMENTtitle를 지정하면 검색을 위한 더 나은 품질의 임베딩이 제공됩니다.

outputDimensionality integer

선택사항입니다. 출력 임베딩의 선택적 축소된 차원입니다. 설정하면 출력 임베딩의 과도한 값이 끝에서 잘립니다. 2024년 이후의 최신 모델에서만 지원됩니다. 이전 모델 (models/embedding-001)을 사용하는 경우 이 값을 설정할 수 없습니다.

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

EmbedContentResponse

EmbedContentRequest에 대한 응답입니다.

필드
embedding object (ContentEmbedding)

출력 전용입니다. 입력 콘텐츠에서 생성된 임베딩입니다.

JSON 표현
{
  "embedding": {
    object (ContentEmbedding)
  }
}

ContentEmbedding

임베딩을 나타내는 부동 소수점 수 목록입니다.

필드
values[] number

삽입 값입니다.

JSON 표현
{
  "values": [
    number
  ]
}

TaskType

임베딩이 사용될 작업 유형입니다.

열거형
TASK_TYPE_UNSPECIFIED 설정되지 않은 값으로, 다른 enum 값 중 하나로 기본 설정됩니다.
RETRIEVAL_QUERY 지정된 텍스트가 검색/가져오기 설정의 쿼리임을 지정합니다.
RETRIEVAL_DOCUMENT 지정된 텍스트가 검색 중인 코퍼스의 문서임을 지정합니다.
SEMANTIC_SIMILARITY 지정된 텍스트를 STS에 사용하도록 지정합니다.
CLASSIFICATION 지정된 텍스트가 분류됨을 지정합니다.
CLUSTERING 클러스터링에 임베딩을 사용하도록 지정합니다.
QUESTION_ANSWERING 지정된 텍스트를 질의 응답에 사용하도록 지정합니다.
FACT_VERIFICATION 지정된 텍스트를 사실 확인에 사용하도록 지정합니다.
CODE_RETRIEVAL_QUERY 지정된 텍스트를 코드 검색에 사용하도록 지정합니다.

EmbedContentBatch

EmbedContent 요청의 일괄 처리를 나타내는 리소스입니다.

필드
model string

필수 항목입니다. 완료를 생성하는 데 사용할 Model의 이름입니다.

형식: models/{model}

name string

출력 전용입니다. 식별자. 일괄 처리의 리소스 이름입니다.

형식: batches/{batchId}

displayName string

필수 항목입니다. 이 배치에 사용자가 정의한 이름입니다.

inputConfig object (InputEmbedContentConfig)

필수 항목입니다. 일괄 처리가 실행되는 인스턴스의 입력 구성입니다.

output object (EmbedContentBatchOutput)

출력 전용입니다. 일괄 요청의 출력입니다.

createTime string (Timestamp format)

출력 전용입니다. 배치가 생성된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.

endTime string (Timestamp format)

출력 전용입니다. 일괄 처리가 완료된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.

updateTime string (Timestamp format)

출력 전용입니다. 배치가 마지막으로 업데이트된 시간입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.

batchStats object (EmbedContentBatchStats)

출력 전용입니다. 배치에 관한 통계입니다.

state enum (BatchState)

출력 전용입니다. 배치의 상태입니다.

priority string (int64 format)

선택사항입니다. 배치의 우선순위입니다. 우선순위 값이 높은 일괄 처리는 우선순위 값이 낮은 일괄 처리보다 먼저 처리됩니다. 음수 값을 사용할 수 있습니다. 기본값은 0입니다.

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

일괄 요청의 입력을 구성합니다.

필드
source Union type
필수 항목입니다. 입력 소스입니다. source는 다음 중 하나여야 합니다.
fileName string

입력 요청이 포함된 File의 이름입니다.

requests object (InlinedEmbedContentRequests)

일괄 처리할 요청입니다.

JSON 표현
{

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

InlinedEmbedContentRequests

일괄 생성 요청의 일부로 제공된 경우 일괄로 처리할 요청입니다.

필드
requests[] object (InlinedEmbedContentRequest)

필수 항목입니다. 일괄 처리할 요청입니다.

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

InlinedEmbedContentRequest

일괄 처리할 요청입니다.

필드
request object (EmbedContentRequest)

필수 항목입니다. 일괄 처리할 요청입니다.

metadata object (Struct format)

선택사항입니다. 요청과 연결할 메타데이터입니다.

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

EmbedContentBatchOutput

일괄 요청의 출력입니다. 이는 AsyncBatchEmbedContentResponse 또는 EmbedContentBatch.output 필드에 반환됩니다.

필드
output Union type
일괄 요청의 출력입니다. output는 다음 중 하나여야 합니다.
responsesFile string

출력 전용입니다. 응답이 포함된 파일의 파일 ID입니다. 파일은 한 줄에 하나의 대답이 있는 JSONL 파일입니다. 대답은 JSON 형식으로 지정된 EmbedContentResponse 메시지입니다. 대답은 입력 요청과 동일한 순서로 작성됩니다.

inlinedResponses object (InlinedEmbedContentResponses)

출력 전용입니다. 배치에 있는 요청에 대한 응답입니다. 인라인 요청을 사용하여 일괄이 빌드된 경우 반환됩니다. 대답은 입력 요청과 동일한 순서로 제공됩니다.

JSON 표현
{

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

InlinedEmbedContentResponses

배치에 있는 요청에 대한 응답입니다.

필드
inlinedResponses[] object (InlinedEmbedContentResponse)

출력 전용입니다. 배치에 있는 요청에 대한 응답입니다.

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

InlinedEmbedContentResponse

배치의 단일 요청에 대한 응답입니다.

필드
metadata object (Struct format)

출력 전용입니다. 요청과 연결된 메타데이터입니다.

output Union type
요청의 출력입니다. output는 다음 중 하나여야 합니다.
error object (Status)

출력 전용입니다. 요청을 처리하는 중에 발생한 오류입니다.

response object (EmbedContentResponse)

출력 전용입니다. 요청에 대한 응답입니다.

JSON 표현
{
  "metadata": {
    object
  },

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

EmbedContentBatchStats

배치에 관한 통계입니다.

필드
requestCount string (int64 format)

출력 전용입니다. 배치의 요청 수입니다.

successfulRequestCount string (int64 format)

출력 전용입니다. 성공적으로 처리된 요청의 수입니다.

failedRequestCount string (int64 format)

출력 전용입니다. 처리되지 않은 요청 수입니다.

pendingRequestCount string (int64 format)

출력 전용입니다. 아직 처리 대기 중인 요청 수입니다.

JSON 표현
{
  "requestCount": string,
  "successfulRequestCount": string,
  "failedRequestCount": string,
  "pendingRequestCount": string
}