Tool calling в LLM: от запроса функции до проверенного результата

На примере заказа разбираем tool calling в LLM. Модель выбирает функцию, приложение проверяет аргументы и права, исполняет вызов и возвращает результат. Код на Python.

11 мин чтенияai · tool calling · llm · python

Коротко

Tool calling, или function calling, — это способ, которым языковая модель запрашивает вызов функции по имени и передаёт её аргументы. Вы выполняете функцию в приложении, возвращаете модели результат и получаете ответ на основе реальных данных. Например, модель просит прочитать заказ № 42, а приложение проверяет, принадлежит ли он пользователю.

  • Описывайте функции через понятные имена, схемы аргументов и короткие результаты.
  • Берите личность пользователя из авторизации. Проверяйте доступ к каждой записи, даже когда аргументы прошли проверку формы.
  • Сохраняйте ID вызова, чтобы результаты двух одноимённых функций не перемешались.
  • Для записи предусмотрите подтверждение параметров и безопасное повторение операции после таймаута.

Что должно произойти с заказами 42 и 43

Пользователь пишет «Посмотри, готовы ли к выдаче заказы 42 и 43». Заказ 42 принадлежит ему и ждёт в пункте выдачи. Заказ 43 принадлежит другому пользователю. Даже предельно полезная модель не получает доступ ко второму заказу по самому факту, что человек знает его номер. Приложение отвечает «Заказ 42 готов к выдаче. Заказ 43 недоступен». Фраза про недоступность подходит и для несуществующего номера. Так интерфейс не подтверждает, что чужой заказ существует.

В руководстве OpenAI о function calling описан обмен между моделью и приложением. Приложение передаёт список инструментов, модель возвращает запрос вызова, код исполняет инструмент и передаёт результат обратно. Точные поля зависят от провайдера. В примере ниже внутренний адаптер уже привёл внешний формат к небольшому объекту, который одинаков для всех инструментов приложения.

ШагКто → комуЧто передаёт
1. ВводПользователь → приложениеВопрос про заказы 42 и 43
2. ОписаниеПриложение → модельВопрос и схема функции чтения статуса
3. Запрос действияМодель → приложениеДва вызова с ID c1 и c2 и разными номерами
4. ИсполнениеПриложение → сервис заказовПроверенный номер и личность вошедшего пользователя
5. РезультатПриложение → модельc1 с состоянием заказа, c2 с кодом недоступности
6. ОтветМодель → пользователь через приложениеКороткая формулировка с результатом по каждому номеру

Если приложение запускает чтения независимо, заказ 43 может ответить раньше заказа 42. Привязывайте результаты по ID вызовов. Совпадение имени бесполезно, потому что оно у обоих одинаковое. Если UI обновляет строки по мере готовности, храните также связь каждого ID с номером заказа внутри приложения. В ответ инструмента достаточно вернуть состояние и безопасную ошибку. Полная карточка с адресом и телефоном для этого вопроса лишняя.

Как описать функцию

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

Опишите выход. Например, ready_for_pickup переводится в «готов к выдаче». order_unavailable означает, что приложение не покажет состояние по этому номеру. Приложение должно знать разницу между такой ошибкой и timeout. В первом случае обычный повтор запроса ничего не изменит. Во втором сервис мог временно опаздывать, и чтение можно повторить в рамках исходного дедлайна.

Схема должна отдельно описывать форму и допустимый результат. JSON Schema даёт типы и обязательные поля. Строгий режим провайдера полезен, когда поддерживает нужные ограничения, но не выдаёт права на запись и не проверяет остатки. Если для заказа 42 передали корректный JSON от другого пользователя, функцией должен распоряжаться сервис заказов, который проверяет права. Ошибка должна быть видна в журнале приложения в безопасной форме, без чужого содержимого.

Проверка и исполнение на Python

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

