Kontroler finansowy w firmie dystrybucyjnej potrzebował co tydzień zestawienia: sprzedaż per region, marża per kategoria produktów, porównanie z poprzednim kwartałem. Pisał to zapytanie samodzielnie albo czekał na analityka. Przy wdrożeniu agenta text-to-SQL ten czas skrócił się do kilkudziesięciu sekund. Nie dlatego, że model „” o bazie. Dlatego, że ktoś wcześniej wykonał właściwą pracę: opisał schemat, zdefiniował słownik biznesowy i ustawił guardrails, które sprawiają, że agent nie może zrobić niczego destrukcyjnego.
To jest realna obietnica text-to-SQL. I tyle. Nic więcej.
Jak działa agent text-to-SQL: schema-aware prompting i pętla narzędzi
#Agent text-to-SQL to agent z dostępem do narzędzia bazodanowego. Jego praca wygląda następująco: użytkownik zadaje pytanie w języku naturalnym, agent buduje kontekst (schemat bazy, słownik biznesowy, przykładowe wartości z kolumn), generuje zapytanie SQL, waliduje je przed wykonaniem, wysyła do bazy, pobiera wynik i formułuje odpowiedź wraz z pokazanym zapytaniem.
Kluczowy element to schema-aware prompting. Przy każdym pytaniu do kontekstu modelu trafia opis schematu: nazwy tabel, kolumny, typy danych, klucze obce i mapowanie kolumn na terminy biznesowe. Bez tego mapowania model nie wie, że kolumna net_rev_adj to „” i że wartości są w tysiącach złotych. Błędna interpretacja jednostek lub nazw wygląda jak błąd modelu, ale jest błędem konfiguracji.
Agent korzysta z tool-use: zamiast generować zapytanie i od razu je wykonywać, wywołuje narzędzie sql_query(statement, limit). Narzędzie to ma twardy limit wierszy (zwykle 500-2000 zależnie od kontekstu), działa wyłącznie na połączeniu read-only i loguje każde wywołanie z pełnym tekstem zapytania oraz timestampem.
Dla złożonych pytań wieloetapowych agent rozkłada zadanie na sekwencję zapytań: najpierw pobiera dane zagregowane, potem je filtruje lub łączy. To ta sama pętla ReAct co w agencie wielokrokowym, tylko narzędziem jest baza SQL zamiast API.
Guardrails, które sprawiają, że to jest bezpieczne
#Sama architektura text-to-SQL bez guardrails to narzędzie, które może wyrządzić szkodę. Poniżej opisuję cztery warstwy ochrony, które stosujemy w Cashcrown przy każdym wdrożeniu.
Warstwa 1: rola read-only na poziomie bazy. Połączenie agenta z bazą używa roli bez uprawnień INSERT, UPDATE, DELETE ani DROP. Nawet jeśli model wygeneruje zapytanie modyfikujące dane (np. przez prompt injection), baza odrzuci je z błędem uprawnień. To jedyna linia obrony, która działa niezależnie od wszystkich pozostałych.
Warstwa 2: allowlista tabel i kolumn. Agent widzi tylko te tabele i kolumny, które zostały jawnie dopuszczone. Tabele z danymi osobowymi (imiona, e-maile, numery klientów), danymi kadrowymi lub finansowo wrażliwymi są domyślnie wykluczone ze schematu podawanego modelowi. Dostęp do nich wymaga decyzji człowieka, nie zmiany konfiguracji przez użytkownika.
Warstwa 3: walidacja zapytania przed wykonaniem. Przed każdym wykonaniem guardrail parsuje wygenerowane zapytanie SQL i sprawdza: czy zawiera tylko instrukcje SELECT, czy nie odwołuje się do tabel spoza allowlisty, czy limit wierszy jest poniżej progu. Zapytanie, które nie przejdzie walidacji, trafia do logu i eskalacji, nie do bazy.
Warstwa 4: human-gate dla niskiej pewności i tabel wrażliwych. Gdy model ocenia pewność odpowiedzi jako niską (złożone JOIN-y, niejasne pytanie, nieznane terminy), agent zamiast odpowiadać sygnalizuje: „” To samo dotyczy każdego zapytania dotykającego tabel oznaczonych jako wrażliwe. Human-oversight nie jest opcją dla tych dwóch klas.
| Warstwa guardrail | Co sprawdza | Co się dzieje przy naruszeniu |
|---|---|---|
| Rola read-only (baza) | Uprawnienia na poziomie DB | Błąd uprawnień, zapytanie odrzucone |
| Allowlista tabel | Czy tabela jest w dozwolonym zestawie | Błąd walidacji, eskalacja do logu |
| Parser zapytania | SELECT-only, brak DDL/DML | Blokada przed wysłaniem do DB |
| Human-gate | Niska pewność lub tabela wrażliwa | Pauza, żądanie akceptacji operatora |
Gdzie agent text-to-SQL się myli: realistyczna ocena
#Precyzja systemów text-to-SQL w środowiskach produkcyjnych waha się od 70 do 85% na czystych, dobrze udokumentowanych schematach. Na schematach nieczytelnych (skróty w nazwach kolumn, brak kluczy obcych, niejednoznaczne typy) spada do 40-60%. My w Cashcrown mierzymy to na golden secie 50-100 pytań przed każdym wdrożeniem produkcyjnym.
Trzy kategorie błędów pojawiają się najczęściej.
Halucynowane kolumny i tabele. Model może wygenerować zapytanie odwołujące się do kolumny, która nie istnieje w schemacie, szczególnie gdy schemat jest duży lub niekompletnie opisany. Guardrail parsujący SQL przed wykonaniem wychwytuje ten błąd zanim dotrze do bazy. Bez tego walidatora zapytanie wywołuje błąd bazy, który model może nieumiejętnie obsłużyć.
Błędne JOIN-y na złożonych relacjach. Pytanie wymagające łączenia pięciu tabel przez klucze częściowo opisane w schemacie często skutkuje zapytaniem, które jest syntaktycznie poprawne, ale semantycznie błędne. Agreguje na złym poziomie granulacji lub pomija warunek filtra. Wynik wygląda wiarygodnie, ale jest niepoprawny. Ochroną jest wymuszenie, żeby agent zawsze pokazywał wygenerowane zapytanie użytkownikowi przed podaniem odpowiedzi.
Wieloznaczność terminów biznesowych. „”, „”, „” mogą mieć różne definicje w różnych działach tej samej firmy. Słownik biznesowy w warstwie semantycznej musi jednoznacznie mapować te terminy na konkretne kolumny i formuły. Brak tego mapowania to źródło błędów, które są trudne do wychwycenia, bo liczby wyglądają sensownie. Szczegóły przygotowania danych pod AI opisuje artykuł AI do analizy danych i BI.
Hardowa granica: co agent nigdy nie robi samodzielnie
#To nie jest kwestia konfiguracji do późniejszego luzowania. To architektoniczna granica.
Agent text-to-SQL nigdy nie wykonuje autonomicznie zapytań INSERT, UPDATE, DELETE ani DDL. Nawet jeśli użytkownik prosi o modyfikację danych przez rozmowę. Nawet jeśli prompt wygląda niewinnie. Rola read-only na poziomie bazy to jedyna linia obrony niezależna od modelu.
Agent nigdy nie dotyka tabel zawierających PII (dane osobowe klientów, pracowników, kontrahentów) bez jawnej decyzji człowieka. Tabele te są wykluczone z schematu podawanego modelowi. Dostęp do nich możliwy jest wyłącznie przez ścieżkę z human-gate, gdzie operator widzi, jakie dane zostaną pobrane, i zatwierdza lub odrzuca zapytanie. Integracją agenta z systemami firmowymi takimi jak ERP zajmuje się oddzielnie artykuł integracja AI z ERP i systemami.
Zapytania o niskiej pewności modelu (niejasne pytanie, brak dopasowania do schematu, wynik pusty przy oczekiwanym niepustym) trafiają do człowieka z kontekstem: pokazanym zapytaniem, powodem eskalacji i propozycją uproszczenia pytania. Obsługę bezpieczeństwa agentów szerzej opisuje artykuł bezpieczeństwo agentów AI.
Obserwabilność i walidacja wyników
#Observability agenta text-to-SQL to nie logowanie dla samego logowania. To fundament zaufania do wyników i wymaganie przy AI Act dla systemów wpływających na decyzje biznesowe.
Każde wywołanie narzędzia bazodanowego generuje rekord zawierający: pytanie użytkownika, wygenerowane zapytanie SQL, liczbę zwróconych wierszy, czas wykonania i wynik walidacji guardrails. Rekordy te służą do trzech celów.
Pierwszy to monitoring jakości: jaki procent zapytań kończy się sukcesem, jaki eskalacją, jaki błędem guardrails. Wzrost odsetka eskalacji to sygnał dryfu (zmiana schematu bazy, nowe terminy w pytaniach użytkowników bez aktualizacji słownika).
Drugi to golden set test: zestaw 50-100 pytań z oczekiwanymi wynikami uruchamiany cyklicznie (raz w tygodniu lub przy każdej zmianie schematu). Spadek precyzji poniżej progu alarmuje przed tym, zanim użytkownicy zgłoszą błędy.
Trzeci to ślad audytowy wymagany przez AI Act i RODO dla systemów wpływających na decyzje finansowe lub kadrowe. Każda odpowiedź musi być odtwarzalna: wiadomo, jakie zapytanie wygenerowało wynik, z jakich danych i w jakim momencie. Walidację wyjść modelu opisuje szczegółowo artykuł walidacja wyjść LLM.
Wypróbuj na żywo
#Opisz schemat swojej bazy i pytanie analityczne, które chcesz zadawać, a model zaprojektuje architekturę agenta text-to-SQL: schema prompting, guardrails i miejsca human-gate dla Twojego zakresu (playground: PII maskowane, zero retencji):
FAQ
#Jaka jest realna precyzja agenta text-to-SQL na produkcyjnej bazie?
#Na czystym, dobrze udokumentowanym schemacie z opisanym słownikiem biznesowym precyzja wynosi od 70 do 85% bez dodatkowego fine-tuningu. Na schemacie z niejednoznacznymi nazwami kolumn, brakiem kluczy obcych lub mieszanymi jednostkami precyzja spada do 40-60% i wymaga najpierw prac porządkowych. My w Cashcrown mierzymy precyzję na golden secie 50-100 pytań przed każdym wdrożeniem produkcyjnym. Bez tego baseline nie wiadomo, od czego się startuje i jak mierzyć poprawę.
Czy agent może przypadkowo zmodyfikować dane w bazie?
#Nie, jeśli architektura jest poprawnie zbudowana. Połączenie agenta używa roli bazodanowej bez uprawnień INSERT, UPDATE, DELETE ani DDL. Ta warstwa działa niezależnie od modelu: nawet gdyby model wygenerował zapytanie modyfikujące dane przez prompt injection lub błąd, baza odrzuci je z błędem uprawnień. Do tego dochodzi guardrail parsujący SQL przed wysłaniem do bazy, który blokuje każde zapytanie zawierające instrukcje inne niż SELECT.
Co się dzieje, gdy agent nie zna odpowiedzi lub jest niepewny?
#Agent sygnalizuje eskalację zamiast odpowiadać: pokazuje wygenerowane zapytanie, podaje powód niepewności (np. nieznany termin, brak dopasowania do schematu, pusty wynik) i prosi operatora o weryfikację lub uproszczenie pytania. To zachowanie jest zaprojektowane, nie awaryjne. System, który odpowiada pewnie na pytania spoza swojego zakresu, jest bardziej niebezpieczny niż system, który przyznaje się do braku wiedzy. Wzorzec structured output z polem confidence i requires_review pozwala agentowi formalnie sygnalizować tę decyzję.
Ile tabel może obsłużyć agent w jednym wywołaniu?
#Praktyczny limit to 30-50 tabel w kontekście schematu przy typowych rozmiarach okna kontekstowego współczesnych modeli. Przy większych bazach stosuje się warstwowanie: agent operuje na perspektywach (views) przygotowanych przez inżyniera danych, nie na surowym schemacie. Alternatywnie schemat jest filtrowany dynamicznie na podstawie pytania, co ogranicza kontekst do tabel istotnych dla danego zapytania. Obie techniki wymagają dodatkowej konfiguracji.
Jak wygląda wdrożenie agenta text-to-SQL z Cashcrown?
#Zaczynamy od audytu schematu i słownika biznesowego (od 1 do 2 tygodni zależnie od liczby tabel i stanu dokumentacji). Potem konfiguracja guardrails, allowlisty tabel i roli read-only. Następnie golden set: 50-100 pytań z oczekiwanymi wynikami, pomiar precyzji baseline. Pilot z użytkownikami przez 2-4 tygodnie z pełnym monitoringiem eskalacji. Pełna autonomia dopiero po walidacji precyzji i poziomu eskalacji poniżej uzgodnionych progów. Wejście przez ocenę gotowości lub kontakt.