Embeddings

Встраивания – это числовое представление текстовых входных данных, которое открывает ряд уникальных вариантов использования, таких как кластеризация, измерение сходства и поиск информации. Подробнее о встраивании…

В отличие от моделей генеративного ИИ, которые создают новый контент, модель Gemini Embedding предназначена только для преобразования формата входных данных в числовое представление. Google предоставляет модель эмбеддинга, которая преобразует формат входных данных в требуемый числовой формат, но пользователи несут полную ответственность за вводимые данные и полученные эмбеддинги. Используя модель Gemini Embedding, вы подтверждаете, что обладаете всеми необходимыми правами на контент, который загружаете. Не генерируйте материалы, нарушающие права на интеллектуальную собственность или право на неприкосновенность частной жизни. Работа с этим сервисом регулируется Правилами в отношении запрещенного использования и Условиями использования Google.

Метод models.embedContent

Генерирует вектор встраивания текста из входных данных Content с помощью указанной модели встраивания Gemini.

Конечная точка

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

Параметры пути

model string

Обязательно. Название ресурса модели. Это идентификатор, который будет использовать модель.

Это название должно совпадать с названием модели, возвращенным методом models.list.

Формат: models/{model}. Форма: models/{model}.

Тело запроса

Ниже приведена структура данных в теле запроса.

Поля
content object (Content)

Обязательно. Контент, который нужно встроить. Будут учитываться только поля parts.text.

taskType
(deprecated)
enum (TaskType)

Необязательное поле. Устарело. Используйте EmbedContentConfig.task_type. Необязательный тип задачи, для которой будут использоваться эмбеддинги. Не поддерживается на более ранних моделях (models/embedding-001).

title
(deprecated)
string

Необязательное поле. Устарело. Используйте EmbedContentConfig.title. Необязательный заголовок для текста. Применимо, только если TaskType – RETRIEVAL_DOCUMENT.

Примечание. Если указать title для RETRIEVAL_DOCUMENT, качество эмбеддингов для извлечения будет выше.

outputDimensionality
(deprecated)
integer

Необязательное поле. Устарело. Используйте EmbedContentConfig.output_dimensionality. Необязательный уменьшенный размер для выходного эмбеддинга. Если задано, лишние значения в выходном эмбеддинге усекаются с конца. Поддерживается только новыми моделями, выпущенными в 2024 году и позже. Если вы используете более раннюю модель (models/embedding-001), то не сможете задать это значение.

embedContentConfig object (EmbedContentConfig)

Необязательное поле. Конфигурация для запроса models.embedContent.

Пример запроса

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

Проложить маршрут

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

Ракушка

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

Генерирует несколько векторов встраивания из входного значения Content, которое состоит из пакета строк, представленных в виде объектов EmbedContentRequest.

Конечная точка

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

Параметры пути

model string

Обязательно. Название ресурса модели. Это идентификатор, который будет использовать модель.

Это название должно совпадать с названием модели, возвращенным методом 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);

Проложить маршрут

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

Ракушка

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)

Только для вывода. Встраивания для каждого запроса в том же порядке, что и в пакетном запросе.

usageMetadata object (EmbeddingUsageMetadata)

Только для вывода. Метаданные об использовании для запроса.

JSON-представление
{
  "embeddings": [
    {
      object (ContentEmbedding)
    }
  ],
  "usageMetadata": {
    object (EmbeddingUsageMetadata)
  }
}

Метод models.asyncBatchEmbedContent

Добавляет в очередь пакет из models.embedContent запросов для пакетной обработки. У нас есть обработчик models.batchEmbedContents в GenerativeService, но он был синхронизирован. Чтобы избежать путаницы, мы назовем этот элемент Async.

Конечная точка

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

Только для вывода. Время создания пакета.

Используется формат RFC 3339. Результат всегда будет Z-нормализованным, и в нем будут использоваться цифры дробных частей 0, 3, 6 или 9. Допустимы и другие типы нормализации. Примеры: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30".

batch.endTime string (Timestamp format)

Только для вывода. Время, когда пакетная обработка была завершена.

Используется формат RFC 3339. Результат всегда будет Z-нормализованным, и в нем будут использоваться цифры дробных частей 0, 3, 6 или 9. Допустимы и другие типы нормализации. Примеры: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30".

batch.updateTime string (Timestamp format)

Только для вывода. Время последнего обновления пакета.