import json ORDERS = { 42: {"owner": "u1", "status": "ready_for_pickup"}, 43: {"owner": "u2", "status": "ready_for_pickup"}, } def dispatch(call, viewer): call_id = call["id"] if call["name"] != "get_order_status": return {"id": call_id, "error": "unknown_tool"} try: arguments = json.loads(call["arguments"]) except (TypeError, json.JSONDecodeError): return {"id": call_id, "error": "invalid_arguments"} if not isinstance(arguments, dict) or set(arguments) != {"order_id"}: return {"id": call_id, "error": "invalid_arguments"} number = arguments["order_id"] if type(number) is not int or number < 1: return {"id": call_id, "error": "invalid_order_id"} order = ORDERS.get(number) if order is None or order["owner"] != viewer: return {"id": call_id, "error": "order_unavailable"} return {"id": call_id, "status": order["status"]} calls = [ {"id": "c1", "name": "get_order_status", "arguments": '{"order_id": 42}'}, {"id": "c2", "name": "get_order_status", "arguments": '{"order_id": 43}'}, {"id": "c3", "name": "get_order_status", "arguments": '{"order_id": true}'}, ] results = {call["id"]: dispatch(call, "u1") for call in reversed(calls)} for call in calls: result = results[call["id"]] print(result["id"], result.get("status", result.get("error"))) assert results["c2"]["error"] == dispatch( dict(calls[1], arguments='{"order_id": 999}'), "u1" )["error"] assert dispatch(dict(calls[0], arguments="{"), "u1")["error"] == "invalid_arguments"

Вывод программы.

c1 ready_for_pickup c2 order_unavailable c3 invalid_order_id

Третий вызов добавлен для проверки. В Python логическое значение является подклассом целого числа, поэтому isinstance(True, int) вернул бы истину. Проверка точного типа отсекает этот случай. У HTTP-адаптера проверьте также размер аргументов и обязательные поля конверта. Кусок кода предполагает, что конверт уже прошёл проверку адаптера. На сетевом краю не принимайте бесконечные входы только потому, что ожидаете простой объект с одним полем.

Для ответа модели сформируйте компактную структуру результатов. Например, возвращайте только status и error, а привязку к номеру восстанавливайте из журнала конкретного вызова. Текстовые поля из внешних систем рассматривайте как данные. Если комментарий к заказу содержит просьбу вызвать другой инструмент, она не даёт права на новый вызов. Список доступных инструментов, пользовательские права и допустимые параметры по-прежнему определяет приложение.

Что делать с таймаутом и записью

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

Рассмотрим продолжение того же сценария. Покупатель просит продлить хранение заказа 42 на два дня. Теперь вызов меняет состояние. Покажите человеку точный номер и новую дату, сохраните его подтверждение на этот набор параметров. При изменении даты подтвердите новый вариант. Если инструмент принял операцию, но ответ потерялся, приложение должно узнать результат по ключу операции. Отправка второго запроса с новым ключом создаст риск повторного продления.

ID запроса модели связывает ответ с конкретным вызовом. Ключ идемпотентности связывает повторные запросы с одним бизнес-действием. После повторной генерации идентификатор модели может поменяться, а подтверждённое действие остаётся прежним. В хранилище операции запишите ключ, согласованные параметры и итог. Запрос с тем же ключом и другими параметрами отклоните. На отказе инструмента показывайте состояние, которое действительно известно. Если ответ потерян и исход ещё уточняется, сообщите об этом вместо заявления «срок продлён».

При параллельных чтениях ограничьте одновременно выполняемые вызовы. Один вопрос о ста заказах не должен создавать сто соединений. Для большого списка предусмотрите отдельный пакетный инструмент, если бизнес его допускает, и пусть он проверяет права по всем номерам. Ставьте ограничение на размер списка в приложении и сервисе. Связь результатов с c1 и c2 сохраняется так же, как в демонстрации.

Как тестировать весь обмен

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

После этого тестируйте выбор инструмента моделью. Дайте вопросы «готов ли заказ 42», «какие правила выдачи» и «можно ли заказать два товара». Для первого нужен статус, для второго подойдёт текстовый справочник, для третьего важно узнать, что человек хочет сделать, прежде чем выбирать действие. Для вопросов о правилах можно использовать RAG. Если при запросах политики модель всё равно зовёт функцию статуса, исправьте описания, доступность инструментов или маршрутизацию до вызова.

Измерьте успешные выборы, валидные параметры и совпадение финального ответа с состоянием. Если функция вернула ready_for_pickup, а текст говорит «уже выдан», проверка аргументов здесь пройдёт. Сравните в журнале ответ инструмента и финальный текст. Журнал хранит IDs, имя инструмента, код результата и задержку. Для состояния заказа достаточно безопасного кода. Подробности для диагностики храните согласно правилам доступа и срока хранения.

