NL2SQL 슬랙봇 시스템 구성도NL2SQL Slack Bot System Architecture

Slack에서 BigQuery까지, 데이터 요청 및 응답의 전체 흐름

사용자 & SlackUser & Slack

Slack 채널에서
/ask 명령어로 질문

터널링 서비스Tunneling Service

Cloudflare Tunnel 또는 ngrok
공개 URL을 로컬 서버로 연결

로컬 개발 환경

FastAPI 서버

localhost:8000에서 실행,
핵심 비즈니스 로직 처리

Gemini API

자연어 질문을
SQL로 변환

Google BigQuery

변환된 SQL을 실행하고
데이터 반환

1. /ask 요청 (Webhook)

2. 요청 전달

3. NL to SQL 변환 요청

4. 변환된 SQL 반환

5. SQL 실행 요청

6. 데이터 결과 반환

7. 최종 결과 전송 (response_url)

터미널 설정 매뉴얼Tunneling Setup Manual

로컬 서버를 외부 인터넷에 연결하는 두 가지 방법: Cloudflare Tunnel 과 ngrok

2.1 사전 준비 사항2.1 Prerequisites

개발 도구 설치Development Tools Installation

① Python 3.7+

Python 설치 여부를 확인하고, 없다면 공식 웹사이트에서 다운로드합니다.

python3 --version

프로젝트 및 가상환경 설정Project and Virtual Environment Setup

패키지 충돌을 방지하기 위해 격리된 개발 환경을 설정합니다.

프로젝트 폴더 생성 및 이동:Create and move to the project folder:
```
mkdir nl2sql-project && cd nl2sql-project
```
Python 가상환경 생성:Create a Python virtual environment:
```
python3 -m venv venv
```
가상환경 활성화:Activate the virtual environment:
```
source venv/bin/activate
```
성공하면 터미널 프롬프트 앞에 (venv)가 표시됩니다.

필수 Python 패키지 설치Install Required Python Packages

requirements.txt 파일 생성 후 아래 내용 붙여넣기:Create a requirements.txt file and paste the content below:

fastapi
uvicorn
google-cloud-bigquery
google-auth
langchain-google-genai
langchain
pandas
pydantic
altair
db-dtypes
google-cloud-bigquery-storage
httpx
tabulate

가상환경에서 모든 패키지 설치:Install all packages from the virtual environment:
```
pip install -r requirements.txt
```

클라우드 서비스 및 계정 설정Cloud Service and Account Setup

① Google Cloud Platform (GCP) 설정Setup

GCP 프로젝트 생성 후 BigQuery API와 Vertex AI API를 '사용 설정'합니다.
로컬 환경 인증:Authenticate local environment:
```
gcloud auth application-default login
```
Gemini API 키 발급 및 환경 변수 설정:Issue Gemini API Key and set environment variable:
```
export GOOGLE_API_KEY="your-google-api-key"
```

② 외부 서비스 계정External Service Accounts

Slack: 앱 설치 권한이 있는 워크스페이스 필요.
Cloudflare or ngrok: 사용할 터널링 서비스의 계정 필요.

2.2 Cloudflare Tunnel 설정Setup

Cloudflare Tunnel을 사용하여 로컬 서버를 외부에 노출하는 방법입니다. CLI 도구 설치가 필요합니다.

# macOS (Homebrew 사용 시)
brew install cloudflared

방법 A: Quick Tunnel (임시 URL)Method A: Quick Tunnel (Temporary URL)

가장 빠르고 간단한 방법으로, 테스트나 일회성 공유에 적합합니다.

cloudflared tunnel --url http://localhost:8000

터널을 재시작하면 URL이 변경됩니다.

방법 B: Named Tunnel (고정 URL)Method B: Named Tunnel (Fixed URL)

개인 도메인이 필요하며, 여러 단계의 초기 설정이 필요합니다.

Cloudflare 계정 로그인Account Login
터미널에서 아래 명령어를 실행하고 웹 브라우저에서 Cloudflare 계정으로 로그인하여 인증합니다.
```
cloudflared tunnel login
```
터널 생성Create Tunnel
터널에 고유한 이름을 부여하여 생성합니다. 이 이름은 나중에 터널을 관리할 때 사용됩니다.
```
# cloudflared tunnel create <터널이름>
# 예시:
cloudflared tunnel create nl2sql-test
```
DNS 라우팅 설정Routing Setup
생성한 터널과 사용할 고정 주소(서브도메인)를 연결합니다.
```
# cloudflared tunnel route dns <터널이름> <사용할 주소>
# 예시:
cloudflared tunnel route dns nl2sql-test your-subdomain.your-domain.com
```
your-subdomain.your-domain.com는 실제 소유한 도메인 주소로 변경해야 합니다.

설정 파일(config.yml) 작성 및 실행Create and Run Config File (config.yml)

