핵심 아이디어: Vanna는 현재 AI 기반 SQL 어시스턴트를 구축하기 위해 가장 많이 사용되는 오픈 소스 (Open Source) 프레임워크 중 하나입니다. 두 단계로 작동합니다: 먼저 사용자의 스키마 (Schema), 문서, 그리고 과거의 실제 SQL 쿼리들을 사용하여 AI 모델(또는 벡터 인덱스 (Vector Index))을 학습시킨 다음, 매우 정밀한 정확도로 코드를 생성합니다.

장점: Snowflake, BigQuery, PostgreSQL 및 MySQL에 네이티브로 연결됩니다. Slack 또는 웹 애플리케이션에서 즉시 사용할 수 있는 그래픽 인터페이스를 포함하고 있습니다.

2.0 버전의 새로운 기능

• 모든 수준에서의 사용자 주의: 쿼리가 사용자의 권한에 따라 자동으로 필터링됩니다.
• 현대적인 웹 인터페이스 <vanna-chat>: 매우 아름답게 사전 설계된 컴포넌트입니다.
• 실시간 응답: 테이블, 차트 및 실시간 진행 상황 업데이트를 제공합니다.
• 엔터프라이즈 보안: 행 수준 보안 (RLS, Row-Level Security), 감사 로그 (Audit Logs) 및 속도 제한 (Rate Limiting)을 지원합니다.
• 프로덕션 준비 완료: FastAPI 통합, 관찰 가능성 (Observability) 및 라이프사이클 훅 (Lifecycle Hooks)을 지원합니다.

어떻게 작동하나요? (핵심 개념)

1. 사용자 리졸버 (User Resolver): 요청에서 사용자의 신원(쿠키, JWT 등)을 추출하는 방법을 정의합니다.
2. 사용자 인식 도구 (User-aware Tools): 도구가 사용자의 그룹 소속에 따라 권한을 자동으로 확인합니다.
3. 스트리밍 컴포넌트 (Streaming Components): 백엔드는 구조화된 사용자 인터페이스 컴포넌트(테이블, 차트)를 프론트엔드로 실시간으로 스트리밍합니다.
4. 통합 웹 사용자 인터페이스: 사전 정의된 <vanna-chat> 컴포넌트가 모든 것을 완벽하게 렌더링합니다.

코드 예시 (인증을 포함한 프로덕션 설정)

다음은 Vanna를 기존 FastAPI 애플리케이션 및 인증 시스템과 통합하는 전체 예시입니다:

1. 백엔드 (Python + FastAPI):

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

FastAPI 앱 정의

app = FastAPI()

1. 사용자 리졸버(UserResolver) 정의 (자체 인증 시스템 사용)

class MyUserResolver(UserResolver):
async def resolve_user(self, request_context: RequestContext) -> User:
# 쿠키, JWT 또는 세션에서 추출
token = request_context.get_header('Authorization')
user_data = self.decode_jwt(token) # 기존 로직 사용

    return User(
        id=user_data['id'],
        email=user_data['email'],
        # ... 필요한 다른 필드 추가
    )

2. 도구(Tool)를 사용하여 에이전트 구성

llm = AnthropicLlmService(model="claude-3-5-sonnet")
tools = ToolRegistry()
tools.register(RunSqlTool(sql_runner=SqliteRunner("./data.db")))

agent = Agent(
llm_service=llm,
tool_registry=tools,
user_resolver=MyUserResolver()
)

3. Vanna 라우트를 애플리케이션에 추가

chat_handler = ChatHandler(agent)
register_chat_routes(app, chat_handler)

이제 다음 엔드포인트가 준비되었습니다: POST /api/vanna/v2/chat_sse (스트리밍)

• 스트리밍 진행 상황 업데이트.
• SQL 코드 블록 ("admin" 사용자에게만 기본적으로 표시됨).
• 대화형 데이터 테이블.
• 차트 (Plotly 시각화).
• 자연어 요약.

커스텀 도구 (Custom Tools)
비즈니스 사용 사례에 맞는 특정 도구로 Vanna를 확장할 수 있습니다 (예: 결과와 함께 자동 이메일 전송):

Python

from vanna.core.tool import Tool, ToolContext, ToolResult
from pydantic import BaseModel, Field
from typing import Type

class EmailArgs(BaseModel):
    recipient: str = Field(description="이메일 수신자")
    subject: str = Field(description="이메일 제목")

class EmailTool(Tool[EmailArgs]):
    @property
    def name(self) -> str:
        return "send_email"

@property
def access_groups(self) -> list[str]:
    return ["send_email"]  # 권한 확인
...

커스텀 도구 등록

tools.register(EmailTool())

고급 기능 및 사용 사례

- Vanna 2.0은 프로덕션 환경을 위한 강력한 엔터프라이즈 기능을 포함합니다:
- 라이프사이클 훅 (Lifecycle Hooks): 할당량 확인, 커스텀 로깅 및 콘텐츠 필터링을 추가합니다.
- LLM 미들웨어 (Middlewares): 캐싱 저장소, 프롬프트 엔지니어링 (Prompt Engineering) 또는 비용 추적을 구현합니다.
- 대화 저장소 (Conversation Storage): 사용자별 대화 기록을 저장하고 검색합니다.

어떤 사례에 이상적인가요?

