Vanna: Your AI Business Intelligence Assistant

Vanna란 무엇인가

Vanna는 파이썬 프레임워크와 호스팅 서비스로 이루어진다. 사람에게 묻듯 질문을 입력하면 쿼리, 표, 차트, 몇 줄짜리 요약이 한 번에 돌아온다. 프로젝트는 2023년 검색 증강 방식을 쓰는 text-to-SQL 라이브러리로 출발했고 GitHub 별이 2만 개를 넘었다. 2025년 11월에 나온 2.0 버전은 구조를 통째로 다시 짜서 권한 관리, 스트리밍 응답, 기존 사이트에 붙일 수 있는 채팅 UI를 갖춘 에이전트 프레임워크로 바뀌었다.

겨냥하는 문제는 기다림이다. 마케팅 담당자가 지난 분기 해지율을 요금제별로 보고 싶어 하는데 데이터 팀은 밀려 있고, 요청은 티켓 대기열에서 사흘을 보낸다. Vanna는 그 담당자 앞에 데이터 웨어하우스와 연결된 채팅창을 놓는다. 답할 수 있는 것은 답하고, 실행한 SQL을 보여주며, 관리자가 로직을 확인할 수 있게 한다.

도입 전에 짚어야 할 제약은 두 가지다. Vanna는 엔지니어용 도구다. 설치하고, 데이터베이스 드라이버를 설정하고, 모델을 고르고, 사용자를 어떻게 식별할지 직접 정해야 한다. 끌어다 놓는 화면은 없다. 또 SQL 품질은 에이전트가 배운 양에 달려 있어서, 큰 스키마에 바로 붙이면 한동안 손이 필요하다. 반나절이 아니라 일주일을 잡아야 한다.

시작하기

1. 가상 환경을 만들고 필요한 확장과 함께 패키지를 설치한다. 예를 들면 pip install 'vanna[anthropic,fastapi]'. 파이썬 3.9 이상이 필요하다.
2. 데이터베이스와 모델을 연결한다. PostgreSQL, MySQL, Snowflake, BigQuery, SQLite, Oracle, SQL Server, DuckDB, ClickHouse를 공식 지원하고, 모델 쪽은 OpenAI, Anthropic, Gemini, Azure, Bedrock, Mistral과 Ollama를 통한 로컬 모델을 쓸 수 있다.
3. 사용자를 어떻게 알아볼지 정한다. 요청에 담긴 쿠키, JWT, OAuth 토큰을 읽어 사용자 아이디와 권한 그룹 목록으로 바꾸는 리졸버를 작성한다.
4. 에이전트가 호출할 도구를 등록한다. 쿼리는 RunSqlTool이 맡고, 직접 만든 도구는 Tool 클래스를 상속해 추가한다. 메일 발송이나 사내 API 호출이 대표적이다.
5. 채팅을 페이지에 올린다. <vanna-chat> 컴포넌트를 아무 페이지에나 넣고 서버의 스트리밍 엔드포인트를 가리키게 한다. React, Vue, 순수 HTML 모두 동작한다.
6. 지켜보고 손본다. 첫 며칠은 감사 로그를 읽고 권한 그룹을 고치고, 질문과 SQL 쌍이 메모리에 쌓이도록 둔다. 반복되는 조회는 이렇게 자리를 잡는다.