Skip to content

Commit 7cb9c83

Browse files
ehddnr301ehddnr301
committed
Update README.md
1 parent 567ac80 commit 7cb9c83

File tree

28 files changed

+5556
-198
lines changed

28 files changed

+5556
-198
lines changed

‎README.md‎

Lines changed: 37 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -96,13 +96,15 @@ Streamlit 웹 인터페이스 실행:
9696
lang2sql run-streamlit
9797
```
9898

99-
사용자 정의 포트 및 DataHub 서버와 함께:
99+
사용자 정의 포트로 실행:
100100

101101
```bash
102-
lang2sql --datahub_server http://your-datahub-server:8080 run-streamlit -p 8888
102+
lang2sql run-streamlit -p 8888
103103
```
104104

105-
참고: Streamlit 서버는 `0.0.0.0` 으로 바인딩되어 외부에서 접속 가능합니다.
105+
**참고**:
106+
- Streamlit 서버는 `0.0.0.0` 으로 바인딩되어 외부에서 접속 가능합니다.
107+
- `--datahub_server` 옵션은 더 이상 사용되지 않습니다(deprecated). DataHub 설정은 UI의 설정 > 데이터 소스 탭에서 관리하세요.
106108

107109
### Graph Builder 페이지
108110

@@ -116,21 +118,23 @@ Streamlit 앱은 멀티 페이지 구조입니다. 좌측 네비게이션에서
116118

117119
### VectorDB 선택
118120

119-
FAISS(로컬) 또는 pgvector(PostgreSQL) 중 선택:
121+
**참고**: CLI 레벨의 `--vectordb-type` 및 `--vectordb-location` 옵션은 더 이상 사용되지 않습니다(deprecated). Streamlit 실행 시 VectorDB 설정은 UI의 설정 > 데이터 소스 탭에서 관리하세요.
122+
123+
`query` 명령어에서는 VectorDB 옵션을 사용할 수 있습니다:
120124

121125
```bash
122126
# FAISS 사용 (기본값)
123-
lang2sql --vectordb-type faiss run-streamlit
127+
lang2sql query "질문" --vectordb-type faiss
124128

125129
# pgvector 사용
126-
lang2sql --vectordb-type pgvector run-streamlit
130+
lang2sql query "질문" --vectordb-type pgvector
127131

128132
# 위치 지정 예시
129133
# FAISS: 인덱스 디렉토리 경로 지정
130-
lang2sql --vectordb-type faiss --vectordb-location ./dev/table_info_db run-streamlit
134+
lang2sql query "질문" --vectordb-type faiss --vectordb-location ./dev/table_info_db
131135

132136
# pgvector: 연결 문자열 지정
133-
lang2sql --vectordb-type pgvector --vectordb-location "postgresql://user:pass@host:5432/db" run-streamlit
137+
lang2sql query "질문" --vectordb-type pgvector --vectordb-location "postgresql://user:pass@host:5432/db"
134138
```
135139

136140
참고: DataHub 없이도 미리 준비된 VectorDB(FAISS 디렉토리 혹은 pgvector 컬렉션)를 바로 사용할 수 있습니다. 자세한 준비 방법은 [DataHub 없이 시작하기](docs/tutorials/getting-started-without-datahub.md)를 참고하세요.
@@ -144,20 +148,41 @@ lang2sql --vectordb-type pgvector --vectordb-location "postgresql://user:pass@ho
144148
### 자연어 쿼리 실행
145149

146150
```bash
147-
# 기본 FAISS 사용
151+
# 기본 사용 (FAISS, clickhouse, 기본 검색기)
148152
lang2sql query "고객 데이터를 기반으로 유니크한 유저 수를 카운트하는 쿼리"
149153

