Text-to-SQL

Елена Дворядкина

Обзор

Text-to-SQL — LLM-сервис, доступный в Enterprise-версии ADQM 26.8.2.7 и выше, который реализует преобразование текстовых вопросов на естественном языке в соответствующие SQL-запросы SELECT для чтения данных кластера ADQM. Полученные в результате преобразования SQL-запросы не выполняются в клиенте автоматически — пользователь сначала просматривает запрос, затем запускает его вручную.

Для работы сервиса используется дообученная языковая модель семейства Qwen3.6, которая устанавливается локально на одном из хостов кластера ADQM с помощью llama.cpp — таким образом, запросы, схема данных и сами данные гарантированно остаются внутри кластера.

Для использования функциональности Text-to-SQL:

  1. Установите сервис Text-to-SQL (tech preview) в кластер ADQM.

  2. Задавайте текстовые вопросы (вида How many orders were paid for yesterday?, Revenue from stores for the current year — до 4000 символов), обращаясь к данным кластера:

ВНИМАНИЕ
Текущая версия сервиса Text-to-SQL находится в режиме технического превью и не предназначена для использования в производственных средах.

Требования

Программные требования для установки сервиса Text-to-SQL (tech preview):

  • Операционная система: Ubuntu 22.04 LTS, Ubuntu 24.04 LTS или RHEL 9.

  • Python версии 3.9 или выше.

Минимальные требования к хосту для установки модели:

  • CPU: x86-64 с AVX2.

  • Память: от 32 ГБ (рекомендуется 48 ГБ).

  • Объем дискового пространства: 48 ГБ (для двух версий модели).

Локальный путь к модели: модель не должна быть установлена в каталоги /home, /root, /run/user, /tmp, /var/tmp.

Установка сервиса

  1. В интерфейсе ADCM откройте страницу Clusters и кликните по имени кластера ADQM. Затем на открывшейся странице кластера перейдите на вкладку Services и нажмите Add services.

    Переход к добавлению сервисов
    Переход к добавлению сервисов

  2. В открывшемся окне выберите Text-to-SQL (tech preview) и нажмите Add.

    Выбор сервиса
    Выбор сервиса

    В результате добавленный сервис отобразится на вкладке Services.

    Результат успешного добавления сервиса в кластер
    Результат успешного добавления сервиса в кластер

  3. На странице кластера откройте вкладку Mapping, чтобы перейти к распределению сервисных компонентов Text-to-SQL Engine и Model Server (llama.cpp) между хостами кластера.

    Переход к распределению сервисных компонентов
    Переход к распределению сервисных компонентов

    Назначьте хосты компонентам — нажмите Add hosts и выберите нужные хосты в открывшемся окне.

    ВНИМАНИЕ
    Оба компонента сервиса Text-to-SQL рекомендуется устанавливать на один хост. Возможно их размещение на хосте с ADQMDB — при этом следует учитывать, что обработка запросов и сбор информации о кластере сервисом Text-to-SQL будут потреблять ресурсы процессора и память сервера ADQMDB. При размещении компонента Text-to-SQL Engine на отдельном хосте ему потребуется сетевой доступ к серверу модели (порт 8080) и к серверам ADQMDB (порты 8123 и 8443 для соединений по HTTP и HTTPS соответственно).

    После завершения распределения компонентов нажмите Save, чтобы сохранить изменения.

  4. Чтобы перейти к настройке сервиса Text-to-SQL, откройте вкладку Services на странице кластера и кликните по имени сервиса в столбце Name.

    Переход к настройке сервиса
    Переход к настройке сервиса

  5. В открывшемся окне заполните или измените необходимые конфигурационные параметры сервиса. Например:

    • Model — укажите источник модели (если указан другой адрес зеркала или модель уже находится на хосте);

    • API — добавьте ключи API (если клиенты будут напрямую обращаться к HTTP API);

    • Scope — укажите базы данных/таблицы, которые движку Text-to-SQL будет разрешено читать;

    • Answers — выберите режим проверки ответа (можно указать, должен ли сервис проверять варианты SQL-запросов с помощью EXPLAIN перед отправкой ответа или возвращать первые строки результата в ответе).

      Настройка сервиса Text-to-SQL
      Настройка сервиса Text-to-SQL

      После указания всех необходимых параметров нажмите Save.

  6. Установите сервис. Для этого на вкладке Services кликните по иконке actions default dark actions default light в столбце Actions и запустите действие Install.

    Переход к установке сервиса
    Переход к установке сервиса

    Дождитесь завершения установки и убедитесь, что статус сервиса изменился с created на installed.

    Процесс установки завершен
    Процесс установки завершен

    Чтобы посмотреть процесс выполнения установки сервиса и проанализировать ошибки в случае их возникновения, выберите пункт Jobs в левом навигационном меню и кликните по имени задачи Install в списке задач Jobs.

    Страница задачи Install
    Страница задачи Install

Использование Text-to-SQL

