Векторные представления
Embeddings API для семантического поиска, индексации документов и сравнения текстов
POST /v1/embeddings преобразует текст в числовой вектор. Такой вектор можно сохранить в поисковом индексе и сопоставлять с вектором запроса пользователя. Embedding-модель не генерирует ответ на вопрос; для RAG сначала найдите подходящие фрагменты, а затем передайте их текстовой модели.
Выбор модели и совместимость индекса
Проверьте доступность точного ID модели для вашего API-ключа через GET /v1/models, а назначение, ограничения и единицу цены — в каталоге. В примере используется text-embedding-3-small; доступность зависит от текущего каталога, ключа и тарифа.
Документы и поисковые запросы кодируйте одной моделью с одинаковыми настройками размерности. Векторы разных моделей нельзя считать совместимыми только потому, что их длина совпадает. При смене модели создайте новый индекс и заново закодируйте документы, затем сравните качество поиска до переключения.
Минимальный запрос
export NEUROAPI_KEY='YOUR_API_KEY'
curl --fail-with-body https://neuroapi.host/v1/embeddings \
-H "Authorization: Bearer $NEUROAPI_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "text-embedding-3-small",
"input": "Как подключить API для поиска по документам?",
"encoding_format": "float"
}'Для нескольких независимых текстов передайте массив строк в input:
{
"model": "text-embedding-3-small",
"input": [
"Подключение API и авторизация",
"Индексация документов для семантического поиска"
],
"encoding_format": "float"
}| Поле | Значение | Требование |
|---|---|---|
model | Точный ID embedding-модели | Обязательное |
input | Непустая строка или массив непустых строк | Обязательное; минимальный текстовый контракт |
encoding_format | float для массива чисел в ответе | Явно задано в примерах |
Начните с текстового input и формата float. Дополнительные форматы кодирования, параметр dimensions, токенизированный или мультимодальный вход проверяйте для конкретной модели; их поддержку нельзя выводить из наличия общего endpoint.
Разбор ответа
Для формата float обрабатывайте следующие поля:
| Поле | Что означает |
|---|---|
data | Массив результатов |
data[].index | Индекс соответствующего элемента входного массива |
data[].embedding | Полный массив числовых координат вектора |
model | Идентификатор модели в ответе |
usage.prompt_tokens, usage.total_tokens | Отчёт об использовании токенов, когда они присутствуют в ответе |
Сопоставляйте результаты с исходными текстами по index. Перед записью в индекс проверяйте наличие вектора, числовые значения и ожидаемую размерность. Для нескольких текстов не предполагайте, что один вектор описывает весь массив.
Храните ID модели, настройки и размерность рядом с индексом. Метрику расстояния и правила нормализации выбирайте по контракту вашей модели и векторного хранилища; одна метрика не подходит автоматически всем моделям.
Ограничения, стоимость и разбиение документов
Не отправляйте пустые строки и пустые массивы. Ограничения длины одного текста, числа элементов в запросе и размерности зависят от модели; универсальные числовые значения для всех моделей здесь не установлены. Сверяйте опубликованные ограничения для выбранного тарифа и уточняйте неподтверждённые до массовой индексации.
Делите длинные документы на осмысленные фрагменты, сохраняя ID документа и положение фрагмента. Длина одного элемента и суммарный объём всего запроса — разные ограничения. Размер групп подбирайте постепенно: большой массив не отменяет лимит отдельного текста.
Сверяйте цену и единицу тарификации в каталоге цен. Предварительный подсчёт токенов служит оценкой; окончательный расход смотрите в истории запросов. Изменение документа требует обновления его векторов, а смена embedding-модели — повторной индексации совместимого набора.
Проверка полезности поиска
Подготовьте реальные вопросы и ожидаемые релевантные документы. Сравнивайте долю попаданий нужного документа в первые результаты, ошибки по русским терминам, стоимость индексации, время запроса и объём хранилища. Сохраняйте одинаковые документы, разбиение и настройки поиска при сравнении моделей: размерность сама по себе не доказывает качество.
При ошибке проверьте ключ, ID модели, форму input и доступные лимиты, затем обработайте код ошибки. После таймаута сначала проверьте историю и расход в кабинете; не повторяйте автоматически всю группу текстов, поскольку исходный запрос мог уже быть обработан и оплачен.