Інтеграція OpenAI Function Calling: схеми, паралельні виклики, Pydantic

OpenAI function calling: чому виклики зриваються в робочому середовищі

OpenAI function calling перетворює модель з генератора тексту на виконавця: замість відповіді словами вона повертає структурований виклик інструмента, який виконує ваш код.

На демонстрації це виглядає надійно, а в робочому середовищі інтеграція AI-асистента ламається в кількох передбачуваних місцях.

Перше джерело збоїв — невалідні аргументи моделі. Одне й те саме поле надходить то рядком, то числом, дати — у вільному форматі, вкладені об’єкти втрачають частину ключів, а іноді модель впевнено підставляє значення, якого у вашому довіднику немає.

Без суворої перевірки на вході такий виклик потрапляє в бізнес-логіку й падає вже там, залишаючи дані в напівзібраному стані.

Друге — розбіжність описів і реального контракту. Описи інструментів у викликах інструментів LLM живуть окремо від коду: параметр перейменували в сервісі, а інструкція залишилася попередньою, і модель продовжує збирати старий набір полів.

З необов’язковими параметрами те саме — якщо не позначити поле обов’язковим, модель просто не надішле його.

Третє — відсутність повторних спроб і розбір паралельних викликів. Відповідь надходить з обмеженням за частотою звернень або перевищенням часу очікування, виклик мовчки губиться, і користувач бачить, що асистент «забув» виконати дію.

Коли модель повертає кілька викликів одразу, частина з них залежить від результату попереднього — і без явного порядку та захисту від повторів повтор перетворюється на дублікат заявки або платежу.

Ми розбираємо кожен сценарій на рівні схеми аргументів, тексту інструкції та логіки повторів, щоб збій залишався рядком у лозі, а не інцидентом у клієнта.

Що дає керована інтеграція function calling

Коли модель сама обирає інструмент, якість сценарію тримається не на формулюваннях промпту, а на строгості опису виклику. Керована інтеграція викликів — це контракт: які функції доступні, які аргументи обов’язкові, що робити при невідповідності типів. Чим точніше він заданий, тим менше рішень модель ухвалює навмання.

Схеми описуємо декларативно й валідуємо кожен аргумент до виконання — на цьому кроці працює шар, що описує типи, на кшталт Pydantic.

Помилка типу або пропущене поле відсікаються на вході, а не всередині бізнес-логіки, тому збій одного інструмента не розгортається в ланцюжок неправильних дій.

Частку успішних викликів рахуємо за кожним інструментом окремо: скільки викликів дійшло до результату, скільки пішло на повтор, скільки модель відкинула сама. Так видно, де схема описана неоднозначно — наприклад, два інструменти конкурують за один і той самий запит.

Незалежні виклики йдуть паралельно, тому час відповіді асистента визначається найповільнішим із них, а не сумою всіх. Обмеження на глибину ланцюжка та кількість повторів не дає сценарію піти в цикл, коли зовнішній сервіс відповідає повільно.

Шар повторних спроб з ідемпотентністю закриває мережеві збої, жорсткий формат відповіді — помилки розбору. Це і є зниження класу відмов: сценарій не падає цілком, а деградує передбачувано, зберігаючи зрозумілу відповідь користувачеві.

Звернення до підтримки скорочуються не через ввічливі формулювання, а тому що користувач частіше доводить дію до кінця. Стабільність ai-сценарію підтверджується логами викликів і метриками, а не відчуттям «стало краще» — на них же будуємо регресійні прогони перед змінами.

Схеми виклику інструментів: які підходи вибрати

Схема виклику інструментів — це контракт між моделлю та сервісом: які функції доступні, які аргументи вони приймають і що повертають.

Від того, наскільки точно описано контракт і хто в який момент тримає керування, залежить кількість ітерацій діалогу та місце, де вклинюється валідація.

Режими роботи асистента різняться саме цим — кому належить керування в момент виклику. Ми підбираємо режим під задачу, а не беремо один за замовчуванням для всього проєкту.

Обмеження інтеграції частіше лежать не в моделі, а в контракті. Аргументи надходять структурованими, але без перевірки за описаною моделлю можливі зайві поля та неправильні типи — валідація схеми відсікає такі виклики до виконання й повертає моделі зрозумілу помилку.

Для паралельних гілок ми фіксуємо граничний час очікування інструмента та поведінку при частковому успіху: повтор, компенсацію або явну відмову.

Як ми впроваджуємо інтеграцію: етапи інженерної роботи

Function calling перетворює асистента з генератора тексту на виконавця: модель повертає не абзац, а структурований виклик інструмента з аргументами.