150-
# pgvector 사용
151-
lang2sql query "고객 데이터를 기반으로 유니크한 유저 수를 카운트하는 쿼리" --vectordb-type pgvector --vectordb-location "postgresql://postgres:postgres@localhost:5432/postgres"
154+
# 옵션 사용 예시
155+
lang2sql query "고객 데이터를 기반으로 유니크한 유저 수를 카운트하는 쿼리" \
156+
--database-env clickhouse \
157+
--retriever-name 기본 \
158+
--top-n 5 \
159+
--device cpu \
160+
--use-enriched-graph \
161+
--vectordb-type faiss \
162+
--vectordb-location ./dev/table_info_db
163+
164+
# pgvector 사용 예시
165+
lang2sql query "고객 데이터를 기반으로 유니크한 유저 수를 카운트하는 쿼리" \
166+
--vectordb-type pgvector \
167+
--vectordb-location "postgresql://postgres:postgres@localhost:5432/postgres"
152168
```
153169

170+
**주요 옵션 설명:**
171+
- `--database-env`: 사용할 데이터베이스 환경 (기본값: clickhouse)
172+
- `--retriever-name`: 테이블 검색기 이름 (기본값: 기본)
173+
- `--top-n`: 검색된 상위 테이블 수 제한 (기본값: 5)
174+
- `--device`: LLM 실행에 사용할 디바이스 (기본값: cpu)
175+
- `--use-enriched-graph`: 확장된 그래프(프로파일 추출 + 컨텍스트 보강) 사용 여부
176+
- `--vectordb-type`: 벡터 데이터베이스 타입 ("faiss" 또는 "pgvector", 기본값: faiss)
177+
- `--vectordb-location`: VectorDB 위치 (FAISS: 디렉토리 경로, pgvector: 연결 문자열)
178+
154179
### 환경 설정
155180

156181
- `.env` 파일을 생성하여 설정을 관리합니다. (예시 파일이 있다면 참조)
157182
- 또는 CLI 옵션으로 환경을 지정할 수 있습니다:
158183
- `--env-file-path`: 환경 변수 파일 경로 지정
159184
- `--prompt-dir-path`: 프롬프트 템플릿(.md) 디렉토리 지정
160-
- `--datahub_server`: DataHub GMS 서버 URL 지정
185+
- `--datahub_server`: [Deprecated] DataHub GMS 서버 URL 지정. 이제는 UI의 설정 > 데이터 소스 탭에서 관리하세요.
161186

162187
## 🏗️ 아키텍처
163188

‎cli/README.md‎

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
# CLI 모듈
2+
3+
Lang2SQL 프로젝트의 CLI(Command Line Interface) 모듈입니다. 자연어 질문을 SQL 쿼리로 변환하고, Streamlit 웹 애플리케이션을 실행하는 기능을 제공합니다.
4+
5+
## 디렉토리 구조
6+
7+
```
8+
cli/
9+
├── __init__.py # CLI 진입점 및 메인 그룹 정의
10+
├── __pycache__/ # Python 캐시 디렉토리
11+
├── commands/ # CLI 명령어 정의 모듈
12+
│ ├── __pycache__/
13+
│ ├── quary.py # 자연어 질문을 SQL로 변환하는 명령어
14+
│ ├── run_streamlit.py # Streamlit 실행 명령어
15+
│ └── README.md # Commands 모듈 문서
16+
├── core/ # CLI 핵심 기능 모듈
17+
│ ├── __pycache__/
18+
│ ├── environment.py # 환경 변수 초기화 모듈
19+
│ ├── streamlit_runner.py # Streamlit 실행 유틸리티
20+
│ └── README.md # Core 모듈 문서
21+
├── utils/ # CLI 유틸리티 모듈
22+
│ ├── __pycache__/
23+
│ ├── env_loader.py # 환경 변수 로드 유틸리티
24+
│ ├── logger.py # 로깅 설정 유틸리티
25+
│ └── README.md # Utils 모듈 문서
26+
└── README.md # 이 파일
27+
```
28+
29+
## 모듈 개요
30+
31+
### `__init__.py`
32+
33+
CLI 프로그램의 진입점입니다. Click 프레임워크를 사용하여 명령어 그룹과 옵션을 정의합니다.
34+
35+
**주요 구성 요소:**
36+
37+
#### CLI 그룹 정의
38+
- **함수**: `cli(ctx, datahub_server, run_streamlit, port, env_file_path, prompt_dir_path, vectordb_type, vectordb_location)`
39+
- **데코레이터**: `@click.group()`
40+
- **역할**: Lang2SQL CLI의 최상위 명령어 그룹
41+
42+
#### 주요 옵션
43+
44+
1. **`--version` / `-v`**: 버전 정보 출력
45+
2. **`--datahub_server`** (Deprecated): DataHub GMS URL 설정 - 더 이상 사용되지 않음
46+
3. **`--run-streamlit`**: CLI 실행 시 Streamlit 애플리케이션을 바로 실행하는 플래그
47+
4. **`-p, --port`**: Streamlit 서버 포트 번호 (기본값: 8501)
48+
5. **`--env-file-path`**: 환경 변수를 로드할 .env 파일 경로
49+
6. **`--prompt-dir-path`**: 프롬프트 템플릿 디렉토리 경로
50+
7. **`--vectordb-type`** (Deprecated): VectorDB 타입 - 더 이상 사용되지 않음
51+
8. **`--vectordb-location`** (Deprecated): VectorDB 위치 - 더 이상 사용되지 않음
52+
53+
#### 주요 동작
54+
55+
1. **환경 변수 초기화**: `initialize_environment()` 호출로 환경 변수 설정
56+
2. **Deprecated 옵션 경고**: 사용되지 않는 옵션 사용 시 경고 메시지 출력
57+
3. **Streamlit 자동 실행**: `--run-streamlit` 플래그가 설정된 경우 Streamlit 실행
58+
59+
#### 등록된 명령어
60+
61+
- `run-streamlit`: Streamlit 애플리케이션 실행 (`cli/commands/run_streamlit.py`)
62+
- `query`: 자연어 질문을 SQL 쿼리로 변환 (`cli/commands/quary.py`)
63+
64+
#### Import 관계
65+
66+
**Import하는 모듈:**
67+
- `cli.commands.quary.query_command`: query 명령어
68+
- `cli.commands.run_streamlit.run_streamlit_cli_command`: run-streamlit 명령어
69+
- `cli.core.environment.initialize_environment`: 환경 변수 초기화
70+
- `cli.core.streamlit_runner.run_streamlit_command`: Streamlit 실행 함수
71+
- `cli.utils.logger.configure_logging`: 로깅 설정
72+
- `version.__version__`: 버전 정보
73+
74+
**사용 위치:**
75+
- CLI 진입점: `pyproject.toml`의 `[project.scripts]` 섹션에 정의됨
76+
```toml
77+
[project.scripts]
78+
lang2sql = "cli.__init__:cli"
79+
```
80+
- 사용 방법: 패키지 설치 후 `lang2sql` 명령어로 실행
81+
```bash
82+
lang2sql --help
83+
lang2sql --version
84+
lang2sql --run-streamlit
85+
lang2sql query "질문"
86+
lang2sql run-streamlit
87+
```
88+
89+
#### 코드 예시
90+
91+
```python
92+
from cli import cli
93+
94+
# CLI 그룹 자동 등록
95+
# lang2sql 명령어로 실행 가능
96+
```
97+
98+
### 하위 모듈
99+
100+
#### `commands/` 모듈
101+
102+
CLI 명령어를 정의하는 모듈입니다. 자연어 질문을 SQL로 변환하는 `query` 명령어와 Streamlit을 실행하는 `run-streamlit` 명령어를 제공합니다.
103+
104+
자세한 내용은 [`commands/README.md`](commands/README.md)를 참고하세요.
105+
106+
**주요 파일:**
107+
- `quary.py`: `query_command` - 자연어를 SQL로 변환하는 명령어
108+
- `run_streamlit.py`: `run_streamlit_cli_command` - Streamlit 실행 명령어
109+
110+
**사용 위치:**
111+
- `cli/__init__.py` (10-11, 116-117번 라인): CLI 그룹에 명령어 등록
112+
```python
113+
from cli.commands.quary import query_command
114+
from cli.commands.run_streamlit import run_streamlit_cli_command
115+
116+
cli.add_command(run_streamlit_cli_command)
117+
cli.add_command(query_command)
118+
```
119+
120+
#### `core/` 모듈
121+
122+
CLI의 핵심 기능을 제공하는 모듈입니다. 환경 변수 초기화와 Streamlit 실행 기능을 담당합니다.
123+
124+
자세한 내용은 [`core/README.md`](core/README.md)를 참고하세요.
125+
126+
**주요 파일:**
127+
- `environment.py`: `initialize_environment` - 환경 변수 초기화 함수
128+
- `streamlit_runner.py`: `run_streamlit_command` - Streamlit 실행 함수
129+
130+
**사용 위치:**
131+
- `cli/__init__.py` (12-13, 85, 113번 라인):
132+
```python
133+
from cli.core.environment import initialize_environment
134+
from cli.core.streamlit_runner import run_streamlit_command
135+
136+
# 환경 변수 초기화
137+
initialize_environment(
138+
env_file_path=env_file_path,
139+
prompt_dir_path=prompt_dir_path
140+
)
141+
142+
# Streamlit 실행
143+
if run_streamlit:
144+
run_streamlit_command(port)
145+
```
146+
147+
#### `utils/` 모듈
148+
149+
CLI 애플리케이션에서 사용되는 유틸리티 함수들을 제공하는 모듈입니다.
150+
151+
자세한 내용은 [`utils/README.md`](utils/README.md)를 참고하세요.
152+
153+
**주요 파일:**
154+
- `env_loader.py`: 환경 변수 로드 및 설정 함수들
155+
- `load_env`: .env 파일 로드
156+
- `set_prompt_dir`: 프롬프트 디렉토리 설정
157+
- `set_vectordb`: VectorDB 설정
158+
- `logger.py`: `configure_logging` - CLI 전용 로깅 설정
159+
160+
**사용 위치:**
161+
- `cli/__init__.py` (14, 18번 라인): 로깅 설정
162+
```python
163+
from cli.utils.logger import configure_logging
164+
165+
logger = configure_logging()
166+
```
167+
- `cli/core/environment.py`: 환경 변수 로드
168+
- `cli/core/streamlit_runner.py`: 로깅 설정
169+
- `cli/commands/quary.py`: 로깅 설정
170+
- `cli/commands/run_streamlit.py`: 로깅 설정
171+
172+
## CLI 사용 방법
173+
174+
### 기본 사용법
175+
176+
```bash
177+
# 도움말 보기
178+
lang2sql --help
179+
180+
# 버전 확인
181+
lang2sql --version
182+
183+
# Streamlit 바로 실행
184+
lang2sql --run-streamlit
185+
186+
# 환경 변수 파일 지정하여 실행
187+
lang2sql --env-file-path /path/to/.env --run-streamlit
188+
```
189+
190+
### 명령어
191+
192+
#### `query` 명령어
193+
194+
자연어 질문을 SQL 쿼리로 변환합니다.
195+
196+
```bash
197+
# 기본 사용
198+
lang2sql query "고객 데이터를 기반으로 유니크한 유저 수를 카운트하는 쿼리"
199+
200+
# 옵션과 함께 사용
201+
lang2sql query "질문" \
202+
--database-env clickhouse \
203+
--retriever-name 기본 \
204+
--top-n 5 \
205+
--device cpu \
206+
--use-enriched-graph \
207+
--vectordb-type faiss \
208+
--vectordb-location ./dev/table_info_db
209+
```
210+
211+
#### `run-streamlit` 명령어
212+
213+
Streamlit 웹 애플리케이션을 실행합니다.
214+
215+
```bash
216+
# 기본 포트(8501)로 실행
217+
lang2sql run-streamlit
218+
219+
# 특정 포트로 실행
220+
lang2sql run-streamlit -p 9000
221+
```
222+
223+
자세한 사용법은 [`commands/README.md`](commands/README.md)를 참고하세요.
224+
225+
## 의존성
226+
227+
### 내부 의존성
228+
229+
- `cli.commands.*`: CLI 명령어 정의
230+
- `cli.core.*`: 핵심 기능 모듈
231+
- `cli.utils.*`: 유틸리티 함수
232+
- `version`: 버전 정보
233+
234+
### 외부 의존성
235+
236+
- `click`: CLI 프레임워크
237+
- `subprocess`: Streamlit 프로세스 실행 (core 모듈)
238+
- `python-dotenv`: 환경 변수 파일 로드 (utils 모듈)
239+
- `streamlit`: Streamlit 웹 애플리케이션 프레임워크
240+
241+
## 모듈 간 관계도
242+
243+
```
244+
cli/__init__.py (진입점)
245+
├── commands/
246+
│ ├── quary.py → engine.query_executor
247+
│ └── run_streamlit.py → core/streamlit_runner.py
248+
├── core/
249+
│ ├── environment.py → utils/env_loader.py
250+
│ └── streamlit_runner.py → utils/logger.py
251+
└── utils/
252+
├── env_loader.py (독립적)
253+
└── logger.py (독립적)
254+
```
255+
256+
## 주요 특징
257+
258+
1. **모듈화된 구조**: 명령어, 핵심 기능, 유틸리티가 명확히 분리됨
259+
2. **확장 가능성**: 새로운 명령어를 쉽게 추가할 수 있는 구조
260+
3. **환경 관리**: 일관된 환경 변수 초기화 보장
261+
4. **UI 중심 설계**: VectorDB 및 DataHub 설정은 UI에서 관리
262+
5. **로깅 지원**: 모든 모듈에서 일관된 로깅 사용
263+
6. **Deprecated 옵션 처리**: 사용되지 않는 옵션에 대한 명확한 경고
264+
265+
## 참고 문서
266+
267+
- [`commands/README.md`](commands/README.md): 명령어 모듈 상세 문서
268+
- [`core/README.md`](core/README.md): 핵심 기능 모듈 상세 문서
269+
- [`utils/README.md`](utils/README.md): 유틸리티 모듈 상세 문서
270+

0 commit comments

Comments
 (0)