Embeddings

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

메서드: 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_DOCUMENT에 title를 지정하면 검색을 위한 더 나은 품질의 임베딩이 제공됩니다.

outputDimensionality integer

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

요청 예시

Python

# With Gemini-2 we're launching a new SDK, see this doc for details.
# https://ai.google.dev/gemini-api/docs/migrate
README.md

Node.js

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({
  model: "text-embedding-004",
});

const result = await model.embedContent("Hello world!");

console.log(result.embedding);
embed.js

Shell

curl "https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:embedContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model": "models/text-embedding-004",
    "content": {
    "parts":[{
      "text": "Hello world"}]}, }' 2> /dev/null | head
embed.sh

응답 본문

EmbedContentRequest에 대한 응답입니다.

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

필드
embedding object (ContentEmbedding)

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

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

메서드: 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

# With Gemini-2 we're launching a new SDK, see this doc for details.
# https://ai.google.dev/gemini-api/docs/migrate
README.md

Node.js

// Make sure to include these imports:
// import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.API_KEY);
const model = genAI.getGenerativeModel({
  model: "text-embedding-004",
});

function textToRequest(text) {
  return { content: { role: "user", parts: [{ text }] } };
}

const result = await model.batchEmbedContents({
  requests: [
    textToRequest("What is the meaning of life?"),
    textToRequest("How much wood would a woodchuck chuck?"),
    textToRequest("How does the brain work?"),
  ],
});

console.log(result.embeddings);
embed.js

Shell

curl "https://generativelanguage.googleapis.com/v1beta/models/text-embedding-004:batchEmbedContents?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"requests": [{
      "model": "models/text-embedding-004",
      "content": {
      "parts":[{
        "text": "What is the meaning of life?"}]}, },
      {
      "model": "models/text-embedding-004",
      "content": {
      "parts":[{
        "text": "How much wood would a woodchuck chuck?"}]}, },
      {
      "model": "models/text-embedding-004",
      "content": {
      "parts":[{
        "text": "How does the brain work?"}]}, }, ]}' 2> /dev/null | grep -C 5 values
embed.sh

응답 본문

BatchEmbedContentsRequest에 대한 응답입니다.

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

필드
embeddings[] object (ContentEmbedding)

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

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

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_DOCUMENT에 title를 지정하면 검색을 위한 더 나은 품질의 임베딩이 제공됩니다.

outputDimensionality integer

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

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

ContentEmbedding

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

필드
values[] number

임베딩 값입니다.

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

TaskType

임베딩이 사용될 태스크 유형입니다.

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