SQL-агент на LangChain для запитів до MySQL природною мовою

Дані компанії зазвичай сховані за технічним бар'єром. Щоб щось із них дістати, доводилося писати SQL або опановувати негнучкий інструмент із кнопками й формами. Інтерфейс природною мовою прибирає цей прошарок: людина, яка ухвалює рішення, ставить питання сама, і аналізом керує її намір, а не технічні навички. SQL-агент на LangChain — один із практичних способів цього досягти. Нижче — що робить агент, як налаштувати середовище й тестову базу MySQL, як зібрати виконавця і які захисні заходи потрібні, перш ніж підпускати його до справжніх даних.

Як доступ до даних ставав простішим

Кожне нове покоління інструментів ховало дедалі більше складності:

1. Консольні клієнти вимагали точного синтаксису й доброго розуміння реляційної алгебри.
2. Візуальні конструктори запитів допомогли, але розбиратися в join і зв'язках між таблицями все одно було треба.
3. Дашборди легко читати, але вони обмежені тими поданнями, які хтось побудував заздалегідь.
4. Інтерфейси природною мовою розуміють зміст, тож знати схему чи мову запитів нікому не потрібно.

ШІ-агент для SQL має кілька конкретних переваг:

• Він сам читає схему й знаходить потрібні таблиці, первинні та зовнішні ключі й шляхи для join.
• Він зіставляє звичайні слова із сутностями в базі, а потім пише й виконує складні запити без будь-чийого втручання.
• Він запитує схему лише для потрібних таблиць, що скорочує витрату токенів і вартість та допомагає продуктивності.
• Він перетворює розмиті питання на кшталт «Як ішли продажі минулого місяця?» на детермінований SQL, виводячи контекст і зіставляючи сутності.

Надійно це працює лише з правильною обв'язкою: фреймворком оркестрації та ізольованим середовищем.

З чого складається SQL-агент на LangChain

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

У центрі — цикл ReAct, скорочення від reasoning plus acting, «міркування плюс дія»:

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

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

Середовище й залежності

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

pip install virtualenv
virtualenv my_env
source my_env/bin/activate

Потім встановіть цей стек саме в цих версіях:

• ibm-watsonx-ai==1.0.4 відповідає за інференс базової моделі.
• ibm-watson-machine-learning==1.0.357 підключає корпоративні LLM.
• langchain==0.2.1 — основний фреймворк оркестрації для логіки агента.
• langchain-ibm==0.1.7 дає обгортки, специфічні для екосистеми IBM.
• langchain-experimental==0.0.59 містить додаткові утиліти для агентів.
• mysql-connector-python==8.4.0 — драйвер бази даних.

База, до якої звертається агент

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

Chinook добре підходить для тестів, бо моделює цілий бізнес цифрових медіа:

• У ній 11 таблиць, зокрема Artist, Album, Invoice і Track.
• Первинні та зовнішні ключі дають агентові змогу будувати join за кількома таблицями.
• У ній понад 15 000 записів — досить, щоб перевірити аналіз трендів і складні вибірки.

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

mysql+mysqlconnector://{mysql_username}:{mysql_password}@{mysql_host}:{mysql_port}/{database_name}

Потрібні п'ять значень: ім'я користувача, пароль, хост, порт (за замовчуванням 3306) та ім'я бази, тут Chinook.

Перш ніж підключати LLM, перевірте з'єднання й схему з MySQL CLI:

-- Verify database existence
SHOW DATABASES;
USE Chinook;

-- Confirm data integrity: This should return exactly 347
SELECT COUNT(*) FROM Album;

Кількість альбомів має бути рівно 347. Перевірена база дає моделі надійну основу й знижує ймовірність помилок прив'язки до даних.

Збираємо виконавця агента

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

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

Агент створюється фабрикою create_sql_agent, а рушієм міркувань слугує ibm/granite-4-h-small. Їй потрібні такі аргументи:

• llm приймає модель Granite, обгорнуту в екземпляр WatsonxLLM.
• db приймає ваше підключення SQLDatabase.
• verbose=True дає змогу стежити за тим, що він робить.
• agent_type зі значенням ZERO_SHOT_REACT_DESCRIPTION для звичайних аналітичних питань.

Не вважайте verbose=True просто перемикачем для налагодження. У бізнес-контексті саме він робить можливим аудит. Можна вивчити ланцюжок міркувань і переконатися, що згенерований SQL і кроки міркування відповідають внутрішній логіці даних і вимогам комплаєнсу, ще до того, як відповідь до когось потрапить.

Відновлення після помилок і захисні заходи

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

Одна зі справжніх сильних сторін цього агента — самовиправлення. Коли згенерований запит падає, агент:

1. Отримує трасування помилки від рушія бази.
2. З'ясовує, що пішло не так, наприклад синтаксична помилка чи друкарська помилка в імені стовпця.
3. Повторює спробу з виправленим запитом, що підвищує частку успішних складних запитів.

Чотири практики захищають дані компанії:

1. Виконуйте кожен запит агента в ізольованій пісочниці, щоб нічого не змінилося випадково.
2. Лишайте людину в контурі: експерт має перевіряти висновки, які йдуть у відповідальні звіти.
3. Постійно доопрацьовуйте промпти, щоб враховувати різні формулювання й особливості предметної галузі.
4. Дайте конектору бази користувача з обмеженими правами, суворим порядковим захистом і межами приватності.

Що в підсумку

Перехід від чистого SQL до запитів природною мовою відкриває дані значно більшій кількості людей. Поєднання точної моделі на кшталт ibm/granite-4-h-small зі структурованою оркестрацією LangChain скорочує розрив між звичайною мовою й корисними висновками. Але систему, якій можна довіряти в продакшені, як і раніше дають постійне тестування й жорстке управління.