GitHub - CausalInferenceLab/Lang2SQL

Lang2SQL은 자연어 쿼리를 최적화된 SQL 문으로 변환하는 오픈소스 도구입니다. 이 프로젝트는 데이터베이스 스키마에 대한 깊은 지식 없이도 사용자가 효율적으로 SQL 쿼리를 생성하고 데이터 인사이트를 얻을 수 있도록 지원하는 것을 목표로 합니다.

Lang2SQL이 해결하고자 하는 주요 문제는 다음과 같습니다: 방대한 테이블 속에서 필요한 정보를 찾기 어려운 점, 복잡한 JOIN 문의 작성 어려움, 쿼리 성능 최적화의 난해함, 그리고 의미 있는 인사이트 추출의 어려움입니다. Lang2SQL은 자연어 입력을 통해 테이블을 추천하고, 적절한 컬럼 조합으로 SQL을 자동 생성하며, 모범 사례 기반으로 성능을 최적화하여 이러한 문제들을 해결합니다.

주요 기능:
* 자연어를 SQL로 변환: 일상 언어를 정확한 SQL 쿼리로 변환합니다.
* 스마트 테이블 발견: 의미론적 검색(semantic search)을 사용하여 사용자 질의와 관련된 테이블을 자동으로 찾아냅니다.
* 스키마 인식: DataHub 메타데이터를 활용하여 정확한 컬럼 매핑을 수행합니다.
* 웹 인터페이스: Streamlit 기반의 대화형 웹 애플리케이션을 제공하여 편리한 사용 환경을 제공합니다.
* 시각화: 생성된 SQL 쿼리 실행 결과를 다양한 차트와 그래프로 시각화하여 데이터 인사이트를 직관적으로 파악할 수 있도록 돕습니다.
* 유연한 VectorDB: 로컬에서 사용할 수 있는 FAISS와 PostgreSQL 기반의 pgvector를 벡터 데이터베이스로 선택하여 사용할 수 있습니다.

핵심 방법론 (아키텍처):
Lang2SQL은 LangGraph를 활용한 다단계(multi-stage) 접근 방식을 따릅니다.

자연어 처리 (Natural Language Processing): 사용자 질의의 의도를 파싱하고 핵심 엔티티(예: 테이블, 컬럼, 필터 조건 등)를 추출합니다. 이는 사용자의 질문이 어떤 데이터에 대한 어떤 종류의 작업을 요구하는지 이해하는 첫 단계입니다.

테이블 검색 (Table Discovery): 추출된 핵심 엔티티와 사용자 질의의 의미론적 유사성을 기반으로 관련성이 높은 테이블을 찾아냅니다. 이 과정은 벡터 검색(Vector Search)을 통해 이루어지며, DataHub에서 수집된 테이블 및 컬럼 메타데이터가 벡터 형태로 저장된 VectorDB(FAISS 또는 pgvector)에서 질의 벡터와의 유사도를 계산하여 관련 테이블을 검색합니다. 이 단계에서 __INLINE_FORMULA_0__개의 최상위(top-N) 관련 테이블을 선택하여 다음 단계의 컨텍스트로 활용할 수 있습니다.

SQL 생성 (SQL Generation): 자연어 처리 단계에서 파싱된 의도, 테이블 검색 단계에서 발견된 관련 테이블 및 DataHub를 통해 얻은 스키마 정보(컬럼, 관계 등)를 종합하여 최적화된 SQL 쿼리를 생성합니다. 이 과정에서 LangGraph의 QUERY_MAKER 노드가 주요 역할을 수행하며, 적절한 컬럼 조합, JOIN 조건, 필터링 및 집계 함수 등을 포함한 완전한 SQL 문을 만듭니다. PROFILE_EXTRACTION (질의에서 추가 정보 추출) 및 CONTEXT_ENRICHMENT (추출된 정보를 기반으로 컨텍스트 보강)와 같은 추가 단계를 통해 SQL 생성의 정확도와 품질을 향상시킬 수 있습니다.

쿼리 시각화 (Query Visualization): 생성된 SQL 쿼리를 데이터베이스에 실행한 후, 그 결과를 Streamlit 웹 인터페이스를 통해 다양한 시각화 차트(예: 바 차트, 라인 차트 등)로 표현하여 사용자가 데이터 인사이트를 쉽게 파악할 수 있도록 돕습니다.

기술 스택:
* LangGraph: LLM(Large Language Model) 기반의 복잡한 워크플로우를 오케스트레이션합니다.
* DataHub: 데이터 메타데이터(스키마, 설명, 계보 등)를 관리하고 SQL 생성 과정에 필요한 컨텍스트를 제공합니다.
* Streamlit: 대화형 웹 인터페이스를 구축하여 사용자에게 직관적인 경험을 제공합니다.

설치 및 사용법:
pip 또는 uv를 통해 lang2sql 패키지를 설치할 수 있습니다.
* 웹 인터페이스 실행: lang2sql run-streamlit 명령어를 사용합니다. VectorDB 및 DataHub 설정은 UI의 "설정 > 데이터 소스" 탭에서 관리됩니다.
* 명령줄 쿼리 실행: lang2sql query "질문" 명령어를 사용하며, --database-env, --vectordb-type, --vectordb-location 등 다양한 옵션을 지정하여 데이터베이스 환경, 벡터 데이터베이스 유형 및 위치를 제어할 수 있습니다.

기여 및 확장:
프로젝트는 Containerization, Agentic 아키텍처 개발, DataHub 통합 강화, VectorDB 유연성 개선, 모니터링/로깅 강화, 문서화 강화, 그리고 LLM 호출을 백엔드 API로 분리하여 보안과 관리를 중앙화하는 등 다양한 영역에서 커뮤니티의 기여를 환영합니다.

Lang2SQL은 가짜연구소의 인과추론팀에서 개발 중인 오픈소스 프로젝트이며, MIT 라이선스를 따릅니다.