Інтеграція YandexGPT API: автентифікація, моделі, RAG під 152-ФЗ

Чому інтеграція YandexGPT ламається на старті проєкту

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

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

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

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

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

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

Що дає інтеграція YandexGPT: швидкість відповіді та частка відмов

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

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

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

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

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

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

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

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

Варіанти підключення моделі: хмара, закритий контур, гібрид

Схему розміщення вибирають не за якістю відповідей, а за двома питаннями: де лежать персональні дані й як запит доходить до моделі. Хмарний варіант — виклик керованої моделі, наприклад YandexGPT, захищеним каналом. Від вибраної схеми залежать вимоги 152-ФЗ, час відгуку та обсяг робіт з експлуатації.

Маршрутизація запитів

Маршрут будуємо на вхідному шарі: класифікатор розмічає запит, і в зовнішній канал виходить лише знеособлена частина. Відновлення вихідних значень відбувається всередині застосунку — зв’язка «токен — значення» за периметр не передається.

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

Етапи впровадження: від аудиту даних до передачі контуру

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

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

1. Аудит даних і сценаріїв. Розбираємо джерела: регламенти, базу знань, історію звернень. Позначаємо, де лежать персональні дані й що потрібно знеособити до надсилання в модель.
2. Схема інтеграції. Фіксуємо, які системи віддають дані, де стоїть проксі-шар, як розмежовані права сервісного облікового запису й як логуються звернення до моделі.
3. Налаштування сценаріїв. Збираємо запити під кожну задачу, налаштовуємо пошук по базі знань із посиланням на джерело у відповіді й задаємо поведінку за нестачі даних.
4. Перевірка якості відповідей. Проганяємо набір реальних питань, рахуємо частку коректних відповідей і обґрунтованих відмов, знаходимо слабкі формулювання й правимо інструкції.
5. Навчання команди замовника. Показуємо, як читати журнали, змінювати інструкції та додавати документи до бази знань без участі розробника.
6. Передача документації та контуру. Віддаємо схеми, конфігурації, регламент оновлення бази знань і порядок дій у разі збою; доступи оформлюємо на замовника.

Що замовник отримує на руки: схеми, політики, регламенти

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

Окремо фіксуємо технічну частину — як влаштована інтеграція YandexGPT і шар пошуку по базі знань, — та організаційну: хто має доступ, як оновлюються дані й як закриваються вимоги 152-ФЗ.

Технічна документація

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

Організаційні документи та 152-ФЗ

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

Кейс: асистент підтримки відповідає за внутрішньою базою знань

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

Перша відповідь займала в середньому 12 хвилин, а близько третини звернень потребували повторного уточнення з того самого питання. Права були налаштовані на рівні папок — оператор або бачив зайве (тарифні умови, розбори інцидентів), або не бачив потрібного й ішов просити доступ.

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

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

Що змінили

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

Метрики до і після

• Перша відповідь: 12 хвилин → 2 хвилини, включно з часом на перевірку джерелом.
• Звернення, закриті без ескалації на другу лінію: 58% → 81%.
• Повторні уточнення з одного питання: 31% → 9%.
• Кожна відповідь прив’язана до конкретного фрагмента бази — перевірюваність замість «оператор так сказав».

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

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

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

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

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

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

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

Вибір визначає одне питання: модель не знає фактів чи не вміє говорити вашою мовою? У першому випадку достатньо пошуку, у другому — донавчання.

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

Типові технічні сумніви перед стартом

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

Як розділяються права співробітників?

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

Що фіксує журнал запитів?

Хто й коли звернувся, яка модель відповідала, скільки зайняла обробка та з яким статусом. Метрики зберігаються окремо від вмісту: для розбору якості достатньо статистики, тексти — лише ролі з потрібним правом. Строк зберігання задає політика, далі дані видаляються автоматично.

Як бути, якщо постачальник моделі не підійде?

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

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

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

• Сценарій: 2-3 приклади «запит → очікувана відповідь» і як результат доходить до користувача.
• Джерела знань: де лежать документи й регламенти, у якому форматі, хто відповідає за їхню актуальність.
• Дані: обсяг, частота змін, чи є персональні дані й який режим обробки потрібен.
• Оточення: де розміщено сервіс, як влаштовані доступи, чи є обмеження на зовнішні сервіси.
• Ролі: хто приймає результат і хто виділить час на перевірку відповідей моделі.
• Обмеження: строки першого запуску, вимоги щодо захисту даних, що вже пробували й чому не підійшло.
• Критерії успіху: за якими ознаками ви зрозумієте, що пілот удався.

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

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

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