Embeddings

Эмбеддинги — это числовое представление входного текста, открывающее множество уникальных возможностей применения, таких как кластеризация, измерение сходства и поиск информации. Для ознакомления с ними обратитесь к руководству по эмбеддингам .

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

Метод: models.embedContent

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

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

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

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

string model

Обязательно. Имя ресурса модели. Оно служит идентификатором для используемой модели.

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

Формат: models/{model} Он принимает вид models/{model} .

Текст запроса

Тело запроса содержит данные следующей структуры:

Поля
объект content object ( Content )

Обязательно. Содержимое для встраивания. Учитываться будут только поля parts.text .

перечисление taskType enum ( TaskType )

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

string title

Необязательно. Необязательный заголовок для текста. Применимо только в том случае, если TaskType имеет значение RETRIEVAL_DOCUMENT .

Примечание: указание title для RETRIEVAL_DOCUMENT обеспечивает более высокое качество векторных представлений для поиска.

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

Идти

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

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

string model

Обязательно. Имя ресурса модели. Оно служит идентификатором для используемой модели.

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

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

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

Метод: 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 дробных знаков. Допускаются также смещения, отличные от "Z". Примеры: "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 дробных знаков. Допускаются также смещения, отличные от "Z". Примеры: "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 дробных знаков. Допускаются также смещения, отличные от "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 .

EmbedContentResponse

Ответ на запрос EmbedContentRequest .

Поля
объект embedding object ( ContentEmbedding )

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

JSON-представление
{
  "embedding": {
    object (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 (Self-Through Text Scheme).
CLASSIFICATION Указывает, что данный текст будет засекречен.
CLUSTERING Указывает, что эмбеддинги будут использоваться для кластеризации.
QUESTION_ANSWERING Указывает, что данный текст будет использоваться для ответа на вопросы.
FACT_VERIFICATION Указывает, что данный текст будет использован для проверки фактов.
CODE_RETRIEVAL_QUERY Указывает, что данный текст будет использоваться для извлечения кода.

EmbedContentBatch

Ресурс, представляющий собой пакет запросов EmbedContent .

Поля
string model

Обязательно. Название Model , которая будет использоваться для генерации автозавершения.

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

string name

Только вывод. Идентификатор. Имя ресурса пакета.

Формат: batches/{batchId} .

displayName string

Обязательно. Заданное пользователем имя для этой партии.

объект inputConfig object ( InputEmbedContentConfig )

Обязательно. Введите конфигурацию экземпляров, на которых выполняется пакетная обработка.

output object ( EmbedContentBatchOutput )

Только вывод. Результат пакетного запроса.

createTime string ( Timestamp format)

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

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

Имя 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

Только вывод. Идентификатор файла, содержащего ответы. Файл будет представлять собой 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
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
}