- 자연어 인터페이스를 갖춘 데이터 분석 애플리케이션.
- 사용자 인식 권한(행 수준 보안, Row-level Security)이 필요한 멀티테넌트 SaaS.
- 엄격한 보안 및 감사(Audit) 요구 사항이 있는 엔터프라이즈 애플리케이션.

### 아키텍처 흐름 (시퀀스 다이어그램)

다음 흐름은 사용자가 질문을 던진 시점부터 시각적 컴포넌트가 렌더링될 때까지 Vanna 2.0에서의 요청 라이프사이클을 상세히 설명합니다:

-   **단계 1:** 사용자가 `<vanna-chat>` 컴포넌트에 _"Show Q4 sales"_와 같은 질문을 입력합니다.
-   **단계 2:** 프론트엔드(Frontend)가 인증 자격 증명을 첨부하여 귀하의 FastAPI 서버에 있는 `/api/vanna/v2/chat_sse` 엔드포인트로 `POST` 요청을 보냅니다.
-   **단계 3:** 귀하의 서버는 사용자의 신원(예: Alice)과 액세스 그룹(`read_sales`)을 확인하여 에이전트(Agent)에게 전달합니다.
-   **단계 4:** 에이전트가 SQL 실행 도구(_User-Aware Tool_)를 호출합니다.
-   **단계 5:** 도구는 사용자의 그룹에 따라 행 수준 보안(RLS, Row-Level Security) 규칙을 자동으로 적용합니다.
-   **단계 6:** 데이터베이스는 필터링되고 권한이 부여된 결과만을 에이전트에게 반환합니다.
-   **단계 7:** 에이전트는 구조화된 블록(표 → 차트 → 요약) 형태로 응답을 스트리밍(_streams_)하여 웹 컴포넌트로 다시 전달하며, 컴포넌트는 이를 화면에 미학적으로 그려냅니다.

## 빠른 비교

| 접근 방식 | 복잡도 | 적합한 용도 | 주요 도구 |
| --- | --- | --- | --- |
| **1. LLM + 순수 Python** | 낮음 | 빠른 프로토타입, 내부 스크립트 | OpenAI API, sqlite3 |
| ... | |

## 결론 및 권장 사항

-   **AI가 생성한 SQL을 검증 없이 절대 실행하지 마세요.** 허용된 작업 목록(예: `SELECT`만 허용)을 사용하고, 읽기 전용 권한을 가진 화이트리스트 데이터베이스 사용자를 활용하세요.
-   **스키마(Schema) 컨텍스트가 핵심입니다.** 모델에 제공하는 스키마가 명확하고 완전할수록 생성되는 SQL의 품질이 향상됩니다.
-   **에이전트는 다단계 작업(Multi-step tasks)에서 빛을 발하지만**, 단순 호출보다 더 많은 토큰과 지연 시간(Latency)이 소요됩니다.
-   **Streamlit은 프로토타입을 비기술 사용자에게 전달하는 가장 빠른 방법입니다.** 귀하의 팀에서 이러한 접근 방식 중 하나를 시도해 보셨나요? 어떤 스택을 사용했는지, 그리고 LLM을 실제 데이터베이스와 연결할 때 어떤 문제에 직면했는지 댓글로 알려주세요.

## 커뮤니티 및 지원 (Vanna Ecosystem)

Vanna AI를 사용하여 기업용 에이전트 (Enterprise Agents) 구현을 선택하기로 결정했다면, 고급 통합 (Advanced Integration) 관련 궁금증을 해결할 수 있는 공식 채널 바로가기는 다음과 같습니다:

**전체 문서 (Full Documentation)** — Vanna API에 대한 완전한 가이드 및 상세 참조 자료.
**GitHub 토론 포럼 (GitHub Discussion Forums)** — 새로운 기능 제안, 확장 기능, 커뮤니티 Q&A를 위한 공간.
**GitHub 이슈 (GitHub Issues)** — 버그 리포트, 커넥터 오류 및 패치 추적.
**기업용 지원 (Enterprise Support)** — `support@vanna.ai`를 통한 직접적인 기술 지원.

_이 포스트는 교육 및 개발자 커뮤니티의 참조를 목적으로 공개된 소스의 예시를 수집하고 편집하였습니다._

공식 퀵스타트 예시: GitHub - vanna-ai/vanna-boilerplate (이 리포지토리는 Flask, Streamlit 또는 FastAPI를 사용하여 바로 클론(Clone)할 수 있는 템플릿을 포함하고 있어, 처음부터 시작하지 않아도 되므로 매우 유용합니다).

공식 프론트엔드 컴포넌트 (): GitHub - vanna-ai/vanna-components (다이어그램에서 보았던 그래픽 사용자 인터페이스(GUI) 웹 컴포넌트의 소스 코드로, 디자인이나 동작을 수정하고 싶을 때 사용합니다).

데이터베이스별 예시가 포함된 Jupyter Notebook: 동일한 GitHub 조직 내에 특정 설정에 대한 단계별 Notebook 형식 가이드가 있습니다:

Snowflake 연결 및 지침 설정: Vanna Snowflake Notebook
BigQuery 연결 및 지침 설정: Vanna BigQuery Notebook
SQLite를 이용한 로컬 환경 설정: Vanna SQLite Notebook