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 сокращает разрыв между обычным языком и полезными выводами. Но систему, которой можно доверять в продакшене, по-прежнему дают постоянное тестирование и жёсткое управление.