Text2SQL-сервис доступен по HTTPS (Traefik) или по NodePort; все вызовы API (кроме /health и /metrics) требуют заголовок X-API-Key.
Режимы работы
Без сохранения в БД — передавайте schema_definition в теле запроса: схема не сохраняется, данные не пишутся, удобно для тестов и разовых запросов. С сохранением в БД — создаёте схему через POST /api/schemas, дальше используете schema_id; сохраняются история, кэш и few-shot примеры.
Быстрый старт (без БД)
Проверка: curl -k https://<ваш-text2sql>/health. Генерация SQL с передачей схемы в запросе:
curl -k -X POST https://<host>/api/generate \
-H "X-API-Key: ВАШ_API_КЛЮЧ" \
-H "Content-Type: application/json" \
-d '{
"user_query": "Покажи всех пользователей",
"schema_definition": "CREATE TABLE users (id INT, name VARCHAR, age INT);"
}'В ответе приходят поля:
| Поле | Описание |
|---|---|
| sql | Сгенерированный SQL-запрос |
| execution_result | Результат выполнения в БД (если execute_query=true) |
| visualization_type | table / chart / text — формат визуализации |
| difficulty | easy / medium / hard — определённая сложность запроса |
| best_candidate_score | Оценка LLM-as-a-judge выбранного кандидата |
| cached | true, если ответ взят из кэша |
Основные endpoints
| Метод | Путь | Назначение |
|---|---|---|
| GET | /health | Проверка здоровья (без ключа) |
| GET | /metrics | Метрики Prometheus (без ключа) |
| POST | /api/generate | Генерация SQL (user_query, schema_id или schema_definition) |
| GET/POST | /api/schemas | Список и создание схем |
| GET | /api/history | История запросов |
Параметры /api/generate
user_query — вопрос на естественном языке; schema_id или schema_definition — схема БД; validate_sql, execute_query, use_cache; use_self_consistency, num_candidates (3–5); auto_visualize. Для сложных запросов с JOIN можно не передавать схему — сервис сам подберёт таблицы (Schema Linking).
Мониторинг
Метрики экспортируются в Prometheus (/metrics): количество запросов, время генерации и выполнения, точность, кэш, количество кандидатов. Визуализация — в Grafana (дашборд Text2SQL).
Итого: Для старта достаточно POST /api/generate с user_query и schema_definition; ключ в заголовке X-API-Key; при постоянном использовании — схемы в БД и история.