Tools и function calling в OpenAI-совместимом API: что проверить

Короткий ответ: модель предлагает, сервер решает

Tools и function calling полезны, когда приложению нужен структурированный запрос к собственной функции: поиск заказа, чтение разрешённого статуса или создание черновика. Но аргументы, предложенные моделью, остаются недоверенным вводом. Ваш backend обязан определить allowlist операций, проверить роль пользователя, схему параметров и бизнес-ограничения до реального вызова.

Совместимый API не означает, что каждый endpoint или model ID поддерживает tools одинаково. Не переносите предположение из SDK, чужого аккаунта или документации другого поставщика. Отметьте в матрице дату теста, маршрут, модель, ожидаемое поле и фактический результат; неподтверждённый вариант не включайте в production.

Минимальная матрица совместимости

Для каждого сценария зафиксируйте: принимается ли объявление tool, возвращается ли структурированный вызов, какой stop reason приходит, допускается ли несколько вызовов и как выглядит ошибка при неверной схеме. Добавьте негативные проверки: неизвестный tool, строка вместо числа, лишнее поле и действие пользователя без права. Это важнее красивого демо, потому что именно границы предотвращают случайное выполнение.

Тестируйте на обезличенном наборе и ограниченном project scope. Сохраняйте только версию теста, request ID вашего приложения, код статуса, длительность и итог pass/fail. Raw prompt, полный ответ, ключ и заголовки не нужны для такой диагностики. После обновления SDK, модели или base URL повторяйте набор, а не полагайтесь на старый результат.

Схема — это договор вашего приложения

Опишите JSON Schema настолько узко, насколько позволяет задача: перечисления вместо свободной строки, максимальную длину, обязательные поля и запрет дополнительных свойств. Схема уменьшает двусмысленность, но не заменяет авторизацию. Например, допустимое поле orderId ещё не даёт пользователю право читать любой заказ; сервер сравнивает его с tenant и текущим actor.

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

Наблюдаемость и контролируемый rollout

Полезная метрика включает число предложений tool, долю отклонённых аргументов, ошибки схемы, длительность и результат выполнения. Она показывает состояние вашего контура, а не обещает SLA модели или gateway. Отделите технический event от пользовательского содержания: event может содержать тип tool и внутренний correlation ID, но не секреты и не полный payload.

Начните с внутреннего обезличенного сценария или feature flag для небольшой группы. Стоп-условиями могут быть неожиданный tool name, рост ошибок валидации, превышение бюджета или нарушение политики данных. При срабатывании отключите flag, вернитесь к последнему подтверждённому пути и разберите контракт. Бесконечный retry не исправляет неверную схему.

Чек-лист перед выпуском

1. Подтвердите model ID и tools на текущем каталоге и тестовом account.
2. Задайте allowlist tool names и строгую server-side схему.
3. Проверьте права пользователя и tenant для каждого аргумента.
4. Добавьте timeout, idempotency для побочных эффектов и audit event без payload.
5. Подготовьте feature flag, лимит расходов и условия rollback.

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

Server-side пример

Пример показывает контрактную проверку на сервере. Ключи берутся только из окружения; до запуска подтвердите маршрут и model ID в текущем каталоге RussiaAPI.

const allowedTools = new Set(['get_order_status']);

export async function executeToolCall({ actor, call }) {
  if (!allowedTools.has(call?.name)) return { ok: false, reason: 'tool_not_allowed' };
  const orderId = call?.arguments?.orderId;
  if (!/^[a-z0-9_-]{1,64}$/i.test(orderId)) return { ok: false, reason: 'invalid_order_id' };
  if (!actor?.tenantId) return { ok: false, reason: 'unauthorized' };
  const order = await findOrderForTenant(orderId, actor.tenantId);
  return order ? { ok: true, status: order.status } : { ok: false, reason: 'not_found' };
}

async function findOrderForTenant(orderId, tenantId) {
  return { id: orderId, tenantId, status: 'pending' }; // Replace with scoped DB query.
}

Проверьте синтаксис через node --check, добавьте аутентификацию вашего маршрута, rate limit и негативные тесты. Не логируйте тело запроса или заголовки только ради отладки.

Границы, данные и безопасный запуск

Это инженерное руководство, а не юридическое заключение и не инструкция по обходу законов, санкций, региональных, платёжных или платформенных ограничений. Не передавайте в тесты реальные персональные данные, коммерческие секреты, upstream-ключи, cookie, пароли или полный заголовок Authorization. Для персональных данных отдельно подтвердите цель, минимизацию, срок хранения, удаление и договорные условия с ответственными специалистами.

Ключ RussiaAPI хранится только в server-side secret store. Разделяйте development, staging и production, ограничивайте доступ, ротируйте ключ при смене сотрудника или подозрении на утечку и ведите журнал без секретов. Неизвестную функцию, модель или поле ответа считайте неподтверждёнными, пока не проверите их на текущем разрешённом тестовом контуре.