Embeddings

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

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

Метод: models.embedContent

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

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

пост 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 ).

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

Питон

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 .

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

пост https: / /generativelanguage.googleapis.com /v1beta /{model=models /*}:batchEmbedContents

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

string model

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

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

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

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

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

Поля
объект requests[] object ( EmbedContentRequest )

Обязательно. Запросы на встраивание для пакета. Модель в каждом из этих запросов должна соответствовать модели, указанной в BatchEmbedContentsRequest.model .

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

Питон

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 .

В случае успеха тело ответа содержит данные со следующей структурой:

Поля
object ( ContentEmbedding ) embeddings[] ( ContentEmbedding )

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

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

Метод: models.asyncBatchEmbedContent

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

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

пост https: / /generativelanguage.googleapis.com /v1beta /{batch.model=models /*}:asyncBatchEmbedContent

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

string batch.model

Обязательно. Имя Model , используемой для создания дополнения.

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

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

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

Поля
string batch.name

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

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

string batch.displayName

Обязательно. Имя этого пакета, заданное пользователем.

объект batch.inputConfig object ( InputEmbedContentConfig )

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

object ( EmbedContentBatchOutput ) batch.output ( 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" .

object ( EmbedContentBatchStats ) batch.batchStats ( EmbedContentBatchStats )

Только вывод. Статистика по партии.

batch.state enum ( BatchState )

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

string ( int64 format) batch.priority (формат int64)

Необязательно. Приоритет пакета. Пакеты с более высоким приоритетом будут обработаны раньше пакетов с более низким приоритетом. Допускаются отрицательные значения. Значение по умолчанию — 0.

Тело ответа

В случае успеха тело ответа содержит экземпляр Operation .

EmbedContentRequest

Запрос, содержащий Content для модели для встраивания.

Поля
string model

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

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

Формат: 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 ).

JSON-представление
{
  "model": string,
  "content": {
    object (Content)
  },
  "taskType": enum (TaskType),
  "title": string,
  "outputDimensionality": integer
}

EmbedContentResponse

Ответ на EmbedContentRequest .

Поля
embedding object ( ContentEmbedding )

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

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

Встраивание контента

Список плавающих элементов, представляющих вложение.

Поля
values[] number

Вложенные значения.

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

Тип задачи

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

Перечисления
TASK_TYPE_UNSPECIFIED Неустановленное значение, которое по умолчанию будет равно одному из других значений перечисления.
RETRIEVAL_QUERY Указывает, что данный текст является запросом в настройках поиска/извлечения.
RETRIEVAL_DOCUMENT Указывает, что данный текст является документом из искомого корпуса.
SEMANTIC_SIMILARITY Указывает, что данный текст будет использоваться для STS.
CLASSIFICATION Указывает, что данный текст будет классифицирован.
CLUSTERING Указывает, что вложения будут использоваться для кластеризации.
QUESTION_ANSWERING Указывает, что данный текст будет использоваться для ответа на вопрос.
FACT_VERIFICATION Указывает, что данный текст будет использован для проверки фактов.
CODE_RETRIEVAL_QUERY Указывает, что данный текст будет использоваться для извлечения кода.

EmbedContentBatch

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

Поля
string model

Обязательно. Имя Model , используемой для создания дополнения.

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

string name

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

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

string displayName

Обязательно. Имя этого пакета, заданное пользователем.

object ( InputEmbedContentConfig ) inputConfig (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" .

object ( EmbedContentBatchStats ) batchStats ( EmbedContentBatchStats )

Только вывод. Статистика по партии.

перечисление state enum ( BatchState )

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

string ( int64 format) priority (формат int64)

Необязательно. Приоритет пакета. Пакеты с более высоким приоритетом будут обработаны раньше пакетов с более низким приоритетом. Допускаются отрицательные значения. Значение по умолчанию — 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

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

Поля
Union type source союза
Обязательно. Источник входных данных. source может быть только одним из следующих:
string fileName

Имя File , содержащего входные запросы.

object ( InlinedEmbedContentRequests ) requests ( 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 может быть только одним из следующих:
object ( Status ) error (статус)

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

объект response object ( EmbedContentResponse )

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

JSON-представление
{
  "metadata": {
    object
  },

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

EmbedContentBatchStats

Статистика по партии.

Поля
string ( int64 format) requestCount (формат int64)

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

string ( int64 format) successfulRequestCount (формат int64)

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

string ( int64 format) failedRequestCount (формат int64)

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

string ( int64 format) pendingRequestCount (формат int64)

Только вывод. Количество запросов, ожидающих обработки.

JSON-представление
{
  "requestCount": string,
  "successfulRequestCount": string,
  "failedRequestCount": string,
  "pendingRequestCount": string
}