ADQM Notebook

  1. Откройте ADQM Notebook.

  2. Введите текстовый вопрос в SQL-ячейку и кликните по иконке AI icon dark AI icon light AI на панели управления ячейки.

    Преобразование текста в SQL
    Преобразование текста в SQL

  3. После выполнения преобразования исходный текстовый вопрос будет закомментирован, а ниже в ячейке будет выведен соответствующий SQL-код запроса. Кликните run icon Run, чтобы выполнить запрос.

    Запуск запроса
    Запуск запроса

  4. После выполнения запроса результирующий набор данных будет выведен в таблице результатов.

    Результат выполнения запроса
    Результат выполнения запроса

SQL-функции

После установки сервиса Text-to-SQL на каждом сервере ADQMDB доступны следующие SQL-функции.

Функция Описание

text2sql(question)

Возвращает SQL-текст запроса или сообщение с объяснением, почему он не может быть получен

text2sql_json(question, options)

Возвращает полный ответ от движка Text-to-SQL в формате JSON (ответ HTTP-запроса POST /v1/sql) или сообщение об ошибке в виде {"error": {…​}}

text2sql_feedback(request_id, verdict, corrected_sql, comment)

Передает сервису обратную связь о правильности ответа (сохраняется в журнал аудита движка Text-to-SQL). Возвращаемое значение: {"accepted": true} или {"error": {…​}}

text2sql_status()

Возвращает отчет о готовности сервиса в формате JSON

text2sql_call(op, payload, caller)

Исполняемая функция, которую вызывают функции text2sql*. ADQM Notebook вызывает эту функцию напрямую
ПРИМЕЧАНИЕ

Эти функции могут вызывать любые пользователи ADQMDB, специальные права не требуются. При вызове функции движок Text-to-SQL обращается к кластеру от имени своего пользователя (text2sql_ro) с правами только на чтение, действующего в рамках указанной области данных (настраивается конфигурационными параметрами сервиса в секции Scope). Таким образом, любой пользователь, имеющий доступ к системе, может сформировать SQL-запрос на основе схемы данных и подсказок по значениям, относящихся к этой области, а также просмотреть первые строки результата запроса — независимо от того, какими правами доступа он обладает фактически. Однако при выполнении SQL-запроса учитываются собственные права пользователя. Рекомендуется ограничивать область (scope) только теми данными, которые разрешено видеть всем потенциальным пользователям.

Вызывать функции text2sql* можно в любом клиенте ADQMDB.

Пример вызова функции text2sql в интерфейсе ADQM Notebook
Пример вызова функции text2sql в интерфейсе ADQM Notebook
Пример вызова функции text2sql_json в интерфейсе ADQM Notebook
Пример вызова функции text2sql_json в интерфейсе ADQM Notebook

HTTP API

Движок Text-to-SQL предоставляет HTTP API по адресу http://<text2sql_engine_host>:8090 (или https://…​, если включен параметр HTTPS в секции API конфигурации сервиса Text-to-SQL), где <text2sql_engine_host> — IP-адрес хоста, на котором установлен компонент Text-to-SQL Engine; 8090 — порт доступа к API (определяется параметром API port в секции API конфигурации сервиса Text-to-SQL).

ADQM Notebook и SQL-функции обращаются к API через исполняемую функцию text2sql_call. Другие клиенты могут обращаться к нему напрямую — для аутентификации необходимо использовать пользовательский ключ API (за исключением доступа к /healthz), передавая его с запросом в формате Authorization: Bearer <key> (где <key> — значение конфигурационного параметра сервиса API keys). Роли пользователей указываются через параметр API key roles (user, admin или metrics).

В таблице перечислены HTTP-методы и конечные точки доступа (endpoint), поддерживаемые API, а также роли пользователей, которые имеют к ним доступ.

HTTP-метод и конечная точка Роль пользователя Описание

POST /v1/sql

user, admin

Отправляет текст для преобразования в SQL-запрос

POST /v1/chat/completions

user, admin

Отправляет текст для преобразования в SQL-запрос через API чата OpenAI

GET /v1/models

user, admin

Возвращает идентификатор модели (adqm-text2sql)

POST /v1/feedback

user, admin

Отправляет обратную связь по ответу

GET /v1/catalog

user, admin

Возвращает состояние cluster info (снепшот кластера, который получает движок Text-to-SQL в рамках области своего действия)

POST /v1/catalog/refresh

admin

Обновляет cluster info

GET /v1/readiness

user, admin

Возвращает отчет о готовности сервиса (что движок "знает" о кластере и какой информации не хватает)

GET /readyz

user, admin

Возвращает 200, если сервис может ответить; в противном случае — 503 (с указанием причины)

GET /healthz

Ключ API не требуется

Возвращает состояние процесса

GET /metrics

Любой пользователь

Возвращает Prometheus-метрики движка и llama.cpp
Нашли ошибку? Выделите текст и нажмите Ctrl+Enter чтобы сообщить о ней