POST /v1/embeddings

Получение числовых векторов через явно настроенную модель эмбеддингов.

Эмбеддинги преобразуют текст в числовые векторы для семантического поиска, поиска контекста перед генерацией ответа (RAG), кластеризации и сравнения по смыслу. Ваше приложение хранит векторы, находит подходящие материалы и при необходимости передаёт их отдельной модели генерации текста. Этот эндпоинт возвращает векторы, а не разговорный ответ.

Выбор модели

Используйте включённую модель из раздела Эмбеддинги / векторы каталога, доступную вашему API-ключу. У модели должна быть явно указана поддержка эндпоинта embeddings, рабочий маршрут к поставщику и применимый тариф на входные токены. Чат-модель или знакомое название модели сами по себе не означают поддержку эмбеддингов. Алиас разрешается до проверки эндпоинта, передачи запроса и тарификации.

embedding-model ниже — условный заполнитель. Замените его точным ID модели или включённым алиасом из вашего каталога: релиз не добавляет и не активирует модели поставщиков автоматически.

Запрос

curl https://api.model-gate.com/v1/embeddings \
  -H "Authorization: Bearer $MODEL_GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "embedding-model",
    "input": ["First text", "Second text"],
    "encoding_format": "float"
  }'

Поле	Значение
`model`	Обязательный ID модели или включённый алиас с явно указанной поддержкой эмбеддингов.
`input`	Непустая строка, непустой список непустых строк, список неотрицательных целых ID токенов либо непустой список непустых списков ID токенов. Не смешивайте эти формы. ID токенов должны соответствовать токенизатору выбранного поставщика.
`encoding_format`	Необязательное значение `float` или `base64`, если его поддерживает выбранный поставщик. В примере явно запрошены числовые массивы.
`dimensions`	Необязательное положительное целое число; применимо только к моделям с изменяемой размерностью вектора.

Предел токенов, размер пакета и допустимую размерность определяет выбранный поставщик. Model Gate проверяет структуру запроса, не обрезает текст незаметно, не угадывает число токенов и не подменяет модель. stream: true и собственный режим async: true для этого эндпоинта не поддерживаются. Обычный запрос возвращает один JSON-ответ. Для поддерживаемых элементов эмбеддингов отдельно доступен интерфейс Files/Batch.

Ответ

Это сокращённый искусственный пример: числа в векторах и количество токенов приведены только для иллюстрации.

{
  "object": "list",
  "model": "embedding-model",
  "data": [
    {"object": "embedding", "index": 0, "embedding": [0.012, -0.044]},
    {"object": "embedding", "index": 1, "embedding": [0.031, 0.009]}
  ],
  "usage": {"prompt_tokens": 6, "total_tokens": 6}
}

Используйте index, чтобы сопоставить вектор со входом, и сохраняйте полный полученный вектор. Для индексируемых материалов и поисковых запросов используйте одну модель эмбеддингов и одинаковую размерность. При переходе на несовместимую модель или размерность перестройте индекс.

Ошибки

Отказ из-за отсутствия поддержки эндпоинта у модели возвращает HTTP 400 до запроса поставщику. Шлюз использует такую OpenAI-совместимую структуру:

{
  "error": {
    "code": "model_endpoint_not_supported",
    "message": "The selected model is not enabled for this endpoint.",
    "type": "invalid_request_error"
  }
}

Код шлюза	Что исправить
`model_endpoint_not_supported`	Выберите модель с явно настроенной поддержкой этого эндпоинта. Флаг чат-эндпоинта не даёт поддержку эмбеддингов.
`invalid_embeddings_input`	Передайте одну из поддерживаемых непустых форм входа; не смешивайте текст и ID токенов.
`invalid_dimensions`	Укажите положительное целое число. Доступность корректной размерности определяет выбранный поставщик.
`invalid_encoding_format`	Используйте `float` или `base64`.
`embeddings_stream_not_supported`	Уберите `stream: true` и используйте единый JSON-ответ.
`async_not_supported`	Уберите `async: true`; при необходимости используйте отдельный поддерживаемый интерфейс пакетных запросов.
`invalid_async_stream_combination`	Не запрашивайте собственный async-режим вместе со streaming.

Эти ошибки проверки возвращают HTTP 400 с типом invalid_request_error. Исправьте запрос, не повторяя его автоматически. Сохраните X-Request-ID для диагностики. Структура и коды ошибок поставщика не обязаны совпадать с примером; ошибки аутентификации, ограничения аккаунта и безопасное представление ошибок поставщика описаны в общем справочнике ошибок.

Учёт токенов и проверка

Эмбеддинги тарифицируются по фактическим входным токенам из ответа поставщика. Координаты вектора не являются выходными токенами или токенами ответа. Если поставщик передал total_tokens, оно должно совпадать с входными токенами; отсутствие общего счётчика не заменяет явно переданное число входных токенов. Отсутствующие или противоречивые данные не вычисляются по длине текста или размерности вектора и не считаются бесплатным успешным использованием. Сохраняются тариф вашего аккаунта и действующие ограничения API-ключа, группы и доступа.

Для администратора: сохраните модель с пунктом Эмбеддинги / векторы (Embeddings / vectors) в настроенных эндпоинтах, добавьте нужный маршрут и цену входных токенов, затем явно запустите OpenAI Embeddings → Эмбеддинги / векторы в проверке возможностей. Для отдельной модели эмбеддингов оставьте текстовые эндпоинты неотмеченными. Сохранение модели не запускает проверку. Ручная проверка делает один платный запрос с двумя короткими входами, проверяет конечные числовые векторы и полный набор индексов, а отдельно — фактические входные токены поставщика. Статус Verified подтверждает этот контракт ответа, а не качество семантики или личность поставщика; выключенная модель автоматически не включается.

Ручная проверка принимает JSON-ответы до 256 КиБ и отклоняет повторяющиеся ключи JSON. Более крупный ответ считается неубедительным для этой ограниченной проверки; это не ограничение размерности векторов публичного API. Автоматический повторный запрос не выполняется.