04. SQL Query Agent: вопросы к базе
Агент превращает вопрос «какая выручка по странам» в SQL, исполняет его и объясняет результат. Полезен как рабочая схема аналитики и как пример правильного дефолта: база открывается только на чтение.
Ответить на вопрос по данным, не заставляя пользователя писать SQL. Демо-режим создаёт учебную базу магазина; можно указать свою SQLite-базу. Граница: агент не знает бизнес-определений (что считать выручкой) и не проверяет результат.
Архитектура
Заголовок раздела «Архитектура»flowchart LR Q["Вопрос"] --> A["Агент"] A -->|"список таблиц"| T["SQLDatabaseToolkit"] T -->|"SQL"| D["База (read-only)"] D -->|"строки"| A A --> R["Ответ"]
Инструменты дают агенту схему, возможность выполнять запрос и смотреть данные.
SQLDatabase.from_uri(sqlite_uri(db, read_only=True))открывает базу.SQLDatabaseToolkitсоздаёт набор инструментов: список таблиц, схема, запрос, проверка.- Агент выбирает инструмент, генерирует SQL, получает строки и формулирует ответ.
Что в коде
Заголовок раздела «Что в коде»def sqlite_uri(db_path: str, read_only: bool = True) -> str: mode = "ro" if read_only else "rw" return f"sqlite:///file:{db_path}?mode={mode}&uri=true"
db = SQLDatabase.from_uri(sqlite_uri(db_path, read_only=read_only))toolkit = SQLDatabaseToolkit(db=db, llm=llm)Чему учит
Заголовок раздела «Чему учит»- Read-only по умолчанию. Это правильная настройка для аналитики: даже при ошибке агент не испортит данные.
- Схема как инструмент. Агент сначала смотрит структуру, потом пишет запрос — это снижает число ошибок в именах полей.
- Демо-база. Учебный набор позволяет проверить агента без доступа к реальным данным.
Где сломается
Заголовок раздела «Где сломается»- Правдоподобный неверный запрос. Соединение таблиц размножает строки, и сумма выглядит разумной.
- NULL как ноль. Агрегаты дают смещённые значения.
- Нет лимитов. Запрос может вернуть миллион строк или занять минуты.
- Нет сверки. Результат не сравнивается с контрольным отчётом.
- Нет бизнес-словаря. «Выручка» может означать сумму заказов или оплат.
Как улучшить
Заголовок раздела «Как улучшить»- Добавить словарь метрик: что считается выручкой, какой период, какие исключения.
- Показывать SQL рядом с ответом.
- Ограничить строки и время, добавить контрольную сумму.
- Прогонять набор эталонных вопросов и сравнивать с проверенными числами — см. Evals.
Связь с другими разделами
Заголовок раздела «Связь с другими разделами»- Данные и аналитика — риски и метрики.
- Безопасность агента — права и изоляция.
- LangChain — фреймворк и toolkit.
Материалы и источники
Заголовок раздела «Материалы и источники»- LangChain: SQLDatabaseToolkit — инструменты работы со схемой и запросами.