SimpleClaw

Руководства

Работа с эмбеддингами

Как получить числовые векторы текста через Provider API и учитывать расход ₽.

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

Эмбеддинг — числовой вектор текста. Его можно использовать в своём приложении для смыслового поиска или сравнения; сопоставляйте векторы, полученные одной моделью. Маршрут возвращает векторы, а не текстовый ответ модели.

  1. Создайте API-ключ SimpleClaw и храните его в переменной окружения SIMPLECLAW_API_KEY, а не в коде или браузере.
  2. Убедитесь, что у аккаунта есть активный Provider-доступ или предоплаченный баланс ₽.
  3. Выберите включённую модель с ID embed/... и протоколом embeddings в каталоге. У неё должна быть действующая ставка. ID в примере ниже замените на доступный вам.

Отправьте текст

POST /v1/embeddings принимает model и input: одну непустую строку или массив из 1–16 непустых строк. В примере массив даёт по одному вектору на каждый текст.

curl -X POST https://simple-claw.ru/v1/embeddings \
  -H "Authorization: Bearer $SIMPLECLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "embed/bge-m3",
    "input": ["Первый текст", "Второй текст"],
    "encoding_format": "float"
  }'

Поле encoding_format необязательно; допустимо только значение float. Токены и бинарные данные на входе, параметр dimensions и другие поля не поддерживаются. Сериализованный текстовый input ограничен 100 КБ.

Получите векторы и usage

Ответ содержит object: "list", публичный ID модели и элементы data. Их index соответствует порядку текстов во входном массиве. Ниже укороченный пример: размерность реального вектора зависит от модели.

Пример ответа embeddingsПоказать
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.12,
        -0.03
      ]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [
        0.08,
        0.19
      ]
    }
  ],
  "model": "embed/bge-m3",
  "usage": {
    "prompt_tokens": 12,
    "total_tokens": 12
  }
}

SimpleClaw резервирует ₽ до обращения к поставщику и фиксирует расход по подтверждённым входным токенам и действующей ставке модели. Выходные токены для этого маршрута не тарифицируются; недельный бюджет ключа, квота тарифа и баланс продолжают действовать. Если ответ или usage поставщика не подтверждены, резерв возвращается.

По умолчанию после подтверждённого ответа тексты сохраняются в личной истории запросов. В настройках профиля можно отключить сохранение текста новых запросов и ответов; модель, время, токены и ₽ останутся в истории для учёта. Уже сохранённые тексты не удаляются. Настройка относится к SimpleClaw и пока не подтверждает запрет хранения у внешнего поставщика. Не отправляйте в input пароли и другие секреты.

Ограничения и ошибки

Embedding-модель нельзя использовать через /v1/chat/completions, /v1/responses или /v1/messages. Включённая модель в каталоге сама по себе не подтверждает доступность upstream в момент запроса.

400 VALIDATION_ERROR означает неверный input или лишнее поле; 401 INVALID_API_KEY — недействительный ключ; 403 PROVIDER_SUBSCRIPTION_REQUIRED или MODEL_NOT_IN_PLAN — недостаточный доступ; 404 MODEL_UNAVAILABLE — модель недоступна; 429 — исчерпана квота, баланс или бюджет ключа. 400 UPSTREAM_INVALID_REQUEST означает явный отказ поставщика до получения ответа: резерв освобождён; исправьте параметры или историю, повтор неизменного запроса не поможет. При 503 UPSTREAM_UNAVAILABLE или UPSTREAM_USAGE_UNCERTAIN проверьте состояние сервиса; автоматического повтора платного запроса нет.

Полный контракт и коды ошибок см. в справочнике Provider API и разделе ошибок.

Работа с эмбеддингами — документация SimpleClaw