From 67082a2b0701f1110070fe96ac9c22a4a99e7ff8 Mon Sep 17 00:00:00 2001 From: seyeong Date: Sun, 15 Mar 2026 16:30:23 +0900 Subject: [PATCH] =?UTF-8?q?docs(readme):=20v2=20=EC=95=84=ED=82=A4?= =?UTF-8?q?=ED=85=8D=EC=B2=98=EC=97=90=20=EB=A7=9E=EA=B2=8C=20README=20?= =?UTF-8?q?=EC=A0=84=EB=A9=B4=20=EA=B0=9C=ED=8E=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 프로젝트 소개를 v2 모듈러 아키텍처(define-by-run) 기반으로 변경 - Python API 빠른 시작 예시(BaselineNL2SQL) 추가 - 파이프라인 선택 가이드 테이블 추가 - deprecated CLI 옵션 제거 (--database-env, --retriever-name 등) - 현재 CLI 옵션으로 교체 (--flow, --dialect, --top-n, --no-gate) - Graph Builder 섹션 제거 (더 이상 존재하지 않음) - v2 아키텍처 디렉토리 구조 및 설계 원칙 추가 - 지원 환경 섹션 추가 (LLM 7개, DB 12개, VectorDB 3개) - 기여 가이드를 프로젝트 컨벤션에 맞게 수정 (uv sync, 브랜치 네이밍) - 레거시 "기여가 필요한 영역" 섹션 제거 Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 334 +++++++++++++++++++++++++++++------------------------- 1 file changed, 177 insertions(+), 157 deletions(-) diff --git a/README.md b/README.md index be7326e..e0e2d00 100644 --- a/README.md +++ b/README.md @@ -25,16 +25,16 @@ ## 🚀 Lang2SQL이란? -Lang2SQL은 자연어 쿼리를 최적화된 SQL 문으로 변환하는 오픈소스 도구입니다. LangGraph와 DataHub 통합으로 구축되어, 복잡한 데이터베이스 스키마에 대한 깊은 지식 없이도 데이터 사용자들이 효율적인 SQL 쿼리를 생성할 수 있도록 도와줍니다. +Lang2SQL은 자연어를 SQL로 변환하는 오픈소스 도구입니다. **define-by-run** 철학에 기반한 모듈러 아키텍처로, 복잡한 데이터베이스 스키마에 대한 깊은 지식 없이도 효율적인 SQL 쿼리를 생성할 수 있도록 도와줍니다. ### 🎯 주요 기능 - **🗣️ 자연어를 SQL로 변환**: 일상 언어를 정확한 SQL 쿼리로 변환 -- **📊 스마트 테이블 발견**: 의미론적 검색을 사용하여 관련 테이블을 자동으로 찾기 -- **🔍 스키마 인식**: DataHub 메타데이터를 활용한 정확한 컬럼 매핑 -- **🛠️ 웹 인터페이스**: 대화형 Streamlit 앱을 통한 사용 -- **📈 시각화**: 생성된 SQL 쿼리 결과를 다양한 차트와 그래프로 시각화하여 데이터 인사이트를 직관적으로 파악 -- **🗄️ 유연한 VectorDB**: FAISS(로컬)와 pgvector(PostgreSQL) 중 선택 가능한 벡터 데이터베이스 지원 +- **📊 스마트 테이블 발견**: BM25 키워드 검색과 벡터 유사도 검색을 결합한 하이브리드 검색 +- **🔌 Port 기반 확장**: LLM, DB, 임베딩, 벡터스토어를 Protocol 인터페이스로 자유롭게 교체 +- **🛠️ 웹 인터페이스**: Streamlit 기반 대화형 앱 (쿼리 생성 + 챗봇) +- **📈 시각화**: SQL 쿼리 결과를 차트와 그래프로 시각화 +- **🗄️ 유연한 VectorDB**: InMemory, FAISS(로컬), pgvector(PostgreSQL) 중 선택 ### 🤔 해결하는 문제 @@ -59,7 +59,7 @@ Lang2SQL은 자연어 쿼리를 최적화된 SQL 문으로 변환하는 오픈 # pip pip install lang2sql -# uv +# uv (권장) uv venv --python 3.11 source .venv/bin/activate uv add lang2sql @@ -68,17 +68,15 @@ uv add lang2sql ### 소스에서 설치 ```bash -# 소스 클론 git clone https://github.com/CausalInferenceLab/lang2sql.git cd lang2sql -# (권장) uv 사용 -# uv 설치가 되어 있다면 아래 두 줄로 개발 모드 설치 +# uv (권장) uv venv --python 3.11 source .venv/bin/activate -uv pip install -e . +uv sync -# (대안) pip 사용 +# pip python -m venv .venv source .venv/bin/activate pip install -e . @@ -86,174 +84,214 @@ pip install -e . --- -## 🛠️ 사용법 - -### 명령줄 인터페이스 - -Streamlit 웹 인터페이스 실행: - -```bash -lang2sql run-streamlit -``` - -사용자 정의 포트로 실행: - -```bash -lang2sql run-streamlit -p 8888 +## ⚡ 빠른 시작 (Python API) + +```python +from lang2sql import BaselineNL2SQL +from lang2sql.integrations.db import SQLAlchemyDB +from lang2sql.integrations.llm import OpenAILLM + +catalog = [ + { + "name": "orders", + "description": "고객 주문 정보", + "columns": { + "order_id": "주문 고유 ID", + "customer_id": "고객 ID", + "order_date": "주문 일시", + "amount": "주문 금액", + "status": "주문 상태", + }, + }, + { + "name": "customers", + "description": "고객 마스터", + "columns": { + "customer_id": "고객 ID", + "name": "고객 이름", + "grade": "고객 등급: bronze / silver / gold", + }, + }, +] + +pipeline = BaselineNL2SQL( + catalog=catalog, + llm=OpenAILLM(model="gpt-4o-mini"), + db=SQLAlchemyDB("sqlite:///sample.db"), + db_dialect="sqlite", +) + +rows = pipeline.run("지난달 주문 건수를 알려줘") +print(rows) ``` -**참고**: -- Streamlit 서버는 `0.0.0.0` 으로 바인딩되어 외부에서 접속 가능합니다. -- `--datahub_server` 옵션은 더 이상 사용되지 않습니다(deprecated). DataHub 설정은 UI의 설정 > 데이터 소스 탭에서 관리하세요. +### 파이프라인 선택 가이드 -### Graph Builder 페이지 +| 파이프라인 | 검색 방식 | 적합한 상황 | +|---|---|---| +| `BaselineNL2SQL` | BM25 키워드 | 빠른 시작, 카탈로그 규모 소~중간 | +| `HybridNL2SQL` | BM25 + Vector | 검색 품질 우선, 비즈니스 문서 활용 | +| `EnrichedNL2SQL` | BM25 + Vector + Gate | 운영 환경, 부적합 질문 필터링 필요 | -Streamlit 앱은 멀티 페이지 구조입니다. 좌측 네비게이션에서 "Graph Builder" 페이지를 열어 LangGraph 워크플로우를 구성할 수 있습니다. +더 자세한 내용은 [튜토리얼](docs/tutorials/01-quickstart.md)을 참고하세요. -- 프리셋 선택: "기본" 또는 "확장" -- 커스텀 옵션: `PROFILE_EXTRACTION`, `CONTEXT_ENRICHMENT`, `QUERY_MAKER` 포함 여부 토글 -- 선택이 바뀌면 그래프가 즉시 컴파일되어 세션에 적용됩니다 -- "세션 그래프 새로고침" 버튼으로 수동 재적용 가능 -- `QUERY_MAKER`를 비활성화하면 테이블 검색 정보만 표시됩니다 - -### VectorDB 선택 +--- -**참고**: CLI 레벨의 `--vectordb-type` 및 `--vectordb-location` 옵션은 더 이상 사용되지 않습니다(deprecated). Streamlit 실행 시 VectorDB 설정은 UI의 설정 > 데이터 소스 탭에서 관리하세요. +## 🛠️ 사용법 -`query` 명령어에서는 VectorDB 옵션을 사용할 수 있습니다: +### CLI ```bash -# FAISS 사용 (기본값) -lang2sql query "질문" --vectordb-type faiss +# Streamlit 웹 인터페이스 실행 +lang2sql run-streamlit +lang2sql run-streamlit -p 8888 # 포트 지정 -# pgvector 사용 -lang2sql query "질문" --vectordb-type pgvector +# 자연어 쿼리 실행 +lang2sql query "지난달 주문 건수를 집계해줘" -# 위치 지정 예시 -# FAISS: 인덱스 디렉토리 경로 지정 -lang2sql query "질문" --vectordb-type faiss --vectordb-location ./dev/table_info_db +# enriched 플로우 (질문 검증 + 프로파일링 + 컨텍스트 보강) +lang2sql query "이번 달 순매출 합계" --flow enriched --dialect sqlite --top-n 5 -# pgvector: 연결 문자열 지정 -lang2sql query "질문" --vectordb-type pgvector --vectordb-location "postgresql://user:pass@host:5432/db" +# QuestionGate 비활성화 (enriched 전용) +lang2sql query "이번 달 순매출 합계" --flow enriched --no-gate ``` -참고: DataHub 없이도 미리 준비된 VectorDB(FAISS 디렉토리 혹은 pgvector 컬렉션)를 바로 사용할 수 있습니다. 자세한 준비 방법은 [DataHub 없이 시작하기](docs/tutorials/getting-started-without-datahub.md)를 참고하세요. - -### 처음 시작하기 (DataHub 없이) +**CLI 옵션:** -튜토리얼 본문이 길어져 별도 문서로 분리되었습니다. 아래 문서를 참고하세요. +| 옵션 | 기본값 | 설명 | +|------|--------|------| +| `--flow` | `baseline` | `baseline` 또는 `enriched` | +| `--dialect` | `None` | SQL 방언 (sqlite, postgresql, mysql, bigquery, duckdb) | +| `--top-n` | `5` | 검색할 최대 테이블 수 | +| `--no-gate` | `False` | QuestionGate 비활성화 (enriched 전용) | -- [DataHub 없이 시작하기 튜토리얼](docs/tutorials/getting-started-without-datahub.md) +> CLI는 `.env` 파일의 환경변수(`LLM_PROVIDER`, `DB_TYPE` 등)를 읽어 동작합니다. `.env.example`을 참고하세요. -### 자연어 쿼리 실행 +### Streamlit 웹 UI -```bash -# 기본 사용 (FAISS, clickhouse, 기본 검색기) -lang2sql query "고객 데이터를 기반으로 유니크한 유저 수를 카운트하는 쿼리" - -# 옵션 사용 예시 -lang2sql query "고객 데이터를 기반으로 유니크한 유저 수를 카운트하는 쿼리" \ - --database-env clickhouse \ - --retriever-name 기본 \ - --top-n 5 \ - --device cpu \ - --use-enriched-graph \ - --vectordb-type faiss \ - --vectordb-location ./dev/table_info_db - -# pgvector 사용 예시 -lang2sql query "고객 데이터를 기반으로 유니크한 유저 수를 카운트하는 쿼리" \ - --vectordb-type pgvector \ - --vectordb-location "postgresql://postgres:postgres@localhost:5432/postgres" -``` +Streamlit 앱은 멀티 페이지 구조입니다: -**주요 옵션 설명:** -- `--database-env`: 사용할 데이터베이스 환경 (기본값: clickhouse) -- `--retriever-name`: 테이블 검색기 이름 (기본값: 기본) -- `--top-n`: 검색된 상위 테이블 수 제한 (기본값: 5) -- `--device`: LLM 실행에 사용할 디바이스 (기본값: cpu) -- `--use-enriched-graph`: 확장된 그래프(프로파일 추출 + 컨텍스트 보강) 사용 여부 -- `--vectordb-type`: 벡터 데이터베이스 타입 ("faiss" 또는 "pgvector", 기본값: faiss) -- `--vectordb-location`: VectorDB 위치 (FAISS: 디렉토리 경로, pgvector: 연결 문자열) +- **🏠 홈** — 프로젝트 소개 +- **🔍 Lang2SQL** — 자연어 쿼리 → SQL 생성 및 실행 +- **🤖 ChatBot** — 멀티턴 대화 기반 SQL 생성 +- **⚙️ 설정** — LLM, DB, 임베딩, 데이터 소스 설정 -### 환경 설정 - -- `.env` 파일을 생성하여 설정을 관리합니다. (예시 파일이 있다면 참조) -- 또는 CLI 옵션으로 환경을 지정할 수 있습니다: - - `--env-file-path`: 환경 변수 파일 경로 지정 - - `--prompt-dir-path`: 프롬프트 템플릿(.md) 디렉토리 지정 - - `--datahub_server`: [Deprecated] DataHub GMS 서버 URL 지정. 이제는 UI의 설정 > 데이터 소스 탭에서 관리하세요. - -## 🏗️ 아키텍처 +### 처음 시작하기 -Lang2SQL은 LangGraph를 사용한 다단계 접근 방식을 따릅니다: +튜토리얼은 난이도 순서로 구성되어 있습니다. -1. **📝 자연어 처리**: 사용자 의도 파싱 및 핵심 엔티티 추출 -2. **🔍 테이블 검색**: 의미론적 유사성을 사용한 관련 테이블 찾기 (Vector Search) -3. **⚙️ SQL 생성**: 최적화된 SQL 쿼리 생성 -4. **🚀 쿼리 시각화**: 쿼리 결과를 시각화 합니다. +| 번호 | 문서 | 내용 | +|------|------|------| +| 01 | [빠른 시작](docs/tutorials/01-quickstart.md) | 5분 안에 NL2SQL 실행 | +| 02 | [Baseline 파이프라인](docs/tutorials/02-baseline.md) | 실제 DB 연결, DB Explorer, Factory 함수 | +| 03 | [벡터 검색](docs/tutorials/03-vector-search.md) | FAISS/pgvector 인덱싱 | +| 04 | [하이브리드 검색](docs/tutorials/04-hybrid.md) | BM25 + Vector, EnrichedNL2SQL | +| 05 | [고급](docs/tutorials/05-advanced.md) | 수동 조합, 커스텀 어댑터, Port 레퍼런스, Hook | --- -## 🧑‍💻 기술 스택 +## 🏗️ 아키텍처 -- **[LangGraph](https://github.com/langchain-ai/langgraph)**: LLM 워크플로우 오케스트레이션 -- **[DataHub](https://datahubproject.io/)**: 메타데이터 관리 및 활용 -- **[Streamlit](https://streamlit.io/)**: 대화형 웹 인터페이스 +Lang2SQL v2는 **define-by-run** 철학을 따르는 모듈러 아키텍처입니다. 파이프라인 제어는 프레임워크 DSL이 아닌 순수 Python 코드로 작성합니다. ---- +``` +src/lang2sql/ +├── core/ # 외부 의존성 0% — 절대 third-party import 금지 +│ ├── base.py # BaseComponent, BaseFlow +│ ├── catalog.py # CatalogEntry, TextDocument, IndexedChunk +│ ├── ports.py # LLMPort, DBPort, EmbeddingPort 등 Protocol 인터페이스 +│ ├── hooks.py # TraceHook, MemoryHook (관측성) +│ └── exceptions.py +│ +├── components/ # 재사용 가능한 부품 +│ ├── retrieval/ # KeywordRetriever, VectorRetriever, HybridRetriever +│ ├── generation/ # SQLGenerator (dialect별 프롬프트) +│ ├── execution/ # SQLExecutor +│ ├── gate/ # QuestionGate, TableSuitabilityEvaluator +│ ├── enrichment/ # QuestionProfiler, ContextEnricher +│ └── loaders/ # MarkdownLoader, PlainTextLoader, DirectoryLoader +│ +├── flows/ # 프리셋 파이프라인 +│ ├── nl2sql.py # BaselineNL2SQL (Keyword → SQL → Execute) +│ ├── hybrid.py # HybridNL2SQL (BM25 + Vector) +│ └── enriched_nl2sql.py # EnrichedNL2SQL (Gate + Profile + Enrich) +│ +└── integrations/ # 외부 의존성 구현체 + ├── llm/ # OpenAI, Anthropic, Azure, Gemini, Bedrock, Ollama, HuggingFace + ├── embedding/ # OpenAI, Azure, Gemini, Bedrock, Ollama, HuggingFace + ├── db/ # SQLAlchemyDB, SQLAlchemyExplorer + ├── vectorstore/ # InMemory, FAISS, pgvector + ├── catalog/ # DataHubCatalogLoader + ├── loaders/ # PDFLoader + └── chunking/ # SemanticChunker +``` -## 🌟 기여가 필요한 영역 (Help!) +### 설계 원칙 -### Containerization +- **`core/`는 외부 의존성 0%**: 모든 third-party 연동은 `integrations/`에서 구현 +- **Port Protocol**: `LLMPort`, `DBPort`, `EmbeddingPort` 등 메서드 시그니처만 맞추면 어떤 구현체든 연결 가능 +- **Hook 기반 관측성**: `MemoryHook`으로 컴포넌트별 실행 시간, 에러를 추적 -- Docker를 활용하여 프로젝트를 컨테이너화하고, `pip install lang2sql` 설치 후 단일 명령어로 실행 가능하도록 개선합니다. -- CI/CD 파이프라인 구축 및 자동화된 테스트 환경 구성까지 확장할 수 있는 작업입니다. +--- -### Agentic 아키텍처 개발 +## 🧑‍💻 지원 환경 -- 쿼리 생성 과정을 에이전틱하게 개선하여 더욱 지능적이고 자율적인 SQL 생성이 가능하도록 개발합니다. -- 데이터 디스커버리 기능을 강화하여 사용자가 원하는 데이터를 더 효과적으로 찾을 수 있도록 지원합니다. +### LLM -### Datahub 통합 강화 +| 프로바이더 | 환경변수 `LLM_PROVIDER` | +|---|---| +| OpenAI | `openai` | +| Anthropic | `anthropic` | +| Azure OpenAI | `azure` | +| Google Gemini | `gemini` | +| AWS Bedrock | `bedrock` | +| Ollama | `ollama` | +| HuggingFace | `huggingface` | -- 현재 Datahub의 Glossary와 쿼리 예시를 코드로 조회하는 기능이 구현되어 있습니다. -- 이러한 메타데이터를 쿼리 생성 과정에 더욱 긴밀하게 통합하여 컨텍스트 기반의 정확한 SQL 생성을 지원하는 작업입니다. +### 데이터베이스 -### VectorDB 유연성 개선 +SQLite, PostgreSQL, MySQL, MariaDB, DuckDB, ClickHouse, Snowflake, Oracle, BigQuery, Trino, Hive, Crate -- 현재는 Datahub를 통해 로컬에 FAISS VectorDB를 생성해야만 사용 가능한 구조입니다. -- 이 결합도를 낮춰서 Datahub 없이도 기존에 준비된 VectorDB만 있으면 바로 활용할 수 있도록 아키텍처를 개선하는 작업입니다. +### VectorDB -### 모니터링 / 로깅 강화 +| 백엔드 | 영속성 | 권장 규모 | +|---|---|---| +| `InMemoryVectorStore` | 없음 | < 50k chunks | +| `FAISSVectorStore` | 로컬 파일 | < 500k chunks | +| `PGVectorStore` | PostgreSQL | 500k+ chunks | -- 프로젝트 사용 패턴과 성능을 모니터링하고, 상세한 로깅 시스템을 구축합니다. -- 사용자 피드백 수집 및 분석 프로세스를 통해 지속적인 개선이 가능한 기반을 마련하는 작업입니다. +--- -### 문서화 강화 +## 🤝 기여하기 -- 프로젝트 기여 장벽을 낮추기 위한 포괄적인 문서화 작업입니다. -- 개발자 가이드, 튜토리얼 등을 체계적으로 정리하여 새로운 기여자들이 쉽게 참여할 수 있는 환경을 조성합니다. +커뮤니티의 기여를 환영합니다! -### LLM 프론트에서 분리하기 +### 🔧 개발 환경 설정 -프런트에서는 LLM 호출·키를 제거하고 내부 백엔드 API로 위임해 보안·권한·모니터링을 중앙화합니다. +```bash +# 1. 저장소 포크 & 클론 +git clone https://github.com/YOUR_USERNAME/lang2sql.git +cd lang2sql ---- +# 2. 의존성 설치 +uv venv --python 3.11 +source .venv/bin/activate +uv sync --group dev -## 🤝 기여하기 +# 3. 브랜치 생성 (네이밍: feature/이슈번호-작업내용) +git checkout -b feature/42-amazing-feature -커뮤니티의 기여를 환영합니다! 여러분이 도울 수 있는 방법들: +# 4. 작업 후 커밋 & PR +git commit -m "feat: add amazing feature" +git push origin feature/42-amazing-feature +``` -### 🔧 개발 환경 설정 +### 📋 개발 가이드라인 -1. 저장소 포크하기 -2. 포크 클론: `git clone https://github.com/YOUR_USERNAME/lang2sql.git` -3. 의존성 설치: `pip install -r requirements.txt` -4. 기능 브랜치 생성: `git checkout -b feature/amazing-feature` -5. 변경사항 커밋: `git commit -m 'Add amazing feature'` -6. 브랜치에 푸시: `git push origin feature/amazing-feature` -7. Pull Request 열기 +- `pre-commit run --all-files`로 포맷팅 확인 +- 새로운 기능에 대한 테스트 작성 (`tests/test__.py`) +- PR은 `master` 브랜치 대상, 최소 2명 리뷰어 승인 필요 +- 커밋 메시지: `feat:`, `fix:`, `docs:`, `refactor:` 등 prefix 사용 ### 🐛 이슈 신고 @@ -263,13 +301,6 @@ Lang2SQL은 LangGraph를 사용한 다단계 접근 방식을 따릅니다: - 예상 동작 vs 실제 동작 - 환경 세부사항 -### 📋 개발 가이드라인 - -- pre-commit 활성화 -- 새로운 기능에 대한 테스트 작성 -- 필요시 문서 업데이트 -- 원자적이고 잘 설명된 커밋 유지 - --- ## 🎓 학습 자료 @@ -298,41 +329,30 @@ Lang2SQL은 LangGraph를 사용한 다단계 접근 방식을 따릅니다: | **Data Engineer** | 홍지영 | ![Python](https://img.shields.io/badge/Python-Expert-3776AB) | LLM, Data Engineering | | **Data Operator** | 이화림 | ![Python](https://img.shields.io/badge/Python-Expert-3776AB) | LLM, Data Engineering | - - ## 🚀 배포 및 릴리스 -### 수동 빌드 - -```bash -uv build -UV_PUBLISH_TOKEN=$PYPI_API_TOKEN uv publish --token $UV_PUBLISH_TOKEN -``` - ### 자동 배포(GitHub Actions) -사전 준비: GitHub Secrets에 `PYPI_API_TOKEN` 등록 +`v*` 태그 푸시 시 `.github/workflows/pypi-release.yml`이 실행되어 PyPI에 배포됩니다. ```bash -# 1) 버전 업데이트 -# - 버전 파일: version.py 의 __version__ = "X.Y.Z" +# 1) 버전 업데이트 (version.py) git add version.py git commit -m "chore: bump version to X.Y.Z" -# 2) 태그 생성/푸시 (v* 형식이 트리거) +# 2) 태그 생성/푸시 git tag vX.Y.Z git push origin HEAD git push origin vX.Y.Z ``` -설명: `v*` 태그가 푸시되면 `.github/workflows/pypi-release.yml`이 실행되어 uv로 빌드/배포합니다. +사전 준비: GitHub Secrets에 `PYPI_API_TOKEN` 등록 -### TestPyPI로 사전 검증(선택) +### 수동 빌드 ```bash uv build -UV_PUBLISH_TOKEN=$TEST_PYPI_API_TOKEN \ - uv publish --repository-url https://test.pypi.org/legacy/ --token $UV_PUBLISH_TOKEN +UV_PUBLISH_TOKEN=$PYPI_API_TOKEN uv publish --token $UV_PUBLISH_TOKEN ``` ---