Тому етапи впровадження інтеграції будуються навколо контрактів — при розмитій схемі асистент викликає не той інструмент або підставляє неправильний параметр.

1. Аудит сценаріїв асистента. Розбираємо записані діалоги та регламенти, виписуємо дії, які асистент ініціює сам, і ті, що потребують підтвердження. На виході — карта сценаріїв із частотою та ціною помилки в кожному.
2. Налаштування схем інструментів. Описуємо кожен інструмент строго: обов’язкові поля, допустимі значення, межі чисел, зрозумілі моделі формулювання. Схеми тримаємо в Pydantic-моделях, щоб контракт і код не розходилися.
3. Режими виклику. Розмічаємо, де доречні паралельні виклики (перевірка замовлення й складу одночасно), а де потрібна строга черговість. Окремо фіксуємо інструменти, які асистент не повинен викликати.
4. Перевірка викликів на стенді. Прогоняємо записані та синтетичні діалоги, рахуємо частку коректних викликів, хибні спрацювання та повтори. Навмисно ламаємо схеми: асистент має уточнити, а не вигадати аргумент.
5. Обробка збоїв і спостережуваність. Налаштовуємо валідацію відповіді, повтори для безпечних операцій і миттєву відмову для списань і відправлень. Журналюємо зв’язку «запит — виклик — результат», щоб зростання невалідних схем було видно до скарг.
6. Передача проєкту. Віддаємо схеми, тести, регламент правки описів і порядок випуску змін, навчаємо команду замовника. Подальші правки контрактів проходять через той самий стенд.

Конфігурації, схеми та регламенти: що залишається в проєкті

Після впровадження в проєкті залишається не лише робочий виклик моделі, а й комплект артефактів, за якими ваша команда зможе розвивати рішення без нас.

Збираємо їх в одну передачу й проходимо за списком разом із вашим інженером на прийманні — щоб кожне налаштування було пояснене, а не просто скопійоване.

• Документація з інтеграції — схема проходження запиту від вашого сервісу до моделі й назад, точки запису в журнал, поведінка при недоступності зовнішнього сервісу та при вичерпанні обмежень за частотою звернень.
• Описи інструментів — призначення кожної функції, склад і типи аргументів, обов’язкові та необов’язкові поля, приклади коректних і граничних значень: за цими описами модель обирає, що викликати, тому вони розбираються докладніше за решту.
• Моделі даних — описи структур на Pydantic, які перевіряють аргументи до виклику й розбирають відповіді: некоректний набір полів відсікається на нашому боці, а не йде в сервіс.
• Політика доступу до сервісів — які ключі та області прав потрібні кожному інструменту, де вони зберігаються, як замінюються і що робити при підозрі на витік.
• Регламент оновлення схем — порядок додавання нового інструмента або зміни наявного, правила версіонування описів і спосіб відкотитися на попередню версію, якщо поведінка змінилася.
• Журнал перевірок — набір сценаріїв на паралельні виклики, відмови сервісів, неповні та неправильні аргументи, з результатами прогону до передачі: видно, які шляхи перевірені, а які залишилися поза покриттям.
• Інструкції для команди — як розгорнути середовище, де змінювати обмеження й час очікування відповіді, куди дивитися при розбіжності відповідей між середовищами.
• Передача налаштувань — перелік змінних середовища, прив’язок до сервісів і режимів роботи з поясненням, чому вибрано кожен режим і що зміниться при його зміні.

Комплект залишається у вас у репозиторії та оновлюється разом із кодом — нова функція без опису й запису в регламент просто не пройде перевірку.

Кейс: як скоротили частку збоїв викликів у шість разів

Сервіс підтримки інтернет-магазину: асистент викликав зовнішні функції — перевірку статусу замовлення, перерахунок вартості доставки, створення звернення.

Схеми аргументів описувалися словами в системній інструкції, і модель повертала їх у вільній формі: рядки замість чисел, зайві поля, виклики функцій, яких у сервісі немає.

Частка збоїв викликів трималася на рівні 18% — кожен п’ятий діалог ішов оператору на ручний розбір, а причину не завжди вдавалося відновити за логами.

Що змінили

Аргументи перевели на строгі схеми: контракт кожної функції описано моделлю даних із типами та обов’язковими полями, виклик без перевірки далі не йде.

Паралельні виклики замінили послідовні там, де функції незалежні — статус замовлення й перерахунок доставки запитуються одним кроком, а не двома підряд.

Додали повторні спроби з уточненням: якщо аргумент не пройшов перевірку, моделі повертається текст помилки, і вона виправляє виклик сама. Валідація переїхала в наш сервіс, до звернення до зовнішніх систем, тому неправильний виклик більше не доходить до бази.

