Эмбеддинги

AI Gateway создаёт векторные представления текста через POST /v1/embeddings по единому адресу https://route.smartaipack.ru/v1. Для запроса нужны API-ключ, текст в поле input и точный идентификатор модели, опубликованный для этого пути в разделе Модели.

Не фиксируйте модель по примеру из статьи: состав каталога и доступность маршрутов меняются. Перед интеграцией скопируйте из кабинета актуальный request_model_id и убедитесь, что рядом с выбранной моделью указан /v1/embeddings.

Что такое векторные представления

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

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

Размер вектора и другие свойства результата зависят от выбранной модели. Клиенту не следует заранее задавать ожидаемую длину массива, если это отдельно не подтверждено для актуальной модели.

Основные сценарии

• Смысловой поиск по базе знаний, каталогу или архиву документов.
• Подбор релевантных фрагментов для RAG-сценария перед генерацией ответа.
• Группировка похожих обращений, отзывов или карточек товаров.
• Поиск дубликатов и близких по смыслу записей.
• Рекомендации на основе сходства текстовых описаний.

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

Как выполнить запрос

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

Базовый запрос

В примере ниже provider/model-id-from-catalog — условное значение. Замените его на точный request_model_id, скопированный в каталоге моделей.

curl https://route.smartaipack.ru/v1/embeddings \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider/model-id-from-catalog",
    "input": "Как подключить смысловой поиск по базе знаний?"
  }'

Эквивалентный запрос через Python и OpenAI SDK:

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AI_GATEWAY_API_KEY"],
    base_url="https://route.smartaipack.ru/v1",
)

response = client.embeddings.create(
    model="provider/model-id-from-catalog",  # замените значением из кабинета
    input="Как подключить смысловой поиск по базе знаний?",
)

vector = response.data[0].embedding
print(f"Получен вектор из {len(vector)} значений")

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

Пакетная обработка

Поле input может содержать массив строк. Это удобно для подготовки поискового индекса:

texts = [
    "Инструкция по выпуску API-ключа",
    "Как проверить расход организации",
    "Диагностика ошибки авторизации",
]

response = client.embeddings.create(
    model="provider/model-id-from-catalog",  # замените значением из кабинета
    input=texts,
)

vectors = [item.embedding for item in response.data]

Не зашивайте в код предполагаемый максимальный размер пакета. Разбивайте данные на управляемые порции, сохраняйте связь между порядком входных строк и результатами и обрабатывайте неуспешный пакет отдельно. Допустимый объём зависит от актуальной модели и поставщика.

Справочник API

Общий порядок авторизации и поддерживаемые пути собраны в справочнике API. Отдельные поля ответа и сведения об использовании могут зависеть от модели и поставщика, поэтому интеграция должна спокойно относиться к дополнительным полям.

Доступные модели

Источник истины — раздел Модели. Выберите модель, для которой опубликован путь /v1/embeddings, и скопируйте показанный рядом request_model_id.

Для некоторых однозначных имён, например с префиксом voyage-*, шлюз умеет автоматически определять поставщика. Но в рабочей интеграции безопаснее использовать полный request_model_id с именем поставщика из каталога: так маршрут остаётся явным и не зависит от неоднозначности имени.

Модель voyage-3-large присутствует в конфигурации AI Gateway как пример модели векторных представлений, однако её текущую доступность всё равно нужно проверить в кабинете. Не используйте это название как гарантированный или универсальный вариант.

Актуальные тарифы смотрите только на странице цен. Фактическую стоимость работы приложения и разбивку по моделям проверяйте в Аналитике.

Практический пример: смысловой поиск

Ниже — минимальный учебный пример без внешней векторной базы. Он создаёт векторы для трёх документов, отдельно векторизует запрос и считает косинусное сходство. Для рабочего объёма храните векторы в подходящем индексе и не пересчитывайте весь корпус при каждом поиске.

import math
import os

from openai import OpenAI

MODEL_ID = "provider/model-id-from-catalog"  # замените значением из кабинета

client = OpenAI(
    api_key=os.environ["AI_GATEWAY_API_KEY"],
    base_url="https://route.smartaipack.ru/v1",
)

documents = [
    "API-ключ создаётся в личном кабинете.",
    "Расход по моделям доступен в аналитике.",
    "При ошибке авторизации проверьте Bearer-заголовок.",
]


def cosine_similarity(left: list[float], right: list[float]) -> float:
    numerator = sum(a * b for a, b in zip(left, right))
    left_norm = math.sqrt(sum(a * a for a in left))
    right_norm = math.sqrt(sum(b * b for b in right))
    if left_norm == 0 or right_norm == 0:
        return 0.0
    return numerator / (left_norm * right_norm)


document_response = client.embeddings.create(
    model=MODEL_ID,
    input=documents,
)
document_vectors = [item.embedding for item in document_response.data]

query = "Где посмотреть затраты на модели?"
query_response = client.embeddings.create(model=MODEL_ID, input=query)
query_vector = query_response.data[0].embedding

ranked = sorted(
    zip(documents, document_vectors),
    key=lambda pair: cosine_similarity(query_vector, pair[1]),
    reverse=True,
)

print(ranked[0][0])

Пример не предполагает, что модель возвращает нормализованные векторы: функция явно делит скалярное произведение на нормы. Перед запуском замените условное значение и проверьте выбранный путь в каталоге.

Рекомендации

• Используйте одну и ту же модель для документов и запросов внутри одного индекса.
• Сохраняйте рядом с вектором идентификатор документа, версию модели и дату индексации.
• Разделяйте длинные документы на осмысленные фрагменты и храните ссылку на исходный текст.
• Обновляйте только изменившиеся документы, а при смене модели планируйте полную переиндексацию.
• Подбирайте метрику сходства и порог на собственном наборе проверочных запросов.
• Смотрите отдельные вызовы в Использовании, а агрегированную стоимость — в Аналитике.
• Для рабочего приложения копируйте точный request_model_id из Моделей, даже если краткое имя сейчас разрешается автоматически.

Ошибки

Если запрос не выполнен, проверяйте HTTP-статус до разбора JSON. Частые причины:

• 401: ключ отсутствует, неверен, отозван или истёк;
• 402: на балансе организации недостаточно средств;
• 400: некорректное тело, отсутствует model, модель не опубликована или не поддерживает выбранный путь;
• 403: модель или область доступа не разрешена ключу;
• 429: превышена допустимая частота запросов;
• 502 или 503: временная недоступность маршрута или поставщика.

Не повторяйте без изменений ошибки авторизации, баланса или валидации. Для временных ошибок используйте ограниченное число повторов с увеличивающейся задержкой. Подробная схема диагностики приведена в статье «Ошибки API».

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

Ограничения

• AI Gateway не обещает в этой инструкции фиксированную размерность вектора, нормализацию результата или единый предел пакетной обработки для всех моделей.
• Список моделей не фиксирован: актуальную доступность и совместимость с /v1/embeddings проверяйте в кабинете.
• Неоднозначное краткое имя может не разрешиться в нужного поставщика. Используйте полный request_model_id с именем поставщика, показанный в каталоге.
• Векторы разных моделей и версий нельзя автоматически считать совместимыми.
• Качество поиска зависит от разбиения документов, тестового набора, метрики и логики фильтрации, а не только от выбранной модели.
• Стоимость не следует вычислять по предположениям из API-ответа: тарифы опубликованы на странице цен, фактические списания — в Аналитике.