Инструменты — обзорготовится

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

Порядок такой. Первое: вы добавляете в тело POST /v1/chat/completions поле tools — массив описаний инструментов. Второе: модель либо отвечает текстом, либо возвращает намерение вызвать инструмент. Третье: вызов исполняется, результат добавляется в разговор отдельным сообщением. Четвёртое: модель продолжает ответ уже с учётом результата.

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

Управлять поведением планируется полем tool_choice: "auto" (по умолчанию, модель решает сама), "none" (инструменты не вызывать), "required" (обязательно вызвать хотя бы один).

# ПЛАНИРУЕМЫЙ контракт. Сейчас этот запрос выполнится как обычный чат:
# поле tools будет проигнорировано.

curl https://api.librachat.kz/v1/chat/completions \
  -H "Authorization: Bearer sk-libra-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "libra-pro",
    "messages": [
      {"role": "user", "content": "Что нового в правилах маркировки рекламы?"}
    ],
    "tools": [
      {"type": "web_search"}
    ],
    "tool_choice": "auto"
  }'

// ПЛАНИРУЕМЫЙ вид ответа для встроенного инструмента.
// Блок tool_usage — наше расширение поверх формата OpenAI,
// имя поля подлежит уточнению.
{
  "id": "chatcmpl-...",
  "model": "libra-pro",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Коротко: ..."},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1840,
    "completion_tokens": 610,
    "total_tokens": 2450
  },
  "tool_usage": [
    {"type": "web_search", "calls": 3}
  ]
}

За разговор с инструментами вы платите дважды, и это надо закладывать в расчёты.

• Токены. Описания инструментов уходят в запрос как часть контекста, а результаты вызовов — как дополнительные сообщения. И то и другое считается по обычным ставкам модели: libra-fast — 337,50 ₽ за 1 млн входных, 54 ₽ за 1 млн из кеша, 675 ₽ за 1 млн выходных; libra-pro — 450 ₽, 72 ₽ и 900 ₽ соответственно.
• Плата за вызов. Каждый исполненный встроенный инструмент считается поштучно, по ставке из таблицы ниже. Один ответ модели может содержать несколько вызовов — платите за каждый.
• Результаты вызовов раздувают контекст. Веб-поиск и чтение файлов приносят в разговор много текста, и на следующем шаге он снова уходит на вход. На длинных диалогах токенная часть счёта обычно перевешивает поштучную.
• Ваши собственные функции бесплатны по вызовам. Вы платите только за токены описания функции и её результата.
• Режимы работы влияют и на вызовы: пакетная обработка — минус 20% к ставкам, приоритетная — ×2 к ставкам.

Важно: сегодня баланс списывается только по полю usage из ответа модели, то есть по токенам. Отдельного поштучного списания за вызов инструмента в сервисе пока нет.

Ставки за 1000 вызовов. Округление до целого вызова, частичные вызовы не тарифицируются.

Цены за вызовы встроенных инструментов

К этим суммам добавляются токены разговора по ставкам модели. Хранение данных для инструментов оплачивается отдельно: файлы — 6,75 ₽ за ГиБ в сутки, коллекции — 27 ₽ за ГиБ в сутки, скачивание — 54 ₽ за ГиБ.

Ниже — четыре инструмента, для которых уже утверждены цены. Технические имена в поле type пока не закреплены: варианты в таблице приведены как рабочие и подлежат уточнению перед релизом. Не зашивайте их в код без сверки с финальной версией документации.

Планируемый набор встроенных инструментов

Ещё не решено и намеренно не описано: возвращать ли ссылки на источники отдельным полем, ограничивать ли число вызовов на один запрос параметром вроде max_tool_calls, как показывать вызовы в потоковом режиме. Эти пункты появятся в документации после реализации.