Що вийшло

Усі виклики йдуть через механізм function calling OpenAI з жорстко заданими схемами. Частка збоїв викликів упала з 18% до 3% — у шість разів менше. Навантаження на операторів скоротилося з 21% діалогів до 5%, час відповіді знизився з 6 до 2,5 секунд завдяки паралельним викликам.

Впровадження зайняло три тижні: переписування контрактів, новий шар перевірки та прогін на історичних діалогах перед запуском.

Чим строга схема відрізняється від вільного розбору відповіді

Вільний розбір відповіді — це коли застосунок виловлює дані з тексту регулярками та пошуком підрядків, а модель просять «повернути структуру без пояснень».

На демо проходить, у роботі розсипається: додається вступна фраза, поле перейменовується — і розбір мовчки віддає порожнє значення замість помилки.

Строга схема аргументів перетворює домовленість на контракт: поля, типи, обов’язковість, допустимі значення. Платформа OpenAI при виклику функції звіряє з ним аргументи й не пропускає невідповідний варіант.

У код надходить структура, готова до перевірки моделлю даних, — а не текст, який ще потрібно витлумачити.

Різниця видна на чотирьох речах: що потрапляє в код, як сценарій переживає правку формулювання запиту, куди йде помилка формату і чим обходиться підтримка.

Межа проходить за споживачем відповіді. Якщо значення йдуть у виклик функції, у запис у базу або в розгалуження сценарію, потрібна схема: вільний розбір там дає тихі відмови, які шукають за логами. Якщо результат читає людина, розбір терпимий — ціна помилки обмежена одним повідомленням.

Схема відповідає за форму, але не за зміст: переліки значень, діапазони та бізнес-правила перевіряємо на своєму боці.

Відхилений виклик повертається моделі з текстом помилки перевірки — вона править аргументи й повторює виклик, тому сценарій сходиться до коректного результату, а не падає.

Часті технічні сумніви перед інтеграцією

Перед стартом інтеграції випливають одні й ті самі питання: чи витримає схема зростання кількості інструментів, що робити з невалідними аргументами, як реагувати на зміни на боці постачальника моделі. Нижче — короткі відповіді щодо кожного.

Що якщо модель надішле невалідні аргументи?

Аргументи проходять валідацію Pydantic-моделлю до виклику коду, тому пропущене поле або неправильний тип не доходить до бізнес-логіки. Моделі повертаємо текст помилки й просимо виправлений виклик — більшість таких випадків закривається з другої спроби.

Новий інструмент — переписувати інтеграцію?

Інструменти живуть у реєстрі: описуємо функцію та її модель, схему для моделі генеруємо автоматично. Диспетчер, логування, обмеження прав і повторні спроби підключаються до нового інструмента за загальними правилами.

Постачальник змінює поведінку моделі — що тоді?

Між нашим кодом і API стоїть адаптер, тому зміна версії моделі правиться в одному місці. Контрактні тести на записаних відповідях ловлять розбіжності до релізу.

Обговоримо задачу: що потрібно для оцінки інтеграції

Щоб повернутися з оцінкою та планом робіт, а не із загальними питаннями, нам потрібен мінімальний набір вихідних даних за проєктом. Нижче — список того, що визначає обсяг інтеграції Function Calling і порядок запуску.

Якщо частину пунктів ще не вирішено, це нормально: зафіксуємо їх як відкриті питання й запропонуємо варіант за замовчуванням.

• Сценарії: які дії модель має виконувати сама, а які залишаються за людиною — це задає кількість функцій і логіку розгалуження діалогу.
• Схеми виклику: перелік функцій, їхні аргументи та обов’язкові поля, обмеження на значення. Корисно побачити поточний опис — чернетку JSON-схеми або Pydantic-моделі.
• Моделі та режими: які моделі використовуєте, чи потрібні паралельні виклики й потокова віддача відповіді, який відгук вважаєте прийнятним.
• Джерела даних і доступи: які системи викликаються з функцій, які способи підключення дозволені на вашому боці, де зберігаються ключі.
• Контур і безпека: де розміщується рішення, вимоги до логування та зберігання діалогів, хто відповідає за доступи.
• Навантаження та відмовостійкість: очікувана кількість звернень, пікові періоди, частка запитів із викликами функцій, що критично при недоступності зовнішньої системи.
• Що вже є: напрацювання, тести, відомі помилки в розборі аргументів і ретраях — заощадимо етап діагностики.

Опишіть задачу у вільній формі та додайте те, що є. Після розбору вихідних даних повернемося з оцінкою та планом робіт: етапи, склад схем, зони ризику й порядок запуску.