Что показать до получения обоих результатов

Отдельно проверьте потоковый интерфейс. Вы можете сразу показать «Проверяем два заказа», а по готовности c1 отобразить статус 42. Строка заказа 43 должна остаться в ожидании, пока не придёт c2 или не истечёт его дедлайн. Если компонент ждёт весь ответ модели, пользователь не видит уже полученное состояние. Если компонент печатает вывод модели до выполнения инструмента, он рискует показать правдоподобный ответ без подтверждения. Подписывайте незавершённые действия в интерфейсе и обновляйте их по событиям приложения.

Потоковый ответ провайдера с аргументами функции тоже бывает разбит на части. Соберите весь вызов по его идентификатору и дождитесь сигнала, что аргументы закончились, прежде чем их разбирать и выполнять. Тест «аргумент пришёл тремя кусками» обнаружит диспетчер, который пытается разобрать JSON на первом куске или исполняет один вызов дважды. Отмену из интерфейса обрабатывайте отдельно. Чтение можно прервать, а у записи, которую уже принял сервис, всё равно нужно выяснить итог.

Как выпустить изменение контракта

Пусть у заказа появилось состояние pickup_delayed. Обновите перевод результата и тест, прежде чем давать модели новую схему. Если старый клиент получит неизвестное состояние, он должен показать статус как недоступный для интерпретации и записать код для диагностики. Молчаливый переход к «готов к выдаче» отправит человека в пункт выдачи зря. Для изменений аргументов проверьте активные запросы, начатые до выпуска. Приложение должно принимать результат по той схеме, которую само передало в начале обмена, или завершать старый запрос явной ошибкой. В тесте отправьте c1 до переключения, верните его после и убедитесь, что старый код состояния сохранил своё значение.

Типичные ошибки

  1. Доверяете полям модели о пользователе. Чужой заказ получает статус. Прогоните одинаковый номер от двух учётных записей и сравните результаты.
  2. Смешиваете ответы одноимённых вызовов. В интерфейсе статус заказа 42 оказался у 43. Принудительно задержите первый ответ и проверьте корреляцию по ID.
  3. Считаете корректный JSON правильной командой. Вызов с отрицательным номером или изменённой датой доходит до сервиса. Проверьте допустимые значения и точные параметры подтверждения.
  4. Повторяете запись с новым ключом. После сетевого обрыва заказ продлевается дважды. Имитируйте обрыв после записи и проверьте состояние во внешней системе.
  5. Результат инструмента теряется при генерации. Заказ готов к выдаче, а ответ объявляет его выданным. Сравните финальный текст с сохранённым выходом функции для того же запроса.

Когда достаточно прямого вызова

Если человек открыл карточку заказа 42 и нажал «показать статус», интерфейс уже знает функцию и аргумент. Вызовите API напрямую и отобразите состояние. Tool calling добавляет пользу, когда человек формулирует вопрос свободно, а приложению нужно выбрать одно из нескольких действий или выполнить два чтения на основе текста. Когда следующий шаг зависит от возвращённых данных, переходы можно оформить в цикле агента с отдельными пределами и проверкой завершения.

Что спрашивают на собеседовании

  1. Кто фактически исполняет функцию? Модель запрашивает имя и аргументы, а код приложения проверяет их и вызывает сервис. Для заказа 42 право чтения берётся из учётной записи, которая уже вошла в приложение.
  2. Зачем идентификатор вызова? Он связывает результат с запросом, даже когда вызовы одного имени выполняются параллельно. Я проверю случай, где c2 приходит раньше c1.
  3. Что проверяет схема? Она задаёт поля и их типы, например целочисленный номер заказа. Положительное значение, доступ и допустимость операции я проверю в коде и сервисе.
  4. Как повторить операцию после таймаута? Для записи я сохраню ключ идемпотентности и попробую получить итог под тем же ключом. Новый ключ для уже подтверждённого продления создаст вторую операцию.
  5. Где полезнее прямой API? Когда действие и номер известны из интерфейса, как при открытии карточки 42. Модель добавлю для свободного вопроса, в котором ещё нужно определить действие.

Потренироваться в спокойной обстановке

Все задачи