GitHub - vanna-ai/vanna: 🤖 Chat with your SQL database 📊. Accurate Text-to-SQL Generation via LLMs using Agentic Retrieval 🔄.

Vanna 2.0은 자연어 질문을 SQL 쿼리로 변환하고, 그 결과를 다시 자연어 답변 및 시각화된 데이터로 제공하는 AI agent-based 시스템입니다. 이 버전은 특히 기업 환경에서의 보안, 확장성 및 사용자 경험에 중점을 두고 재설계되었습니다.

핵심 방법론 및 기술적 특징:

Vanna 2.0의 핵심은 Agent 기반 아키텍처와 user-aware 시스템입니다.

Agent-based Architecture:

* 사용자의 자연어 질의는 Web Component($<vanna-chat>$)를 통해 Your Server(FastAPI로 구현 가능)로 전달됩니다.
* Your Server는 요청에 포함된 사용자 인증 정보(예: 쿠키, JWT)를 기반으로 User Resolver를 사용하여 User 객체(ID, 이메일, 그룹 멤버십 포함)를 생성합니다.
* 이 User 객체는 Agent에게 전달되어 모든 후속 작업의 context로 활용됩니다.
* Agent는 LLM service (예: AnthropicLlmService)와 ToolRegistry를 사용하여 사용자의 질의를 처리합니다.

User-Aware at Every Layer:

* User Resolver: 개발자가 기존 인증 시스템(쿠키, JWT 등)과 연동하여 RequestContext로부터 사용자 신원(User 객체)을 추출하는 로직을 정의합니다. 이를 통해 시스템은 사용자의 identity와 group memberships를 명확히 인지합니다.
* User-Aware Tools: Agent가 호출하는 모든 Tool은 ToolContext를 통해 현재 사용자의 정보를 자동으로 받습니다. 예를 들어, SQL 실행을 담당하는 RunSqlTool은 사용자의 권한(group memberships)을 기반으로 row-level security를 자동 적용하여 해당 사용자가 접근할 수 있는 데이터만 쿼리 결과에 포함하도록 필터링합니다. 사용자 정의 Tool 또한 access_groups 속성을 통해 접근 권한을 정의하고, execute 메서드 내에서 user 정보를 활용할 수 있습니다.
* Enterprise Security Features: User-awareness는 audit logs(사용자별 쿼리 추적), rate limiting(사용자별 쿼터 관리), content filtering 등 다양한 보안 기능의 기반이 됩니다.

Streaming Responses:

* Agent는 쿼리 실행 및 데이터 처리 결과를 Streaming Components 형태로 Web Component로 실시간 스트리밍합니다. 여기에는 Progress Updates, SQL Code Block(관리자에게만 표시 가능), Interactive Data Table, Charts(Plotly 기반 시각화), 그리고 Natural Language Summary가 포함됩니다. 이는 Server-Sent Events (SSE)를 통해 이루어집니다.

Extensible But Opinionated:

* Custom Tools: 개발자는 Tool 클래스를 상속받아 비즈니스 로직에 맞는 새로운 Tool을 정의하고 Agent에 등록할 수 있습니다. 각 Tool은 pydantic 기반의 args_schema를 정의하여 LLM이 호출할 때 필요한 인자를 명확히 합니다. access_groups 속성을 통해 Tool의 접근 권한도 설정할 수 있습니다.
* Lifecycle Hooks: 요청 처리 과정의 특정 지점(예: 쿼터 확인, 커스텀 로깅, 콘텐츠 필터링)에 사용자 정의 로직을 삽입할 수 있는 hooks를 제공합니다.
* LLM Middlewares: LLM 호출 전후에 캐싱, 프롬프트 엔지니어링, 비용 추적 등을 구현할 수 있는 middleware 계층을 지원합니다.
* Observability: 내장된 tracing 및 metrics 통합을 통해 시스템의 동작을 모니터링할 수 있습니다.

아키텍처 흐름 요약:

User는 Web Component($<vanna-chat>$)를 통해 자연어 질문을 합니다. 이 질문은 인증 정보와 함께 Your Server로 POST 요청됩니다. Your Server는 User Resolver를 통해 사용자(User)를 식별하고, 이 정보를 Agent에게 전달합니다. Agent는 식별된 사용자 정보를 바탕으로 Tools(예: RunSqlTool)를 호출하여 SQL 쿼리를 생성하고 실행합니다. 이때 Tools는 사용자의 권한에 따라 row-level security를 적용하여 데이터 접근을 제어합니다. 최종적으로 Agent는 처리된 결과(Table, Chart, Summary)를 Web Component로 스트리밍하고, Web Component는 이를 사용자에게 beautiful UI로 표시합니다.

Vanna 2.0은 이러한 agent-based 및 user-aware 설계를 통해 다양한 LLM 및 Database와 호환되며, 기존 인증 시스템과 쉽게 통합되어 데이터 분석 애플리케이션, 멀티테넌트 SaaS, 또는 엔터프라이즈 환경에서의 natural language interface 구축에 적합합니다.