Используется формат RFC 3339. Результат всегда будет Z-нормализованным, и в нем будут использоваться цифры дробных частей 0, 3, 6 или 9. Допустимы и другие типы нормализации. Примеры: "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.

batch.webhookConfig.uris[] string

Необязательное поле. Если задать эти URI, они будут использоваться для событий вебхуков вместо зарегистрированных вебхуков.

Тело ответа

Если ответ получен успешно, его тело содержит экземпляр Operation.

EmbedContentResponse

Ответ на EmbedContentRequest.

Поля
embedding object (ContentEmbedding)

Только для вывода. Встраивание, сгенерированное на основе входного контента.

usageMetadata object (EmbeddingUsageMetadata)

Только для вывода. Метаданные об использовании для запроса.

JSON-представление
{
  "embedding": {
    object (ContentEmbedding)
  },
  "usageMetadata": {
    object (EmbeddingUsageMetadata)
  }
}

ContentEmbedding

Список чисел с плавающей запятой, представляющих встраивание.

Поля
values[] number

Значения эмбеддинга. Это поле заполняется только для сторонних пользователей.

shape[] integer

В этом поле хранится форма кадра тензора мягких токенов (например, [1, 1, 256, 2048]).

JSON-представление
{
  "values": [
    number
  ],
  "shape": [
    integer
  ]
}

TaskType

Тип задачи, для которой будет использоваться эмбеддинг.

Перечисления
TASK_TYPE_UNSPECIFIED Значение не задано. По умолчанию будет использоваться одно из других значений перечисления.
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)

Только для вывода. Время создания пакета.

Используется формат RFC 3339. Результат всегда будет Z-нормализованным, и в нем будут использоваться цифры дробных частей 0, 3, 6 или 9. Допустимы и другие типы нормализации. Примеры: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30".

endTime string (Timestamp format)

Только для вывода. Время, когда пакетная обработка была завершена.

Используется формат RFC 3339. Результат всегда будет Z-нормализованным, и в нем будут использоваться цифры дробных частей 0, 3, 6 или 9. Допустимы и другие типы нормализации. Примеры: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" или "2014-10-02T15:01:23+05:30".

updateTime string (Timestamp format)

Только для вывода. Время последнего обновления пакета.

Используется формат RFC 3339. Результат всегда будет Z-нормализованным, и в нем будут использоваться цифры дробных частей 0, 3, 6 или 9. Допустимы и другие типы нормализации. Примеры: "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
Обязательно. Источник входных данных. Ниже приведен список взаимоисключающих полей. В ответе будет задано не более одного из следующих полей:
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
Выходные данные пакетного запроса. Ниже приведен список взаимоисключающих полей. В ответе будет задано не более одного из следующих полей:
responsesFile string

Только для вывода. Идентификатор файла, содержащего ответы. Файл будет иметь формат JSONL, в котором каждая строка содержит один ответ. Ответы будут представлять собой сообщения EmbedContentResponse в формате JSON. Ответы будут записаны в том же порядке, что и входные запросы.

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
Результат запроса. Ниже приведен список взаимоисключающих полей. В ответе будет задано не более одного из следующих полей:
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
}

EmbedContentConfig

Конфигурации для запроса EmbedContent.

Поля
title string

Необязательное поле. Заголовок текста.

taskType enum (TaskType)

Необязательное поле. Тип задачи для эмбеддинга.

autoTruncate boolean

Необязательное поле. Указывает, нужно ли автоматически усекать входной контент, если он превышает максимальную длину последовательности.

outputDimensionality integer

Необязательное поле. Уменьшенная размерность для выходного эмбеддинга. Если задано, лишние значения в выходном эмбеддинге усекаются с конца.

documentOcr boolean

Необязательное поле. Включить ли оптическое распознавание символов для содержимого документа.

audioTrackExtraction boolean

Необязательное поле. Извлекать ли аудио из видеоконтента.

JSON-представление
{
  "title": string,
  "taskType": enum (TaskType),
  "autoTruncate": boolean,
  "outputDimensionality": integer,
  "documentOcr": boolean,
  "audioTrackExtraction": boolean
}

EmbeddingUsageMetadata

Метаданные об использовании запроса на встраивание.

Поля
promptTokenCount integer

Только для вывода. Количество токенов в запросе.

promptTokenDetails[] object (ModalityTokenCount)

Только для вывода. Список модальностей, которые были обработаны во входных данных запроса.

JSON-представление
{
  "promptTokenCount": integer,
  "promptTokenDetails": [
    {
      object (ModalityTokenCount)
    }
  ]
}