터널의 상세 설정을 위해 ~/.cloudflared/ 폴더에 config.yml 파일을 생성하고 아래 내용을 붙여넣습니다.

# /path/to/your/.cloudflared/config.yml

tunnel: nl2sql-test
credentials-file: /path/to/your/.cloudflared/your-credentials-file.json

ingress:
  # 'your-subdomain.your-domain.com' 주소로 들어오는 요청은
  - hostname: your-subdomain.your-domain.com
    # 로컬의 8000번 포트(FastAPI 서버)로 전달합니다.
    service: http://localhost:8000
  # 위 규칙에 맞지 않는 모든 요청은 404 에러를 반환합니다.
  - service: http_status:404

파일 작성이 완료되면, 아래 명령어로 터널을 실행합니다.

cloudflared tunnel run nl2sql-test

2.3 ngrok 설정Setup

ngrok을 사용하여 로컬 서버를 외부 인터넷에 연결하는 방법입니다. CLI 도구 설치 및 계정 설정이 필요합니다.

1단계: ngrok 설치Installation

# macOS (Homebrew 사용 시)
brew install ngrok

2단계: ngrok 회원가입 및 Authtoken 등록Sign Up and Register Authtoken

최신 ngrok 정책에 따라, 터널을 사용하려면 반드시 ngrok 계정에 가입하고, 개인 인증 토큰(Authtoken)을 컴퓨터에 등록해야 합니다. 이 과정은 최초 한 번만 수행하면 됩니다.

# ngrok 대시보드에서 복사한 Authtoken 등록 명령어
ngrok config add-authtoken your-ngrok-authtoken

3단계: ngrok 실행Execution

ngrok http 8000

무료 플랜은 터널을 재시작하면 URL이 변경됩니다.

2.4 Slack 앱 설정App Setup

위에서 얻은 공개 URL을 사용하여 Slack 슬래시 커맨드와 로컬 서버를 연결합니다.

1단계: Slack 앱 생성 및 슬래시 커맨드 추가Create Slack App and Add Slash Command

Slack API 페이지에서 Create New App > From scratch 옵션으로 앱을 생성합니다.
앱 설정 페이지 왼쪽 메뉴에서 Features > Slash Commands를 클릭하고 Create New Command 버튼을 누릅니다.

2단계: Request URL 설정Setup

아래 내용을 참고하여 슬래시 커맨드 설정 창을 채웁니다.

Command: /ask

Request URL: 가장 중요!Most Important! 아래 형식에 맞게 입력합니다.Enter it in the format below.

[Cloudflare 또는 ngrok 공개 URL]/slack/ask

# 예시 (Cloudflare): https://random.trycloudflare.com/slack/ask
# 예시 (ngrok): https://random.ngrok-free.app/slack/ask

Short Description: 'BigQuery에 자연어로 질문합니다'와 같이 간단한 설명을 입력합니다.

Usage Hint: '[질문 내용]'과 같이 사용자에게 입력 형식을 안내합니다.

3단계: 앱 설치 및 재설치App Installation & Reinstallation

왼쪽 메뉴의 Settings > Install App으로 이동하여 Install to Workspace 버튼을 클릭하고 권한을 허용합니다.
Request URL을 변경하는 등, 앱 설정을 수정한 후에는 반드시 이 페이지에서 Reinstall to Workspace 버튼을 눌러 변경사항을 워크스페이스에 적용해야 합니다.

NL2SQL 배포 매뉴얼NL2SQL Deployment Manual

로컬 개발부터 클라우드 배포까지 전 과정 안내

3.1 최종 결과물3.1 Final Result

이 매뉴얼을 따라 성공적으로 배포하면 아래 링크의 웹 애플리케이션이 완성됩니다.

라이브 데모 바로가기

3.2 프로젝트 폴더 구조3.2 Project Folder Structure

이 프로젝트는 백엔드와 프론트엔드가 명확히 분리된 구조를 가집니다. 각 파일의 역할은 다음과 같습니다.

nl-to-sql-project/
├── backend/
│   ├── main.py              # FastAPI 서버 로직 (API 엔드포인트)
│   ├── requirements.txt     # 백엔드 Python 라이브러리 목록
│   └── Dockerfile           # Cloud Run 배포를 위한 컨테이너 설계도
└── frontend/
    ├── index.html           # 웹페이지의 구조 (HTML)
    ├── style.css            # 웹페이지의 디자인 (CSS)
    └── script.js            # 웹페이지의 동작 (JavaScript)

3.3 로컬 설치 및 실행 (macOS)Local Installation & Execution (macOS)

Cloud에 배포하기 전, 로컬 PC에서 앱을 테스트하고 실행하는 방법입니다.

사전 준비Prerequisites

로컬 개발을 위해 다음 도구들이 설치되어 있어야 합니다.

Homebrew: macOS용 패키지 관리자. brew.sh에서 설치.
Python 3.10+:
```
brew install python
```
Google Cloud SDK:
```
brew install --cask google-cloud-sdk
```

