Streszczenie AI
Framework Vanna przywraca sprawność translacji zapytań naturalnych na SQL, łącząc Retrieval‑Augmented Generation z agentem Pythonowym, który wybiera odpowiednie narzędzia, weryfikuje schemat i bezpiecznie wykonuje kod w dowolnym dialekcie. Dzięki pamięci narzędzi (vectorized tool memory) oraz weryfikacji tożsamości użytkownika (moduł UserResolver), system dynamicznie podnosi jakość zapytań, zapewniając izolację uprawnień i audytowalność. Integracja z FastAPI i obsługa Server‑Sent Events pozwala na asynchroniczne strumieniowanie zwizualizowanych wyników bez konieczności pisania dedykowanego front‑endu.
Spis treści:
Translacja języka naturalnego na dialekty SQL (Text-to-SQL) stanowi jedno z kluczowych wyzwań w inżynierii systemów bazodanowych zintegrowanych z dużymi modelami językowymi (LLM). Otwartoźródłowy framework Vanna rozwiązuje problem halucynowania schematów relacyjnych poprzez połączenie mechanizmu Retrieval-Augmented Generation (RAG) z modularnym środowiskiem wykonawczym agenta w języku Python. Narzędzie pozwala na automatyczne przekształcanie zapytań analitycznych na precyzyjny kod SQL, jego bezpieczną egzekucję w silniku bazodanowym oraz asynchroniczne strumieniowanie zwizualizowanych wyników bezpośrednio do aplikacji klienckich.
Ewolucja architektury: od prostego RAG do agenta Vanna 2.0
Wczesne wydania frameworka Vanna (gałąź 0.x) opierały się na prostym modelu proceduralnym i wzorcu dziedziczenia klas bazowych (VannaBase). Cały przepływ sprowadzał się do zaindeksowania definicji tabel (DDL), dokumentacji oraz wzorcowych par pytanie-SQL w bazie wektorowej, a następnie pojedynczego wywołania metody generującej zapytanie. Choć podejście to sprawdzało się w testach koncepcyjnych, wdrożenia produkcyjne ujawniały braki w warstwie kontroli dostępu, brak możliwości wieloetapowego wnioskowania oraz trudności w bezpiecznym zarządzaniu tożsamością użytkownika.
Wydanie Vanna 2.0 zreorganizowało strukturę biblioteki, zastępując sztywne dziedziczenie architekturą zorientowaną na agentów (Agent API) oraz rejestr narzędzi (ToolRegistry). W tym modelu model językowy nie generuje wyłącznie surowego tekstu z zapytaniem, lecz zarządza cyklem decyzyjnym: wybiera odpowiednie narzędzia egzekucyjne, weryfikuje poprawność schematu, wykonuje zapytanie w dialekcie bazy danych i decyduje o formie prezentacji danych.
Cecha architektoniczna | Vanna 0.x (podejście tradycyjne) | Vanna 2.0 (podejście agentowe) |
|---|---|---|
| Model interakcji | Jednorazowe tłumaczenie (Single-shot Text-to-SQL) | Pętla decyzyjna agenta (wieloetapowe użycie narzędzi) |
| Kontekst tożsamości | Brak wbudowanej warstwy autoryzacji zapytań | Natywny obiekt kontekstu użytkownika (UserResolver) |
| Zarządzanie wiedzą | Statyczna faza treningowa (indeksowanie DDL) | Dynamiczna pamięć narzędzi (Tool Memory) i RAG |
| Zwracany rezultat | Ciąg tekstowy SQL lub obiekt DataFrame | Strumieniowane komponenty UI (tabele, wykresy Plotly) |
| Integracja serwerowa | Dedykowany, prosty interfejs demonstracyjny | Natywna obsługa protokołu SSE dla FastAPI i Flask |
Mechanizm ekstrakcji wiedzy i rola pamięci narzędzi
Kluczowym elementem determinującym precyzję generowanego kodu SQL w Vanna jest unikanie fine-tuningu wag modeli językowych na rzecz inżynierii kontekstu wspomaganej wektorowo. Modele fundamentalne posiadają ogólną wiedzę o składni SQL, jednak nie znają specyfiki konkretnej bazy danych: niestandardowych nazw kolumn, relacji kluczy obcych, reguł biznesowych ani dialektów takich jak PostgreSQL, Snowflake czy ClickHouse.
Vanna organizuje przestrzeń informacyjną w bazie wektorowej (np. ChromaDB, PGVector, Qdrant) w trzech głównych wymiarach:
- Struktura bazy danych (DDL): deklaracje tabel, typy danych, klucze główne oraz zdefiniowane ograniczenia więzów integralności.
- Dokumentacja semantyczna: definicje wskaźników biznesowych, glosariusze pojęć, opisy kolumn i specyficzne formuły kalkulacji marży czy konwersji.
- Przykłady referencyjne (Question-SQL Pairs): pary pytań w języku naturalnym i odpowiadających im, zweryfikowanych przez inżynierów zapytań SQL.
W architekturze Vanna 2.0 tradycyjna faza wstępnego trenowania została uzupełniona o moduł pamięci narzędzi (Tool Memory). Każde zapytanie, które zakończyło się poprawną egzekucją i zostało zaakceptowane lub skorygowane przez analityka, zostaje automatycznie zaindeksowane jako wektor stanu. Podczas obsługi nowego pytania agent odpytuje przestrzeń wektorową o najbliższe semantycznie przypadki użycia, dzięki czemu jakość generowanego kodu rośnie wraz z eksploatacją systemu bez konieczności ponownego wdrażania parametrów modelu.
Bezpieczeństwo wielodostępne i kontekst tożsamości użytkownika
Główną przeszkodą we wdrażaniu modeli Text-to-SQL w środowiskach korporacyjnych jest ryzyko nieautoryzowanego dostępu do danych oraz iniekcji niebezpiecznych instrukcji bazodanowych. Bezpośrednie podłączenie agenta LLM do bazy danych przy użyciu jednego konta serwisowego prowadzi do zatarcia granic uprawnień pomiędzy pracownikami.
Vanna 2.0 rozwiązuje ten problem na poziomie architektury poprzez wymuszenie izolacji tożsamości w każdym wywołaniu narzędzia. Wzorzec ten opiera się na module UserResolver, który weryfikuje nagłówki autoryzacyjne (np. tokeny JWT lub sesje cookie) przekazywane przez protokół HTTP:
- Ekstrakcja tożsamości: agent przekształca żądanie sieciowe na obiekt zawierający identyfikator użytkownika, adres e-mail oraz przypisane role lub grupy uprawnień.
- Kontrola dostępu na poziomie wierszy (Row-Level Security): narzędzia bazodanowe automatycznie modyfikują zapytania lub przekazują zmienne sesyjne do silnika bazy, wymuszając filtrowanie danych wyłącznie do dozwolonych jednostek organizacyjnych.
- Rejestracja audytowa (Audit Logging): każde wygenerowane zapytanie, czas wykonania oraz identyfikator użytkownika są zapisywane w logach zgodności operacyjnej.
- Ograniczanie kosztów i zasobów (Rate Limiting): wbudowane punkty przechwytywania (lifecycle hooks) umożliwiają weryfikację limitów zapytań przed przekazaniem promptu do komercyjnych interfejsów API LLM.
Implementacja serwera z wykorzystaniem FastAPI i biblioteki Vanna
Wdrożenie Vanna w środowisku produkcyjnym polega zazwyczaj na osadzeniu agenta w asynchronicznym frameworku sieciowym, takim jak FastAPI. Poniższy przykład demonstruje konfigurację agenta wykorzystującego zewnętrzny model LLM, runner bazy SQLite oraz niestandardową klasę weryfikującą tożsamość użytkownika.
from fastapi import FastAPI
from vanna import Agent
from vanna.servers.fastapi.routes import register_chat_routes
from vanna.servers.base import ChatHandler
from vanna.core.user import UserResolver, User, RequestContext
from vanna.integrations.anthropic import AnthropicLlmService
from vanna.tools import RunSqlTool
from vanna.integrations.sqlite import SqliteRunner
from vanna.core.registry import ToolRegistry
app = FastAPI()
class CorporateUserResolver(UserResolver):
async def resolve_user(self, context: RequestContext) -> User:
auth_header = context.get_header("Authorization")
# Logika dekodowania tokenu uwierzytelniającego (np. JWT)
user_payload = {"sub": "analyst_01",
"email": "analyst@corp.local", "roles": ["finance_read"]}
return User(
id=user_payload["sub"],
email=user_payload["email"],
group_memberships=user_payload["roles"]
)
llm_service = AnthropicLlmService(model="claude-3-5-sonnet-20241022")
database_runner = SqliteRunner("./analytics_warehouse.db")
tool_registry = ToolRegistry()
tool_registry.register(RunSqlTool(sql_runner=database_runner))
agent = Agent(
llm_service=llm_service,
tool_registry=tool_registry,
user_resolver=CorporateUserResolver()
)
chat_handler = ChatHandler(agent)
register_chat_routes(app, chat_handler)
Po zainicjalizowaniu tras sieciowych serwer udostępnia punkt końcowy obsługujący strumieniowanie zdarzeń Server-Sent Events (SSE). Po stronie przeglądarki integracja sprowadza się do osadzenia natywnego komponentu sieciowego
Praktyczne zastosowania frameworka
Zastosowanie architektury Vanna wykracza poza proste generowanie kodu w notatnikach badawczych. Do głównych obszarów implementacji należą:
- Samoobsługowa analityka biznesowa (Self-Service BI): umożliwienie kadrze menedżerskiej i analitykom biznesowym zadawania pytań ad-hoc w języku naturalnym, co redukuje liczbę powtarzalnych zgłoszeń kierowanych do zespołów inżynierii danych.
- Systemy SaaS z wieloma najemcami (Multi-Tenant): wdrażanie asystentów danych w aplikacjach chmurowych, w których ten sam model obsługuje tysiące klientów przy zachowaniu ścisłej izolacji danych w oparciu o UserResolver.
- Zarządzanie operacyjne w systemach ERP i CRM: bezpośrednia integracja z relacyjnymi magazynami danych w celu szybkiego generowania raportów sprzedaży, logistyki czy stanów magazynowych na żądanie.
- Eksploracja rozproszonych hurtowni danych: integracja z silnikami kolumnowymi (Snowflake, BigQuery, ClickHouse), gdzie agent wspomaga konstruowanie złożonych agregacji analitycznych w oparciu o zaindeksowaną dokumentację hurtowni.
Praktyczna wartość systemów Text-to-SQL nie zależy wyłącznie od parametrów samego modelu językowego, lecz od precyzji dostarczonego kontekstu schematu bazy danych oraz rygorystycznej kontroli tożsamości na poziomie egzekucji kodu.
Dzięki połączeniu wektorowej pamięci kontekstowej, wbudowanego wsparcia dla protokołu SSE oraz architektury uwzględniającej uprawnienia użytkowników, framework Vanna stanowi solidną bazę do budowy stabilnych, audytowalnych asystentów bazodanowych w nowoczesnych stosach technologicznych opartych na języku Python.
vanna-ai/vanna
by vanna-ai🤖 Chat with your SQL database 📊. Accurate Text-to-SQL Generation via LLMs using Agentic Retrieval 🔄.