인증 및 API 키 설정Authentication and API Key Setup

로컬 PC가 Google Cloud 서비스 및 AI 모델에 접근할 수 있도록 인증을 설정합니다.

Google 계정 로그인:Google Account Login: 터미널에서 아래 명령어를 실행하고, `your-gcp-project-id` 프로젝트에 접근 권한이 있는 Google 계정으로 로그인합니다.Run the command below in the terminal and log in with a Google account that has access to the `your-gcp-project-id` project.
```
gcloud auth login
```
프로젝트 설정:Project Setup: 사용할 Google Cloud 프로젝트를 지정합니다.Specify the Google Cloud project to use.
```
gcloud config set project your-gcp-project-id
```
로컬 환경 인증:Local Environment Authentication: 로컬 애플리케이션이 Google Cloud API를 사용할 수 있도록 인증합니다.Authenticate your local application to use Google Cloud APIs.
```
gcloud auth application-default login
```
Gemini API 키 설정:Gemini API Key Setup: 터미널에서 환경 변수로 API 키를 설정합니다. (터미널을 닫으면 초기화됩니다)Set the API key as an environment variable in the terminal. (It will be reset when the terminal is closed)
```
export GOOGLE_API_KEY="your-google-api-key"
```

서버 실행Run Server

백엔드와 프론트엔드 서버를 각각 실행합니다.

백엔드 서버 (터미널 1)Backend Server (Terminal 1)

다른 파이썬 프로젝트와의 충돌을 방지하기 위해, 이 프로젝트만을 위한 격리된 '가상환경'을 사용합니다.

`backend` 폴더로 이동:Navigate to `backend` folder:
```
cd path/to/your/nl-to-sql-project/backend
```
가상환경 생성 (최초 한 번만 실행):
```
python3 -m venv venv
```
가상환경 활성화 (서버 실행 전 항상 실행):
```
source venv/bin/activate
```
성공하면 터미널 프롬프트 앞에 (venv)가 표시됩니다.
라이브러리 설치:Install libraries:
```
pip install -r requirements.txt
```
서버 실행:Run server:
```
uvicorn main:app --reload --port 8000
```

프론트엔드 서버 (터미널 2)Frontend Server (Terminal 2)

백엔드 서버는 켜둔 채로, 새로운 터미널 창을 열어 진행합니다.

`frontend` 폴더로 이동:Navigate to `frontend` folder:
```
cd path/to/your/nl-to-sql-project/frontend
```
웹 서버 실행:Run web server:
```
python3 -m http.server 5500
```

브라우저에서 테스트Test in Browser

웹 브라우저를 열고 주소창에 http://localhost:5500를 입력하여 앱을 테스트합니다. frontend/script.js 파일의 BACKEND_BASE_URL 변수가 http://127.0.0.1:8000로 설정되어 있는지 확인하세요.

3.4 Google Cloud Run 배포Deployment

로컬 테스트가 완료된 앱을 실제 사용자들이 접근할 수 있도록 Google Cloud Run에 배포하는 방법입니다.

주의:Note: 배포를 진행하기 전, `backend/main.py` 파일의 CORS 설정 (`origins` 리스트)에 GitHub Pages 등 실제 프론트엔드가 배포될 주소를 추가해야 합니다.

컨테이너 이미지 빌드 및 업로드:Build and Upload Container Image: 터미널에서 `nl-to-sql-project` 폴더로 이동한 후, 다음 명령어로 백엔드 코드를 컨테이너 이미지로 만들어 Google Container Registry에 업로드합니다.Navigate to the `nl-to-sql-project` folder in the terminal, then use the following command to build the backend code into a container image and upload it to the Google Container Registry.
```
gcloud builds submit ./backend --tag gcr.io/your-gcp-project-id/nl-to-sql-api
```
Cloud Run에 배포:Deploy to Cloud Run: 업로드된 이미지를 사용하여 Cloud Run 서비스를 생성하고 배포합니다. API 키는 `--set-env-vars` 플래그를 통해 안전하게 주입합니다.Create and deploy a Cloud Run service using the uploaded image. The API key is securely injected via the `--set-env-vars` flag.
```
gcloud run deploy nl-to-sql-api \
  --image gcr.io/your-gcp-project-id/nl-to-sql-api \
  --platform managed \
  --region asia-northeast3 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_API_KEY=your-google-api-key"
```
배포 완료 및 URL 확인: 배포가 성공하면 `Service URL: https://...` 형태의 주소가 출력됩니다. 이 주소가 실제 운영되는 백엔드 API 주소입니다.
프론트엔드 업데이트:Frontend Update: `frontend/script.js` 파일의 `BACKEND_BASE_URL` 변수 값을 새로 얻은 Cloud Run 서비스 URL로 변경한 후, 프론트엔드 코드를 GitHub Pages 등 원하는 곳에 배포합니다.